# Cloud Firestore Client - Class FirestoreSessionHandler (2.2.0-RC1)

2.2.0-RC1 2.1.0 (latest) 2.0.2-RC1 1.55.0 1.54.4 1.53.1 1.52.0 1.51.0 1.50.0 1.48.1 1.47.3 1.46.0 1.45.2 1.44.1 1.43.3 1.40.0 1.39.0 1.38.0 1.37.7 1.36.1 1.35.0 1.34.0 1.33.0 1.32.0 1.31.0 1.30.0 1.28.0 1.27.3 Reference documentation and code samples for the Cloud Firestore Client class FirestoreSessionHandler.

Custom session handler backed by Cloud Firestore.

Instead of storing the session data in a local file, this handler stores the
data in Firestore. The biggest benefit of doing this is the data can be
shared by multiple instances, making it suitable for cloud applications.

The downside of using Firestore is that write operations will cost you some
money, so it is highly recommended to minimize the write operations while
using this handler. In order to do so, keep the data in the session as
limited as possible; for example, it is ok to put only signed-in state and
the user id in the session with this handler. However, for example, it is
definitely not recommended that you store your application's whole undo
history in the session, because every user operation will cause a Firestore
write, potentially costing you a lot of money.

This handler doesn't provide pessimistic lock for session data. Instead, it
uses a Firestore transaction for data consistency. This means that if
multiple requests are modifying the same session data simultaneously, there
will be more probablity that some of the `write` operations will fail.

If you are building an AJAX application which may issue multiple requests
to the server, please design your session data carefully in order to avoid
possible data contentions. Also please see the 2nd example below for how to
properly handle errors on `write` operations.

The handler stores data in a collection formatted from the values of
session.save_path and session.name, which can be customized using the
$collectionNameTemplate option. This isolates the session data from your
application data. It creates documents in the specified collection where the
ID is the session ID. By default, it does nothing on gc for reducing the
cost. Pass a positive value up to 500 for $gcLimit option to delete entities
in gc.

The first example automatically writes the session data. It's handy, but
the code doesn't stop even if it fails to write the session data, because
the `write` happens when the code exits. If you want to know whether the
session data is correctly written to Firestore, you need to call
`session_write_close()` explicitly and then handle `E_USER_WARNING`
properly. See the second example for a demonstration.

Example:

    use Google\Cloud\Firestore\FirestoreClient;

    $firestore = new FirestoreClient();

    $handler = $firestore->sessionHandler();

    session_set_save_handler($handler, true);
    session_save_path('sessions');
    session_start();

    // Then write and read the $_SESSION array.
    $_SESSION['name'] = 'Bob';
    echo $_SESSION['name'];

    // Session handler with error handling:
    use Google\Cloud\Firestore\FirestoreClient;

    $firestore = new FirestoreClient();

    $handler = $firestore->sessionHandler();
    session_set_save_handler($handler, true);
    session_save_path('sessions');
    session_start();

    // Then read and write the $_SESSION array.
    $_SESSION['name'] = 'Bob';

    function handle_session_error($errNo, $errStr, $errFile, $errLine) {
        // We throw an exception here, but you can do whatever you need.
        throw new RuntimeException(
            "$errStr in $errFile on line $errLine",
            $errNo
        );
    }
    set_error_handler('handle_session_error', E_USER_WARNING);

    // If `write` fails for any reason, an exception will be thrown.
    session_write_close();
    restore_error_handler();

    // You can still read the $_SESSION array after closing the session.
    echo $_SESSION['name'];

## Namespace

Google \\ Cloud \\ Firestore

## Methods

### __construct

Create a custom session handler backed by Cloud Firestore.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `firestoreClient` | `https://docs.cloud.google.com/php/docs/reference/cloud-firestore/latest/V1.Client.FirestoreClient` A FirestoreClient instance. |
| `valueMapper` | `ValueMapper` A Firestore Value Mapper. |
| `projectId` | `string` The current project id. |
| `database` | `string` The database id. |
| `options` | `array` Configuration Options. |
| `↳ gcLimit` | `int` The number of entities to delete in the garbage collection. Values larger than 500 will be limited to 500. **Defaults to** `0`, indicating garbage collection is disabled by default. |
| `↳ collectionNameTemplate` | `string` A sprintf compatible template for formatting the collection name where sessions will be stored. The template receives two values, the first being the save path and the latter being the session name. |
| `↳ begin` | `array` Configuration options for beginTransaction. |
| `↳ commit` | `array` Configuration options for commit. |
| `↳ rollback` | `array` Configuration options for rollback. |
| `↳ read` | `array` Configuration options for read. |
| `↳ query` | `array` Configuration options for runQuery. |

### open

Start a session, by getting the Firebase collection from $savePath.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `savePath` | `string` The value of `session.save_path` setting will be used in the Firestore collection ID. |
| `sessionName` | `string` The value of `session.name` setting will be used in the Firestore collection ID. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `bool` |   |

### close

Close the transaction and commit any changes.

### read

Read the session data from Cloud Firestore.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `id` | `string` Identifier used for the session. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `string` |   |

### write

Write the session data to Cloud Firestore.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `id` | `string` Identifier used for the session. |
| `data` | `string` The session data to write to the Firestore document. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `bool` |   |

### destroy

Delete the session data from Cloud Firestore.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `id` | `string` Identifier used for the session |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `bool` |   |

### gc

Delete the old session data from Cloud Firestore.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `maxlifetime` | `int` Remove all session data older than this number in seconds. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `int|bool` |   |