From f1e4470db2fce1b382ab79bfdf7eea61b58f60a6 Mon Sep 17 00:00:00 2001 From: Ignace Nyamagana Butera Date: Fri, 1 Dec 2017 14:28:14 +0100 Subject: [PATCH] prepare 5.2.0 release --- CHANGELOG.md | 13 +- composer.json | 8 +- docs/5.0/components/host.md | 32 ++-- docs/5.0/components/installation.md | 10 +- docs/5.0/components/query-parsers.md | 235 +++++++++++++++++++++++++++ docs/5.0/components/query.md | 163 +------------------ docs/5.0/functions.md | 7 +- docs/5.0/parser/parser.md | 3 + docs/5.0/uri/installation.md | 2 +- docs/_data/project.yml | 2 +- docs/_layouts/homepage.html | 16 +- 11 files changed, 295 insertions(+), 196 deletions(-) create mode 100644 docs/5.0/components/query-parsers.md diff --git a/CHANGELOG.md b/CHANGELOG.md index b71ec367..cbda9fba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,12 +2,17 @@ All Notable changes to `League\Uri` will be documented in this file -## 5.2.0 - 2017-11-17 +## 5.2.0 - 2017-12-01 -- [URI hostname parser](https://github.com/thephpleague/uri-hostname-parser/releases/tag/1.0.0) +- [URI Parser](https://github.com/thephpleague/uri-parser/releases/tag/1.3.0) +- [URI Hostname parser](https://github.com/thephpleague/uri-hostname-parser/releases/tag/1.0.4) +- [URI Manipulations 1.3.0 Changelog](https://github.com/thephpleague/uri-manipulations/releases/tag/1.3.0) +- [URI Components 1.5.0 Changelog](https://github.com/thephpleague/uri-components/releases/tag/1.5.0) +- [URI Schemes 1.1.1 Changelog](https://github.com/thephpleague/uri-schemes/releases/tag/1.1.1) -- See [URI Manipulations 1.3.0 Changelog](https://github.com/thephpleague/uri-manipulations/blob/master/CHANGELOG.md#130---2017-11-24) -- See [URI Components 1.3.0 Changelog](https://github.com/thephpleague/uri-components/blob/master/CHANGELOG.md#130---2017-11-24) +### Fixed + +- Support for PHP7.2 ## 5.1.0 - 2017-11-17 diff --git a/composer.json b/composer.json index e026af6f..ad93c449 100644 --- a/composer.json +++ b/composer.json @@ -38,12 +38,12 @@ "ext-mbstring" : "*", "ext-intl" : "*", "ext-fileinfo": "*", - "league/uri-components": "^1.4.1", - "league/uri-hostname-parser": "^1.0.2", + "league/uri-components": "^1.5.0", + "league/uri-hostname-parser": "^1.0.4", "league/uri-interfaces": "^1.0", "league/uri-manipulations": "^1.3", - "league/uri-parser": "^1.2", - "league/uri-schemes": "^1.1", + "league/uri-parser": "^1.3.0", + "league/uri-schemes": "^1.1.1", "php" : ">=7.0.13", "psr/http-message": "^1.0" }, diff --git a/docs/5.0/components/host.md b/docs/5.0/components/host.md index 22f0f1ef..10370e7e 100644 --- a/docs/5.0/components/host.md +++ b/docs/5.0/components/host.md @@ -26,7 +26,7 @@ class Host implements ComponentInterface, Countable, IteratorAggregate public function getLabel(int $offset, $default = null): mixed public function getLabels(void): array public function getPublicSuffix(void): string - public function getRegisterableDomain(void): string + public function getRegistrableDomain(void): string public function getSubDomain(void): string public function hasZoneIdentifier(void): bool public function isIp(void): bool @@ -40,7 +40,7 @@ class Host implements ComponentInterface, Countable, IteratorAggregate public function withoutLabels(array $offsets): self public function withoutRootLabel(void): self public function withoutZoneIdentifier(void): self - public function withRegisterableDomain(string $host): self + public function withRegistrableDomain(string $host): self public function withRootLabel(void): self public function withSubDomain(string $host): self } @@ -184,24 +184,26 @@ $newHost->getIp(); //returns null ## Host represented by a registered name +

Host::getRegisterableDomain and Host::withRegisterableDomain are deprecated and replaced by Host::getRegistrableDomain and Host::withRegistrableDomain starting with version 1.5.0.

