PHPORM-174 Add doc for cache and locks

docs/cache.txt

@@ -0,0 +1,234 @@
+.. _laravel-queues:
+
+===============
+Cache and Locks
+===============
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: php framework, cache, lock, code example
+
+Configuration
+-------------
+
+In order to use MongoDB as backend for `Laravel Cache and Locks <https://laravel.com/docs/{+laravel-docs-version+}/cache>`__,
+add a store configuration using the ``mongodb`` driver in ``config/cache.php``:
+
+.. code-block:: php
+
+   'stores' => [
+       'mongodb' => [
+           'driver' => 'mongodb',
+           'connection' => 'mongodb',
+           'collection' => 'cache',
+           'lock_connection' => 'mongodb',
+           'lock_collection' => 'cache_locks',
+           'lock_lottery' => [2, 100],
+           'lock_timeout' => 86400,
+       ],
+   ],
+
+The following table describes a list of cache and lock options
+and their default values:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 75
+
+   * - Setting
+     - Description
+
+   * - ``driver``
+     - **Required**. Specifies the lock driver to use. Must be ``mongodb``.
+
+   * - ``connection``
+     - **Required**. The database connection to use to store cache items. It must be a ``mongodb`` connection.
+
+   * - ``collection``
+     - Default ``cache``. Name of the MongoDB collection to store cache items.
+
+   * - ``lock_connection``
+     - Default to the cache ``connection``. The database connection to use to store locks. It must be a ``mongodb`` connection.
+
+   * - ``lock_collection``
+     - Default ``cache_locks``. Name of the MongoDB collection to store locks.
+
+   * - ``lock_lottery``
+     - Default ``[2, 100]``. Probability [chance, total] of pruning expired cache items. Set to [0, 0] to disable
+
+   * - ``lock_timeout``
+     - Default ``86400``. Time-to-live of the locks in seconds
+
+
+Setup auto-expiration indexes
+-----------------------------
+
+The :manual:`TTL indexes </core/index-ttl/>` integrated into MongoDB automatically
+delete documents when they have expired. Their use is optional with the ``mongodb``
+driver, but recommended as they provide better performance by delegating the
+deletion of expired documents to MongoDB instead of requiring the application to
+perform this task randomly.
+
+The best way is to create the indexes with a migration calling the methods
+``createTTLIndex()`` provided by both the cache and the lock stores:
+
+.. literalinclude:: /includes/cache/migration.php
+   :language: php
+   :emphasize-lines: 11,12
+   :dedent:
+
+Then run the migration:
+
+.. code-block:: none
+
+   $ php artisan migrate
+
+Alternatively, the index can be created using :mdb-shell:`MongoDB Shell <>` (``mongosh``):
+
+.. code-block:: ts
+
+   db.cache.createIndex(
+     /* Field that holds the expiration date */
+     { expires_at: 1 },
+     /* Delay to remove items after expiration */
+     { expireAfterSeconds: 0 }
+   )
+
+If you use Locks, disable ``lock_lottery`` by setting the probability to ``0``:
+
+.. code-block:: php
+   :highlightLines: [4]
+
+   'stores' => [
+       'mongodb' => [
+           'driver' => 'mongodb',
+           'connection' => 'mongodb',
+           'lock_lottery' => [0, 100], // Disabled
+       ],
+   ],
+
+Using MongoDB cache
+-------------------
+
+The Laravel cache can be used to store any serializable data using the facade
+``Illuminate\Support\Facades\Cache``:
+
+In this example:
+- Gets the cache repository with the store ``mongodb``,
+- Tries to read and return the cache item named ``foo``,
+- If missing, calls the closure to compute the value, store this value forever and return it.
+
+..code-block:: php
+
+   use Illuminate\Support\Facades\Cache;
+
+   $value = Cache::store('mongodb')->get('foo', function () {
+       return [1, 2, 3];
+   });
+
+The default, cached objects do not expire. It is possible to define an expiry time.
+
+..code-block:: php
+
+   Cache::store('mongodb')->set('foo', 'abc', '1 day');
+
+Incrementing and decrementing a value is also supported, the value must
+be initialized before. The following example initialize the counter to ``3``,
+adds 5 and removes 2.
+
+..code-block:: php
+
+   Cache::store('mongodb')->set('counter', 3);
+   Cache::store('mongodb')->increment('counter', 5);
+   Cache::store('mongodb')->decrement('counter', 2);
+
+.. note::
+
+   {+odm-short+} supports incrementing and decrementing with integer and float values.
+
+Configuring MongoDB as default cache
+------------------------------------
+
+To use the ``mongodb`` store by default, change the default store in
+``config/cache.php``:
+
+.. code-block:: php
+   :emphasize-lines: 2
+
+   return [
+       'default' => env('CACHE_STORE', 'mongodb'),
+
+       'stores' => [
+           'mongodb' => [
+               'driver' => 'mongodb',
+               'connection' => 'mongodb',
+           ],
+       ],
+   ];
+
+The variable ``CACHE_STORE`` could be set in your environment or in
+the ``.env`` file. Update or remove it:
+
+.. code-block:: none
+
+   CACHE_STORE=mongodb
+
+Then you can use the ``Illuminate\Support\Facades\Cache`` facade and
+automatic injection:
+
+.. code-block:: php
+
+   use Illuminate\Support\Facades\Cache;
+
+   Cache::get('foo', 5);
+
+This example shows how to use automatic injection of the cache
+manager, using the default store. It is a controller that
+increments a counter each time it is invoked.
+
+
+.. code-block:: php
+   :emphasize-lines: 9,14
+
+   <?php
+
+   namespace App\Http\Controllers;
+
+   use App\Contracts\CacheManager;
+
+   class CountController extends Controller
+   {
+       public function __construct(
+           private CacheManager $cache,
+       ) {}
+
+       public function hit(): int
+       {
+           return $this->cache->increment('counter');
+       }
+   }
+
+
+Using MongoDB Lock
+------------------
+
+Atomic locks allow for the manipulation of distributed locks without worrying
+about race conditions.
+
+..code-block:: php
+   :emphasize-lines: 3
+
+   use Illuminate\Support\Facades\Cache;
+
+   $lock = Cache::store('mongodb')->lock('foo', 10);
+
+   if ($lock->get()) {
+       // Lock acquired for 10 seconds...
+
+       $lock->release();
+   }
+
+

docs/includes/cache/migration.php

@@ -0,0 +1,14 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Support\Facades\Cache;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        $store = Cache::store('mongodb');
+        $store->createTTLIndex();
+        $store->lock('')->createTTLIndex();
+    }
+};