Configure les fonctions de stockage de sessions

# session_set_save_handler

(PHP 4, PHP 5, PHP 7, PHP 8)

session_set_save_handler — Configure les fonctions de stockage de sessions

### Description

function session_set_save_handler(
callable `$open`,
callable `$close`,
callable `$read`,
callable `$write`,
callable `$destroy`,
callable `$gc`,
callable `$create_sid` = ?,
callable `$validate_sid` = ?,
callable `$update_timestamp` = ?
): bool

Il est possible d'enregistrer le prototype suivant :

function session_set_save_handler(object `$sessionhandler`, bool `$register_shutdown` = `true`): bool

session_set_save_handler() configure les fonctions de stockage de sessions, et permet de choisir des fonctions utilisateurs pour sauver et relire toutes les sessions. Cette fonction est très pratique lorsqu'il faut sauver les données de sessions en utilisant une autre technique que le système par fichier fourni par défaut, par exemple le stockage en base de données.

### Liste de paramètres

Cette fonction a deux prototypes.

`sessionhandler`

  Une instance d'une classe implémentant une ou plusieurs des interfaces suivantes: SessionHandlerInterface, et optionnellement SessionIdInterface, et/ou SessionUpdateTimestampHandlerInterface, comme la classe SessionHandler, pour l'enregistrement comme gestionnaire de session.

`register_shutdown`

  Enregistre la fonction session_write_close() comme fonction register_shutdown_function().

ou

`open`

  Une fonction de rappel avec la signature suivante :

  function open(string `$savePath`, string `$sessionName`): bool

  La fonction de rappel `open` fonctionne comme un constructeur dans une classe, et est exécutée lorsque la session s'ouvre. C'est la première fonction de rappel exécutée lorsque la session démarre automatiquement ou manuellement avec la fonction session_start(). La valeur retournée est `true` en cas de succès ou `false` si une erreur survient.

`close`

  Une fonction de rappel avec la signature suivante :

  function close(): bool

  La fonction de rappel `close` fonctionne comme un destructeur dans une classe, et est exécutée une fois que la fonction de rappel write de la session a terminé de s'exécuter. Elle est également appelée lorsque la fonction session_write_close() est appelée. La valeur retournée est `true` en cas de succès, ou `false` si une erreur survient.

`read`

  Une fonction de rappel avec la signature suivante :

  function read(string `$sessionId`): string

  La fonction de rappel `read` doit toujours retourner une chaîne sérialisée contenant les données de session encodées ou une chaîne vide s'il n'y a aucune donnée à lire.

  Cette fonction de rappel est appelée en interne par PHP lorsque la session commence ou lorsque la fonction session_start() est appelée. Avant que cette fonction de rappel ne soit invoquée, PHP invoquera la fonction de rappel `open`.

  La valeur retournée par cette fonction de rappel doit être exactement du même format de sérialisation que celui passé pour le stockage à la fonction de rappel `write`. La valeur retournée sera désérialisée automatiquement par PHP et utilisée pour peupler la variable superglobale $_SESSION. Malgré le fait que les données ressemblent fortement aux données issues de la fonction serialize(), il est à noter que c'est bien un format différent, qui est spécifié via l'option de configuration session.serialize_handler.

`write`

  Une fonction de rappel avec la signature suivante :

  function write(string `$sessionId`, string `$data`): bool

  La fonction de rappel `write` est appelée lorsque la session doit être sauvegardée et fermée. Cette fonction de rappel reçoit l'identifiant de la session courante ainsi qu'une version sérialisée du contenu de la variable superglobale $_SESSION. La méthode de sérialisation utilisée en interne par PHP est spécifiée via l'option de configuration session.serialize_handler.

  Les données de session sérialisées passées à cette fonction de rappel doivent être stockées en utilisant l'identifiant de session fourni. Lors de la récupération de ces données, la fonction de rappel `read` doit retourner la valeur exacte, originalement passée à la fonction de rappel `write`.

  Cette fonction de rappel est invoquée lorsque PHP s'arrête ou explicitement lorsque la fonction session_write_close() est appelée. Il est à noter qu'après l'exécution de cette fonction, PHP exécutera en interne la fonction de rappel `close`.

  > Note:

  > Le gestionnaire d'écriture n'est pas exécuté tant que le flux de sortie n'aura pas été fermé. Aussi, la sortie des requêtes de débogage du gestionnaire "write" ne sera jamais affichée dans le navigateur. Si la sortie de débogage est nécessaire, il est suggéré qu'elle soit plutôt orientée dans un fichier.

