{"id":14966460,"url":"https://github.com/yiisoft/proxy-middleware","last_synced_at":"2025-08-02T02:34:12.394Z","repository":{"id":169267790,"uuid":"640537436","full_name":"yiisoft/proxy-middleware","owner":"yiisoft","description":"Middleware to set request parameters based on headers provided by proxy","archived":false,"fork":false,"pushed_at":"2025-03-20T10:51:19.000Z","size":77,"stargazers_count":7,"open_issues_count":4,"forks_count":0,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-07-10T20:44:21.840Z","etag":null,"topics":["forwarded","load-balancer","middleware","proxy","psr-15","yii3"],"latest_commit_sha":null,"homepage":"https://www.yiiframework.com","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yiisoft.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"open_collective":"yiisoft","github":["yiisoft"]}},"created_at":"2023-05-14T12:30:17.000Z","updated_at":"2025-03-20T10:51:23.000Z","dependencies_parsed_at":"2024-04-15T09:05:26.679Z","dependency_job_id":"67067958-0724-4a06-aa50-a1f408169591","html_url":"https://github.com/yiisoft/proxy-middleware","commit_stats":{"total_commits":24,"total_committers":6,"mean_commits":4.0,"dds":0.5833333333333333,"last_synced_commit":"474feb076ffcb04070c8333b119f012939eeb002"},"previous_names":["yiisoft/proxy-middleware"],"tags_count":3,"template":false,"template_full_name":"yiisoft/package-template","purl":"pkg:github/yiisoft/proxy-middleware","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiisoft%2Fproxy-middleware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiisoft%2Fproxy-middleware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiisoft%2Fproxy-middleware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiisoft%2Fproxy-middleware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yiisoft","download_url":"https://codeload.github.com/yiisoft/proxy-middleware/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yiisoft%2Fproxy-middleware/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265940463,"owners_count":23852822,"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":["forwarded","load-balancer","middleware","proxy","psr-15","yii3"],"created_at":"2024-09-24T13:36:24.996Z","updated_at":"2025-08-02T02:34:12.347Z","avatar_url":"https://github.com/yiisoft.png","language":"PHP","funding_links":["https://opencollective.com/yiisoft","https://github.com/sponsors/yiisoft"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/yiisoft\" target=\"_blank\"\u003e\n        \u003cimg src=\"https://yiisoft.github.io/docs/images/yii_logo.svg\" height=\"100px\" alt=\"Yii\"\u003e\n    \u003c/a\u003e\n    \u003ch1 align=\"center\"\u003eYii Proxy Middleware\u003c/h1\u003e\n    \u003cbr\u003e\n\u003c/p\u003e\n\n[![Latest Stable Version](https://poser.pugx.org/yiisoft/proxy-middleware/v)](https://packagist.org/packages/yiisoft/proxy-middleware)\n[![Total Downloads](https://poser.pugx.org/yiisoft/proxy-middleware/downloads)](https://packagist.org/packages/yiisoft/proxy-middleware)\n[![Build status](https://github.com/yiisoft/proxy-middleware/actions/workflows/build.yml/badge.svg)](https://github.com/yiisoft/proxy-middleware/actions/workflows/build.yml)\n[![Code Coverage](https://codecov.io/gh/yiisoft/proxy-middleware/branch/master/graph/badge.svg)](https://codecov.io/gh/yiisoft/proxy-middleware)\n[![Mutation testing badge](https://img.shields.io/endpoint?style=flat\u0026url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fyiisoft%2Fproxy-middleware%2Fmaster)](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/proxy-middleware/master)\n[![static analysis](https://github.com/yiisoft/proxy-middleware/workflows/static%20analysis/badge.svg)](https://github.com/yiisoft/proxy-middleware/actions?query=workflow%3A%22static+analysis%22)\n[![type-coverage](https://shepherd.dev/github/yiisoft/proxy-middleware/coverage.svg)](https://shepherd.dev/github/yiisoft/proxy-middleware)\n[![psalm-level](https://shepherd.dev/github/yiisoft/proxy-middleware/level.svg)](https://shepherd.dev/github/yiisoft/proxy-middleware)\n\nThe package provides proxy related middleware classes that implement\n[PSR-15](https://www.php-fig.org/psr/psr-15/#12-middleware):\n\n- [`TrustedHeaderProtocolResolver`](#trustedheaderprotocolresolver).\n- [`TrustedHostsNetworkResolver`](#trustedhostsnetworkresolver).\n\nFor other miscellaneous middleware, there is a separate package -\n[Yii Middleware](https://github.com/yiisoft/yii-middleware).\n\nFor more information on how to use middleware in the [Yii Framework](https://www.yiiframework.com/), see the\n[Yii middleware guide](https://github.com/yiisoft/docs/blob/master/guide/en/structure/middleware.md).\n\n## Requirements\n\n- PHP 8.0 or higher.\n\n## Installation\n\nThe package could be installed with [Composer](https://getcomposer.org):\n\n```shell\ncomposer require yiisoft/proxy-middleware\n```\n\n## General usage\n\n### `TrustedHeaderProtocolResolver`\n\nTrusted header protocol resolver sets a server request protocol based on special header you trust\nsuch as `X-Forwarded-Proto`.\n\nYou can use it if your server is behind a trusted load balancer or a proxy that's always setting the special header\nitself discarding any header values provided by user.\n\n```php\nuse Yiisoft\\Yii\\Middleware\\TrustedHeaderProtocolResolver;\n\n/**\n * @var Psr\\Http\\Message\\ServerRequestInterface $request\n * @var Psr\\Http\\Server\\RequestHandlerInterface $handler\n */\n\n$middleware = new TrustedHeaderProtocolResolver();\n\n$middleware = $middleware-\u003ewithAddedProtocolHeader('x-forwarded-proto', [\n    'http' =\u003e ['http'],\n    'https' =\u003e ['https', 'on'],\n]);\n// Disable earlier settings:\n$middleware = $middleware-\u003ewithoutProtocolHeader('x-forwarded-proto');\n\n$response = $middleware-\u003eprocess($request, $handler);\n```\n\n### `TrustedHostsNetworkResolver`\n\nScans the entire connection chain and resolves the data from forwarded headers taking into account trusted IPs.\nAdditionally, all items' structure is thoroughly validated because headers' data can't be trusted. The following data is\nresolved:\n\n- IP.\n- Protocol\n- Host.\n- Port.\n- IP identifier - [unknown](https://datatracker.ietf.org/doc/html/rfc7239#section-6.2) or\n[obfuscated](https://datatracker.ietf.org/doc/html/rfc7239#section-6.3). Used with `Forwarded` RFC header.\n\nThe typical use case is having an application behind a load balancer.\n\n#### Trusted IPs\n\nA list of trusted IPs from connection chain.\n\nProxies' IPs including the one in `$_SERVER['REMOTE_ADDR']` must be specified here. For example, for\n`$_SERVER['REMOTE_ADDR']` with value `18.18.18.18` and 2 other proxies - `2.2.2.2` and `8.8.8.8`, the configuration will\nbe:\n\n```php\nuse Yiisoft\\ProxyMiddleware\\TrustedHostsNetworkResolver;\n\n/** @var TrustedHostsNetworkResolver $middleware */\n$middleware = $middleware-\u003ewithTrustedIps([['8.8.8.8', '2.2.2.2', '18.18.18.18']]);\n```\n\nThe order of IPs is not important.\n\n#### Forwarded header groups\n\nHeader groups to parse the data from. By including headers in this list, they are trusted automatically.\n\nThe default is:\n\n```php\nuse Yiisoft\\ProxyMiddleware\\TrustedHostsNetworkResolver;\n\n/** @var TrustedHostsNetworkResolver $middleware */\n$middleware = $middleware-\u003ewithForwardedHeaderGroups([    \n    TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_RFC,\n    TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_X_PREFIX,           \n]);\n```\n\nwhich is an alternative/shorter way of writing this:\n\n```php\nuse Yiisoft\\ProxyMiddleware\\TrustedHostsNetworkResolver;\n\n/** @var TrustedHostsNetworkResolver $middleware */\n$middleware = $middleware-\u003ewithForwardedHeaderGroups([    \n    'forwarded',\n    [\n        'ip' =\u003e 'x-forwarded-for',\n        'protocol' =\u003e 'x-forwarded-proto',\n        'host' =\u003e 'x-forwarded-host',\n        'port' =\u003e 'x-forwarded-port',    \n    ],           \n]);\n```\n\nThe accepted values are:\n\n- `TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_RFC` string constant. Parse all data from single `Forwarded`\nheader according to [RFC 7239](https://datatracker.ietf.org/doc/html/rfc7239).\n- Array. Parse data from separate forwarded headers with \"X\" prefix. Unlike with RFC variation, each header stores only\none data unit (for example, IP). Headers with \"X\" prefix are quite common despite being non-standard:\n  - [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) - IP.\n  - [X-Forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto) - protocol.\n  - [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host) - host.\n  - `X-Forwarded-Port` - port.\n\nThe header groups are processed in the order they are defined. If the header containing IP is present and is non-empty,\nthis group will be selected and further ones will be ignored.\n\nYou can add support for custom headers and/or change priority:\n\n```php\nuse Yiisoft\\ProxyMiddleware\\TrustedHostsNetworkResolver;\n\n/** @var TrustedHostsNetworkResolver $middleware */\n$middleware = $middleware-\u003ewithForwardedHeaderGroups([    \n    [\n        'ip' =\u003e 'y-forwarded-for',\n        'protocol' =\u003e 'y-forwarded-proto',\n        'host' =\u003e 'y-forwarded-host',\n        'port' =\u003e 'y-forwarded-port',    \n    ],\n    TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_X_PREFIX,    \n    TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_RFC,               \n]);\n```\n\nFor protocol, it's also possible to resolve non-standard values via mapping:\n\n```php\nuse Yiisoft\\ProxyMiddleware\\TrustedHostsNetworkResolver;\n\n/** @var TrustedHostsNetworkResolver $middleware */\n$middleware = $middleware-\u003ewithForwardedHeaderGroups([\n    TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_RFC,    \n    [\n        'ip' =\u003e 'y-forwarded-for',\n        'protocol' =\u003e [\n            'front-end-https', \n            ['on' =\u003e 'https'],\n        ],\n        'host' =\u003e 'y-forwarded-host',\n        'port' =\u003e 'y-forwarded-port',    \n    ],\n    TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_X_PREFIX,               \n]);\n```\n\nor via callable:\n\n```php\nuse Yiisoft\\ProxyMiddleware\\TrustedHostsNetworkResolver;\n\n/** @var TrustedHostsNetworkResolver $middleware */\n$middleware = $middleware-\u003ewithForwardedHeaderGroups([\n    TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_RFC,    \n    [\n        'ip' =\u003e 'y-forwarded-for',\n        'protocol' =\u003e [\n            'front-end-https', \n            static fn (string $protocol): ?string =\u003e $protocol === 'On' ? 'https': 'http',,\n        ],\n        'host' =\u003e 'y-forwarded-host',\n        'port' =\u003e 'y-forwarded-port',    \n    ],\n    TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_X_PREFIX,               \n]);\n```\n\nIt's also a good idea to limit default header groups to the only guaranteed sources of data:\n\n```php\nuse Yiisoft\\ProxyMiddleware\\TrustedHostsNetworkResolver;\n\n/** @var TrustedHostsNetworkResolver $middleware */\n$middleware = $middleware-\u003ewithForwardedHeaderGroups([    \n    TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_RFC,           \n]);\n```\n\n#### Typical forwarded headers\n\nList of headers that are considered related to forwarding.\n\nThe default is:\n\n```php\nuse Yiisoft\\ProxyMiddleware\\TrustedHostsNetworkResolver;\n\n/** @var TrustedHostsNetworkResolver $middleware */\n$middleware = $middleware-\u003ewithTypicalForwardedHeaders([\n    // RFC\n    'forwarded',\n\n    // \"X\" prefix\n    'x-forwarded-for',\n    'x-forwarded-host',\n    'x-forwarded-proto',\n    'x-forwarded-port',\n\n    // Microsoft\n    'front-end-https',\n]);\n```\n\nThe headers that are present in this list but missing in a matching forwarded header group will be deleted from request\nbecause they are potentially not secure and likely were not passed by a proxy server.\n\nFor example, with default forwarded header groups' setup used as well:\n\n```php\nuse Yiisoft\\ProxyMiddleware\\TrustedHostsNetworkResolver;\n\n/** @var TrustedHostsNetworkResolver $middleware */\n$middleware = $middleware-\u003ewithForwardedHeaderGroups([\n    TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_RFC,\n    TrustedHostsNetworkResolver::FORWARDED_HEADER_GROUP_X_PREFIX,\n]);\n```\n\nand with the following request headers passed:\n\n```php\n[\n    'Forwarded' =\u003e [\n        'for=\"9.9.9.9:8013\";proto=http;host=example13.com',\n        'for=\"8.8.8.8:8012\";proto=http;host=example12.com',\n        'for=\"2.2.2.2:8011\";proto=http;host=example11.com',\n    ],\n    'X-Forwarded-For' =\u003e 'not-secure',\n    'X-Forwarded-Host' =\u003e 'not-secure',\n    'X-Forwarded-Proto' =\u003e 'not-secure',\n    'X-Forwarded-Port' =\u003e 'not-secure',\n    'Front-End-Https' =\u003e 'not-secure',\n    'Non-Forwarded' =\u003e 'not-typical',\n];\n```\n\nmiddleware will remove these headers from request:\n\n- `x-forwarded-for`.\n- `x-forwarded-host`.\n- `x-forwarded-proto`.\n- `x-forwarded-port`.\n- `front-end-https`.\n\nbecause RFC group is matching and the rest can't be trusted. The headers that are not declared as typical forwarded\nheaders will be left as is (`Non-Forwarded` in the example above).\n\n#### Accessing resolved data\n\nResolved IP is saved to a special request's attribute:\n\n```php\nuse Psr\\Http\\Message\\ServerRequestInterface;\n\n/** @var ServerRequestInterface $request */\n$ip = $request-\u003egetAttribute(TrustedHostsNetworkResolver::ATTRIBUTE_REQUEST_CLIENT_IP);\n```\n\nThere is an additional attribute allowing to retrieve all previous validated and trusted connection chain items. It\nneeds explicit configuration:\n\n```php\nuse Psr\\Http\\Message\\ServerRequestInterface;\nuse Yiisoft\\ProxyMiddleware\\TrustedHostsNetworkResolver;\n\n/** @var TrustedHostsNetworkResolver $middleware */\n$middleware = $middleware-\u003ewithConnectionChainItemsAttribute('connectionChainItems');\n// ...\n/** @var ServerRequestInterface $request */\n$connectionChainItems = $request-\u003egetAttribute('connectionChainItems');\n```\n\nAn example of contents:\n\n```php\n[\n    [\n        'ip' =\u003e '18.18.18.18',\n        'protocol' =\u003e null,\n        'host' =\u003e null,\n        'port' =\u003e null,\n        'ipIdentifier' =\u003e null,\n    ],\n    [\n        'ip' =\u003e '2.2.2.2',\n        'protocol' =\u003e 'http',\n        'host' =\u003e 'example1.com',\n        'port' =\u003e null,\n        'ipIdentifier' =\u003e '_obfuscated1',\n    ]\n],\n```\n\n#### Reverse-obfuscating IP identifier\n\nYou may extend middleware class and provide reverse-obfuscating logic for\n[obfuscated](https://datatracker.ietf.org/doc/html/rfc7239#section-6.3) IP identifiers:\n\n```php\nuse Yiisoft\\ProxyMiddleware\\TrustedHostsNetworkResolver;\n\nclass MyTrustedHostsNetworkResolver extends TrustedHostsNetworkResolver\n{\n    protected function reverseObfuscateIpIdentifier(\n        string $ipIdentifier,\n        array $validatedConnectionChainItems,\n        array $remainingConnectionChainItems,\n        RequestInterface $request,\n    ): ?array\n    {\n        return match ($ipIdentifier) {\n            '_obfuscated1' =\u003e ['2.2.2.2', null], // Without port\n            '_obfuscated2' =\u003e ['5.5.5.5', '8082'], // With port\n            default =\u003e null, // Unable to resolve (default)\n        };\n    }\n}\n```\n\n## Documentation\n\n- [Internals](docs/internals.md)\n\nIf you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.\nYou may also check out other [Yii Community Resources](https://www.yiiframework.com/community).\n\n## License\n\nThe Yii Proxy Middleware is free software. It is released under the terms of the BSD License.\nPlease see [`LICENSE`](./LICENSE.md) for more information.\n\nMaintained by [Yii Software](https://www.yiiframework.com/).\n\n## Support the project\n\n[![Open Collective](https://img.shields.io/badge/Open%20Collective-sponsor-7eadf1?logo=open%20collective\u0026logoColor=7eadf1\u0026labelColor=555555)](https://opencollective.com/yiisoft)\n\n## Follow updates\n\n[![Official website](https://img.shields.io/badge/Powered_by-Yii_Framework-green.svg?style=flat)](https://www.yiiframework.com/)\n[![Twitter](https://img.shields.io/badge/twitter-follow-1DA1F2?logo=twitter\u0026logoColor=1DA1F2\u0026labelColor=555555?style=flat)](https://twitter.com/yiiframework)\n[![Telegram](https://img.shields.io/badge/telegram-join-1DA1F2?style=flat\u0026logo=telegram)](https://t.me/yii3en)\n[![Facebook](https://img.shields.io/badge/facebook-join-1DA1F2?style=flat\u0026logo=facebook\u0026logoColor=ffffff)](https://www.facebook.com/groups/yiitalk)\n[![Slack](https://img.shields.io/badge/slack-join-1DA1F2?style=flat\u0026logo=slack)](https://yiiframework.com/go/slack)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyiisoft%2Fproxy-middleware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyiisoft%2Fproxy-middleware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyiisoft%2Fproxy-middleware/lists"}