diff --git a/cookbook/configuration/pdo_session_storage.rst b/cookbook/configuration/pdo_session_storage.rst index e14ecf0ad74..a388d759133 100644 --- a/cookbook/configuration/pdo_session_storage.rst +++ b/cookbook/configuration/pdo_session_storage.rst @@ -4,6 +4,12 @@ How to Use PdoSessionHandler to Store Sessions in the Database ============================================================== +.. caution:: + + There was a backwards-compatibility break in Symfony 2.6: the database + schema changed slightly. See :ref:`Symfony 2.6 Changes ` + for details. + The default Symfony session storage writes the session information to file(s). 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 @@ -24,18 +30,11 @@ configuration format of your choice): # ... handler_id: session.handler.pdo - parameters: - pdo.db_options: - db_table: session - db_id_col: session_id - db_data_col: session_data - db_time_col: session_time - db_lifetime_col: session_lifetime - services: pdo: class: PDO arguments: + # see below for how to use your existing DB config dsn: "mysql:dbname=mydatabase" user: myuser password: mypassword @@ -44,7 +43,7 @@ configuration format of your choice): session.handler.pdo: class: Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler - arguments: ["@pdo", "%pdo.db_options%"] + arguments: ["@pdo"] .. code-block:: xml @@ -53,16 +52,6 @@ configuration format of your choice): - - - session - session_id - session_data - session_time - session_lifetime - - - mysql:dbname=mydatabase @@ -76,7 +65,6 @@ configuration format of your choice): - %pdo.db_options% @@ -94,14 +82,6 @@ configuration format of your choice): ), )); - $container->setParameter('pdo.db_options', array( - 'db_table' => 'session', - 'db_id_col' => 'session_id', - 'db_data_col' => 'session_data', - 'db_time_col' => 'session_time', - 'db_lifetime_col' => 'session_lifetime', - )); - $pdoDefinition = new Definition('PDO', array( 'mysql:dbname=mydatabase', 'myuser', @@ -112,15 +92,74 @@ configuration format of your choice): $storageDefinition = new Definition('Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler', array( new Reference('pdo'), - '%pdo.db_options%', )); $container->setDefinition('session.handler.pdo', $storageDefinition); -* ``db_table``: The name of the session table in your database -* ``db_id_col``: The name of the id column in your session table (VARCHAR(128)) -* ``db_data_col``: The name of the value column in your session table (BLOB) -* ``db_time_col``: The name of the time column in your session table (INTEGER) -* ``db_lifetime_col``: The name of the lifetime column in your session table (INTEGER) +Configuring the Table and Column Names +-------------------------------------- + +This will expect a ``sessions`` table with a number of different columns. +The table name, and all of the column names, can be configured by passing +a second array argument to ``PdoSessionHandler``: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + services: + # ... + session.handler.pdo: + class: Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler + arguments: + - "@pdo" + - { 'db_table': 'sessions'} + + .. code-block:: xml + + + + + + + sessions + + + + + .. code-block:: php + + // app/config/config.php + + use Symfony\Component\DependencyInjection\Definition; + // ... + + $storageDefinition = new Definition( + 'Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler', + array( + new Reference('pdo'), + array('db_table' => 'session') + ) + ); + $container->setDefinition('session.handler.pdo', $storageDefinition); + +.. versionadded:: 2.6 + The ``db_lifetime_col`` was introduced in Symfony 2.6. Prior to 2.6, + this column did not exist. + +The following things can be configured: + +* ``db_table``: (default ``session``) The name of the session table in your + database; +* ``db_id_col``: (default ``sess_id``) The name of the id column in your + session table (VARCHAR(128)); +* ``db_data_col``: (default ``sess_data``) The name of the value column in + your session table (BLOB); +* ``db_time_col``: (default ``sess_time``) The name of the time column in + your session table (INTEGER); +* ``db_lifetime_col``: (default ``sess_lifetime``) The name of the lifetime + column in your session table (INTEGER). Sharing your Database Connection Information -------------------------------------------- @@ -163,6 +202,24 @@ of your project's data, you can use the connection settings from the Example SQL Statements ---------------------- +.. _pdo-session-handle-26-changes: + +.. sidebar:: Schema Changes needed when Upgrading to Symfony 2.6 + + If you use the ``PdoSessionHandler`` prior to Symfony 2.6 and upgrade, you'll + need to make a few changes to your session table: + + * A new session lifetime (``sess_lifetime`` by default) integer column + needs to be added; + * The data column (``sess_data`` by default) needs to be changed to a + BLOG type. + + Check the SQL statements below for more details. + + To keep the old (2.5 and earlier) functionality, change your class name + to use ``LegacyPdoSessionHandler`` instead of ``PdoSessionHandler`` (the + legacy class was added in Symfony 2.6.2). + MySQL ~~~~~ @@ -172,10 +229,10 @@ following (MySQL): .. code-block:: sql CREATE TABLE `session` ( - `session_id` VARBINARY(128) NOT NULL PRIMARY KEY, - `session_data` BLOB NOT NULL, - `session_time` INTEGER UNSIGNED NOT NULL, - `session_lifetime` MEDIUMINT NOT NULL + `sess_id` VARBINARY(128) NOT NULL PRIMARY KEY, + `sess_data` BLOB NOT NULL, + `sess_time` INTEGER UNSIGNED NOT NULL, + `sess_lifetime` MEDIUMINT NOT NULL ) COLLATE utf8_bin, ENGINE = InnoDB; PostgreSQL @@ -186,10 +243,10 @@ For PostgreSQL, the statement should look like this: .. code-block:: sql CREATE TABLE session ( - session_id VARCHAR(128) NOT NULL PRIMARY KEY, - session_data BYTEA NOT NULL, - session_time INTEGER NOT NULL, - session_lifetime INTEGER NOT NULL + sess_id VARCHAR(128) NOT NULL PRIMARY KEY, + sess_data BYTEA NOT NULL, + sess_time INTEGER NOT NULL, + sess_lifetime INTEGER NOT NULL ); Microsoft SQL Server @@ -200,12 +257,12 @@ For MSSQL, the statement might look like the following: .. code-block:: sql CREATE TABLE [dbo].[session]( - [session_id] [nvarchar](255) NOT NULL, - [session_data] [ntext] NOT NULL, - [session_time] [int] NOT NULL, - [session_lifetime] [int] NOT NULL, + [sess_id] [nvarchar](255) NOT NULL, + [sess_data] [ntext] NOT NULL, + [sess_time] [int] NOT NULL, + [sess_lifetime] [int] NOT NULL, PRIMARY KEY CLUSTERED( - [session_id] ASC + [sess_id] ASC ) WITH ( PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF,