Cookies Laravel Package

Getting Started

Install the package via Composer: composer require spiral/cookies. As a read-only subtree split of Spiral Framework, it provides secure cookie handling — typically used in HTTP middleware stacks. Start by registering the Spiral\Cookies\CookieMiddleware in your middleware pipeline (e.g., in App\Kernel). Then, inject Spiral\Cookies\CookieManager to read/write cookies securely. The first use case is usually setting a signed or encrypted cookie:

$cookies = $cookieManager->withDefaultSigner(new SecretSigner($secretKey));
$cookies->set('user_pref', 'dark_mode', ttl: 86400, secure: true, httpOnly: true);

Implementation Patterns

• Middleware Layer: Use CookieMiddleware early in the stack to automatically sign/verify cookies on each request. Configure it with a CookieSigner (e.g., SecretSigner for HMAC signing or EncrypterSigner for encryption).
• Persistence & Dependency Injection: Inject CookieManager into services/controllers to manage cookies explicitly, or use CookieAwareTrait in action classes for quick access.
• Integration with Auth/Session: Often paired with authentication flows — e.g., store signed user preferences, CSRF tokens, or轻量 session IDs (not full sessions). For Laravel-style usage, wrap its manager in a custom adapter.
• Bulk Operations: Use CookieManager::batch() to attach multiple cookies in a single response without manual iteration.

Gotchas and Tips

• No Framework Coupling: This package is framework-agnostic — you must wire it manually into your HTTP kernel or request lifecycle (no Laravel/ Symfony integration out-of-the-box).
• Signing vs. Encryption: SecretSigner signs only (detects tampering); use EncrypterSigner for confidentiality. Never store sensitive data unencrypted.
• TTL/Expiration Handling: Cookies lack native "time-to-live" — TTL is encoded in the signed/encrypted payload and re-encoded on each set() call. Ensure clock synchronization across servers if using time-bound cookies.
• Debugging Failures: Failed cookie verification (e.g., InvalidSignatureException) often stems from mismatched secret keys, timezone differences, or modifying cookie values client-side. Log $_COOKIE and middleware input/output to trace.
• Extensibility: Extend CookieSignerInterface to implement custom signing logic (e.g., rotating keys, multi-tenant secrets). The CookieManager::withSigner() method allows per-request signer overrides.