Кешування
*********

<div class=perex>

Кеш прискорює роботу вашого додатка, зберігаючи дані - одного разу насилу витягнуті - для використання в майбутньому. Ми покажемо вам:

- Як використовувати кеш
- Як змінити сховище кешу
- Як правильно анулювати кеш

</div>

Використання кешу в Nette дуже просте, при цьому він також покриває дуже складні потреби в кешуванні. Він розроблений для забезпечення продуктивності та 100% довговічності. В основному, ви знайдете адаптери для найпоширеніших внутрішніх сховищ. Дозволяє анулювання на основі тегів, захист кеш-пам'яті, закінчення часу тощо.


Встановлення .[#toc-installation]
=================================

Завантажте та встановіть пакет за допомогою [Composer |best-practices:composer]:

```shell
composer require nette/caching
```


Використання .[#toc-basic-usage]
================================

Центром роботи з кешем є об'єкт [api:Nette\Caching\Cache]. Ми створюємо його екземпляр і передаємо конструктору як параметр так зване сховище. Це об'єкт, що представляє місце, де дані будуть фізично зберігатися (база даних, Memcached, файли на диску, ...). Ви отримуєте об'єкт сховища, передаючи його за допомогою [впровадження залежностей |dependency-injection:passing-dependencies] з типом `Nette\Caching\Storage`. Усе найнеобхідніше ви знайдете в [розділі С ховища|#Хранилища].

Для наступних прикладів припустимо, що у нас є псевдонім `Cache` і сховище у змінній `$storage`.




```php
use Nette\Caching\Cache;

$storage = /* ... */; // екземпляр Nette\Caching\Storage
```

Кеш фактично є сховищем типу *ключ-значення*, тому ми читаємо і записуємо дані за ключами так само, як і асоціативні масиви. Додатки складаються з декількох незалежних частин, і якби всі вони використовували одне сховище (наприклад, один каталог на диску), рано чи пізно відбудеться зіткнення ключів. Nette Framework вирішує цю проблему шляхом поділу всього простору на простори імен (підкаталоги). У цьому разі кожна частина програми використовує свій власний простір з унікальним ім'ям, і колізії не виникають.

Ім'я простору вказується як другий параметр конструктора класу Cache:

```php
$cache = new Cache($storage, 'Full Html Pages');
```

Тепер ми можемо використовувати об'єкт `$cache` для читання і запису з кешу. Для обох використовується метод `load()`. Перший аргумент - ключ, а другий - зворотний виклик PHP, який викликається, коли ключ не знайдено в кеші. Зворотний виклик генерує значення, повертає його і кешує:

```php
$value = $cache->load($key, function () use ($key) {
	$computedValue = /* ... */; // важкі обчислення
	return $computedValue;
});
```

Якщо другий параметр не вказано (`$value = $cache->load($key)`), повертається `null`, якщо елемента немає в кеші.

.[tip]
Чудово те, що кешувати можна будь-які серіалізовані структури, а не тільки рядки. Те ж саме стосується і ключів.

Елемент видаляється з кешу за допомогою методу `remove()`:

```php
$cache->remove($key);
```

Ви також можете кешувати елементи за допомогою методу `$cache->save($key, $value, array $dependencies = [])`. Однак описаний вище метод з використанням `load()` є кращим.


Мемоїзація .[#toc-memoization]
==============================

Мемоїзація означає кешування результату функції або методу, щоб ви могли використати його наступного разу, а не обчислювати те саме знову і знову.

Методи та функції можна викликати мемоїзовано за допомогою `call(callable $callback, ...$args)`:

```php
$result = $cache->call('gethostbyaddr', $ip);
```

Функція `gethostbyaddr()` викликається тільки один раз для кожного параметра `$ip` і наступного разу буде повернуто значення з кешу.

Також можна створити мемоїзовану обгортку для методу або функції, яка може бути викликана пізніше:

```php
function factorial($num)
{
	return /* ... */;
}

$memoizedFactorial = $cache->wrap('factorial');

$result = $memoizedFactorial(5); // підраховує
$result = $memoizedFactorial(5); // повертає з кешу
```


Закінчення терміну дії та анулювання .[#toc-expiration-invalidation]
====================================================================

Під час кешування необхідно вирішити питання про те, що деякі з раніше збережених даних із часом стануть недійсними. Nette Framework надає механізм, як обмежити дійсність даних і як видалити їх контрольованим чином ("зробити їх недійсними", використовуючи термінологію фреймворку).

Дійсність даних встановлюється в момент збереження за допомогою третього параметра методу `save()`, наприклад:

```php
$cache->save($key, $value, [
	$cache::Expire => '20 minutes',
]);
```

Або використовуючи параметр `$dependencies`, переданий за посиланням у зворотний виклик у методі `load()`, наприклад:

```php
$value = $cache->load($key, function (&$dependencies) {
	$dependencies[Cache::Expire] = '20 minutes';
	return /* ... */;
});
```

Або використовуючи 3-й параметр у методі `load()`, наприклад:

```php
$value = $cache->load($key, function () {
	return ...;
}, [Cache::Expire => '20 minutes']);
```

У наступних прикладах ми будемо припускати другий варіант і, отже, існування змінної `$dependencies`.


Термін дії .[#toc-expiration]
-----------------------------

Найпростіший виняток - це обмеження за часом. Ось як кешувати дані, дійсні протягом 20 хвилин:

```php
// також можна передати число секунд або тимчасову мітку UNIX
$dependencies[Cache::Expire] = '20 minutes';
```

Якщо ми хочемо збільшувати термін дії під час кожного читання, цього можна домогтися таким чином, але врахуйте, що це збільшить накладні витрати кешу:

```php
$dependencies[Cache::Sliding] = true;
```

Зручною опцією є можливість дозволити закінчення терміну дії даних під час зміни конкретного файлу або одного з декількох файлів. Це можна використовувати, наприклад, для кешування даних, отриманих у результаті обробки цих файлів. Використовуйте абсолютні шляхи:

```php
$dependencies[Cache::Files] = '/путь/до/data.yaml';
// або
$dependencies[Cache::Files] = ['/путь/до/data1.yaml', '/путь/до/data2.yaml'];
```

Ми можемо дозволити елементу в кеші закінчитися, коли закінчується термін дії іншого елемента (або одного з декількох інших). Це можна використовувати, коли ми кешуємо всю HTML-сторінку та її фрагменти під іншими ключами. Щойно сніпет змінюється, вся сторінка стає недійсною. Якщо у нас є фрагменти, що зберігаються під такими ключами, як `frag1` і `frag2`, ми будемо використовувати:

```php
$dependencies[Cache::Items] = ['frag1', 'frag2'];
```

Термін дії також можна контролювати за допомогою користувацьких функцій або статичних методів, які під час читання завжди вирішують, чи дійсний ще елемент. Наприклад, ми можемо дозволити елементу спливати щоразу, коли змінюється версія PHP. Ми створимо функцію, яка порівнює поточну версію з параметром, і під час збереження додамо масив у вигляді `[имя функции, ...аргументы]` до залежностей:

```php
function checkPhpVersion($ver): bool
{
	return $ver === PHP_VERSION_ID;
}

$dependencies[Cache::Callbacks] = [
	['checkPhpVersion', PHP_VERSION_ID] // закінчується, коли checkPhpVersion(...) === false
];
```

Звичайно, всі критерії можуть бути об'єднані. Термін дії кешу закінчується, якщо хоча б один критерій не виконано.

```php
$dependencies[Cache::Expire] = '20 minutes';
$dependencies[Cache::Files] = '/path/to/data.yaml';
```


Інвалідація з використанням тегів .[#toc-invalidation-using-tags]
-----------------------------------------------------------------

Теги є дуже корисним інструментом визнання недійсності. Ми можемо призначити список тегів, які є довільними рядками, кожному елементу, що зберігається в кеші. Наприклад, припустимо, що в нас є HTML-сторінка зі статтею та коментарями, яку ми хочемо кешувати. Тому ми вказуємо теги під час збереження в кеш:

```php
$dependencies[Cache::Tags] = ["article/$articleId", "comments/$articleId"];
```

Тепер перейдемо до адміністрування. Тут у нас є форма для редагування статті. Разом зі збереженням статті в базі даних ми викликаємо команду `clean()`, яка видаляє кешовані елементи за тегами:

```php
$cache->clean([
	$cache::Tags => ["article/$articleId"],
]);
```

Аналогічним чином, у місці додавання нового коментаря (або редагування коментаря) ми не забудемо анулювати відповідний тег:

```php
$cache->clean([
	$cache::Tags => ["comments/$articleId"],
]);
```

Чого ми досягли? Що наш HTML-кеш буде анульовано (видалено) при кожній зміні статті або коментарів. Під час редагування статті з ID = 10 тег `article/10` примусово анулюється, а HTML-сторінка, що містить цей тег, видаляється з кешу. Те ж саме відбувається при вставці нового коментаря під відповідною статтею.

.[note]
Тегам потрібен [Журнал |#Журнал].


Інвалідація за пріоритетом .[#toc-invalidation-by-priority]
-----------------------------------------------------------

Ми можемо встановити пріоритет для окремих елементів у кеші, і їх можна буде видаляти контрольованим чином, коли, наприклад, кеш перевищить певний розмір:

```php
$dependencies[Cache::Priority] = 50;
```

Видаляємо всі елементи з пріоритетом, що дорівнює або менший за 100:

```php
$cache->clean([
	$cache::Priority => 100,
]);
```

.[note]
Пріоритетам також потрібен [Журнал |#Журнал].


Очищення кешу .[#toc-clear-cache]
---------------------------------

Параметр `Cache::All` очищає все:

```php
$cache->clean([
	$cache::All => true,
]);
```


Масове читання .[#toc-bulk-reading]
===================================

Для масового читання і запису в кеш використовується метод `bulkLoad()`, в якому ми передаємо масив ключів і отримуємо масив значень:

```php
$values = $cache->bulkLoad($keys);
```

Метод `bulkLoad()` працює аналогічно `load()` з другим параметром зворотного виклику, якому передається ключ згенерованого елемента:

```php
$values = $cache->bulkLoad($keys, function ($key, &$dependencies) {
	$computedValue = /* ... */; // важкі обчислення
	return $computedValue;
});
```


Використання з PSR-16 .[#toc-using-with-psr-16]
===============================================

Щоб використовувати Nette Cache з інтерфейсом PSR-16, ви можете скористатися `PsrCacheAdapter`. Він дозволяє легко інтегрувати Nette Cache з будь-яким кодом або бібліотекою, що очікує використання PSR-16-сумісного кешу.

```php
$psrCache = new Nette\Bridges\Psr\PsrCacheAdapter($storage);
```

Тепер ви можете використовувати `$psrCache` як кеш PSR-16:

```php
$psrCache->set('key', 'value', 3600); // зберігає значення протягом 1 години
$value = $psrCache->get('key', 'default');
```

Адаптер підтримує всі методи, визначені в PSR-16, включаючи `getMultiple()`, `setMultiple()` і `deleteMultiple()`.


Кешування виведення .[#toc-output-caching]
==========================================

Вихідні дані можна перехоплювати і кешувати дуже елегантно:

```php
if ($capture = $cache->capture($key)) {

	echo ... // виводимо деякі дані

	$capture->end(); // зберігаємо виведення в кеш
}
```

У разі якщо виведення вже присутнє в кеші, метод `capture()` друкує його і повертає `null`, тому умова не буде виконана. В іншому разі він починає буферизацію виводу і повертає об'єкт `$capture`, за допомогою якого ми остаточно зберігаємо дані в кеш.

.[note]
У версії 3.0 метод називався `$cache->start()`.


Кешування в Latte .[#toc-caching-in-latte]
==========================================

Кешування в шаблонах [Latte |latte:] дуже легко налаштовується, достатньо обернути частину шаблону тегами `{cache}...{/cache}`. Кеш автоматично анулюється при зміні вихідного шаблону (включаючи будь-які включені шаблони в тегах `{cache}`). Теги `{cache}` можуть бути вкладеними, і коли вкладений блок анулюється (наприклад, тегом), батьківський блок також анулюється.

У тезі можна вказати ключі, до яких буде прив'язано кеш (тут змінна `$id`) і встановити термін дії та [теги анулювання |#Инвалидация с использованием тегов].

```latte
{cache $id, expire => '20 minutes', tags => [tag1, tag2]}
	...
{/cache}
```

Усі параметри є необов'язковими, тому вам не потрібно вказувати термін дії, теги або ключі.

Використання кешу також може бути обумовлено `if` - вміст буде кешуватися тільки при виконанні умови:

```latte
{cache $id, if => !$form->isSubmitted()}
	{$form}
{/cache}
```


Сховища .[#toc-hranilisa]
=========================

Сховище - це об'єкт, який являє собою місце фізичного зберігання даних. Ми можемо використовувати базу даних, сервер Memcached або найбільш доступне сховище, яким є файли на диску.

|----------------------
| Зберігання | Опис
|----------------------
| [FileStorage |#FileStorage] | зберігання за замовчуванням зі збереженням у файли на диску
| [MemcachedStorage |#MemcachedStorage] | використовується сервер `Memcached
| [MemoryStorage |#MemoryStorage] | дані тимчасово знаходяться в пам'яті
| [SQLiteStorage |#SQLiteStorage] | дані зберігаються в базі даних SQLite
| [DevNullStorage |#DevNullStorage] | дані не зберігаються - з метою тестування

Ви отримуєте об'єкт сховища, передаючи його за допомогою [впровадження залежностей |dependency-injection:passing-dependencies] з типом `Nette\Caching\Storage`. За замовчуванням Nette надає об'єкт FileStorage, який зберігає дані в підпапці `cache` в каталозі для [тимчасових файлів |application:bootstrap#Temporary-Files].

Ви можете змінити сховище в конфігурації:

```neon
services:
	cache.storage: Nette\Caching\Storages\DevNullStorage
```


FileStorage .[#toc-filestorage]
-------------------------------

Записує кеш у файли на диску. Сховище `Nette\Caching\Storages\FileStorage` дуже добре оптимізоване для продуктивності і, перш за все, забезпечує повну атомарність операцій. Що це означає? Щоб під час використання кешу не вийшло так, що ми читаємо файл, який ще не був повністю записаний іншим потоком, або щоб хтось видалив його "з-під руки". Тому використання кешу повністю безпечне.

Це сховище також має важливу вбудовану функцію, яка запобігає екстремальному збільшенню завантаження процесора, коли кеш очищається або охолоджується (тобто не створюється). Це профілактика "cache stampede":https://en.wikipedia.org/wiki/Cache_stampede_.
Буває так, що в один момент надходить кілька одночасних запитів, які хочуть отримати з кешу одне й те саме (наприклад, результат великого SQL-запиту), а оскільки він не кешується, усі процеси починають виконувати один і той самий SQL-запит.
Навантаження на процесор збільшується в кілька разів, і може навіть трапитися так, що жоден потік не зможе відповісти у відведений час, кеш не буде створено, і додаток аварійно завершить роботу.
На щастя, кеш у Nette працює таким чином, що за наявності декількох одночасних запитів на один елемент, він генерується тільки першим потоком, інші чекають і потім використовують згенерований результат.

Приклад створення FileStorage:

```php
// сховищем буде каталог '/path/to/temp' на диску
$storage = new Nette\Caching\Storages\FileStorage('/path/to/temp');
```


MemcachedStorage .[#toc-memcachedstorage]
-----------------------------------------

Сервер [Memcached |https://memcached.org] - це високопродуктивна розподілена система зберігання даних, адаптером якої є `Nette\Caching\Storages\MemcachedStorage`. У конфігурації вкажіть IP-адресу та порт, якщо він відрізняється від стандартного 11211.

.[caution]
Потрібно PHP-розширення `memcached`.

```neon
services:
	cache.storage: Nette\Caching\Storages\MemcachedStorage('10.0.0.5')
```


MemoryStorage .[#toc-memorystorage]
-----------------------------------

`Nette\Caching\Storages\MemoryStorage` це сховище, яке зберігає дані в масиві PHP і, таким чином, втрачається при завершенні запиту.


SQLiteStorage .[#toc-memorystorage]
-----------------------------------

База даних SQLite та адаптер `Nette\Caching\Storages\SQLiteStorage` пропонують спосіб кешування в єдиному файлі на диску. У конфігурації буде вказано шлях до цього файлу.

.[caution]
Вимагає PHP-розширень `pdo` і `pdo_sqlite`.

```neon
services:
	cache.storage: Nette\Caching\Storages\SQLiteStorage('%tempDir%/cache.db')
```


DevNullStorage .[#toc-devnullstorage]
-------------------------------------

Особливою реалізацією сховища є `Nette\Caching\Storages\DevNullStorage`, яка насправді не зберігає дані взагалі. Тому вона підходить для тестування, якщо ми хочемо виключити вплив кешу.


Використання кешу в коді .[#toc-devnullstorage]
===============================================

При використанні кешування в коді у вас є два способи, як це зробити. Перший полягає в тому, що ви отримуєте об'єкт сховища, передаючи його за допомогою [впровадження залежностей |dependency-injection:passing-dependencies], а потім створюєте об'єкт `Cache`:

```php
use Nette;

class ClassOne
{
	private Nette\Caching\Cache $cache;

	public function __construct(Nette\Caching\Storage $storage)
	{
		$this->cache = new Nette\Caching\Cache($storage, 'my-namespace');
	}
}
```

Другий спосіб полягає в тому, що ви отримуєте об'єкт зберігання `Cache`:

```php
class ClassTwo
{
	public function __construct(
		private Nette\Caching\Cache $cache,
	) {
	}
}
```

Потім об'єкт `Cache` створюється безпосередньо в конфігурації наступним чином:

```neon
services:
	- ClassTwo( Nette\Caching\Cache(namespace: 'my-namespace') )
```


Журнал .[#toc-zurnal]
=====================

Nette зберігає теги та пріоритети в так званому журналі. За замовчуванням для цього використовуються SQLite і файл `journal.s3db`. Крім того, **потрібні PHP-розширення `pdo` і `pdo_sqlite`**.

Ви можете змінити журнал у конфігурації:

```neon
services:
	cache.journal: MyJournal
```


Послуги з проведення розслідувань .[#toc-di-services]
=====================================================

Ці сервіси додаються до контейнера DI:

| Назва | Тип | Опис
|----------------------------------------------------------
| `cache.journal` | [api:Nette\Caching\Storages\Journal] | журнал
| `cache.storage` | [api:Nette\Caching\Storage] | репозиторій


Вимкнення кешу .[#toc-turning-off-cache]
========================================

Один із способів вимкнути кешування в додатку - встановити для сховища значення [DevNullStorage |#DevNullStorage]:

```neon
services:
	cache.storage: Nette\Caching\Storages\DevNullStorage
```

Це налаштування не впливає на кешування шаблонів у Latte або контейнері DI, оскільки ці бібліотеки не використовують сервіси nette/caching і керують своїм кешем самостійно. Крім того, їх кеш [не потрібно |nette:troubleshooting#how-to-disable-cache-during-development] вимикати в режимі розробки.


{{leftbar: nette:@menu-topics}}