session_set_save_handler

(PHP 4, PHP 5, PHP 7)

session_set_save_handler — Configure les fonctions de stockage de sessions

Description

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

Depuis PHP 5.4, il est possible d'enregistrer le prototype suivant :

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.

Retour à la première page de Manuel PHP Table des matières Haut

Liste de paramètres

Cette fonction a deux prototypes.

sessionhandler: Une instance d'une classe implémentant une ou plusieurs des interfaces suivantes: SessionHandlerInterface, SessionIdInterface, SessionUpdateTimestampHandlerInterface, comme la classe SessionHandler, pour l'enregistrement comme gestionnaire de session. Depuis PHP 5.4 uniquement.
register_shutdown: Enregistre la fonction session_write_close() comme fonction register_shutdown_function().

open(string $savePath, string $sessionName)

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()

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é 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(string $sessionId)

La fonction de rappel read doit toujours retournée une chaîne linéarisé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 linéarisation que celui passé pour le stockage à la fonction de rappel write. La valeur retournée sera délinéarisé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 issuées de la fonction serialize(), notez que c'est bien un format différent, qui est spécifié via l'option de configuration session.serialize_handler.

write(string $sessionId, string $data)

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 linéarisée du contenu de la variable superglobale $_SESSION. La méthode de linéarisation utilisée en interne par PHP est spécifiée via l'option de configuration session.serialize_handler.

Les données de session linéarisées passées à cette fonction de rappel doivent être stockées en utilisant l'identifiant de session fournie. 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. Notez 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($sessionId)

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éfinie à TRUE. La valeur retournée doit être TRUE en cas de succès, ou FALSE si une erreur survient.

gc($lifetime)

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é 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()

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 votre gestionnaire.

Retour à la première page de Manuel PHP Table des matières Haut

Valeurs de retour

Cette fonction retourne TRUE en cas de succès ou FALSE si une erreur survient.

Retour à la première page de Manuel PHP Table des matières Haut

Historique

Version	Description
7.0.0	Ajout des paramètres optionnels `validate_sid` et `update_timestamp`.
5.5.1	Ajout du paramètre optionnel `create_sid`.
5.4.0	Ajout de l'interface SessionHandlerInterface pour implémenter les gestionnaires de sessions et de la classe SessionHandler pour exposer les gestionnaires de sessions internes de PHP.

Retour à la première page de Manuel PHP Table des matières Haut

Exemples

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

Le code suivant est pour PHP version 5.4.0 et supérieure. Vous pouvez y voir l'invocation, l'exemple complet peut être vu dans la documentation de l'interface SessionHandlerInterface.

Notez 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

Exemple #2 Gestionnaire de sauvegarde de session personnalisé en utilisant des objets

Le code suivant est pour PHP en version inférieure à 5.4.0.

L'exemple suivant fournit un gestionnaire de stockage des sessions basé sur les fichiers, similaire au gestionnaire de sauvegarde de session par défaut de PHP files. Cet exemple peut facilement être étendu pour couvrir le stockage par base de données, en utilisant votre moteur de base de données préféré.

Notez que nous enregistrons la fonction d'arrêt session_write_close() en utilisant la fonction register_shutdown_function() en version antérieure à PHP 5.4.0. C'est généralement préférable lors de l'enregistrement d'objets comme gestionnaires de sauvegarde des sessions sous PHP antérieure à la version 5.4.0.


<?php
class FileSessionHandler
{
    private $savePath;

    function open($savePath, $sessionName)
    {
        $this->savePath = $savePath;
        if (!is_dir($this->savePath)) {
            mkdir($this->savePath, 0777);
        }

        return true;
    }

    function close()
    {
        return true;
    }

    function read($id)
    {
        return (string)@file_get_contents("$this->savePath/sess_$id");
    }

    function write($id, $data)
    {
        return file_put_contents("$this->savePath/sess_$id", $data) === false ? false : true;
    }

    function destroy($id)
    {
        $file = "$this->savePath/sess_$id";
        if (file_exists($file)) {
            unlink($file);
        }

        return true;
    }

    function gc($maxlifetime)
    {
        foreach (glob("$this->savePath/sess_*") as $file) {
            if (filemtime($file) + $maxlifetime < time() && file_exists($file)) {
                unlink($file);
            }
        }

        return true;
    }
}

$handler = new FileSessionHandler();
session_set_save_handler(
    array($handler, 'open'),
    array($handler, 'close'),
    array($handler, 'read'),
    array($handler, 'write'),
    array($handler, 'destroy'),
    array($handler, 'gc')
    );

// Ceci permet de prévenir des effets non désirés lors de l'utilisation d'objets
// comme gestionnaires de session
register_shutdown_function('session_write_close');

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

Retour à la première page de Manuel PHP Table des matières Haut

Notes

Avertissement

Lors de l'utilisation d'objets comme gestionnaires de sauvegarde des sessions, il est important d'enregistrer la fonction d'arrêt avec PHP pour éviter les effets non désirés issus de la façon dont PHP détruit en interne les objets lors de l'arrêt, et peut empécher les fonctions de rappel write et close d'être exécutées. Typiquement, vous devez enregistrer 'session_write_close' en utilisant la fonction register_shutdown_function().

Depuis PHP 5.4.0, vous pouvez utiliser la fonction session_register_shutdown() ou simplement utiliser le drapeau 'register shutdown' lors de l'appel à la fonction session_set_save_handler() en utilisant la méthode orientée objet, et passer une instance qui implémente l'interface SessionHandlerInterface.

Avertissement

Les gestionnaires d'écriture et de fermeture sont appelés après la destruction des objets depuis PHP 5.0.5. 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 innatendue.

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().

Retour à la première page de Manuel PHP Table des matières Haut

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 pour PHP 5.4.0+
Se reporter à » save_handler.inc pour une mise en œuvre procédurales complète

Rechercher une fonction PHP

Version en cache

22/12/2024 19:22:30 Cette version de la page est en cache (à la date du 22/12/2024 19:22:30) afin d'accélérer le traitement. Vous pouvez activer le mode utilisateur dans le menu en haut pour afficher la dernère version de la page.

Document créé le 30/01/2003, dernière modification le 26/10/2018
Source du document imprimé : https://www.gaudry.be/php-rf-function.session-set-save-handler.html

L'infobrol est un site personnel dont le contenu n'engage que moi. Le texte est mis à disposition sous licence CreativeCommons(BY-NC-SA). Plus d'info sur les conditions d'utilisation et sur l'auteur.

Références

Manuel PHP : http://php.net

Ces références et liens indiquent des documents consultés lors de la rédaction de cette page, ou qui peuvent apporter un complément d'information, mais les auteurs de ces sources ne peuvent être tenus responsables du contenu de cette page.
L'auteur de ce site est seul responsable de la manière dont sont présentés ici les différents concepts, et des libertés qui sont prises avec les ouvrages de référence. N'oubliez pas que vous devez croiser les informations de sources multiples afin de diminuer les risques d'erreurs.

Table des matières Haut