{"id":22104687,"url":"https://github.com/riimu/kit-urlparser","last_synced_at":"2025-06-27T00:36:50.797Z","repository":{"id":11328165,"uuid":"13751992","full_name":"Riimu/Kit-UrlParser","owner":"Riimu","description":"RFC 3986 compliant url parsing library with PSR-7 Uri component","archived":false,"fork":false,"pushed_at":"2022-12-14T12:58:36.000Z","size":149,"stargazers_count":32,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-01T21:15:05.622Z","etag":null,"topics":["php","php-library","psr-7","rfc-3986","uri","url-parsing"],"latest_commit_sha":null,"homepage":"http://kit.riimu.net","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/Riimu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-10-21T19:01:08.000Z","updated_at":"2025-02-18T21:25:31.000Z","dependencies_parsed_at":"2023-01-13T16:27:37.932Z","dependency_job_id":null,"html_url":"https://github.com/Riimu/Kit-UrlParser","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/Riimu/Kit-UrlParser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riimu%2FKit-UrlParser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riimu%2FKit-UrlParser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riimu%2FKit-UrlParser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riimu%2FKit-UrlParser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Riimu","download_url":"https://codeload.github.com/Riimu/Kit-UrlParser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Riimu%2FKit-UrlParser/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262166288,"owners_count":23269017,"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":["php","php-library","psr-7","rfc-3986","uri","url-parsing"],"created_at":"2024-12-01T06:34:10.169Z","updated_at":"2025-06-27T00:36:50.776Z","avatar_url":"https://github.com/Riimu.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RFC 3986 URL Parser #\n\n*UrlParser* is PHP library that provides a [RFC 3986](https://tools.ietf.org/html/rfc3986)\ncompliant URL parser and a [PSR-7](http://www.php-fig.org/psr/psr-7/) compatible\nURI component. The purpose of this library is to provide a parser that\naccurately implements the RFC specification unlike the built in function\n`parse_url()`, which differs from the specification in some subtle ways.\n\nThis library has two main purposes. The first to provide information from the\nparsed URLs. To achieve this, the library implements the standard URI handling\ninterface from the PSR-7 and also provides additional methods that make it\neasier to retrieve commonly used information from the URLs. The second purpose\nis to also permit the modification of said URLs using the interface from the\nPSR-7 standard in addition to few extra methods that make some tasks more\nstraightforward.\n\nWhile this library is mainly intended for parsing URLs, the parsing is simply\nbased on the generic URI syntax. Thus, it is possible to use this library to\nvalidate and parse any other types of URIs against the generic syntax. The\nlibrary does not perform any scheme specific validation for the URLs.\n\nIn addition to the default RFC 3986 compliant mode, the library also offers\noptions that allow parsing of URLs that contain UTF-8 characters in different\ncomponents of the URL while converting them to the appropriate percent encoded\nand IDN ascii formats.\n\nThe API documentation is available at: http://kit.riimu.net/api/urlparser/\n\n[![CI](https://img.shields.io/github/workflow/status/Riimu/Kit-UrlParser/CI/main?style=flat-square)](https://github.com/Riimu/Kit-UrlParser/actions)\n[![Scrutinizer](https://img.shields.io/scrutinizer/quality/g/Riimu/Kit-UrlParser/main?style=flat-square)](https://scrutinizer-ci.com/g/Riimu/Kit-UrlParser/)\n[![codecov](https://img.shields.io/codecov/c/github/Riimu/Kit-UrlParser/main?style=flat-square)](https://codecov.io/gh/Riimu/Kit-UrlParser)\n[![Packagist](https://img.shields.io/packagist/v/riimu/kit-urlparser.svg?style=flat-square)](https://packagist.org/packages/riimu/kit-urlparser)\n\n## Requirements ##\n\n  * The minimum supported PHP version is 5.6\n  * The library depends on the following external PHP libraries:\n    * [psr/http-message](https://packagist.org/packages/psr/http-message) (`^1.0`)\n  * The library depends on the following PHP Extensions\n    * [`intl`](http://php.net/manual/en/book.intl.php) (only required IDN support)\n\n## Installation ##\n\n### Installation with Composer ###\n\nThe easiest way to install this library is to use Composer to handle your\ndependencies. In order to install this library via Composer, simply follow\nthese two steps:\n\n  1. Acquire the `composer.phar` by running the Composer\n     [Command-line installation](https://getcomposer.org/download/)\n     in your project root.\n\n  2. Once you have run the installation script, you should have the `composer.phar`\n     file in you project root and you can run the following command:\n\n     ```\n     php composer.phar require \"riimu/kit-urlparser:^2.1\"\n     ```\n\nAfter installing this library via Composer, you can load the library by\nincluding the `vendor/autoload.php` file that was generated by Composer during\nthe installation.\n\n### Adding the library as a dependency ###\n\nIf you are already familiar with how to use Composer, you may alternatively add\nthe library as a dependency by adding the following `composer.json` file to your\nproject and running the `composer install` command:\n\n```json\n{\n    \"require\": {\n        \"riimu/kit-urlparser\": \"^2.1\"\n    }\n}\n```\n\n### Manual installation ###\n\nIf you do not wish to use Composer to load the library, you may also download\nthe library manually by downloading the [latest release](https://github.com/Riimu/Kit-UrlParser/releases/latest)\nand extracting the `src` folder to your project. You may then include the\nprovided `src/autoload.php` file to load the library classes.\n\nPlease note that using Composer will also automatically download the other\nrequired PHP libraries. If you install this library manually, you will also need\nto make those other required libraries available.\n\n## Usage ##\n\nUsing this library is relatively straightforward. The library provides a URL\nparsing class `UriParser` and an immutable value object class `Uri` that\nrepresents the URL. To parse an URL, you could simply provide the URL as a\nstring to the `parse()` method in `UriParser` which returns an instance of `Uri`\nthat has been generated from the parsed URL.\n\nFor example:\n\n```php\n\u003c?php\n\nrequire 'vendor/autoload.php';\n\n$parser = new \\Riimu\\Kit\\UrlParser\\UriParser();\n$uri = $parser-\u003eparse('http://www.example.com');\n\necho $uri-\u003egetHost(); // Outputs 'www.example.com'\n```\n\nAlternatively, you can just skip using the `UriParser` completely and simply\nprovide the URL as a constructor parameter to the `Uri`:\n\n```php\n\u003c?php\n\nrequire 'vendor/autoload.php';\n$uri = new \\Riimu\\Kit\\UrlParser\\Uri('http://www.example.com');\necho $uri-\u003egetHost(); // Outputs 'www.example.com'\n```\n\nThe main difference between using the `parse()` method and the constructor is\nthat the `parse()` method will return a `null` if the provided URL is not a\nvalid url, while the constructor will throw an `InvalidArgumentException`.\n\nTo retrieve different types of information from the URL, the `Uri` class\nprovides various different methods to help you. Here is a simple example as an\noverview of the different available methods:\n\n```php\n\u003c?php\n\nrequire 'vendor/autoload.php';\n\n$parser = new \\Riimu\\Kit\\UrlParser\\UriParser();\n$uri = $parser-\u003eparse('http://jane:pass123@www.example.com:8080/site/index.php?action=login\u0026prev=index#form');\n\necho $uri-\u003egetScheme() . PHP_EOL;         // outputs: http\necho $uri-\u003egetUsername() . PHP_EOL;       // outputs: jane\necho $uri-\u003egetPassword() . PHP_EOL;       // outputs: pass123\necho $uri-\u003egetHost() . PHP_EOL;           // outputs: www.example.com\necho $uri-\u003egetTopLevelDomain() . PHP_EOL; // outputs: com\necho $uri-\u003egetPort() . PHP_EOL;           // outputs: 8080\necho $uri-\u003egetStandardPort() . PHP_EOL;   // outputs: 80\necho $uri-\u003egetPath() . PHP_EOL;           // outputs: /site/index.php\necho $uri-\u003egetPathExtension() . PHP_EOL;  // outputs: php\necho $uri-\u003egetQuery() . PHP_EOL;          // outputs: action=login\u0026prev=index\necho $uri-\u003egetFragment() . PHP_EOL;       // outputs: form\n\nprint_r($uri-\u003egetPathSegments());    // [0 =\u003e 'site', 1 =\u003e 'index.php']\nprint_r($uri-\u003egetQueryParameters()); // ['action' =\u003e 'login', 'prev' =\u003e 'index']\n```\n\nThe `Uri` component also provides various methods for modifying the URL, which\nallows you to construct new URLs from separate components or modify existing\nones. Note that the `Uri` component is an immutable value object, which means\nthat each of the modifying methods return a new `Uri` instance instead of\nmodifying the existing one. Here is a simple example of constructing an URL\nfrom it's components:\n\n```php\n\u003c?php\n\nrequire 'vendor/autoload.php';\n\n$uri = (new \\Riimu\\Kit\\UrlParser\\Uri())\n    -\u003ewithScheme('http')\n    -\u003ewithUserInfo('jane', 'pass123')\n    -\u003ewithHost('www.example.com')\n    -\u003ewithPort(8080)\n    -\u003ewithPath('/site/index.php')\n    -\u003ewithQueryParameters(['action' =\u003e 'login', 'prev' =\u003e 'index'])\n    -\u003ewithFragment('form');\n\n// Outputs: http://jane:pass123@www.example.com:8080/site/index.php?action=login\u0026prev=index#form\necho $uri;\n```\n\nAs can be seen from the previous example, the `Uri` component also provides a\n`__toString()` method that provides the URL as a string.\n\n### Retrieving Information ###\n\nHere is the list of methods that the `Uri` component provides for retrieving\ninformation from the URL:\n\n  * `getScheme()` returns the scheme from the URL or an empty string if the URL\n    has no scheme.\n\n  * `getAuthority()` returns the component from the URL that consists of the\n    username, password, hostname and port in the format `user-info@hostname:port`\n\n  * `getUserInfo()` returns the component from the URL that contains the\n    username and password separated by a colon.\n\n  * `getUsername()` returns the *decoded* username from the URL or an empty\n    string if there is no username present in the URL.\n\n  * `getPassword()` returns the *decoded* password from the URL or an empty\n    string if there is no password present in the URL.\n\n  * `getHost()` return the hostname from the URL or an empty string if the URL\n    has no host.\n\n  * `getIpAddress()` returns the IP address from the host, if the host is an\n    IP address. Otherwise this method will return `null`. If an IPv6 address\n    was provided, the address is returned without the surrounding braces.\n\n  * `getTopLevelDomain()` returns the top level domain from the host. If there\n    is no host or the host is an IP address, an empty string will be returned\n    instead.\n\n  * `getPort()` returns the port from the URL or a `null` if there is no port\n    present in the url. This method will also return a `null` if the port is the\n    standard port for the current scheme (e.g. 80 for http).\n\n  * `getStandardPort()` returns the standard port for the current scheme. If\n    there is no scheme or the standard port for the scheme is not known, a\n    `null` will be returned instead.\n\n  * `getPath()` returns the path from the URL or an empty string if the URL has\n    no path.\n\n  * `getPathSegments()` returns an array of *decoded* path segments (i.e. the\n    path split by each forward slash). Empty path segments are discarded and not\n    included in the returned array.\n\n  * `getPathExtension()` returns the file extension from the path or an empty\n    string if the URL has no path.\n\n  * `getQuery()` returns the query string from the URL or an empty string if the\n    URL has no query string.\n\n  * `getQueryParameters()` parses the query string from the URL using the\n    `parse_str()` function and returns the array of parsed values.\n\n  * `getFragment()` returns the fragment from the URL or an empty string if the\n    URL has no fragment.\n\n  * `__toString()` returns the URL as a string.\n\n### Modifying the URL ###\n\nThe `Uri` component provides various methods that can be used to modify URLs\nand construct new ones. Note that since the `Uri` class is an immutable value\nobject, each method returns a new instance of `Uri` rather than modifying the\nexisting one.\n\n  * `withScheme($scheme)` returns a new instance with the given scheme. An empty\n    scheme can be used to remove the scheme from the URL. Note that any provided\n    scheme is normalized to lowercase.\n\n  * `withUserInfo($user, $password = null)` returns a new instance with the\n    given username and password. Note that the password is ignored unless an\n    username is provided. Empty username can be used to remove the username and\n    password from the URL. Any character that cannot be inserted in the URL by\n    itself will be percent encoded.\n\n  * `withHost($host)` returns a new instance with the given host. An empty host\n    can be used to remove the host from the URL. Note that this method does not\n    accept international domain names. Note that this method will also normalize\n    the host to lowercase.\n\n  * `withPort($port)` returns a new instance with the given port. A `null` can\n    be used to remove the port from the URL.\n\n  * `withPath($path)` returns a new instance with the given path. An empty path\n    can be used to remove the path from the URL. Note that any character that is\n    not a valid path character will be percent encoded in the URL. Existing\n    percent encoded characters will not be double encoded, however.\n\n  * `withPathSegments(array $segments)` returns a new instance with the path\n    constructed from the array of path segments. All invalid path characters in\n    the segments will be percent encoded, including the forward slash and\n    existing percent encoded characters.\n\n  * `withQuery($query)` returns a new instance with the given query string. An\n    empty query string can be used to remove the path from the URL. Note that\n    any character that is not a valid query string character will be percent\n    encoded in the URL. Existing percent encoded characters will not be double\n    encoded, however.\n\n  * `withQueryParameters(array $parameters)` returns a new instance with the\n    query string constructed from the provided parameters using the\n    `http_build_query()` function. All invalid query string characters in the\n    parameters will be percent encoded, including the ampersand, equal sign and\n    existing percent encoded characters.\n\n  * `withFragment($fragment)` returns a new instance with the given fragment. An\n    empty string can be used to remove the fragment from the URL. Note that any\n    character that is not a valid fragment character will be percent encoded in\n    the URL. Existing percent encoded characters will not be double encoded,\n    however.\n\n### UTF-8 and International Domains Names ###\n\nBy default, this library provides a parser that is RFC 3986 compliant. The RFC\nspecification does not permit the use of UTF-8 characters in the domain name or\nany other parts of the URL. The correct representation for these in the URL is\nto use the an IDN standard for domain names and percent encoding the UTF-8\ncharacters in other parts.\n\nHowever, to help you deal with UTF-8 encoded characters, many of the methods in\nthe `Uri` component will automatically percent encode any characters that cannot\nbe inserted in the URL on their own, including UTF-8 characters. Due to\ncomplexities involved, however, the `withHost()` method does not allow UTF-8\nencoded characters.\n\nBy default, the parser also does not parse any URLs that include UTF-8 encoded\ncharacters because that would be against the RFC specification. However, the\nparser does provide two additional parsing modes that allows these characters\nwhenever possible.\n\nIf you wish to parse URLs that may contain UTF-8 characters in the user\ninformation (i.e. the username or password), path, query or fragment components\nof the URL, you can simply use the UTF-8 parsing mode. For example:\n\n```php\n\u003c?php\n\nrequire 'vendor/autoload.php';\n\n$parser = new \\Riimu\\Kit\\UrlParser\\UriParser();\n$parser-\u003esetMode(\\Riimu\\Kit\\UrlParser\\UriParser::MODE_UTF8);\n\n$uri = $parser-\u003eparse('http://www.example.com/föö/bär.html');\necho $uri-\u003egetPath(); // Outputs: /f%C3%B6%C3%B6/b%C3%A4r.html\n```\n\nUTF-8 characters in the domain name, however, are a bit more complex issue. The\nparser, however, does provide a rudimentary support for parsing these domain\nnames using the IDNA mode. For example:\n\n```php\n\u003c?php\n\nrequire 'vendor/autoload.php';\n\n$parser = new \\Riimu\\Kit\\UrlParser\\UriParser();\n$parser-\u003esetMode(\\Riimu\\Kit\\UrlParser\\UriParser::MODE_IDNA);\n\n$uri = $parser-\u003eparse('http://www.fööbär.com');\necho $uri-\u003egetHost(); // Outputs: www.xn--fbr-rla2ga.com\n```\n\nNote that using this parsing mode requires the PHP extension `intl` to be\nenabled. The appropriate parsing mode can also be provided to the constructor of\nthe `Uri` component using the second constructor parameter.\n\nWhile support for parsing these UTF-8 characters is available, this library does\nnot provide any methods for the reverse operations since the purpose of this\nlibrary is to deal with RFC 3986 compliant URIs.\n\n### URL Normalization ###\n\nDue to the fact that the RFC 3986 specification defines some URLs as equivalent\ndespite having some slight differences, this library does some minimal\nnormalization to the provided values. You may encounter these instances when,\nfor example, parsing URLs provided by users. The most notable normalizations you\nmay encounter are as follows:\n\n  * The `scheme` and `host` components are considered case insensitive. Thus,\n    these components will always be normalized to lower case.\n  * The port number will not be included in the strings returned by\n    `getAuthority()` and `__toString()` if the port is the standard port for the\n    current scheme.\n  * Percent encodings are treated in case insensitive manner. Thus, this library\n    will normalize the hexadecimal characters to upper case.\n  * The number of forward slashes in the beginning of the path in the string\n    returned by `__toString()` may change depending on whether the URL has an\n    `authority` component or not.\n  * Percent encoded characters in parsed and generated URIs in the `userinfo`\n    component may differ due to the fact that the `UriParser` works with the\n    PSR-7 specification which does not provide a way to provide encoded username\n    or password.\n\n## Credits ##\n\nThis library is Copyright (c) 2013-2022 Riikka Kalliomäki.\n\nSee LICENSE for license and copying information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friimu%2Fkit-urlparser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friimu%2Fkit-urlparser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friimu%2Fkit-urlparser/lists"}