Merge pull request #45 from franzliedke/fl/23-deprecate-pointless-expire-methods

Deprecate pointless cookie expiry facades

Author: simensen

README.md

@@ -150,7 +150,7 @@ $request = FigRequestCookies::modify($request, 'theme', $modify);
 
 #### Remove a Request Cookie
 
-The `remove` method removes a cookie if it exists.
+The `remove` method removes a cookie from the request headers if it exists.
 
 ```php
 use Dflydev\FigCookies\FigRequestCookies;
@@ -159,7 +159,7 @@ $request = FigRequestCookies::remove($request, 'theme');
 ```
 
 Note that this does not cause the client to remove the cookie. Take a look at
-`FigResponseCookies::expire` to do that.
+the `SetCookie` class' `expire()` method to do that.
 
 ### Response Cookies
 
@@ -261,10 +261,22 @@ $response = FigResponseCookies::remove($response, 'theme');
 The `expire` method sets a cookie with an expiry date in the far past. This
 causes the client to remove the cookie.
 
+Note that in order to expire a cookie, you need to configure its `Set-Cookie`
+header just like when you initially wrote the cookie (i.e. same domain/path).
+The easiest way to do this is to re-use the same code for configuring the
+header when setting as well as expiring the cookie:
+
 ```php
 use Dflydev\FigCookies\FigResponseCookies;
+use Dflydev\FigCookies\SetCookie;
+
+$setCookie = SetCookie::create('ba')
+    ->withValue('UQdfdafpJJ23k111m')
+    ->withPath('/')
+    ->withDomain('.example.com')
+;
 
-$response = FigResponseCookies::expire($response, 'session_cookie');
+FigResponseCookies::set($response, $setCookie->expire());
 ```
 
 

src/Dflydev/FigCookies/FigResponseCookies.php

@@ -30,6 +30,12 @@ public static function set(ResponseInterface $response, SetCookie $setCookie): R
             ->renderIntoSetCookieHeader($response);
     }
 
+    /**
+     * @deprecated Do not use this method. Will be removed in v4.0.
+     *
+     * If you want to remove a cookie, create it normally and call ->expire()
+     * on the SetCookie object.
+     */
     public static function expire(ResponseInterface $response, string $cookieName): ResponseInterface
     {
         return static::set($response, SetCookie::createExpired($cookieName));

src/Dflydev/FigCookies/SetCookie.php

@@ -239,6 +239,12 @@ public static function createRememberedForever(string $name, ?string $value = nu
         return static::create($name, $value)->rememberForever();
     }
 
+    /**
+     * @deprecated Do not use this method. Will be removed in v4.0.
+     *
+     * If you want to remove a cookie, create it normally and call ->expire()
+     * on the SetCookie object.
+     */
     public static function createExpired(string $name): self
     {
         return static::create($name)->expire();

tests/Dflydev/FigCookies/SetCookieTest.php

@@ -150,7 +150,12 @@ public function provideParsesFromSetCookieStringData(): array
      */
     public function it_expires_cookies(): void
     {
-        $setCookie = SetCookie::createExpired('expire_immediately');
+        $setCookie = SetCookie::create('HSID')
+            ->withValue('AYQEVn/.DKrdst')
+            ->withDomain('.foo.com')
+            ->withPath('/')
+            ->withHttpOnly(true)
+            ->expire();
 
         self::assertLessThan(time(), $setCookie->getExpires());
     }