diff --git a/changelog.rst b/changelog.rst index f91895f535c..56bd10cef6f 100644 --- a/changelog.rst +++ b/changelog.rst @@ -17,78 +17,6 @@ documentation. Do you also want to participate in the Symfony Documentation? Take a look at the ":doc:`/contributing/documentation/overview`" article. -October, 2016 -------------- - -New Documentation -~~~~~~~~~~~~~~~~~ - -* `#6958 `_ [FrameworkBundle] add support for prioritizing form type extension tags (dmaicher) -* `#7074 `_ [PhpUnitBridge] Doc for @expectedDeprecation & new configuration env vars (nicolas-grekas) -* `#6947 `_ [Cache] Add chapter about invalidation, tags, etc. (nicolas-grekas) -* `#7021 `_ [ServiceContainer] Remove implementation details of private services (lemoinem) -* `#7023 `_ Added useful debug commands in the debug documentation (hiddewie) -* `#6946 `_ [VarDumper] Adding semantics with metadata (nicolas-grekas) -* `#6949 `_ Update ProgressBar docs with regress information (jameshalsall) -* `#7019 `_ [Framework] Update link-to-source mapping definition (nicolas-grekas) -* `#6938 `_ Document new utf8 option of Routing component (mickaelandrieu) -* `#6932 `_ Explain the limitations of the custom messages in UniqueEntity (javiereguiluz) -* `#6876 `_ Updated single command How to (mickaelandrieu) -* `#6870 `_ [Debug] Added configuration reference for new debug options (lyrixx) -* `#6783 `_ Routing: add explanation for the "_fragment" parameter (alexislefebvre) - -Fixed Documentation -~~~~~~~~~~~~~~~~~~~ - -* `#7049 `_ Fix the platform.sh builds (wouterj) - -Minor Documentation Changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -* `#7090 `_ Remove suggestion to change the `.class` parameters (mpdude) -* `#7095 `_ Also mention "hasXXX" methods as validation targets (mpdude) -* `#7091 `_ A bracket was missed (hpatoio) -* `#7097 `_ link to specific HTTP Cache RFC (snoek09) -* `#7098 `_ Improved Redirecting paragraph of Testing page (ShinDarth) -* `#7100 `_ Update birthday.rst (angyvolin) -* `#7020 `_ Added jQuery symfony-collection plugin to Form collection docs (hiddewie) -* `#7086 `_ Update bug documentation input console /console/input.rst (Quiss) -* `#7085 `_ Update custom_authentication_provider.rst (BatsaxIV) -* `#7083 `_ update github example (hootlex) -* `#7082 `_ Update metadata.rst (fberthereau) -* `#7078 `_ Simple typo fix (Renrhaf) -* `#7077 `_ remove caution message (snoek09) -* `#7073 `_ Accept only array in TagAwareAdapter::invalidateTags() (Koc) -* `#7048 `_ [#6938] tweak the wording a bit (xabbuh) -* `#7061 `_ Change link to docs instead repo (mik-laj) -* `#7066 `_ Remove erroneous placeholder text (regularjack) -* `#7068 `_ Remove double spaces in some YAML configuration (michaelperrin) -* `#7069 `_ use FCQN to reference the form type in add() (xabbuh) -* `#6785 `_ Twig reference: Add links from routing functions to special routing parameters (alexislefebvre) -* `#7043 `_ [Serializer] Move the see also block in the Learn More section (dunglas) -* `#7035 `_ Redirect /form to /forms for consistency (wouterj) -* `#7054 `_ Fix IS_AUTHENTICATED_FULLY annotation (mschobner) -* `#7044 `_ Add Nginx configuration to environment variables (peterkokot) -* `#6928 `_ Update the Apache Router article to deprecate it entirely (javiereguiluz) -* `#7053 `_ Minor improvements for the contribution guide (javiereguiluz) -* `#7050 `_ use single quotes for YAML strings (snoek09) -* `#7047 `_ Fix typo in doctrine.rst (to manage) (lacyrhoades) -* `#7046 `_ Fix incorrect callback validation example (mvar) -* `#7034 `_ Changed RFC links from drafts to proposed standarts (a-ast) -* `#7038 `_ Remove a dead link to the old PR header (dunglas) -* `#7037 `_ Fix a typo in the serializer doc (dunglas) -* `#7036 `_ Fix 404 error link for American English Oxford Dictionary (peterkokot) -* `#6980 `_ Use strict comparison (greg0ire) -* `#7025 `_ Update buisness-logic (zairigimad) -* `#7027 `_ Remove dash prefix from route name (bocharsky-bw) -* `#7028 `_ A few minor tweaks (bocharsky-bw) -* `#7029 `_ refer to Symfony instead of Symfony2 (snoek09) -* `#7031 `_ Capitalize the time designator (simoheinonen) -* `#7018 `_ Reorder arguments: $request as the first argument (bocharsky-bw) -* `#7014 `_ Add a note about Filesystem:mkdir behavior (mickaelandrieu) -* `#6886 `_ Update controllers.rst (asandjivy) - - September, 2016 --------------- @@ -147,7 +75,7 @@ Minor Documentation Changes * `#6911 `_ Article about logout. (BorodinDemid) * `#6923 `_ Clarify by_reference use (jxmallett) * `#6942 `_ Updated the "Build a Login Form" article (javiereguiluz) -* `#6931 `_ [Guard] Improve clarity using the configured provider (chalasr) +* `#6931 `_ [Guard] Improve clarity using the configured provider (chalasr) * `#6933 `_ Misplaced paragraph about placeholders in routing.rst (antoin-m) * `#6930 `_ Use Terminal lexer for console examples (wouterj) * `#6893 `_ Update entity_provider.rst (asandjivy) @@ -158,7 +86,7 @@ Minor Documentation Changes * `#6983 `_ Update voters.rst (seferov) * `#6986 `_ Fixed directory name typo (JoeThielen) * `#6988 `_ fix link role syntax (xabbuh) -* `#6960 `_ [Reference] add back the option's description (xabbuh) +* `#6960 `_ [Reference] add back the option's description (xabbuh) * `#6987 `_ Update input.rst (adyassine) * `#6974 `_ Fix minor typo in security chapter How to Build a Traditional Login Form (peterkokot) * `#6941 `_ Mentioned the "Symfony Upgrade Fixer" in the upgrade article (javiereguiluz) @@ -406,7 +334,7 @@ Minor Documentation Changes * `#6674 `_ CheckStyle in Voters cookbook (JakeFr) * `#6672 `_ [Book][Testing] remove Symfony core testing note (xabbuh) * `#6670 `_ Fix typo 'even' >> 'event' in event_listener.rst (kuusas) -* `#6667 `_ [Contributing][Code] fix list item terminators (xabbuh) +* `#6667 `_ [Contributing][Code] fix list item terminators (xabbuh) * `#6616 `_ Better explain the mandatory/convention location of some elements (rcousens, javiereguiluz) * `#6628 `_ Fix for #6625 (kix) * `#6668 `_ [Contributing][Code] remove PHPUnit requirement (xabbuh) @@ -1558,7 +1486,7 @@ Fixed Documentation - `6ba6ffd `_ #5058 Fix: assets_version instead of asset_version (sebastianblum) - `edf9b78 `_ #5118 Update logger.rst (jdecoster) -- `adf5b90 `_ #5110 [Serializer] Fix class name (iamluc) +- `adf5b90 `_ #5110 [Serializer] Fix class name (iamluc) - `d65880f `_ #5092 Fixed a minor error introduced by the new redirectToRoute() method (javiereguiluz) - `206e613 `_ #4304 [DX] Suggest a hint to any auth-check (larsborn) - `df9c3f4 `_ #5053 Correct RegisterListenersPass namespace (hacfi) @@ -2078,7 +2006,7 @@ Minor Documentation Changes - `3e4c92a `_ #4104 Use ${APACHE_LOG_DIR} instead of /var/log/apache2 (xamgreen) - `3da0776 `_ #4338 ESI Variable Details Continuation (Farkie, weaverryan) - `7f461d2 `_ #4325 [Components][Form] Correct a typo (fabschurt) -- `d162329 `_ #4276 [Components][HttpFoundation] Make a small grammatical adjustment (fabschurt) +- `d162329 `_ #4276 [Components][HttpFoundation] Make a small grammatical adjustment (fabschurt) - `69bfac1 `_ #4322 [Components][DependencyInjection] Correct a typo: replace "then" by "the" (fabschurt) - `8073239 `_ #4318 [Cookbook][Bundles] Correct a typo: remove unnecessary "the" word (fabschurt) - `228111b `_ #4316 Remove horizontal scrollbar (ifdattic) @@ -2728,4 +2656,4 @@ Minor Documentation Changes - `7c5a914 `_ #3369 Indicate that Group Sequence Providers can use YAML (karptonite) - `1e0311e `_ #3416 add empty_data option where required option is used (xabbuh) - `2be3f52 `_ #3422 [Cookbook][Custom Authentication Provider] add a note of warning for when forbidding anonymous users (cordoval) -- `e255de9 `_ #3429 [Reference][Form Types] Document "with_minutes" time/datetime option (bicpi) +- `e255de9 `_ #3429 [Reference][Form Types] Document "with_minutes" time/datetime option (bicpi) \ No newline at end of file diff --git a/doctrine/dbal_session_storage.rst b/doctrine/dbal_session_storage.rst new file mode 100644 index 00000000000..3c85d8efe71 --- /dev/null +++ b/doctrine/dbal_session_storage.rst @@ -0,0 +1,232 @@ +.. index:: + single: Session; Database Storage + +How to Use DbalSessionHandler to Store Sessions in the Database +=============================================================== + +The default Symfony session storage writes the session information to files. +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 +multiple web server environment. + +Symfony has a built-in solution for database session storage called +:class:`Symfony\\Bridge\\Doctrine\\HttpFoundation\\DbalSessionHandler`. +To use it, you just need to change some parameters in the main configuration file: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + framework: + session: + # ... + handler_id: session.handler.dbal + + services: + session.handler.pdo: + class: Symfony\Bridge\Doctrine\HttpFoundation\DbalSessionHandler + public: false + arguments: + - "@doctrine.dbal.default_connection" + - "sessions" + + .. code-block:: xml + + + + + + + + + + sessions + + + + .. code-block:: php + + // app/config/config.php + use Symfony\Component\DependencyInjection\Definition; + use Symfony\Component\DependencyInjection\Reference; + + $container->loadFromExtension('framework', array( + ..., + 'session' => array( + // ..., + 'handler_id' => 'session.handler.dbal', + ), + )); + + $storageDefinition = new Definition('Symfony\Bridge\Doctrine\HttpFoundation\DbalSessionHandler', array( + new Reference('doctrine.dbal.default_connection'), + 'sessions' + )); + $container->setDefinition('session.handler.dbal', $storageDefinition); + +Configuring the Table and Column Names +-------------------------------------- + +The table name, and all of the column names, can be configured by passing +a second string (for the table) and a third array argument (for the columns) to ``DbalSessionHandler``: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + framework: + session: + # ... + handler_id: session.handler.dbal + + services: + session.handler.pdo: + class: Symfony\Bridge\Doctrine\HttpFoundation\DbalSessionHandler + public: false + arguments: + - "@doctrine.dbal.default_connection" + - "sessions" + - db_id_col: sess_id + db_data_col: sess_data + db_time_col: sess_time + + .. code-block:: xml + + + + + + + + + + sessions + + sess_id + sess_data + sess_time + + + + + .. code-block:: php + + // app/config/config.php + use Symfony\Component\DependencyInjection\Definition; + use Symfony\Component\DependencyInjection\Reference; + + $container->loadFromExtension('framework', array( + ..., + 'session' => array( + // ..., + 'handler_id' => 'session.handler.dbal', + ), + )); + + $storageDefinition = new Definition('Symfony\Bridge\Doctrine\HttpFoundation\DbalSessionHandler', array( + new Reference('doctrine.dbal.default_connection'), + 'sessions', + array('db_id_col' => 'sess_id', 'db_data_col' => 'sess_data', 'db_time_col' => 'sess_time') + )); + $container->setDefinition('session.handler.dbal', $storageDefinition); + +These are parameters that you must configure: + +``db_table``: + 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); + +Preparing the Database to Store Sessions +---------------------------------------- + +Before storing sessions in the database, you must create the table that stores +the information. As this is a Doctrine bridge, you will need to create a +Doctrine database file in your preferred flavor. + +.. configuration-block:: + + .. code-block:: php-annotations + + // src/AppBundle/Entity/Session.php + namespace AppBundle\Entity; + + use Doctrine\ORM\Mapping as ORM; + + /** + * @ORM\Entity + * @ORM\Table(name="sessions") + */ + class Session + { + /** + * @ORM\Column(type="string", length=128) + * @ORM\Id + */ + private $sess_id; + + /** + * @ORM\Column(type="blob") + */ + private $sess_data; + + /** + * @ORM\Column(type="integer") + */ + private $sess_time; + } + + .. code-block:: yaml + + # src/AppBundle/Resources/config/doctrine/Session.orm.yml + AppBundle\Entity\Session: + type: entity + table: sessions + id: + sess_id: + type: string + length: 128 + fields: + sess_data: + type: blob + sess_time: + type: integer + + .. code-block:: xml + + + + + + + + + + + + + +.. caution:: + + If the session data doesn't fit in the data column, it might get truncated + by the database engine. To make matters worse, when the session data gets + corrupted, PHP ignores the data without giving a warning. + + If the application stores large amounts of session data, this problem can + be solved by increasing the column size (use ``BLOB`` or even ``MEDIUMBLOB``). + When using MySQL as the database engine, you can also enable the `strict SQL mode`_ + to get noticed when such an error happens. + +.. _`strict SQL mode`: https://dev.mysql.com/doc/refman/5.7/en/sql-mode.html diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index 50c5ac2cde0..8e97be66c62 100644 --- a/reference/configuration/framework.rst +++ b/reference/configuration/framework.rst @@ -685,7 +685,8 @@ installation. .. seealso:: You can see an example of the usage of this in - :doc:`/doctrine/pdo_session_storage`. + :doc:`/doctrine/pdo_session_storage` or + :doc:`/doctrine/dbal_session_storage`. .. _name: diff --git a/session/sessions_directory.rst b/session/sessions_directory.rst index c1b91f5472f..8aee066e467 100644 --- a/session/sessions_directory.rst +++ b/session/sessions_directory.rst @@ -4,8 +4,103 @@ Configuring the Directory where Session Files are Saved ======================================================= -By default, Symfony stores session metadata on the filesystem. If you want to control -this path, update the ``framework.session.save_path`` configuration key: +By default, the Symfony Standard Edition uses the global ``php.ini`` values +for ``session.save_handler`` and ``session.save_path`` to determine where +to store session data. This is because of the following configuration: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + framework: + session: + # handler_id set to null will use default session handler from php.ini + handler_id: ~ + + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + 'session' => array( + // handler_id set to null will use default session handler from php.ini + 'handler_id' => null, + ), + )); + +With this configuration, changing *where* your session metadata is stored +is entirely up to your ``php.ini`` configuration. + +However, if you have the following configuration, Symfony will store the session +data in files in the cache directory ``%kernel.cache_dir%/sessions``. This +means that when you clear the cache, any current sessions will also be deleted: + +.. configuration-block:: + + .. code-block:: yaml + + # app/config/config.yml + framework: + session: ~ + + .. code-block:: xml + + + + + + + + + + .. code-block:: php + + // app/config/config.php + $container->loadFromExtension('framework', array( + 'session' => array(), + )); + +Using a different directory to save session data is one method to ensure +that your current sessions aren't lost when you clear Symfony's cache. + +.. tip:: + + Using a different session save handler is an excellent (yet more complex) + method of session management available within Symfony. See + :doc:`/components/http_foundation/session_configuration` for a + discussion of session save handlers. There are also articles + about storing sessions in a :doc:`relational database (PDO) `, + :doc:`DBAL relational database ` + or a :doc:`NoSQL database `. + +To change the directory in which Symfony saves session data, you only need +change the framework configuration. In this example, you will change the +session directory to ``app/sessions``: .. configuration-block::