Cookies

Cookies are small pieces of text sent to a client's browser by your application. They help your app remember information about users' visits, which can both make it easier to visit your app and make it more useful to your users.

Leaf provides a lightweight cookie module that helps you create, delete, and interact with cookies.

Getting Started

You can install Leaf's cookie module using composer or the Leaf CLI.

Leaf CLI

leaf install cookie

Composer

composer require leafs/cookie

Setting Cookies

Since cookies are sent to the client's browser as part of the response, Leaf provides a direct way to set cookies on your response. You can directly call withCookie() on your response object to set a cookie.

response()->withCookie('name', 'Fullname');

Using this method, you can even chain multiple cookies together with your response like this:

response()
  ->withCookie('name', 'Fullname')
  ->withCookie('age', 20)
  ->json([
      'message' => 'Cookies set'
    ]);

The withCookie() method takes in 3 parameters:

• cookie name
• cookie value
• cookie expiration time (optional)

Setting Cookies with Options

response()->withCookie() is a simple way to set cookies, but it only works for the most basic use cases. If you need more control over how a cookie is set, you can use the set() method. It takes in 3 parameters:

• cookie name
• cookie value
• cookie options

cookie()->set('name', 'Fullname', [
  'expires' => time() + 3600,
  'path' => '/',
  'domain' => 'example.com',
  'secure' => true,
  'httponly' => true,
  'samesite' => 'None'
]);

The set() method allows you to set cookies with more advanced options like expiration time, path, domain, secure, httponly, and samesite which are all optional.

You can also set multiple cookies at once by passing an array of names and values. The options you pass apply to every cookie in the array.

cookie()->set([
  'name' => 'Fullname',
  'age' => 20
], '', [
  'path' => '/',
  'secure' => true
]);

If you just need a cookie with an expiry time, simpleCookie() takes a name, a value and an expiry which can be a timestamp or a strtotime()-style string like '7 days' or '1 hour'. It defaults to 7 days if you don't pass one.

cookie()->simpleCookie('name', 'Fullname', '7 days');

Setting Cookie Defaults

Instead of repeating options like path and domain on every cookie, you can set them once with setDefaults(). Any option you don't pass to set() falls back to these defaults.

cookie()->setDefaults([
  'path' => '/',
  'secure' => true,
  'httponly' => true
]);

This matters for deleting cookies too: a cookie is only removed if it's deleted with the same path and domain it was set with, and Leaf uses your configured defaults when deleting. Setting your defaults once (especially path => '/') keeps setting and deleting consistent.

Reading Cookies

When you send cookies to the client, they are stored in your users' browsers and automatically sent back to your app on every request. You can read these cookies using the cookies() method on the incoming request.

$name = request()->cookies('name');

// You can also get multiple cookies at once
$cookies = request()->cookies(['name', 'age']);
// $cookies['name'] and $cookies['age']

if a cookie doesn't exist, the cookies() method will return null for that cookie.

You can also get all cookies at once by calling cookies() without any parameters.

$cookies = request()->cookies();

This method returns an array of all cookies sent to your app. Be careful when using this method as it can return a lot of data, including cookies that you may not need.

Deleting Cookies

Deleting cookies works by letting your user's browser know that the cookie should be deleted. Once this is done, the cookie is removed from the user's browser and won't be sent back to your app. You can delete cookies using either the delete() method or withoutCookie() on your response object.

Response Object

response()->withoutCookie('name');

// It is also chainable with your response
response()
  ->withoutCookie('name')
  ->json([
      'message' => 'Cookie deleted'
    ]);

Cookie Object

cookie()->delete('name');

You may also choose to delete all your cookies, for instance if you detect an authentication or authorization breech in your application. You can do this using the deleteAll() method on Leaf cookies.

cookie()->deleteAll();