8000 Updated docs. · symfony/symfony-docs@dadffe9 · GitHub
[go: up one dir, main page]
Skip to content

Commit dadffe9

Browse files
author
Drak
committed
Updated docs.
1 parent 66ce132 commit dadffe9

File tree

1 file changed

+185
-17
lines changed

1 file changed

+185
-17
lines changed

‎ 8000 components/http_foundation.rst

Lines changed: 185 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -401,6 +401,80 @@ Quick example::
401401

402402
echo $session->getFlashBag()->get('notice');
403403

404+
Session API
405+
~~~~~~~~~~~
406+
407+
The :class:`Symfony\\Component\\HttpFoundation\\Session\\Session` implements
408+
:class:`Symfony\\Component\\HttpFoundation\\Session\\SessionInterface.
409+
410+
The :class:`Symfony\\Component\\HttpFoundation\\Session\\Session` has a simple API
411+
as follows divided into a couple of groups.
412+
413+
Session workflow
414+
415+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::start`:
416+
Starts the session - do not use `session_start()`.
417+
418+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::migrate`:
419+
Starts the session - do not use `session_start()`.
420+
421+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::invalidate`:
422+
Starts the session - do not use `session_start()`.
423+
424+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::getId`: Gets the
425+
session ID.
426+
427+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::setId`: Gets the
428+
session ID.
429+
430+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::getName`: Gets the
431+
session name.
432+
433+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::setName`: Sets the
434+
session name.
435+
436+
Session attributes
437+
438+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::set`:
439+
Sets an attribute by key;
440+
441+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::get`:
442+
Gets an attribute by key;
443+
444+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::all`:
445+
Gets all attributes as an array of key => value;
446+
447+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::has`:
448+
Returns true if the attribute exists;
449+
450+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::keys`:
451+
Returns an array of stored attribute keys;
452+
453+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::replace`:
454+
Sets multiple attributes at once: takes a keyed array and sets each key => value pair.
455+
456+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::remove`:
457+
Deletes an attribute by key;
458+
459+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::clear`:
460+
Clear the bag;
461+
462+
Bag management
463+
464+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::registerBag`:
465+
Registers a `Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface`
466+
467+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::getBag`:
468+
Gets a `Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface` by
469+
bag name.
470+
471+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Session::getFlashBag`:
472+
Gets the `Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface`.
473+
This is just a shortcut for convenience.
474+
475+
476+
477+
404478
Save Handlers
405479
~~~~~~~~~~~~~
406480

@@ -480,6 +554,20 @@ Symfony2 provides 2 kinds of bags, with two separate implementations.
480554
Everything is written against interfaces so you may extend or create your own
481555
bag types if necessary.
482556

557+
:class:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface` has
558+
the following API which is intended mainly for internal purposes:
559+
560+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface::getStorageKey`:
561+
Returns the key which the bag will ultimately store its array under in `$_SESSION`.
562+
Generally this value can be left at its default and is for internal use.
563+
564+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface::initialize`:
565+
This is called internally by Symfony2 session storage classes to link bag data
566+
to the session.
567+
568+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\SessionBagInterface::getName`:
569+
Returns the name of the session bag.
570+
483571
Attributes
484572
~~~~~~~~~~
485573

@@ -518,6 +606,33 @@ structure like this using a namespace character (defaults to `/`)::
518606

519607
This way you can easily access a key within the stored array directly and easily.
520608

609+
:class:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface`
610+
has a simple API
611+
612+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::set`:
613+
Sets an attribute by key;
614+
615+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::get`:
616+
Gets an attribute by key;
617+
618+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::all`:
619+
Gets all attributes as an array of key => value;
620+
621+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::has`:
622+
Returns true if the attribute exists;
623+
624+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::keys`:
625+
Returns an array of stored attribute keys;
626+
627+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::replace`:
628+
Sets multiple attributes at once: takes a keyed array and sets each key => value pair.
629+
630+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::remove`:
631+
Deletes an attribute by key;
632+
633+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Attribute\\AttributeBagInterface::clear`:
634+
Clear the bag;
635+
521636
Flash messages
522637
~~~~~~~~~~~~~~
523638

@@ -539,6 +654,36 @@ This is however just one application for flash messages.
539654
they are explicitly retrieved or cleared. This makes it possible to use ESI
540655
caching.
541656