+ If you don't have a IP then you are dealing with a registered name. A registered name is a [domain name](http://tools.ietf.org/html/rfc1034) subset according to [RFC1123](http://tools.ietf.org/html/rfc1123#section-2.1). As such a registered name can not, for example, contain an `_`. ~~~php getPublicSuffix(); //display 'co.uk' -echo $host->getRegisterableDomain(); //display 'example.co.uk' -echo $host->getSubdomain(); //display 'www' +echo $host->getRegistrableDomain(); //display 'example.co.uk' +echo $host->getSubDomain(); //display 'www' $host->isPublicSuffixValid(); //return a boolean 'true' in this example ~~~ @@ -226,14 +228,14 @@ use League\Uri\Components\Host; $host = new Host('192.158.26.30'); echo $host->getPublicSuffix(); //return '' -echo $host->getRegisterableDomain(); //return '' -echo $host->getSubdomain(); //return '' +echo $host->getRegistrableDomain(); //return '' +echo $host->getSubDomain(); //return '' $host->isPublicSuffixValid(); //return false ~~~ -### Updating the Registerable domain part +### Updating the Registrable domain part -You can update the registerable domain part of the host. +You can update the registrable domain part of the host. ~~~php withRegisterableDomain('co.uk'); +$newHost = $host->withRegistrableDomain('co.uk'); echo $newHost; //displays 'www.11.co.uk' ~~~ @@ -257,7 +259,7 @@ You can update the subdomain part of the host. use League\Uri\Components\Host; $host = new Host('www.11.be'); -$newHost = $host->withSubdomain('shop'); +$newHost = $host->withSubDomain('shop'); echo $newHost; //displays 'shop.11.be' ~~~ diff --git a/docs/5.0/components/installation.md b/docs/5.0/components/installation.md index fc12e445..4a01fd99 100644 --- a/docs/5.0/components/installation.md +++ b/docs/5.0/components/installation.md @@ -25,4 +25,12 @@ $ composer require league/uri-components Dependencies ------- -- [PHP Domain Parser](https://github.com/jeremykendall/php-domain-parser) \ No newline at end of file +Prior to version 1.4.0 + +- [PHP Domain Parser](https://github.com/jeremykendall/php-domain-parser) + +Starting with version 1.4.0 + +- [Uri Hostname parser](/5.0/publicsuffix/) + +The changes between dependencies was done to support `PHP7.2+` \ No newline at end of file diff --git a/docs/5.0/components/query-parsers.md b/docs/5.0/components/query-parsers.md new file mode 100644 index 00000000..ed0c583c --- /dev/null +++ b/docs/5.0/components/query-parsers.md @@ -0,0 +1,235 @@ +--- +layout: default +title: The Query component +--- + +Query Parsers +======= + +The library provides two classes `QueryParser` and `QueryBuilder` to ease query string creation and conversion. + +~~~php + 'baz']; + +$parser = new QueryParser(); +$arr =$parser->extract($query_string); +// $arr = ['foo.bar' => 'bar', 'foo_bar' => baz']; +~~~ + +

Since version 1.2.0 The alias function Uri\extract_query is available

+ +~~~php + 'baz']; + +$arr = Uri\extract_query($query_string); +// $arr = ['foo.bar' => 'bar', 'foo_bar' => baz']; +~~~ + + +## QueryParser::parse + +~~~php +parse($query_string, '&'); +// [ +// "toto.foo" => ["bar", "baz"], +// "foo" => null, +// "baz" => "", +// ] +~~~ + + +

QueryParser::parse is not simlar to parse_str, QueryParser::extract is.

+ +

QueryParser::parse and QueryParser::extract both convert the query string into an array but QueryParser::parse logic don't result in data loss.

+ +

Since version 1.2.0 The alias function Uri\parse_query is available

+ +~~~php + ["bar", "baz"], +// "foo" => null, +// "baz" => "", +// ] +~~~ + +## QueryParser::convert + +

Available since version 1.5.0.

+ + +~~~php +convert(['foo.bar' => ['2', 3, true]]); +//or +$arr = Uri\pairs_to_params(['foo.bar' => ['2', 3, true]]); +//in both cases $arr = ['foo.bar' => 'true']; +~~~ + + +## QueryBuilder::build + +~~~php +By default the encoding is set to EncodingInterface::RFC3986_ENCODING

+

Since version 1.3.0 The method accepts any iterable construct.

+ +~~~php +parse($query_string, '&', Query::RFC3986_ENCODING); +// $arr include the following data ["foo[]" => ['bar', 'baz']]; + +$res = $builder->build($arr, '&', false); +// $res = 'foo[]=bar&foo[]=baz' +~~~ + +

QueryBuilder::build is not similar to http_build_query.

+

Since version 1.2.0 The alias function Uri\build_query is available

+

Since version 1.3.0 The function accepts any iterable construct.

