Added Cache::getOrSet()

docs/guide-ru/caching-data.md

@@ -11,8 +11,8 @@
 $data = $cache->get($key);
 
 if ($data === false) {
-
-    // $data нет в кэше, считаем с нуля.
+    // $data нет в кэше, вычисляем заново
+    $data = $this->calculateSomething();
 
     // Сохраняем значение $data в кэше. Данные можно получить в следующий раз.
     $cache->set($key, $data);
@@ -21,6 +21,33 @@ if ($data === false) {
 // Значение $data доступно здесь.
 ```
 
+Начиная с версии 2.0.11, [компонент кэширования](#cache-components) предоставляет метод
+[[yii\caching\Cache::getOrSet()|getOrSet()]], который упрощает код при получении, вычислении и сохранении данных.
+Приведённый ниже код делает в точности то же самое, что и код в предыдущем примере:
+
+```php
+$data = $cache->getOrSet($key, function () {
+    return $this->calculateSomething();
+});
+```
+
+Если в кэше есть данные по ключу `$key`, они будут сразу возвращены. 
+Иначе, будет вызвана переданная анонимная функция, вычисляющаяя значение, которое будет сохранено в кэш и возвращено
+из метода.
+
+В случае, когда анонимной функции требуются данные из внешней области видимости, можно передать их с помощью
+оператора `use`. Например:
+
+```php
+$user_id = 42;
+$data = $cache->getOrSet($key, function () use ($user_id) {
+    return $this->calculateSomething($user_id);
+});
+```
+
+> Note: В [[yii\caching\Cache::getOrSet()|getOrSet()]] можно передать срока действия и зависимости кэша.
+  Прочтите [Срок действия кэша](#cache-expiration) и [Зависимости кеша](#cache-dependencies) чтобы узнать больше.
+
 
 ## Компоненты кэширования <span id="cache-components"></span>
 
@@ -161,8 +188,8 @@ if ($data === false) {
 }
 ```
 
-Начиная с версии 2.0.11 вы можете изменить значение по умолчанию (бесконечность) для длительности кеширования задав
-[[yii\caching\Cache::$defaultDuration|defaultDuration]] в конфигурации компонента кеша. Таким образом, можно будет
+Начиная с версии 2.0.11 вы можете изменить значение по умолчанию (бесконечность) для длительности кэширования задав
+[[yii\caching\Cache::$defaultDuration|defaultDuration]] в конфигурации компонента кэша. Таким образом, можно будет
 не передавать значение `duration` в [[yii\caching\Cache::set()|set()]] каждый раз.
 
 ### Зависимости кэша <span id="cache-dependencies"></span>
@@ -231,7 +258,7 @@ $result = Customer::getDb()->cache(function ($db) {
  - `yii cache`: отображает список доступных кэширующих компонентов приложения
  - `yii cache/flush cache1 cache2`: очищает кэш в компонентах `cache1`, `cache2` (можно передать несколько названий
  компонентов кэширования, разделяя их пробелом)
- - `yii cache/flush-all`: очищает кэш во всех кеширующих компонентах приложения
+ - `yii cache/flush-all`: очищает кэш во всех кэширующих компонентах приложения
 
 > Info: Консольное приложение использует отдельный конфигурационный файл по умолчанию. Для получения должного
 результата, убедитесь, что в конфигурациях консольного и веб-приложения у вас одинаковые компоненты кэширования.
@@ -311,4 +338,4 @@ $result = $db->cache(function ($db) {
 
 Кэширование запросов не работает с результатами запросов, которые содержат обработчики ресурсов. Например, при использовании типа столбца `BLOB` в некоторых СУБД, в качестве результата запроса будет выведен ресурс обработчик данных столбца.
 
-Некоторые кэш хранилища имеют ограничение в размере данных. Например, Memcache ограничивает максимальный размер каждой записи до 1 Мб. Таким образом, если результат запроса превышает этот предел, данные не будут закешированы.
+Некоторые кэш хранилища имеют ограничение в размере данных. Например, Memcache ограничивает максимальный размер каждой записи до 1 Мб. Таким образом, если результат запроса превышает этот предел, данные не будут закэшированы.

docs/guide/caching-data.md

@@ -13,8 +13,8 @@ a [cache component](#cache-components):
 $data = $cache->get($key);
 
 if ($data === false) {
-
     // $data is not found in cache, calculate it from scratch
+    $data = $this->calculateSomething();
 
     // store $data in cache so that it can be retrieved next time
     $cache->set($key, $data);
@@ -23,6 +23,32 @@ if ($data === false) {
 // $data is available here
 ```
 
+Since version 2.0.11, [cache component](#cache-components) provides [[yii\caching\Cache::getOrSet()|getOrSet()]] method
+that simplifies code for data getting, calculating and storing. The following code does exactly the same as the 
+previous example:
+
+```php
+$data = $cache->getOrSet($key, function () {
+    return $this->calculateSomething();
+});
+```
+
+When cache has data associated with the `$key`, the cached value will be returned. 
+Otherwise, the passed anonymous function will be executed to calculate the value that will be cached and returned.
+
+If the anonymous function requires some data from the outer scope, you can pass it with the `use` statement.
+For example:
+
+```php
+$user_id = 42;
+$data = $cache->getOrSet($key, function () use ($user_id) {
+    return $this->calculateSomething($user_id);
+});
+```
+
+> Note: [[yii\caching\Cache::getOrSet()|getOrSet()]] method supports duration and dependencies as well. 
+  See [Cache Expiration](#cache-expiration) and [Cache Dependencies](#cache-dependencies) to know more.
+  
 
 ## Cache Components <span id="cache-components"></span>
 
@@ -118,6 +144,8 @@ All cache components have the same base class [[yii\caching\Cache]] and thus sup
   value will be returned if the data item is not found in the cache or is expired/invalidated.
 * [[yii\caching\Cache::set()|set()]]: stores a data item identified by a key in cache.
 * [[yii\caching\Cache::add()|add()]]: stores a data item identified by a key in cache if the key is not found in the cache.
+* [[yii\caching\Cache::getOrSet()|getOrSet()]]: retrieves a data item from cache with a specified key or executes passed
+  callback, stores return of the callback in a cache by a key and returns that data.  
 * [[yii\caching\Cache::multiGet()|multiGet()]]: retrieves multiple data items from cache with the specified keys.
 * [[yii\caching\Cache::multiSet()|multiSet()]]: stores multiple data items in cache. Each item is identified by a key.
 * [[yii\caching\Cache::multiAdd()|multiAdd()]]: stores multiple data items in cache. Each item is identified by a key.
@@ -128,7 +156,7 @@ All cache components have the same base class [[yii\caching\Cache]] and thus sup
 
 > Note: Do not cache a `false` boolean value directly because the [[yii\caching\Cache::get()|get()]] method uses
 `false` return value to indicate the data item is not found in the cache. You may put `false` in an array and cache
-this array instead to avoid this problem.
+this array instead to avoid this problem. 
 
 Some cache storage, such as MemCache, APC, support retrieving multiple cached values in a batch mode,
 which may reduce the overhead involved in retrieving cached data. The APIs [[yii\caching\Cache::multiGet()|multiGet()]]