feature #4907 Adjustments to PDO Session storage page (kbond)

This PR was merged into the 2.6 branch.

Discussion
----------

Adjustments to PDO Session storage page

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | 2.6+
| Fixed tickets | #4609

1. Adds a note about the issues with exceeding the max `BLOB` size for mysql - do the other DBMS's have this issue?
2. Remove `PDO` service from example and has `PdoSessionHandler` connect lazily to the db.
3. Make `session.handler.pdo` private

Commits
-------

e0996eb Add note about max blob size
e5d7936 Change PdoSessionHandler to lazy connection

Author: weaverryan

cookbook/configuration/pdo_session_storage.rst

@@ -31,19 +31,12 @@ configuration format of your choice):
                 handler_id: session.handler.pdo
 
         services:
-            pdo:
-                class: PDO
-                arguments:
-                    # see below for how to use your existing DB config
-                    dsn:      "mysql:dbname=mydatabase"
-                    user:     myuser
-                    password: mypassword
-                calls:
-                    - [setAttribute, [3, 2]] # \PDO::ATTR_ERRMODE, \PDO::ERRMODE_EXCEPTION
-
             session.handler.pdo:
                 class:     Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler
-                arguments: ["@pdo"]
+                public:    false
+                arguments:
+                    - "mysql:dbname=mydatabase"
+                    - { db_username: myuser, db_password: mypassword }
 
     .. code-block:: xml
 
@@ -53,18 +46,12 @@ configuration format of your choice):
         </framework:config>
 
         <services>
-            <service id="pdo" class="PDO">
-                <argument>mysql:dbname=mydatabase</argument>
-                <argument>myuser</argument>
-                <argument>mypassword</argument>
-                <call method="setAttribute">
-                    <argument type="constant">PDO::ATTR_ERRMODE</argument>
-                    <argument type="constant">PDO::ERRMODE_EXCEPTION</argument>
-                </call>
-            </service>
-
-            <service id="session.handler.pdo" class="Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler">
-                <argument type="service" id="pdo" />
+            <service id="session.handler.pdo" class="Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler" public="false">
+                <argument>mysql:dbname=mydatabase</agruement>
+                <argument type="collection">
+                    <argument key="db_username">myuser</argument>
+                    <argument key="db_password">mypassword</argument>
+                </argument>
             </service>
         </services>
 
@@ -82,16 +69,9 @@ configuration format of your choice):
             ),
         ));
 
-        $pdoDefinition = new Definition('PDO', array(
-            'mysql:dbname=mydatabase',
-            'myuser',
-            'mypassword',
-        ));
-        $pdoDefinition->addMethodCall('setAttribute', array(\PDO::ATTR_ERRMODE, \PDO::ERRMODE_EXCEPTION));
-        $container->setDefinition('pdo', $pdoDefinition);
-
         $storageDefinition = new Definition('Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler', array(
-            new Reference('pdo'),
+            'mysql:dbname=mydatabase',
+            array('db_username' => 'myuser', 'db_password' => 'mypassword')
         ));
         $container->setDefinition('session.handler.pdo', $storageDefinition);
 
@@ -111,19 +91,21 @@ a second array argument to ``PdoSessionHandler``:
             # ...
             session.handler.pdo:
                 class:     Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler
+                public:    false
                 arguments:
-                    - "@pdo"
-                    - { 'db_table': 'sessions'}
+                    - "mysql:dbname=mydatabase"
+                    - { db_table: sessions, db_username: myuser, db_password: mypassword }
 
     .. 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" />
+            <service id="session.handler.pdo" class="Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler" public="false">
+                <argument>mysql:dbname=mydatabase</agruement>
                 <argument type="collection">
                     <argument key="db_table">sessions</argument>
+                    <argument key="db_username">myuser</argument>
+                    <argument key="db_password">mypassword</argument>
                 </argument>
             </service>
         </services>
@@ -135,13 +117,10 @@ a second array argument to ``PdoSessionHandler``:
         use Symfony\Component\DependencyInjection\Definition;
         // ...
 
-        $storageDefinition = new Definition(
-            'Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler',
-            array(
-                new Reference('pdo'),
-                array('db_table' => 'session')
-            )
-        );
+        $storageDefinition = new Definition('Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler', array(
+            'mysql:dbname=mydatabase',
+            array('db_table' => 'sessions', 'db_username' => 'myuser', 'db_password' => 'mypassword')
+        ));
         $container->setDefinition('session.handler.pdo', $storageDefinition);
 
 .. versionadded:: 2.6
@@ -177,27 +156,28 @@ of your project's data, you can use the connection settings from the
     .. code-block:: yaml
 
         services:
-            pdo:
-                class: PDO
+            session.handler.pdo:
+                class:     Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler
+                public:    false
                 arguments:
                     - "mysql:host=%database_host%;port=%database_port%;dbname=%database_name%"
-                    - "%database_user%"
-                    - "%database_password%"
+                    - { db_username: %database_user%, db_password: %database_password% }
 
     .. code-block:: xml
 
-        <service id="pdo" class="PDO">
-            <argument>mysql:host=%database_host%;port=%database_port%;dbname=%database_name%</argument>
-            <argument>%database_user%</argument>
-            <argument>%database_password%</argument>
+        <service id="session.handler.pdo" class="Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler" public="false">
+            <argument>mysql:host=%database_host%;port=%database_port%;dbname=%database_name%</agruement>
+            <argument type="collection">
+                <argument key="db_username">%database_user%</argument>
+                <argument key="db_password">%database_password%</argument>
+            </argument>
         </service>
 
     .. code-block:: php
 
-        $pdoDefinition = new Definition('PDO', array(
+        $storageDefinition = new Definition('Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler', array(
             'mysql:host=%database_host%;port=%database_port%;dbname=%database_name%',
-            '%database_user%',
-            '%database_password%',
+            array('db_username' => '%database_user%', 'db_password' => '%database_password%')
         ));
 
 Example SQL Statements
@@ -236,6 +216,13 @@ following (MySQL):
         `sess_lifetime` MEDIUMINT NOT NULL
     ) COLLATE utf8_bin, ENGINE = InnoDB;
 
+.. note::
+
+    A ``BLOB`` column type can only store up to 64 kb. If the data stored in
+    a user's session exceeds this, an exception may be thrown or their session
+    will be silently reset. Consider using a ``MEDIUMBLOB`` if you need more
+    space.
+
 PostgreSQL
 ~~~~~~~~~~