Permalink
Browse files

feature #4609 Adding details about the changes to the PdoSessionHandl…

…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 committed Dec 29, 2014
2 parents 91f6f41 + 1e34823 commit aa88f99cfdf3b9807af372ab8b3ea4467942aebf
Showing with 104 additions and 47 deletions.
  1. +104 −47 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 <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
@@ -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):
<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>
@@ -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>
@@ -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
<!-- 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
--------------------------------------------
@@ -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
~~~~~
@@ -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
@@ -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
@@ -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,

0 comments on commit aa88f99

Please sign in to comment.