How to manage a user session

Overview

To store and retrieve data about the user session, use the sfUser class and its standard methods, or override it to encapsulate user logic into a custom myUser class.

Introduction

Information about the current user and his/her session can be found in the sfUser object.

Getting access to this object and its methods differs whether you are in an action:

$this->getUser();

or if you are in a template:

$sf_user

The sfUser class owns a few default attributes used by symfony to deal with classical user session interactions:

• culture holds the user Culture (language and country)
• authentication attributes (these are described in detail in the authentication and rigths chapter)

In addition, the sfUser class owns a parameter holder in which you can store custom attributes.

Custom user attributes

If you need to store information about a user until his/her session is closed, use the ->getAttribute() and ->setAttribute() methods. Attributes can store any type of data (strings, arrays, associative arrays, even objects).

For instance, to set and get an attribute nickname in an action:

$this->getUser()->setAttribute('nickname', 'foo');
...
$this->getUser()->getAttribute('nickname');

These informations are stored whatever the user, whether he/she is identified or not.

To check whether an attribute has been defined for a user, use the ->hasAttribute() method.

$hasNickname = $this->getUser()->hasAttribute('nickname');

To remove an attribute from the session use:

$this->getUser()->getAttributeHolder()->remove('nickname');

Note: If you need to store information just for the duration of one request - for instance to pass information through a chain of action calls - you may prefer the sfRequest class, which also has ->getAttribute() and ->setAttribute() methods.

Flash parameters

A recurrent problem with user attributes is the cleaning of the user session once the attribute is not needed anymore. Did you ever dream of an ephemeral attribute, one that you could define and forget, knowing that it will disappear after the next request and leave your user session clean for the future? Symfony provides a simple mechanism to keep the user session clean in this case: the flash parameter.

In your action, define the flash attribute like this:

$this->setFlash('attrib', $value);

The template will be built and decorated, the page will be delivered to the user, who will then make a new request to another action. In this second action, just get the value of the flash attribute by:

$value = $this->getFlash('attrib');

Then, forget about it. After delivering this second page, the attrib flash attribute will be cleared, erased, removed, in a word: flashed. And even if you don't require it during this second action, the flash will disappear from the session anyway.

If you need to access a flash attribute from a template, use the $sf_flash object:

<?php if($sf_flash->has('attrib')): ?>
  <?php $attrib = $sf_flash->get('attrib') ?>
<?php endif ?>

Flash parameters are a clean way of passing information to the next action, and once you start using them, you'll probably consider session attributes as an unforgivable archaism.

Extending the session class

When the application needs to hold key information in the session, it is better to encapsulate this logic into an extension of the sfUser class.

Let's imagine you are building a chat website where users have to choose a nickname. A simple way to store and read this nickname would be:

$this->getUser()->setAttribute('nickname', 'foo');
$this->getUser()->getAttribute('nickname');

Although this is exactly the previous example, this is not a very good solution, partly because it shows the real attribute and doesn't encapsulate the inner logic of the class. What would happen, for instance, if you decided suddenly to change the attribute name from 'nickname' to 'name' ? To settle this problem, you just need to extend the sfUser class. Check the myproject/apps/myapp/lib/ directory of your application: an empty myUser class just waits to be completed.

class myUser extends sfUser
{
  public function getNickname()
  {
    return $this->getAttribute('nickname');
  }
 
  public function setNickname($nickname)
  {
    return $this->setAttribute('nickname', $nickname);
  }
}

Then, in the action, the calls would be:

$this->getUser()->setNickname('foo');
$this->getUser()->getNickname();

The reason why symfony uses the custom myUser class instead of the prebuilt sfUser is that the factories.yml configuration file of the application specifies it. You could decide to write a completely new user class, with your own custom methods, and call it myproject/apps/myapp/lib/myCustomUser.php. But then, you would have to force symfony to use it instead of the myUser class by writing in the factories.yml:

all:
  user:
    class: myCustomUser

Session expiration

Session expiration occurs automatically after sf_timeout seconds. This constant is of 30 minutes by default and can be modified for each environment in the myproject/apps/myapp/config/settings.yml configuration file:

default:
  .settings:
    timeout:     1800