+ +~~~php + ['bar', 'baz']]; + +$res = Uri\build_query($arr, '&', false); +// $res = 'foo[]=bar&foo[]=baz' +~~~ \ No newline at end of file diff --git a/docs/5.0/components/query.md b/docs/5.0/components/query.md index ac4d3249..12df10be 100644 --- a/docs/5.0/components/query.md +++ b/docs/5.0/components/query.md @@ -20,11 +20,8 @@ use League\Uri\Components; class Query implements ComponentInterface, \Countable, \IteratorAggregate { - public static function build(iterable $pairs, string $separator = '&' , int $enc_type = self::RFC3986_ENCODING): string public static function createFromPairs(iterable $pairs, string $separator = '&'): self public static function createFromParams(iterable $params, string $separator = '&'): self - public static function extract(string $query, string $separator = '&', int $enc_type = self::RFC3986_ENCODING): array - public static function parse(string $query, string $separator = '&', int $enc_type = self::RFC3986_ENCODING): array public function __construct(?string $content = null, string $separator = '&'): void public function append(string $query): self public function getPair(string $name, mixed $default = null): mixed @@ -42,13 +39,16 @@ class Query implements ComponentInterface, \Countable, \IteratorAggregate public function withoutParams(array $offset): self public function withSeparator(string $separator): self } +~~~ -//functions aliases +

+Since version 1.5.0:
+Query::parse is deprecated and replaced by QueryParser::parse
+Query::extract is deprecated and replaced by QueryParser::extract
+Query::build is deprecated and replaced by QueryBuilder::build
+Please refers to the Query Parsers documentation page for more informations. +

-function Uri\build_query(iterable $pairs, string $separator = '&', int $enc_type = PHP_QUERY_RFC3986): string -function Uri\extract_query(string $query, string $separator = '&', int $enc_type = PHP_QUERY_RFC3986): array -function Uri\parse_query(string $query, string $separator = '&', int $enc_type = PHP_QUERY_RFC3986): array -~~~ ## Basic usage @@ -198,7 +198,6 @@ $newQuery->__toString(); //return baz=toto&foo=bar ~~~php getParams(); //return ['foo' => ['bar', 'baz']] $new_query->getParams(); //return ['foo' => ['bar', 'baz']] ~~~ -### Query::extract - -~~~php - 'baz']; - -$arr = Query::extract($query_string); -// $arr = ['foo.bar' => 'bar', 'foo_bar' => baz']; -~~~ - -

Since version 1.2.0 The alias function Uri\extract_query is available

- -~~~php - 'baz']; - -$arr = Uri\extract_query($query_string); -// $arr = ['foo.bar' => 'bar', 'foo_bar' => baz']; -~~~ - ## Query as a collection of key/value pairs ~~~php withoutEmptyPairs(); echo $query; //displays '&&=toto&&&&=&' echo $newQuery; //displays '=toto&=' -~~~ - -### Query::parse - -This method parse the query string into an associative `array` of key/values pairs. The method expects three (3) arguments: - -- The query string **required**; -- The query string separator **optional**, by default it is set to `&`; -- The query string encoding. One of the `ComponentInterface` encoding type constant. - -The value returned for each pair can be: - -- `null`, -- a `string` -- an array of `string` and/or `null` values. - -~~~php - ["bar", "baz"], -// "foo" => null, -// "baz" => "", -// ] -~~~ - - -

Query::parse is not simlar to parse_str, Query::extract is.

- -

Query::parse and Query::extract both convert the query string into an array but Query::parse logic don't result in data loss.

- -

Since version 1.2.0 The alias function Uri\parse_query is available

- -~~~php - ["bar", "baz"], -// "foo" => null, -// "baz" => "", -// ] -~~~ - -### Query::build - -The `Query::build` restore the query string from the result of the `Query::parse` method. The method expects at most 3 arguments: - -- A valid `iterable` of key/value pairs to convert; -- The query string separator, by default it is set to `&`; -- The query string encoding using one of the `ComponentInterface` constant - -

By default the encoding is set to ComponentInterface::RFC3986_ENCODING

-

Since version 1.3.0 The method accepts any iterable construct.

- -~~~php - ['bar', 'baz']]; - -$res = Query::build($arr, '&', false); -// $res = 'foo[]=bar&foo[]=baz' -~~~ - -

Query::build is not similar to http_build_query.

-

Since version 1.2.0 The alias function Uri\build_query is available

-

Since version 1.3.0 The function accepts any iterable construct.

- -~~~php - ['bar', 'baz']]; - -$res = Uri\build_query($arr, '&', false); -// $res = 'foo[]=bar&foo[]=baz' ~~~ \ No newline at end of file diff --git a/docs/5.0/functions.md b/docs/5.0/functions.md index ea18f22f..c4a1ab43 100644 --- a/docs/5.0/functions.md +++ b/docs/5.0/functions.md @@ -94,9 +94,10 @@ Because these functions require different URI packages. Some of them may be miss ### URI components