`destroy`

  Une fonction de rappel avec la signature suivante :

  function destroy(string `$sessionId`): bool

  Cette fonction de rappel est exécutée lorsqu'une session est détruite avec la fonction session_destroy() ou avec session_regenerate_id() avec le paramètre de destruction défini à `true`. La valeur retournée doit être `true` en cas de succès, ou `false` si une erreur survient.

`gc`

  Une fonction de rappel avec la signature suivante :

  function gc(int `$lifetime`): bool

  La fonction de rappel de ramasse miettes (garbage collector) est invoquée en interne par PHP périodiquement afin de purger les anciennes données de session. La fréquence est contrôlée par les options de configuration session.gc_probability et session.gc_divisor. La valeur de la durée de vie passée à cette fonction de rappel peut être définie via l'option de configuration session.gc_maxlifetime. La valeur retournée doit être `true` en cas de succès, ou `false` si une erreur survient.

`create_sid`

  Une fonction de rappel avec la signature suivante :

  function create_sid(): string

  Cette fonction de rappel est exécutée lorsqu'un nouvel ID de session est nécessaire. Aucun paramètre n'est fourni, et la valeur retournée doit être une chaîne de caractères qui est un ID de session valide pour le gestionnaire.

`validate_sid`

  Une fonction de rappel avec la signature suivante :

  function validate_sid(string `$key`): bool

  Cette fonction de rappel est exécutée quand une session va démarrer, un ID de session est fourni et que session.use_strict_mode est activé. `key` est l'ID de session à valider. Un ID de session est valide, si une session avec cet ID existe déjà. La valeur de retour devrait être `true` en cas de succès, `false` en cas d'échec.

`update_timestamp`

  Une fonction de rappel avec la signature suivante :

  function update_timestamp(string `$key`, string `$val`): bool

  Cette fonction de rappel est exécutée quand une session est mise à jour. `key` est l'ID de session, `val` sont les données de session. La valeur de retour devrait être `true` en cas de succès, `false` en cas d'échec.

### Valeurs de retour

Cette fonction retourne `true` en cas de succès ou `false` si une erreur survient.

### Historique

Version | Description
--- | ---
8.4.0 | Appeler session_set_save_handler() avec plus de deux arguments est désormais obsolète. Il faut utiliser plutôt la signature à deux arguments.

### Exemples

Exemple #1 Gestionnaire de session personnalisé : voir le code complet dans la documentation sur l'interface SessionHandlerInterface.

Nous montrons juste l'invocation ici, l'exemple complet peut être vu dans la documentation de l'interface SessionHandlerInterface.

Il est à noter que nous utilisons ici le prototype orienté objet avec session_set_save_handler() et enregistrons la fonction d'arrêt en utilisant le drapeau dans le paramètre de la fonction. C'est généralement préférable lors de l'enregistrement d'objets comme gestionnaires de sauvegarde de session.

    <?php
    class MySessionHandler implements SessionHandlerInterface
    {
        // implémentation de l'interface ici
    }

    $handler = new MySessionHandler();
    session_set_save_handler($handler, true);
    session_start();

    // processus pour définir et récupérer les valeurs par leurs clés depuis $_SESSION

### Notes

Avertissement

Les gestionnaires d'écriture `write` et de fermeture `close` sont appelés après la destruction des objets, et donc, ne peuvent pas utiliser les objets ou lancer des exceptions. Les exceptions ne peuvent donc pas être attrapées ni affichées, et l'exécution ne fera que s'arrêter de façon inattendue.

Il est possible d'appeler session_write_close() depuis le destructeur pour résoudre ce problème mais la façon la plus élégante est d'enregistrer la fonction d'arrêt tel que décrit ci-dessus.

Avertissement

Le dossier de travail courant change suivant les SAPIs si la session est fermée à la fin du script. Il est possible de fermer la session plus tard, grâce à la fonction session_write_close().

### Voir aussi

- La directive de configuration session.save_handler
- La directive de configuration session.serialize_handler.
- register_shutdown_function() - Enregistre une fonction de rappel pour exécution à l'extinction
- session_register_shutdown() - Fonction de fermeture de session
- Se reporter à » save_handler.inc pour une mise en œuvre procédurale complète

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open