merged branch GromNaN/doc-alternative-session-storage (PR #275)

Commits
-------

4a5c10e1 Grammar
e1264470 Fix URL to Symfony API doc
7a176af4 Cookbook recipe on how to use PdoSessionStorage

Discussion
----------

Cookbook recipe on how to use PdoSessionStorage

Related to this issue #254

---------------------------------------------------------------------------

by igorw at 2012-03-09T16:23:11Z

👍

doc/cookbook/index.rst

@@ -9,6 +9,7 @@ The cookbook section contains recipes for solving specific problems.
 
     json_request_body
     translating_validation_messages
+    session_storage
 
 Recipes
 -------
@@ -18,3 +19,5 @@ Recipes
   the request body.
 
 * :doc:`Translating Validation Messages<translating_validation_messages>`.
+
+* :doc:`How to use PdoSessionStorage to store sessions in the database <session_storage>`.

doc/cookbook/session_storage.rst

+How to use PdoSessionStorage to store sessions in the database
+==============================================================
+
+By default, the :doc:`SessionServiceProvider <providers/session>` writes session
+information in files with the NativeFileSessionStorage of Symfony2. Most medium
+to large websites use a database to store the session values instead of files,
+because databases are easier to use and scale in a multi-webserver environment.
+
+Symfony2 has multiple session storage solutions. For database, its called
+`PdoSessionStorage <http://api.symfony.com/master/Symfony/Component/HttpFoundation/Session/Storage/PdoSessionStorage.html>
+To use it, you need to replace the ``session.storage`` service in your application.
+
+Example
+-------
+
+    use Symfony\Component\HttpFoundation\Session\Storage\PdoSessionStorage;
+
+    $app->register(new Silex\Provider\SessionServiceProvider());
+
+    $app['pdo.dsn'] = 'mysql:dbname=mydatabase';
+    $app['pdo.user'] = 'myuser';
+    $app['pdo.password'] = 'mypassword';
+
+    $app['pdo.db_options'] = array(
+        'db_table'      => 'session',
+        'db_id_col'     => 'session_id',
+        'db_data_col'   => 'session_value',
+        'db_time_col'   => 'session_time',
+    );
+
+    $app['pdo'] = $app->share(function () use ($app) {
+        return new PDO(
+            $app['pdo.dsn'],
+            $app['pdo.user'],
+            $app['pdo.password']
+        );
+    });
+
+    $app['session.storage'] = $app->share(function () use ($app) {
+        return new PdoSessionStorage(
+            $app['pdo'],
+            $app['pdo.db_options'],
+            $app['session.storage.options']
+        );
+    });
+
+
+Database structure
+------------------
+
+PdoSessionStorage needs a database table with 3 columns:
+
+* ``session_id``: ID column (VARCHAR(255) or larger)
+* ``session_value``: Value column (TEXT or CLOB)
+* ``session_time``: Time column (INTEGER)
+
+Examples of SQL statements to create the session table on `Symfony2 cookbook
+<http://symfony.com/doc/current/cookbook/configuration/pdo_session_storage.html>`