DOCSP-45065: sessions documentation (#3254)

* DOCSP-45065: sessions documentation

* MW PR fixes 1

* JT tech review 1

* small fix error in build

docs/eloquent-models/schema-builder.txt

@@ -248,6 +248,8 @@ field:
 To learn more about index options, see :manual:`Options for All Index Types </reference/method/db.collection.createIndex/#options-for-all-index-types>`
 in the {+server-docs-name+}.
 
+.. _laravel-schema-builder-special-idx:
+
 Create Sparse, TTL, and Unique Indexes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/index.txt

@@ -21,6 +21,7 @@
    Query Builder </query-builder>
    User Authentication </user-authentication>
    Cache & Locks </cache>
+   HTTP Sessions </sessions>
    Queues </queues>
    Transactions </transactions>
    GridFS Filesystems </filesystems>
@@ -84,6 +85,7 @@ see the following content:
 - :ref:`laravel-aggregation-builder`
 - :ref:`laravel-user-authentication`
 - :ref:`laravel-cache`
+- :ref:`laravel-sessions`
 - :ref:`laravel-queues`
 - :ref:`laravel-transactions`
 - :ref:`laravel-filesystems`

docs/query-builder.txt

@@ -678,7 +678,7 @@ a query:
    :end-before: end options
 
 The query builder accepts the same options that you can set for
-the :phpmethod:`find() <phpmethod.MongoDB\\Collection::find()>` method in the
+the :phpmethod:`MongoDB\Collection::find()` method in the
 {+php-library+}. Some of the options to modify query results, such as
 ``skip``, ``sort``, and ``limit``, are settable directly as query
 builder methods and are described in the

docs/sessions.txt

@@ -0,0 +1,102 @@
+.. _laravel-sessions:
+
+=============
+HTTP Sessions
+=============
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: php framework, odm, cookies, multiple requests
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to set up HTTP sessions by
+using {+odm-long+}. Sessions allow your application to store information
+about a user across multiple server requests. Your application stores this
+information in a specified location that it can access in future
+requests that the user makes. The session driver in {+odm-long+} uses
+the ``MongoDbSessionHandler`` class from the Symfony framework to store
+session information.
+
+To learn more about support for sessions, see `HTTP Session
+<https://laravel.com/docs/{+laravel-docs-version+}/session>`__ in the
+Laravel documentation.
+
+Register a Session
+------------------
+
+Before you can register a session, you must configure your connection to
+MongoDB in your application's ``config/database.php`` file. To learn how
+to set up this connection, see the
+:ref:`laravel-quick-start-connect-to-mongodb` step of the Quick Start
+guide.
+
+Next, you can select the session driver and connection in one of the
+following ways:
+
+1. In an ``.env`` file, by setting the following environment variables:
+
+   .. code-block:: ini
+      :caption: .env
+
+      SESSION_DRIVER=mongodb
+      # Optional, this is the default value
+      SESSION_CONNECTION=mongodb
+
+#. In the ``config/session.php`` file, as shown in the following code:
+
+   .. code-block:: php
+      :caption: config/session.php
+
+      <?php return [
+          'driver' => 'mongodb',     // Required
+          'connection' => 'mongodb', // Database connection name, default is "mongodb"
+          'table' => 'sessions',     // Collection name, default is "sessions"
+          'lifetime' => null,        // TTL of session in minutes, default is 120
+          'options' => []            // Other driver options
+      ];
+
+The following list describes other driver options that you can set in
+the ``options`` array:
+
+- ``id_field``: Field name for storing the session ID (default: ``_id``)
+- ``data_field``: Field name for storing the session data (default: ``data``)
+- ``time_field``: Field name for storing the timestamp (default: ``time``)
+- ``expiry_field``: Field name for storing the expiry-timestamp (default: ``expires_at``)
+- ``ttl``: Time to live in seconds
+
+We recommend that you create an index on the ``expiry_field`` field for
+garbage collection. You can also automatically expire sessions in the
+database by creating a TTL index on the collection that stores session
+information.
+
+You can use the ``Schema`` builder to create a TTL index, as shown in
+the following code:
+
+.. code-block:: php
+
+   Schema::create('sessions', function (Blueprint $collection) {
+       $collection->expire('expiry_field', 0);
+   });
+
+Setting the time value to ``0`` in the index
+definition instructs MongoDB to expire documents at the clock time
+specified in the ``expiry_field`` field.
+
+To learn more about using the ``Schema`` builder to create indexes, see
+the :ref:`laravel-schema-builder-special-idx` section of the Schema
+Builder guide.
+
+To learn more about TTL indexes, see :manual:`Expire Data from
+Collections by Setting TTL </tutorial/expire-data/>` in the
+{+server-docs-name+}.