{"id":21819352,"url":"https://github.com/dflydev/dflydev-fig-cookies","last_synced_at":"2025-05-14T19:01:54.574Z","repository":{"id":29436269,"uuid":"32972322","full_name":"dflydev/dflydev-fig-cookies","owner":"dflydev","description":"Cookies for PSR-7 HTTP Message Interface.","archived":false,"fork":false,"pushed_at":"2024-11-06T20:18:44.000Z","size":214,"stargazers_count":226,"open_issues_count":15,"forks_count":29,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-04-11T06:17:34.717Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dflydev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-27T07:05:09.000Z","updated_at":"2025-02-12T17:13:52.000Z","dependencies_parsed_at":"2024-12-11T18:07:44.794Z","dependency_job_id":"2b0ff973-3f6d-46dd-a729-d16068a5ce0b","html_url":"https://github.com/dflydev/dflydev-fig-cookies","commit_stats":{"total_commits":85,"total_committers":15,"mean_commits":5.666666666666667,"dds":"0.49411764705882355","last_synced_commit":"ebe6c15c9895fc490efe620ad734c8ef4a85bdb0"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dflydev%2Fdflydev-fig-cookies","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dflydev%2Fdflydev-fig-cookies/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dflydev%2Fdflydev-fig-cookies/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dflydev%2Fdflydev-fig-cookies/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dflydev","download_url":"https://codeload.github.com/dflydev/dflydev-fig-cookies/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248351394,"owners_count":21089272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-27T16:18:36.684Z","updated_at":"2025-04-11T06:17:38.435Z","avatar_url":"https://github.com/dflydev.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"FIG Cookies\n===========\n\nManaging Cookies for PSR-7 Requests and Responses.\n\n[![Latest Stable Version](https://poser.pugx.org/dflydev/fig-cookies/v/stable)](https://packagist.org/packages/dflydev/fig-cookies)\n[![Total Downloads](https://poser.pugx.org/dflydev/fig-cookies/downloads)](https://packagist.org/packages/dflydev/fig-cookies)\n[![Latest Unstable Version](https://poser.pugx.org/dflydev/fig-cookies/v/unstable)](https://packagist.org/packages/dflydev/fig-cookies)\n[![License](https://poser.pugx.org/dflydev/fig-cookies/license)](https://packagist.org/packages/dflydev/fig-cookies)\n\u003cbr\u003e\n[![Build Status](https://travis-ci.org/dflydev/dflydev-fig-cookies.svg?branch=master)](https://travis-ci.org/dflydev/dflydev-fig-cookies)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/dflydev/dflydev-fig-cookies/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/dflydev/dflydev-fig-cookies/?branch=master)\n[![Code Coverage](https://scrutinizer-ci.com/g/dflydev/dflydev-fig-cookies/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/dflydev/dflydev-fig-cookies/?branch=master)\n[![Code Climate](https://codeclimate.com/github/dflydev/dflydev-fig-cookies/badges/gpa.svg)](https://codeclimate.com/github/dflydev/dflydev-fig-cookies)\n\u003cbr\u003e\n[![Join the chat at https://gitter.im/dflydev/dflydev-fig-cookies](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dflydev/dflydev-fig-cookies?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n\nInstallation\n------------\n\n```bash\n$\u003e composer require dflydev/fig-cookies\n```\n\n\nConcepts\n--------\n\nFIG Cookies tackles two problems, managing **Cookie** *Request* headers and\nmanaging **Set-Cookie** *Response* headers. It does this by way of introducing\na `Cookies` class to manage collections of `Cookie` instances and a\n`SetCookies` class to manage collections of `SetCookie` instances.\n\nInstantiating these collections looks like this:\n\n```php\n// Get a collection representing the cookies in the Cookie headers\n// of a PSR-7 Request.\n$cookies = Dflydev\\FigCookies\\Cookies::fromRequest($request);\n\n// Get a collection representing the cookies in the Set-Cookie headers\n// of a PSR-7 Response\n$setCookies = Dflydev\\FigCookies\\SetCookies::fromResponse($response);\n```\n\nAfter modifying these collections in some way, they are rendered into a\nPSR-7 Request or PSR-7 Response like this:\n\n```php\n// Render the Cookie headers and add them to the headers of a\n// PSR-7 Request.\n$request = $cookies-\u003erenderIntoCookieHeader($request);\n\n// Render the Set-Cookie headers and add them to the headers of a\n// PSR-7 Response.\n$response = $setCookies-\u003erenderIntoSetCookieHeader($response);\n```\n\nLike PSR-7 Messages, `Cookie`, `Cookies`, `SetCookie`, and `SetCookies`\nare all represented as immutable value objects and all mutators will\nreturn new instances of the original with the requested changes.\n\nWhile this style of design has many benefits it can become fairly\nverbose very quickly. In order to get around that, FIG Cookies provides\ntwo facades in an attempt to help simplify things and make the whole process\nless verbose.\n\n\nBasic Usage\n-----------\n\nThe easiest way to start working with FIG Cookies is by using the\n`FigRequestCookies` and `FigResponseCookies` classes. They are facades to the\nprimitive FIG Cookies classes. Their jobs are to make common cookie related\ntasks easier and less verbose than working with the primitive classes directly.\n\nThere is overhead on creating `Cookies` and `SetCookies` and rebuilding\nrequests and responses. Each of the `FigCookies` methods will go through this\nprocess so be wary of using too many of these calls in the same section of\ncode. In some cases it may be better to work with the primitive FIG Cookies\nclasses directly rather than using the facades.\n\n\n### Request Cookies\n\nRequests include cookie information in the **Cookie** request header. The\ncookies in this header are represented by the `Cookie` class.\n\n```php\nuse Dflydev\\FigCookies\\Cookie;\n\n$cookie = Cookie::create('theme', 'blue');\n```\n\nTo easily work with request cookies, use the `FigRequestCookies` facade.\n\n#### Get a Request Cookie\n\nThe `get` method will return a `Cookie` instance. If no cookie by the specified\nname exists, the returned `Cookie` instance will have a `null` value.\n\nThe optional third parameter to `get` sets the value that should be used if a\ncookie does not exist.\n\n```php\nuse Dflydev\\FigCookies\\FigRequestCookies;\n\n$cookie = FigRequestCookies::get($request, 'theme');\n$cookie = FigRequestCookies::get($request, 'theme', 'default-theme');\n```\n\n#### Set a Request Cookie\n\nThe `set` method will either add a cookie or replace an existing cookie.\n\nThe `Cookie` primitive is used as the second argument.\n\n```php\nuse Dflydev\\FigCookies\\FigRequestCookies;\n\n$request = FigRequestCookies::set($request, Cookie::create('theme', 'blue'));\n```\n\n#### Modify a Request Cookie\n\nThe `modify` method allows for replacing the contents of a cookie based on the\ncurrent cookie with the specified name. The third argument is a `callable` that\ntakes a `Cookie` instance as its first argument and is expected to return a\n`Cookie` instance.\n\nIf no cookie by the specified name exists, a new `Cookie` instance with a\n`null` value will be passed to the callable.\n\n```php\nuse Dflydev\\FigCookies\\FigRequestCookies;\n\n$modify = function (Cookie $cookie) {\n    $value = $cookie-\u003egetValue();\n\n    // ... inspect current $value and determine if $value should\n    // change or if it can stay the same. in all cases, a cookie\n    // should be returned from this callback...\n\n    return $cookie-\u003ewithValue($value);\n}\n\n$request = FigRequestCookies::modify($request, 'theme', $modify);\n```\n\n#### Remove a Request Cookie\n\nThe `remove` method removes a cookie from the request headers if it exists.\n\n```php\nuse Dflydev\\FigCookies\\FigRequestCookies;\n\n$request = FigRequestCookies::remove($request, 'theme');\n```\n\nNote that this does not cause the client to remove the cookie. Take a look at\nthe `SetCookie` class' `expire()` method to do that.\n\n### Response Cookies\n\nResponses include cookie information in the **Set-Cookie** response header. The\ncookies in these headers are represented by the `SetCookie` class.\n\n```php\nuse Dflydev\\FigCookies\\Modifier\\SameSite;\nuse Dflydev\\FigCookies\\SetCookie;\n\n$setCookie = SetCookie::create('lu')\n    -\u003ewithValue('Rg3vHJZnehYLjVg7qi3bZjzg')\n    -\u003ewithExpires('Tue, 15-Jan-2013 21:47:38 GMT')\n    -\u003ewithMaxAge(500)\n    -\u003erememberForever()\n    -\u003ewithPath('/')\n    -\u003ewithDomain('.example.com')\n    -\u003ewithSecure(true)\n    -\u003ewithHttpOnly(true)\n    -\u003ewithSameSite(SameSite::lax())\n;\n```\n\nTo easily work with response cookies, use the `FigResponseCookies` facade.\n\n#### Get a Response Cookie\n\nThe `get` method will return a `SetCookie` instance. If no cookie by the\nspecified name exists, the returned `SetCookie` instance will have a `null`\nvalue.\n\nThe optional third parameter to `get` sets the value that should be used if a\ncookie does not exist.\n\n```php\nuse Dflydev\\FigCookies\\FigResponseCookies;\n\n$setCookie = FigResponseCookies::get($response, 'theme');\n$setCookie = FigResponseCookies::get($response, 'theme', 'simple');\n```\n\n#### Set a Response Cookie\n\nThe `set` method will either add a cookie or replace an existing cookie.\n\nThe `SetCookie` primitive is used as the second argument.\n\n```php\nuse Dflydev\\FigCookies\\FigResponseCookies;\n\n$response = FigResponseCookies::set($response, SetCookie::create('token')\n    -\u003ewithValue('a9s87dfz978a9')\n    -\u003ewithDomain('example.com')\n    -\u003ewithPath('/firewall')\n);\n```\n\n#### Modify a Response Cookie\n\nThe `modify` method allows for replacing the contents of a cookie based on the\ncurrent cookie with the specified name. The third argument is a `callable` that\ntakes a `SetCookie` instance as its first argument and is expected to return a\n`SetCookie` instance.\n\nIf no cookie by the specified name exists, a new `SetCookie` instance with a\n`null` value will be passed to the callable.\n\n```php\nuse Dflydev\\FigCookies\\FigResponseCookies;\n\n$modify = function (SetCookie $setCookie) {\n    $value = $setCookie-\u003egetValue();\n\n    // ... inspect current $value and determine if $value should\n    // change or if it can stay the same. in all cases, a cookie\n    // should be returned from this callback...\n\n    return $setCookie\n        -\u003ewithValue($newValue)\n        -\u003ewithExpires($newExpires)\n    ;\n}\n\n$response = FigResponseCookies::modify($response, 'theme', $modify);\n```\n\n#### Remove a Response Cookie\n\nThe `remove` method removes a cookie from the response if it exists.\n\n```php\nuse Dflydev\\FigCookies\\FigResponseCookies;\n\n$response = FigResponseCookies::remove($response, 'theme');\n```\n\n#### Expire a Response Cookie\n\nThe `expire` method sets a cookie with an expiry date in the far past. This\ncauses the client to remove the cookie.\n\nNote that in order to expire a cookie, you need to configure its `Set-Cookie`\nheader just like when you initially wrote the cookie (i.e. same domain/path).\nThe easiest way to do this is to re-use the same code for configuring the\nheader when setting as well as expiring the cookie:\n\n```php\nuse Dflydev\\FigCookies\\FigResponseCookies;\nuse Dflydev\\FigCookies\\SetCookie;\n\n$setCookie = SetCookie::create('ba')\n    -\u003ewithValue('UQdfdafpJJ23k111m')\n    -\u003ewithPath('/')\n    -\u003ewithDomain('.example.com')\n;\n\nFigResponseCookies::set($response, $setCookie-\u003eexpire());\n```\n\n\nFAQ\n---\n\n### Do you call `setcookies`?\n\nNo.\n\nDelivery of the rendered `SetCookie` instances is the responsibility of the\nPSR-7 client implementation.\n\n\n### Do you do anything with sessions?\n\nNo.\n\nIt would be possible to build session handling using cookies on top of FIG\nCookies but it is out of scope for this package.\n\n\n### Do you read from `$_COOKIES`?\n\nNo.\n\nFIG Cookies only pays attention to the `Cookie` headers on\n[PSR-7](https://packagist.org/packages/psr/http-message) Request\ninstances. In the case of `ServerRequestInterface` instances, PSR-7\nimplementations should be including `$_COOKIES` values in the headers\nso in that case FIG Cookies may be interacting with `$_COOKIES`\nindirectly.\n\n\nLicense\n-------\n\nMIT, see LICENSE.\n\n\nCommunity\n---------\n\nWant to get involved? Here are a few ways:\n\n * Find us in the #dflydev IRC channel on irc.freenode.org.\n * Mention [@dflydev](https://twitter.com/dflydev) on Twitter.\n * [![Join the chat at https://gitter.im/dflydev/dflydev-fig-cookies](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dflydev/dflydev-fig-cookies?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdflydev%2Fdflydev-fig-cookies","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdflydev%2Fdflydev-fig-cookies","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdflydev%2Fdflydev-fig-cookies/lists"}