Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[#3276] Trying to further clarify the session storage directory details #3404

Merged
merged 2 commits into from
Jan 21, 2014
Merged

[#3276] Trying to further clarify the session storage directory details #3404

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f094237
[#3276] Trying to further clarify the session storage directory details
weaverryan Jan 1, 2014
adc57be
[#3404] Adding a few comments, per @WouterJ
weaverryan Jan 21, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 74 additions & 13 deletions cookbook/session/sessions_directory.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,84 @@
Configuring the Directory Where Sessions Files are Saved
========================================================

By default, Symfony stores 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.
By default, the Symfony Standard Edition uses the global ``php.ini`` values
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is no good in this format because the docs are not for symfony standard, but for the full stack framework. You need to be very explicit when documenting something that is not the full stack stuff. It is also wrong to remove the documentation about what the full stack is doing. You need something separate but please not not remove that was there.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find Symfony stores the session data... unclear - only because I don't know what "Symfony" is - it could be the full stack, could be SE, and in many cases, users don't really know the difference. Chances are, if someone starts using Symfony today, they will use the SE and then the effective default is for the php.ini values to be used. So even though what you had before is correct, an average user will see this as a bug in the documentation.

What do you think?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also don't know why we don't write for the Symfony Standard? All our code examples rely on the SE.

I also think Ryan's approach is the clearest: Instead of telling what is happening by default, tell people what happends with which configuration.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All the cook book examples are for Symfony Full Stack Framework, not SE.
I have no problems with note in the document for Symfony Standard Edition, but he's changed the document to default as Symfony Standard Edition and that breaks the entire convention of everything.

I would be happy to work this stuff into another PR but as it stands you are adding confusion, not removing it.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Drak I think you have another definition for the documentation than we have :) The Quick Tour fully uses the SE, you can't follow it without using the SE. The book and cookbook chapters are written for everyone, but heavily based on the SE and the components chapters are talking about using specific components outside of a Symfony scope. Are you sure you are not confusing cookbook and component chapters?

To give you some examples, Assetic and Monolog doesn't come in when installing Symfony. They only come in when installing the SE. However, we never document how to install and register those bundle into your project, as we based those articles on the SE.

The bundles section is completely based on the SE. It talks about removing the AcmeDemoBundle, which only comes in when installing the SE. It also talks about overriding files by using app/Resources, well how can we base our docs more on the SE? :)

Configuration, "How to override Symfony's Default Directory Structure". The Default Directory Structure, we mean the one that comes in by using the SE.

Workflow, here we tell which files of the SE you should put in the .gitignore file and how you should handle the parameters.yml and parameters.yml.dist file, those are fully based on the SE.

So to summarize: Yes, the way you did it would make sense if we put it in the components section, as that's talking about using the HttpFoundation component outside of Symfony. But since it's a cookbook article, it should be focussed more on the SE than on Symfony core. Saying "Symfony" in the components section means the standalone component, saying "Symfony" in the cookbook will result in many people thinking we are talking about the SE. Even if we change it to "symfony core", we will still get a lot of PRs and issues from people thinking that core === SE.

for ``session.save_handler`` and ``session.save_path`` to determine where
to store session data. This is because of the following configuration:

.. note::
.. 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

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
>
<framework:config>
<framework:session handler-id="null" />
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing

</framework:config>
</container>

If the ``session`` configuration key is set to ``~``, Symfony will use the
global PHP ini values for ``session.save_handler`` and associated
``session.save_path`` from ``php.ini``.
.. code-block:: php

// app/config/config.php
$container->loadFromExtension('framework', array(
'session' => array(
'handler-id' => null,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missing the comment too

),
));

.. note::
With this configuration, changing *where* your session metadata is stored
is entirely up to your ``php.ini`` configuration.

While the Symfony Full Stack Framework defaults to using the
``session.handler.native_file``, the Symfony Standard Edition is
configured to use PHP's global session settings by default and therefor
sessions will be stored according to the ``session.save_path`` location
and will not be deleted when clearing the cache.
However, if you have the following configuration, Symfony will store the session
data in files in the cache directory ``%kernel.cache_dir%/sessions``. This
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe add something like "..., as it falls back to its default" to still clarify the symfony default?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the session data in files in the cache directory is not very clear

do you mean it will now store session data in the cache directory explicitly specified?

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

<!-- app/config/config.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:framework="http://symfony.com/schema/dic/symfony"
xsi:schemaLocation="http://symfony.com/schema/dic/services
http://symfony.com/schema/dic/services/services-1.0.xsd
http://symfony.com/schema/dic/symfony
http://symfony.com/schema/dic/symfony/symfony-1.0.xsd"
>
<framework:config>
<framework:session />
</framework:config>
</container>

.. 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.
Expand Down