Skip to content

Commit a1a30d3

Browse files
wouterjwouterj
committed
feature #5478 Add cookbook article for using MongoDB to store session data (stevenmusumeche)
This PR was merged into the 2.3 branch. Discussion ---------- Add cookbook article for using MongoDB to store session data | Q | A | ------------- | --- | Doc fix? | yes | New docs? | yes | Applies to | all | Fixed tickets | none Commits ------- deccf85 remove links from incorrect page 5f30b07 add reference to mongodb session storage to cookbook index 4238fcc add reference to PDO and MongoDB session handlers in session index 2faa2ac add information about adding an index to improve garbage collection performance dde0ee1 add link to MongoDB cookbook article d3ba62f move parameter configuration into separate section of the article 4048e97 fix formatting 52d89dc add xml and php configuration blocks 8e20ba4 add new cookbook article to index files 2e7757f Add cookbook article for using MongoDB to store session data
2 parents 408c102 + deccf85 commit a1a30d3

File tree

4 files changed

+177
-2
lines changed

4 files changed

+177
-2
lines changed

‎cookbook/configuration/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ Configuration
1313
apache_router
1414
web_server_configuration
1515
configuration_organization
16+
mongodb_session_storage

‎cookbook/configuration/mongodb_session_storage.rst

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
How to Use MongoDbSessionHandler to Store Sessions in a MongoDB Database
2+
========================================================================
3+
4+
The default Symfony session storage writes the session information to files.
5+
Some medium to large websites use a NoSQL database called MongoDB to store the
6+
session values instead of files, because databases are easier to use and scale
7+
in a multi-webserver environment.
8+
9+
Symfony has a built-in solution for NoSQL database session storage called
10+
:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\MongoDbSessionHandler`.
11+
MongoDB is an open-source document database that provides high performance,
12+
high availability and automatic scaling. This article assumes that you have
13+
already `installed and configured a MongoDB server`_. To use it, you just
14+
need to change/add some parameters in the main configuration file:
15+
16+
.. configuration-block::
17+
18+
.. code-block:: yaml
19+
20+
# app/config/config.yml
21+
framework:
22+
session:
23+
# ...
24+
handler_id: session.handler.mongo
25+
cookie_lifetime: 2592000 # optional, it is set to 30 days here
26+
gc_maxlifetime: 2592000 # optional, it is set to 30 days here
27+
28+
services:
29+
# ...
30+
mongo_client:
31+
class: MongoClient
32+
# if using a username and password
33+
arguments: [mongodb://%mongodb_username%:%mongodb_password%@%mongodb_host%:27017]
34+
# if not using a username and password
35+
arguments: [mongodb://%mongodb_host%:27017]
36+
session.handler.mongo:
37+
class: Symfony\Component\HttpFoundation\Session\Storage\Handler\MongoDbSessionHandler
38+
arguments: [@mongo_client, %mongo.session.options%]
39+
40+
.. code-block:: xml
41+
42+
<?xml version="1.0" encoding="UTF-8"?>
43+
<container xmlns="http://symfony.com/schema/dic/services"
44+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-Instance"
45+
xmlns:framework="http://symfony.com/schema/dic/symfony"
46+
xsi:schemaLocation="http://symfony.com/schema/dic/services
47+
http://symfony.com/schema/dic/services/services-1.0.xsd
48+
http://symfony.com/schema/dic/symfony
49+
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
50+
51+
<framework:config>
52+
<!-- ... -->
53+
54+
<!-- cookie-lifetime and gc-maxlifetime are optional and set to
55+
30 days in this example -->
56+
<framework:session handler-id="session.handler.mongo"
57+
cookie-lifetime="2592000"
58+
gc-maxlifetime="2592000"
59+
/>
60+
</framework:config>
61+
62+
<services>
63+
<service id="mongo_client" class="MongoClient">
64+
<!-- if using a username and password -->
65+
<argument>mongodb://%mongodb_username%:%mongodb_password%@%mongodb_host%:27017</argument>
66+
67+
<!-- if not using a username and password -->
68+
<argument>mongodb://%mongodb_host%:27017</argument>
69+
</service>
70+
71+
<service id="session.handler.mongo" class="Symfony\Component\HttpFoundation\Session\Storage\Handler\MongoDbSessionHandler">
72+
<argument type="service">mongo_client</argument>
73+
<argument>%mongo.session.options%</argument>
74+
</service>
75+
</container>
76+
77+
.. code-block:: php
78+
79+
use Symfony\Component\DependencyInjection\Reference;
80+
use Symfony\Component\DependencyInjection\Definition;
81+
82+
$container->loadFromExtension('framework', array(
83+
'session' => array(
84+
// ...
85+
'handler_id' => 'session.handler.mongo',
86+
'cookie_lifetime' => 2592000, // optional, it is set to 30 days here
87+
'gc_maxlifetime' => 2592000, // optional, it is set to 30 days here
88+
),
89+
));
90+
91+
$container->setDefinition('mongo_client', new Definition('MongoClient', array(
92+
// if using a username and password
93+
array('mongodb://%mongodb_username%:%mongodb_password%@%mongodb_host%:27017'),
94+
// if not using a username and password
95+
array('mongodb://%mongodb_host%:27017'),
96+
)));
97+
98+
$container->setDefinition('session.handler.mongo', new Definition(
99+
'Symfony\Component\HttpFoundation\Session\Storage\Handler\MongoDbSessionHandler',
100+
array(new Reference('mongo_client'), '%mongo.session.options%')
101+
));
102+
103+
The parameters used above should be defined somewhere in your application, often in your main
104+
parameters configuration:
105+
106+
.. configuration-block::
107+
108+
.. code-block:: yaml
109+
110+
# app/config/parameters.yml
111+
parameters:
112+
# ...
113+
mongo.session.options:
114+
database: session_db # your MongoDB database name
115+
collection: session # your MongoDB collection name
116+
mongodb_host: 1.2.3.4 # your MongoDB server's IP
117+
mongodb_username: my_username
118+
mongodb_password: my_password
119+
120+
.. code-block:: xml
121+
122+
<?xml version="1.0" encoding="UTF-8"?>
123+
<container xmlns="http://symfony.com/schema/dic/services"
124+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-Instance"
125+
xmlns:framework="http://symfony.com/schema/dic/symfony"
126+
xsi:schemaLocation="http://symfony.com/schema/dic/services
127+
http://symfony.com/schema/dic/services/services-1.0.xsd
128+
http://symfony.com/schema/dic/symfony
129+
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
130+
131+
<parameters>
132+
<parameter key="mongo.session.options" type="collection">
133+
<!-- your MongoDB database name -->
134+
<parameter key="database">session_db</parameter>
135+
<!-- your MongoDB collection name -->
136+
<parameter key="collection">session</parameter>
137+
</parameter>
138+
<!-- your MongoDB server's IP -->
139+
<parameter key="mongodb_host">1.2.3.4</parameter>
140+
<parameter key="mongodb_username">my_username</parameter>
141+
<parameter key="mongodb_password">my_password</parameter>
142+
</parameters>
143+
</container>
144+
145+
.. code-block:: php
146+
147+
use Symfony\Component\DependencyInjection\Reference;
148+
use Symfony\Component\DependencyInjection\Definition;
149+
150+
$container->setParameter('mongo.session.options', array(
151+
'database' => 'session_db', // your MongoDB database name
152+
'collection' => 'session', // your MongoDB collection name
153+
));
154+
$container->setParameter('mongodb_host', '1.2.3.4'); // your MongoDB server's IP
155+
$container->setParameter('mongodb_username', 'my_username');
156+
$container->setParameter('mongodb_password', 'my_password');
157+
158+
Setting Up the MongoDB Collection
159+
---------------------------------
160+
161+
Because MongoDB uses dynamic collection schemas, you do not need to do anything to initialize your
162+
session collection. However, you may want to add an index to improve garbage collection performance.
163+
From the `MongoDB shell`_:
164+
165+
.. code-block:: sql
166+
167+
use session_db
168+
db.session.ensureIndex( { "expireAt": 1 }, { expireAfterSeconds: 0 } )
169+
170+
.. _installed and configured a MongoDB server: http://docs.mongodb.org/manual/installation/
171+
.. _MongoDB shell: http://docs.mongodb.org/v2.2/tutorial/getting-started-with-the-mongo-shell/

‎cookbook/map.rst.inc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
* :doc:`/cookbook/configuration/apache_router`
3939
* :doc:`/cookbook/configuration/web_server_configuration`
4040
* :doc:`/cookbook/configuration/configuration_organization`
41+
* :doc:`/cookbook/configuration/mongodb_session_storage`
4142

4243
* :doc:`/cookbook/console/index`
4344

@@ -189,6 +190,7 @@
189190
* :doc:`/cookbook/session/sessions_directory`
190191
* :doc:`/cookbook/session/php_bridge`
191192
* (configuration) :doc:`/cookbook/configuration/pdo_session_storage`
193+
* (configuration) :doc:`/cookbook/configuration/mongodb_session_storage`
192194
* :doc:`/cookbook/session/avoid_session_start`
193195

194196
* **symfony1**

‎cookbook/session/sessions_directory.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -93,8 +93,9 @@ that your current sessions aren't lost when you clear Symfony's cache.
9393
Using a different session save handler is an excellent (yet more complex)
9494
method of session management available within Symfony. See
9595
:doc:`/components/http_foundation/session_configuration` for a
96-
discussion of session save handlers. There is also an entry in the cookbook
97-
about storing sessions in the :doc:`database </cookbook/configuration/pdo_session_storage>`.
96+
discussion of session save handlers. There are also entries in the cookbook
97+
about storing sessions in a :doc:`relational database </cookbook/configuration/pdo_session_storage>`
98+
or a :doc:`NoSQL database </cookbook/configuration/mongodb_session_storage>`.
9899

99100
To change the directory in which Symfony saves session data, you only need
100101
change the framework configuration. In this example, you will change the

0 commit comments

Comments
 (0)