657+
:class:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface`
658+
has a simple API
659+
660+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::set`:
661+
Sets a flash by type;
662+
663+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::get`:
664+
Gets a flash by type and clears the flash from the bag;
665+
666+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::setAll`:
667+
Sets an array of flashes by type => message;
668+
669+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::all`:
670+
Gets all flashes and clears the flashes from the bag;
671+
672+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::peek`:
673+
Gets a flash by type (read only);
674+
675+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::peekAll`:
676+
Gets all flashes (readoly);
677+
678+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::has`:
679+
Returns true if the type exists;
680+
681+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::keys`:
682+
Returns an array of stored types;
683+
684+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\Flash\\FlashBagInterface::clear`:
685+
Clear the bag;
686+
542687
Testability
543688
-----------
544689

@@ -554,8 +699,21 @@ The mock storage engines simulate the PHP session workflow without actually
554699
starting one allowing you to test your code without complications. You may also
555700
run multiple instances in the same PHP process.
556701

557-
The only caveat, `session_id()` is global, so the session ID should be read
558-
using `$session->getId()` but generally this is of no relevance during testing.
702+
The mock storage drivers do not read or write the system globals
703+
`session_id()` or `session_name()`. Methods are provided to simulate this if
704+
required:
705+
706+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\SessionStorageInterface::getId`: Gets the
707+
session ID.
708+
709+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\SessionStorageInterface::setId`: Gets the
710+
session ID.
711+
712+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\SessionStorageInterface::getName`: Gets the
713+
session name.
714+
715+
* :method:`Symfony\\Component\\HttpFoundation\\Session\\SessionStorageInterface::setName`: Sets the
716+
session name.
559717

560718
Unit Testing
561719
~~~~~~~~~~~~
@@ -584,9 +742,9 @@ separate PHP processes, simply change the storage engine to
584742
PHP 5.4 compatibility
585743
~~~~~~~~~~~~~~~~~~~~~
586744

587-
Since PHP 5.4.0, :phpclass:`SessionHandler` and :phpclass:`SessionHandlerInterface` are available.
588-
Symfony 2.1 provides forward compatibility for the :phpclass:`SessionHandlerInterface` so
589-
it can be used under PHP 5.3. This greatly improves inter-operability with other
745+
Since PHP 5.4.0, :phpclass:`SessionHandler` and :phpclass:`SessionHandlerInterface`
746+
are available. Symfony 2.1 provides forward compatibility for the :phpclass:`SessionHandlerInterface`
747+
so it can be used under PHP 5.3. This greatly improves inter-operability with other
590748
libraries.
591749

592750
:phpclass:`SessionHandler` is a special PHP internal class which exposes native save
@@ -598,17 +756,27 @@ which under PHP 5.4, extends from `\SessionHandler` and under PHP 5.3 is just a
598756
empty base class. This provides some interesting opportunities to leverage
599757
PHP 5.4 functionality if it is available.
600758

601-
Handler Proxy
602-
~~~~~~~~~~~~~
759+
Save Handler Proxy
760+
~~~~~~~~~~~~~~~~~~
761+
762+
There are two kinds of save handler classes proxy which inherit from
763+
:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\AbstractProxy`,
764+
they are :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\NativeProxy`
765+
and :class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\SessionHandlerProxy`.
603766

604767
:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\NativeSessionStorage`
605-
injects storage handlers into a handler proxy. The reason for this is that
606-
under PHP 5.4, all handlers implement :phpclass:`SessionHandlerInterface`
607-
including native handlers (those which activate internal PHP/PHP-extension
608-
handlers. Native handlers under PHP 5.4 will be children of
609-
:phpclass:`SessionHandler` which allows one to intercept and modify even native session
610-
handlers.
611-
612-
In order to manage all of this, Symfony2 uses a proxy handler object. It means
613-
that you could write a single adapter, that for example encrypts the session
614-
data, and it will work regardless of the save handler in use, custom, or native.
768+
automatically injects storage handlers into a save handler proxy unless already
769+
wrapped by one.
770+
771+
:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\NativeProxy`
772+
is used automatically under PHP 5.3 when internal PHP save handlers are specified
773+
using the `Native*SessionHandler` classes, while
774+
:class:`Symfony\\Component\\HttpFoundation\\Session\\Storage\\Handler\\SessionHandlerProxy`
775+
will be used to wrap any custom save handlers, that implement :phpclass:`SessionHandlerInterface`.
776+
777+
Under PHP 5.4 and above, all session handlers implement :phpclass:`SessionHandlerInterface`
778+
including `Native*SessionHandler` classes which inherit from :phpclass:`SessionHandler`.
779+
780+
The proxy mechanism allow you to get more deeply involved in session save handler
781+
classes. A proxy for example could be used to encrypt any session transaction
782+
without knowledge of the specific save handler.

0 commit comments

Comments
 (0)
0