{"id":18576107,"url":"https://github.com/thiagodp/cors","last_synced_at":"2025-04-10T08:31:03.183Z","repository":{"id":65392422,"uuid":"591541195","full_name":"thiagodp/cors","owner":"thiagodp","description":"🔌 CORS middleware for phputil/router","archived":false,"fork":false,"pushed_at":"2025-02-26T22:38:49.000Z","size":64,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T19:02:53.063Z","etag":null,"topics":["cors","express","php","router"],"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/thiagodp.png","metadata":{"files":{"readme":"readme.md","changelog":null,"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":"2023-01-21T02:54:46.000Z","updated_at":"2025-02-26T22:38:53.000Z","dependencies_parsed_at":"2025-01-07T15:03:36.165Z","dependency_job_id":"dfbd65c8-d814-45f3-81b4-3a8487544f4b","html_url":"https://github.com/thiagodp/cors","commit_stats":{"total_commits":9,"total_committers":2,"mean_commits":4.5,"dds":"0.11111111111111116","last_synced_commit":"8bb8c1eba105c2351b7274fc31c8cabb4354dcc7"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiagodp%2Fcors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiagodp%2Fcors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiagodp%2Fcors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiagodp%2Fcors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thiagodp","download_url":"https://codeload.github.com/thiagodp/cors/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248185323,"owners_count":21061495,"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":["cors","express","php","router"],"created_at":"2024-11-06T23:23:36.280Z","updated_at":"2025-04-10T08:31:03.172Z","avatar_url":"https://github.com/thiagodp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Version](https://poser.pugx.org/phputil/cors/v?style=flat-square)](https://packagist.org/packages/phputil/cors)\n![Build](https://github.com/thiagodp/cors/actions/workflows/ci.yml/badge.svg?style=flat)\n[![License](https://poser.pugx.org/phputil/cors/license?style=flat-square)](https://packagist.org/packages/phputil/cors)\n\n# phputil/cors\n\n\u003e 🔌 CORS middleware for [phputil/router](https://github.com/thiagodp/router)\n\n- Unit-tested ✔\n- Well-documented 📖\n- Syntax compatible with [expressjs/cors](https://github.com/expressjs/cors) 🎯\n\n## Installation\n\n\u003e Requires phputil/router **v0.2.14+**\n\n```bash\ncomposer require phputil/cors\n```\n\n## Usage\n\n### Basic usage\n\n```php\nrequire_once 'vendor/autoload.php';\nuse phputil\\router\\Router;\nuse function phputil\\cors\\cors; // Step 1: Declare the namespace usage for the function.\n$app = new Router();\n\n$app-\u003euse( cors() ); // Step 2: Invoke the function to use it as a middleware.\n\n$app-\u003eget( '/', function( $req, $res ) {\n    $res-\u003esend( 'Hello' );\n} );\n$app-\u003elisten();\n```\n\n## API\n\n```php\nfunction cors( array|CorOptions $options ): callable;\n```\n`$options` can be an **array** or an **object** from the class `CorOptions`. All its keys/attributes are **optional**:\n\n### `origin: bool|string|string[]`\n- Configures the response header [`Access-Control-Allow-Origin`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin), which indicates the allowed origin.\n- `true`, **the default value**, reflects the `Origin` request header - that is, it **allows any origin**.\n- `false` makes it to return `'*'` as the header value.\n- A non-empty `string` (e.g. `'https://example.com'`) restricts the origin to the defined value. An origin must contain the protocol (e.g. `http`/`https`), and the port (e.g. `:8080`) when the port is different from the default for the protocol (`80` for http, `443` for https).\n- A non-empty `array` indicates the list of allowed origins.\n- When the `Origin` request header _is not sent_ and the option `origin` is `true`, it will return `*` - aiming to accept any origin (which may not work on httpS or using credentials). Other options will block the request.\n- Using `*` will probably not work when using credentials or httpS. Therefore, make sure to include the allowed origins.\n\nNote: The status code returned for an origin that is not in the allowed list is `403` (Forbidden).\n\n### `credentials: bool`\n- Configures the response header [`Access-Control-Allow-Credentials`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials).\n- `true`, **the default value**, makes it to include the header.\n- `false` makes it to omit the header.\n- This option is needed if your application uses cookies or some kind of authentication header.\n- _Bonus tip_: If you are using `fetch()` in your front-end (JavaScript), make sure to set `credentials: 'include'` (when cross-origin) or `credentials: 'same-origin` to your request options.\n\n### `methods: string|string[]`\n- Configures the response header [`Access-Control-Allow-Methods`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods).\n- The **default value** is `GET,HEAD,OPTIONS,POST,PUT,DELETE,PATCH` when the request header `Access-Control-Request-Method` is _not_ defined.\n- When the request header `Access-Control-Request-Method` is defined, the response header `Access-Control-Allow-Methods` will return the received method, unless the option `methods` is defined.\n- HTTP methods in a `string` must be separated by **comma**.\n\n### `allowedHeaders: string|string[]`\n- Configures the response header [`Access-Control-Allow-Headers`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers).\n- The **default value** is `'*'`, meaning to accept any request header.\n- The value `*` only counts as a special wildcard value for requests without credentials (e.g. cookies, authorization headers). Therefore, change it if your application needs credentials.\n- HTTP headers in a `string` must be separated by **comma**.\n\n### `exposedHeaders: string|string[]`\n- Configures the response header [`Access-Control-Expose-Headers`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers).\n- The **default value** is `''` (empty string), meaning to not include the header.\n- HTTP headers in a `string` must be separated by **comma**.\n- If your application needs credentials (e.g. cookies, authentication headers), you probably should configure it.\n\n### `maxAge: int|null`\n- Configures the response header [`Access-Control-Max-Age`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age).\n- The **default value** is `null`, meaning to not include the header.\n- An `int` value means the number of seconds that a preflight request can be cached (by the browser).\n\n\n## Example\n\nUsing an array:\n\n```php\n$options = [\n    'origin' =\u003e 'mydomain.com',\n    'methods' =\u003e 'GET,POST'\n];\n\n$app-\u003euse( cors( $options ) );\n```\n\nUsing the class `CorOptions`, that has nestable builder methods with the prefix `with`:\n\n```php\nuse phputil\\cors\\CorsOptions; // Needed\n\n$options = ( new CorsOptions() )\n    -\u003ewithOrigin( 'mydomain.com' )\n    -\u003ewithMethods( 'GET,POST' );\n\n$app-\u003euse( cors( $options ) );\n```\n\n## Additional examples\n\nAccepting credentials (e.g. cookies) and cross-site requests from authorized domains:\n\n```php\n$options = [\n    'origin'            =\u003e [ 'https://my-app.com', 'https://authorized-domain.com' ], // Replace with your trusted domains\n    'credentials'       =\u003e true,\n    'allowedHeaders'    =\u003e [ 'Accept', 'Authorization', 'Cookie', 'Content-Length', 'Content-Type', 'Host', 'Origin', 'Referer' ],\n    'exposeHeaders'     =\u003e [ 'Content-Length', 'Content-Type', 'Set-Cookie' ],\n    'maxAge'            =\u003e 3600 // Cache Preflight requests for 1 hour\n];\n\n$app-\u003euse( cors( $options ) );\n```\n\n## License\n\n[MIT](LICENSE) © [Thiago Delgado Pinto](https://github.com/thiagodp)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthiagodp%2Fcors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthiagodp%2Fcors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthiagodp%2Fcors/lists"}