Alpha ZealPHP is early-stage and under active development. APIs may change between minor versions until v1.0. Feedback and bug reports welcome on GitHub.
Esc
API Index — Namespaces, Packages, Reports, Indices

FileSessionHandler
in package
implements SessionHandlerInterface

File-backed \SessionHandlerInterface for ZealPHP.

Stores session data as flat files named sess_{sessionId} inside $savePath (defaults to /var/lib/php/sessions, matching the PHP-FPM convention). This handler is a direct coroutine-mode replacement for PHP's built-in file session handler — it performs standard blocking file I/O, which is coroutine-hooked under Runtime::HOOK_ALL and yields transparently.

IMPORTANT: not suitable for high-concurrency coroutine mode without an external file lock. For concurrent workloads use TableSessionHandler (the default in coroutine mode) or RedisSessionHandler. Use this handler only when you need filesystem-compatible session files, e.g. when sharing sessions with a PHP-FPM process on the same host.

Register via App::$session_handler = 'file' or by passing an instance to session_set_save_handler() before App::run().

Table of Contents

Interfaces

SessionHandlerInterface

Properties

$savePath  : string
Absolute path to the session-file directory, resolved in open().

Methods

close()  : bool
Close the session — no-op for file sessions; always returns true.
destroy()  : bool
Delete the session file for $sessionId. Always returns true — a missing file is treated as already-destroyed (idempotent).
gc()  : int
Garbage-collect session files older than $maxLifetime seconds.
open()  : bool
Open the session storage at $savePath, creating the directory if absent.
read()  : string
Read and return the raw session data string for $sessionId.
write()  : bool
Write serialised $sessionData to the session file for $sessionId.

Properties

$savePath

Absolute path to the session-file directory, resolved in open().

private string $savePath

Methods

close()

Close the session — no-op for file sessions; always returns true.

public close() : bool
Return values
bool

destroy()

Delete the session file for $sessionId. Always returns true — a missing file is treated as already-destroyed (idempotent).

public destroy(mixed $sessionId) : bool
Parameters
$sessionId : mixed
Return values
bool

gc()

Garbage-collect session files older than $maxLifetime seconds.

public gc(mixed $maxLifetime) : int

Scans $savePath/sess_* and unlinks files whose mtime is older than time() - $maxLifetime. Returns 0 (PHP's \SessionHandlerInterface contract accepts any non-negative int as "number of deleted sessions"; we return 0 rather than counting for performance).

Parameters
$maxLifetime : mixed
Return values
int

open()

Open the session storage at $savePath, creating the directory if absent.

public open(mixed $savePath, mixed $sessionName) : bool

Falls back to the system temp dir when $savePath is empty — matching PHP-FPM, which uses sys_get_temp_dir() when session.save_path is the empty-string default (#343). The prior code computed the fallback into $this->savePath but then overwrote it back to the raw (empty) $savePath on the last line, AND ran is_dir()/mkdir() on the empty value — so writes hit /sess_… at the filesystem root and failed with Permission denied, breaking session storage entirely.

Parameters
$savePath : mixed
$sessionName : mixed
Return values
bool

read()

Read and return the raw session data string for $sessionId.

public read(mixed $sessionId) : string

Returns an empty string when the session file does not exist (new session).

Parameters
$sessionId : mixed
Return values
string

write()

Write serialised $sessionData to the session file for $sessionId.

public write(mixed $sessionId, mixed $sessionData) : bool

The file is named sess_{sessionId} inside $savePath. Returns false only when file_put_contents() fails.

Parameters
$sessionId : mixed
$sessionData : mixed
Return values
bool
On this page