Session

    Sessions are used in PHP to persist data between requests. This enables developers to build better applications and increase the user experience. A very common usage of sessions is to keep whether a user is logged in or not. Phalcon\Session\Manager is an object oriented approach to handle sessions using Phalcon. There are several reasons to use this component instead of raw sessions or accessing the superglobal:

    • You can easily isolate session data across applications on the same domain
    • Intercept where session data is set/get in your application
    • Change the session adapter according to the application needs

    Manager

    Phalcon\Session\Manager is a component that allows you to manipulate sessions in your application. This manager accepts a an adapter which is the way the data will be communicated to a particular store.

    First we need to create an adapter object. The object can be one of the adapters distributed with Phalcon (see below) but it can also be an object that implements . Once we instantiate the new Phalcon\Session\Manager object and pass the adapter in it. After that you can start working with the session.

    1. public function __construct(array $options = [])

    The constructor accepts an array of options that relate to the session. You can set a unique id for your session using uniqueId as a key and your chosen id string. This allows you to create more than one of these objects, each with its own unique id, if necessary. This parameter is optional, but it is advisable to set it always. Doing so will help you with potential session leaks.

    Start

    In order to work with the session, you need to start it. start() performs this task. Usually this call is made when the component is registered or at the very top of your application’s workflow. start() returns a boolean value indicating success or failure.

    1. <?php
    3. use Phalcon\Session\Manager;
    4. use Phalcon\Session\Adapter\Stream;
    6. $session = new Manager();
    7. $files = new Stream(
    8.     [
    9.         'savePath' => '/tmp',
    10.     ]
    11. );
    12. $session->setAdapter($files);
    14. $session->start();

    Destroy

    Similarly, you can call destroy() to kill the session. Usually this happens when a user logs out.

    1. <?php
    3. use Phalcon\Session\Manager;
    4. use Phalcon\Session\Adapter\Stream;
    6. $session = new Manager();
    7. $files = new Stream(
    8.     [
    9.         'savePath' => '/tmp',
    10.     ]
    11. );
    12. $session
    13.     ->setAdapter($files)
    14.     ->start();
    16. // ....
    18. $session->destroy();

    Exists

    To check if your session has started, you can use exists()

    1. <?php
    3. use Phalcon\Session\Manager;
    4. use Phalcon\Session\Adapter\Stream;
    6. $session = new Manager();
    7. $files = new Stream(
    8.     [
    9.         'savePath' => '/tmp',
    10.     ]
    11. );
    13. var_dump(
    14.     $session->exists()
    15. );
    16. // `false`
    18. $session
    19.     ->setAdapter($files)
    20.     ->start();
    22. var_dump(
    23.     $session->exists()
    24. );
    25. // `true`

    Regenerate Id

    supports regenerating the session id. This allows you to replace the current session id with a new one and keep the current session information intact. To achieve this you can call regenerateId(). The method also accepts a bool parameter, which if true will instruct the component to remove old session file.

    1. <?php
    3. use Phalcon\Session\Manager;
    4. use Phalcon\Session\Adapter\Stream;
    6. $session = new Manager();
    7. $files = new Stream(
    8.     [
    9.         'savePath' => '/tmp',
    10.     ]
    11. );
    13. $session
    14.     ->setAdapter($files)
    15.     ->start();
    17. $session->regenerateId();

    Get

    1. <?php
    3. use Phalcon\Session\Manager;
    4. use Phalcon\Session\Adapter\Stream;
    6. $session = new Manager();
    7. $files = new Stream(
    8.     [
    9.         'savePath' => '/tmp',
    10.     ]
    11. );
    13. $session
    14.     ->setAdapter($files)
    15.     ->start();
    17. echo $session->get('userId');
    18. echo $session->userId;

    You can use has() to check whether a particular element is stored in your session. The component also supports the magic __isset, allowing you to use PHP’s isset() method if you want.

    1. <?php
    3. use Phalcon\Session\Manager;
    4. use Phalcon\Session\Adapter\Stream;
    6. $session = new Manager();
    7. $files = new Stream(
    8.     [
    9.         'savePath' => '/tmp',
    10.     ]
    11. );
    13. $session
    14.     ->setAdapter($files)
    15.     ->start();
    17. echo $session->has('userId');
    18. var_dump(
    19.     isset($session->userId)
    20. );

    Id

    You can also set the session id. The session id is set in a HTTP cookie. You can set the name by calling setId(). getId() is used to retrieve the session id.

    Name

    Each session can have a name. The session name is set in a HTTP cookie. If this is not set, the session.name php.ini setting is used. You can set the name by calling setName(). getName() is used to retrieve the session name.

    1. <?php
    3. use Phalcon\Session\Adapter\Stream;
    5. $session = new Manager();
    6. $files = new Stream(
    7.     [
    8.         'savePath' => '/tmp',
    9.     ]
    11. $session
    12.     ->setAdapter($files)
    13.     ->setName('phalcon-app')
    14.     ->start();
    16. echo $session->getName(); // 'phalcon-app'

    Options

    You can set options for the manager by using setOptions(). The method accepts an array and in it you can set the uniqueId for the session. To get the options you can call getOptions() which will return the array of options stored in the manager.

    1. <?php
    3. use Phalcon\Session\Manager;
    4. use Phalcon\Session\Adapter\Stream;
    6. $session = new Manager('id-1');
    7. $files = new Stream(
    8.     [
    9.         'savePath' => '/tmp',
    10.     ]
    11. );
    12. $session
    13.     ->setAdapter($files)
    14.     ->start();
    16. $session->setOptions(
    17.     [
    18.         'uniqueId' => 'id-2'
    19.     ]   
    20. );

    In the above example, after setOptions() is called with a new uniqueId, data will be stored using id-2 now and anything stored before that will not be accessible until you change the key back to id-1.

    Set

    You can use set() to store contents in your session. The method accepts a string as the name of the element and the value to be stored.. The component also supports the magic setter so you can set it as a property of the manager.

    1. <?php
    3. use Phalcon\Session\Manager;
    4. use Phalcon\Session\Adapter\Stream;
    6. $session = new Manager();
    7. $files = new Stream(
    8.     [
    9.         'savePath' => '/tmp',
    10.     ]
    11. );
    13. $session
    14.     ->setAdapter($files)
    15.     ->start();
    17. $session->set('userId', 12345);
    18. $session->userId = 12345;

    Remove

    To remove a stored element in the session, you need to call remove() with the name of the element. The component also supports the magic __unset so you can use PHP’s unset() method if you want.

    1. <?php
    3. use Phalcon\Session\Manager;
    4. use Phalcon\Session\Adapter\Stream;
    6. $session = new Manager();
    7. $files = new Stream(
    8.     [
    9.         'savePath' => '/tmp',
    10.     ]
    11. );
    13. $session
    14.     ->setAdapter($files)
    15.     ->start();
    17. $session->remove('userId');
    18. unset($session->userId);

    Phalcon\Session\Adapter\Libmemcached uses the internally to store data in Memcached. In order to use this adapter you need the settings for Memcached and a Phalcon\Storage\AdapterFactory object in order for the adapter to be created internally.

    • client - client settings
    • servers - array of server data
      • host - the host
      • port - the port
      • weight - the weight for the server
    1. <?php
    3. use Phalcon\Session\Manager;
    4. use Phalcon\Storage\AdapterFactory;
    5. use Phalcon\Session\Adapter\Libmemcached;
    7. $options = [
    8.     'client'  => [],
    9.     'servers' => [
    10.         [
    11.             'host'   => '127.0.0.1',
    12.             'port'   => 11211,
    13.             'weight' => 0,
    14.         ],
    15.     ],
    16. ];
    18. $session = new Manager();
    19. $factory = new AdapterFactory();
    20. $redis   = new Libmemcached($factory, $options);
    22. $session
    23.     ->setAdapter($redis)
    24.     ->start();

    Noop

    Phalcon\Session\Adapter\Noop is an “empty” or null adapter. It can be used for testing, a joke for your colleages or any other purpose that no session needs to be invoked.

    1. <?php
    3. use Phalcon\Session\Manager;
    4. use Phalcon\Session\Adapter\Noop;
    6. $session = new Manager();
    7. $session
    8.     ->setAdapter(new Noop())
    9.     ->start();

    Redis

    Phalcon\Session\Adapter\Redis uses the internally to store data in Redis. In order to use this adapter you need the settings for Redis and a Phalcon\Storage\AdapterFactory object in order for the adapter to be created internally.

    The available options for Redis are:

    • host - the host
    • port - the port
    • index - the index
    • persistent - whether to persist connections or not
    • auth - authentication parameters
    • socket - socket connection
    1. <?php
    3. use Phalcon\Session\Manager;
    4. use Phalcon\Storage\AdapterFactory;
    5. use Phalcon\Session\Adapter\Redis;
    7. $options = [
    8.     'host'  => '127.0.0.1',
    9.     'port'  => 6379,
    10.     'index' => '1',
    11. ];
    13. $session = new Manager();
    14. $factory = new AdapterFactory();
    15. $redis   = new Redis($factory, $options);
    17. $session
    18.     ->setAdapter($redis)
    19.     ->start();

    Stream

    This adapter is the most common one, storing the session files on the file system. You need to create a Phalcon\Session\Adapter\Stream adapter with the savePath defined in the options. The path needs to be writeable by the web server, otherwise your sessions will not work.

    Custom

    The adapters implement PHP’s SessionHandlerInterface. As a result you can create any adapter you need by extending this interface. You can also use any adapter that implements this interface and set the adapter to . There are more adapters available for this components in the Phalcon Incubator.

    1. <?php
    3. namespace MyApp\Session\Adapter;
    5. use SessionHandlerInterface;
    7. class Custom extends SessionHandlerInterface
    8. {
    9.     /**
    10.      * Close
    11.      */
    12.     public function close() -> bool;
    14.      * Destroy
    15.      */
    16.     public function destroy($sessionId) -> bool;
    18.     /**
    19.      * Garbage Collector
    20.      */
    21.     public function gc($maxlifetime) -> bool;
    23.     /**
    24.      * Read
    25.      */
    26.     public function read($sessionId) -> string;
    28.     /**
    29.      * Open
    30.      */
    31.     public function open($savePath, $sessionName) -> bool;
    33.     /**
    34.      * Write
    35.      */
    36.     public function write($sessionId, $data) -> bool;
    37. }

    Exceptions

    Any exceptions thrown in the Session component will be of type Phalcon\Session\Exception. It is thrown any session operation is not completed correctly. You can use these exceptions to selectively catch exceptions thrown only from this component.

    1. <?php
    3. use Phalcon\Session\Exception;
    4. use Phalcon\Session\Manager;
    5. use Phalcon\Mvc\Controller;
    7. /**
    8.  * @property Manager $session
    9.  */
    10. class IndexController extends Controller
    11. {
    12.     public function index()
    13.     {
    14.         try {
    15.             $this->session->set('key', 'value');
    16.         } catch (Exception $ex) {
    17.             echo $ex->getMessage();
    18.         }
    19.     }
    20. }

    is a component that helps separating session data into namespaces. This way you can create groups of session variables for your application. Setting data in the bag stores them automatically in the session:

    1. <?php
    3. use Phalcon\Di;
    4. use Phalcon\Session\Bag as SessionBag;
    6. $container = new Di();
    7. $user      = new SessionBag('user');
    9. $user->setDI($container);
    11. $user->name     = 'Dark Helmet';
    12. $user->password = 12345;

    Dependency Injection

    If you use the container you can register your session manager. An example of the registration of the service as well as accessing it is below:

    1. <?php
    3. use Phalcon\Di;
    4. use Phalcon\Session\Manager;
    5. use Phalcon\Session\Adapter\Stream;
    7. $container = new Di();
    9. $container->set(
    10.     'session',
    11.     function () {
    12.         $session = new Manager();
    13.         $files = new Stream(
    14.             [
    15.                 'savePath' => '/tmp',
    16.             ]
    17.         );
    19.         $session
    20.             ->setAdapter($files)
    21.             ->start();
    23.         return $session;
    24.     }
    25. );

    After registering the manager you can access your session from controllers, views or any other components that extend Phalcon\Di\Injectable as follows:

    1. <?php
    3. use Phalcon\Mvc\Controller;
    4. use Phalcon\Session\Manager;
    6. /**
    7.  * @property Manager $session
    8.  */
    9. class InvoicesController extends Controller
    10. {
    11.     public function indexAction()
    12.     {
    13.         // Set a session variable
    14.         $this->session->set('user-name', 'Dark Helmet');
    15.     }
    16. }

    Persistent Data

    You can also inject the Phalcon\Session\Bag component. Doing so will help you isolate variables for every class without polluting the session. The component is registered automatically using the persistent property name. Anything set in $this->persist will only be available in each class itself, whereas if data is set in the session manager will be available throughout the application.

    1. <?php
    3. use Phalcon\Mvc\Controller;
    4. use Phalcon\Session\Bag;
    5. use Phalcon\Session\Manager;
    7. /**
    8.  * @property Bag     $persistent
    9.  * @property Manager $session
    10.  */
    11. class InvoicesController extends Controller
    12. {
    13.     public function indexAction()
    14.     {
    15.         // Set a session variable
    16.         $this->persistent->name = 'Dark Helmet';
    17.         $this->session->name    = 'Princess Vespa';
    18.     }
    20.     public function echoAction()
    21.     {
    22.         // Set a session variable
    23.         echo $this->persistent->name; // 'Dark Helmet';
    24.         echo $this->session->name;    // 'Princess Vespa';
    25.     }
    26. }

    In a component:

    1. <?php
    3. use Phalcon\Mvc\Controller;
    4. use Phalcon\Session\Bag;
    5. use Phalcon\Session\Manager;
    7. /**
    8.  * @property Bag     $persistent
    9.  * @property Manager $session
    10.  */
    11. class InvoicesController extends Controller
    12. {
    13.     public function indexAction()
    14.     {
    15.         // Set a session variable
    16.         $this->persistent->name = 'President Skroob';
    17.     }
    19.     public function echoAction()
    20.     {
    21.         // Set a session variable
    22.         echo $this->persistent->name; // 'President Skroob';
    23.         echo $this->session->name;    // 'Princess Vespa';