Skip to content

Commit

Permalink
feature #4609 Adding details about the changes to the PdoSessionHandl…
Browse files Browse the repository at this point in the history 
…er in 2.6 (weaverryan)

This PR was merged into the 2.6 branch.

Discussion
----------

Adding details about the changes to the PdoSessionHandler in 2.6

Hi guys!

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | yes symfony/symfony#12833
| Applies to    | 2.6+
| Fixed tickets | n/a

This follows #4557.

This adds more details about the table schema changes to the PdoSessionHandler in 2.6. I also made some improvements (not showing all the extra configuration by default), which I'll backport to 2.3 after this is accepted.

Thanks!

Commits
-------

1e34823 Fixes thanks to comments and a new note about the LegacyPdoSessionHandler
2f974bb Updating statements, now that we're not overriding the names
fd8b552 Adding details about the changes to the PdoSessionHandler in 2.6
  • Loading branch information
@weaverryan
weaverryan committed Dec 29, 2014
2 parents 91f6f41 + 1e34823 commit aa88f99
Showing 1 changed file with 104 additions and 47 deletions.
151 changes: 104 additions & 47 deletions cookbook/configuration/pdo_session_storage.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <pdo-session-handle-26-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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -53,16 +52,6 @@ configuration format of your choice):
<framework:session handler-id="session.handler.pdo" cookie-lifetime="3600" auto-start="true"/>
</framework:config>
<parameters>
<parameter key="pdo.db_options" type="collection">
<parameter key="db_table">session</parameter>
<parameter key="db_id_col">session_id</parameter>
<parameter key="db_data_col">session_data</parameter>
<parameter key="db_time_col">session_time</parameter>
<parameter key="db_lifetime_col">session_lifetime</parameter>
</parameter>
</parameters>
<services>
<service id="pdo" class="PDO">
<argument>mysql:dbname=mydatabase</argument>
Expand All @@ -76,7 +65,6 @@ configuration format of your choice):
<service id="session.handler.pdo" class="Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler">
<argument type="service" id="pdo" />
<argument>%pdo.db_options%</argument>
</service>
</services>
Expand All @@ -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',
Expand All @@ -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
<!-- app/config/config.xml -->
<services>
<service id="session.handler.pdo"
class="Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler">
<argument type="service" id="pdo" />
<argument type="collection">
<argument key="db_table">sessions</argument>
</argument>
</service>
</services>
.. 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
--------------------------------------------
Expand Down Expand Up @@ -164,6 +203,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
~~~~~

Expand All @@ -173,10 +230,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
Expand All @@ -187,10 +244,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
Expand All @@ -201,12 +258,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,
Expand Down

0 comments on commit aa88f99

Please sign in to comment.