Fig Cookies Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require dflydev/fig-cookies
   

2. First Use Case:

   • Reading a cookie from a PSR-7 Request:

     use Dflydev\FigCookies\FigRequestCookies;
     
     $cookie = FigRequestCookies::get($request, 'user_preference');
     $value = $cookie->getValue(); // Returns 'dark' or null
     

   • Setting a cookie in a PSR-7 Response:

     use Dflydev\FigCookies\FigResponseCookies;
     use Dflydev\FigCookies\SetCookie;
     
     $response = FigResponseCookies::set($response, SetCookie::create('theme', 'dark'));
     

Where to Look First

• Facade Methods: Start with FigRequestCookies and FigResponseCookies for simplicity.
• Primitive Classes: Use Cookie, Cookies, SetCookie, and SetCookies for granular control.
• Documentation: Focus on the README and changelog for API details.

Implementation Patterns

Common Workflows

1. Middleware for Cookie Handling:

   use Dflydev\FigCookies\FigRequestCookies;
   use Dflydev\FigCookies\FigResponseCookies;
   
   public function handle($request, Closure $next) {
       // Read a cookie
       $theme = FigRequestCookies::get($request, 'theme')->getValue();
   
       // Modify request (e.g., attach theme to request)
       $request = $request->withAttribute('theme', $theme);
   
       // Process request
       $response = $next($request);
   
       // Set a cookie based on response logic
       if ($theme === 'dark') {
           $response = FigResponseCookies::set($response, SetCookie::create('theme', 'dark')->rememberForever());
       }
   
       return $response;
   }
   

2. Service Layer for Cookie Operations:

   class CookieService {
       public function getUserPreference(Request $request): ?string {
           return FigRequestCookies::get($request, 'user_preference')->getValue();
       }
   
       public function setUserPreference(Response $response, string $preference): Response {
           return FigResponseCookies::set($response, SetCookie::create('user_preference', $preference)->rememberForever());
       }
   }
   

3. Bulk Cookie Operations:

   // Read all cookies (primitive approach)
   $cookies = Cookies::fromRequest($request);
   foreach ($cookies as $cookie) {
       // Process each cookie
   }
   
   // Set multiple cookies
   $setCookies = SetCookies::create();
   $setCookies = $setCookies->with(SetCookie::create('cookie1', 'value1'));
   $setCookies = $setCookies->with(SetCookie::create('cookie2', 'value2'));
   $response = $setCookies->renderIntoSetCookieHeader($response);
   

Integration Tips

• PSR-7 Middleware: Use FigRequestCookies/FigResponseCookies in middleware to read/write cookies without mutating the request/response directly.
• Laravel-Specific:
  • Use with Laravel's Illuminate\Http\Request and Illuminate\Http\Response by casting to PSR-7 interfaces:

    $psr7Request = new Zend\Diactoros\ServerRequest($request->createFromBase());
    $cookie = FigRequestCookies::get($psr7Request, 'key')->getValue();
    

  • For Laravel 8+, leverage Symfony\Component\HttpFoundation\Request/Response with PSR-7 adapters like nyholm/psr7.
• Immutable Design: Embrace immutability—always reassign variables after mutations (e.g., $request = FigRequestCookies::set(...)).

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Facades (FigRequestCookies, FigResponseCookies) create new Cookies/SetCookies instances and rebuild headers on every call. Avoid chaining multiple facade calls in tight loops.
   • Fix: Use primitive classes (Cookies, SetCookies) for batch operations.

2. Strict Types:

   • Since v2.0, the package enforces strict types. Ensure your codebase uses declare(strict_types=1) and update type hints (e.g., ?string for nullable values).
   • Example:

     // Old (pre-2.0)
     $cookie = Cookie::create('name', null);
     
     // New (2.0+)
     $cookie = Cookie::create('name', null); // Valid, but ensure callers handle null
     

3. Cookie Expiry:

   • Expiring a cookie requires recreating its SetCookie with the same domain/path as the original. Forgetting this causes the client to ignore the expiry.
   • Fix: Store original SetCookie configurations or recreate them identically.

4. PSR-7 Compatibility:

   • Not all PSR-7 implementations parse $_COOKIE into headers. Test with your HTTP server (e.g., Swoole, ReactPHP) to ensure cookies are correctly parsed.
   • Fix: Use a PSR-7 server that supports $_COOKIE (e.g., zend-diactoros with PHP's built-in server).

5. Facade vs. Primitive Tradeoffs:

   • Facades hide complexity but add overhead. Use primitives for:
     • Batch operations (e.g., reading all cookies).
     • Custom logic (e.g., modifying multiple cookies in one pass).
   • Example:

     // Facade (simple)
     $request = FigRequestCookies::set($request, Cookie::create('key', 'value'));
     
     // Primitive (batch)
     $cookies = Cookies::fromRequest($request);
     $cookies = $cookies->with(Cookie::create('key1', 'value1'));
     $cookies = $cookies->with(Cookie::create('key2', 'value2'));
     $request = $cookies->renderIntoCookieHeader($request);
     

Debugging Tips

1. Inspect Headers:

   • Dump headers to verify cookie parsing/rendering:

     dump($request->getHeader('Cookie')); // For request cookies
     dump($response->getHeader('Set-Cookie')); // For response cookies
     

2. Cookie String Parsing:

   • Use Cookie::listFromCookieString() to debug malformed cookie strings:

     $cookies = Cookie::listFromCookieString($request->getHeaderLine('Cookie'));
     

3. SameSite Attributes:

   • Ensure SameSite modifiers are set correctly (e.g., SameSite::lax()). Browsers enforce these strictly.
   • Example:

     $setCookie = SetCookie::create('session')
         ->withValue('abc123')
         ->withSameSite(SameSite::lax());
     

Extension Points

1. Custom Cookie Attributes:

   • Extend SetCookie to support non-standard attributes (e.g., Priority):

     class ExtendedSetCookie extends SetCookie {
         public function withPriority(string $priority): self {
             return $this->withAttribute('Priority', $priority);
         }
     }
     

2. Cookie Validation:

   • Validate cookie values before setting them:

     $validator = function (Cookie $cookie) {
         if (!preg_match('/^[a-z]+$/', $cookie->getValue())) {
             throw new \InvalidArgumentException('Invalid cookie value');
         }
         return $cookie;
     };
     $request = FigRequestCookies::modify($request, 'theme', $validator);
     

3. PSR-15 Middleware:

   • Create middleware to centralize cookie logic:

     class CookieMiddleware implements MiddlewareInterface {
         public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface {
             $request = FigRequestCookies::set($request, Cookie::create('visited', 'true'));
             return $handler->handle($request);
         }
     }
     

4. Cookie Serialization:

   • Serialize cookies for caching or logging:

     $cookies = Cookies::fromRequest($request);
     $serialized = json_encode(array_map(fn($c) => [$c->getName() => $c->getValue()], $cookies->all()));