Home

InitPHP Cookies — Wiki

Welcome to the official documentation for initphp/cookies — a signed, tamper-evident cookie manager for PHP. Your values live in a single browser cookie whose payload is authenticated with an HMAC-SHA256 signature, so a client can read it but cannot forge or alter it. Each value can carry its own time-to-live, and writes are staged in memory and flushed with one call.

The package ships three types:

Type	Purpose
Cookie	The default concrete implementation (final).
CookieInterface	The contract — type-hint this in your services.
CookieInvalidArgumentException	Thrown on an invalid name/salt, value, or TTL.

composer require initphp/cookies

use InitPHP\Cookies\Cookie;

// The salt is the HMAC secret — keep it private and stable across requests.
$cookie = new Cookie('app_session', getenv('COOKIE_SALT'));

$cookie->set('user_id', 42);
$cookie->set('flash', 'Saved!', 60); // expires in 60 seconds

$cookie->send(); // write the staged changes before any output

On the next request:

$cookie = new Cookie('app_session', getenv('COOKIE_SALT'));

$cookie->has('user_id');      // true
$cookie->get('user_id');      // 42 (int — scalar types are preserved)
$cookie->pull('flash');       // reads the value once, then removes it
$cookie->get('missing', '-'); // '-' (default)

Start here

• New to the package? Read Installation, then Quick Start.
• Storing values? See Basic Usage and TTL & Expiry.
• Reading, clearing, deleting? Read Reading & Removing.
• When does a cookie actually get written? Read Sending & Lifecycle.
• What does the signature protect (and not)? Read the Security Model.
• Keeping a user signed in? Read the Remember Me recipe.
• Upgrading from 1.x? Read Migration (v1 → v2).
• Looking for a specific method? The full API Reference lists every public member.

At a glance — capabilities

Capability	Supported
HMAC-SHA256 signed payload	✅
Constant-time verification (hash_equals)	✅
Object-injection-safe deserialization (allowed_classes => false)	✅
Tamper → discard & re-issue clean	✅
Per-key time-to-live	✅
Many values under one named cookie	✅
Deferred writes (stage in memory, one send())	✅
Scalar type preservation (int/float/bool/string)	✅
Injectable cookie source & writer (for tests)	✅
Confidentiality / encryption of values	❌ (integrity only — see Security Model)

Package metadata

• License: MIT
• Minimum PHP: 7.4 (also tested on 8.0 – 8.4)
• Runtime dependency: initphp/parameterbag ^2.0
• Packagist: initphp/cookies
• Source: github.com/InitPHP/Cookies
• Issues: github.com/InitPHP/Cookies/issues
• Discussions: github.com/orgs/InitPHP/discussions
• Security: SECURITY.md

Integrity, not secrecy. Signing proves a cookie was issued by you and has not been altered; it does not hide the values from the client. Never store secrets in a cookie — see the Security Model.

If something in this wiki is unclear, ambiguous, or wrong, please open an issue — documentation fixes are reviewed eagerly.