From 4cbda740fd7ffff71aacd4760b2e12ce79582112 Mon Sep 17 00:00:00 2001
From: Ignace Nyamagana Butera
Date: Fri, 17 Nov 2017 08:48:17 +0100
Subject: [PATCH] improve Query component documentation
---
docs/5.0/components/query.md | 312 +++++++++++++++++++----------------
1 file changed, 174 insertions(+), 138 deletions(-)
diff --git a/docs/5.0/components/query.md b/docs/5.0/components/query.md
index 625f17c7..dd454e0e 100644
--- a/docs/5.0/components/query.md
+++ b/docs/5.0/components/query.md
@@ -14,13 +14,17 @@ The library provides a `Query` class to ease query string creation and manipulat
~~~php
Query::getSeparator
and Query::withSeparator
are available since version 1.3.0
~~~php
__toString(); //return baz=toto&foo=bar
## Query as a PHP data transport layer
-### 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'];
+public static Query::extract(string $query, string $separator = '&', int $enc_type = self::RFC3986_ENCODING): array
+public static Query::createFromParams(array $params, string $separator = '&'): self
+public Query::getParams(): array
+public Query::getParam(string $name, $default = null): mixed
+public Query::withoutNumericIndices(): self
+public Query::withoutParams(string[] $offsets): self
~~~
### Query::createFromParams
@@ -327,116 +296,76 @@ $query->getParams(); //return ['foo' => ['bar', 'baz']]
$new_query->getParams(); //return ['foo' => ['bar', 'baz']]
~~~
-## Query as a collection of key/value pairs
+### Query::extract
~~~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
- 'baz'];
-$query_string = 'toto.foo=bar&toto.foo=baz&foo&baz=';
-$arr = Uri\parse_query($query_string, '&');
-// [
-// "toto.foo" => ["bar", "baz"],
-// "foo" => null,
-// "baz" => "",
-// ]
+$arr = Query::extract($query_string);
+// $arr = ['foo.bar' => 'bar', 'foo_bar' => 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 `array` 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.2.0
The alias function Uri\extract_query
is available
~~~php
['bar', 'baz']];
+$query_string = 'foo.bar=bar&foo_bar=baz';
+parse_str($query_string, $out);
+var_export($out);
+// $out = ["foo_bar" => 'baz'];
-$res = Query::build($arr, '&', false);
-// $res = 'foo[]=bar&foo[]=baz'
+$arr = Uri\extract_query($query_string);
+// $arr = ['foo.bar' => 'bar', 'foo_bar' => baz'];
~~~
-Query::build
is not similar to http_build_query
.
-
-Since version 1.2.0
The alias function Uri\build_query
is available
+## Query as a collection of key/value pairs
~~~php
['bar', 'baz']];
-
-$res = Uri\build_query($arr, '&', false);
-// $res = 'foo[]=bar&foo[]=baz'
+public static Query::parse(string $query_string [, string $separator = '&' [, int $enc_type = self::RFC3986_ENCODING]]): array
+public static Query::build(array $pairs [, string $separator = '&' [, int $enc_type = self::RFC3986_ENCODING]]): string
+public static Query::createFromPairs(iterable $pairs[, string $separator = '&']): self
+public Query::getIterator(): ArrayIterator
+public Query::count(): int
+public Query::getPairs(): array
+public Query::getPair(string $offset, $default = null): mixed
+public Query::hasPair(string $offset): bool
+public Query::keys([mixed $value = null]): array
+public Query::withoutEmptyPairs(): self
+public Query::withoutPairs(array $offsets): self
~~~
+This class mainly represents the query string as a collection of key/value pairs.
+
### Query::createFromPairs
Returns a new `Query` object from an `array` or a `Traversable` object.
@@ -575,4 +504,111 @@ use League\Uri\Components\Query;
$query = new Query('foo=bar&p=y+olo&z=');
$newQuery = $query->withoutPairs(['foo', 'p']);
echo $newQuery; //displays 'z='
+~~~
+
+### Query::withoutEmptyPairs
+
+`Query::withoutEmptyPairs` returns a new `Query` object with deleted empty pairs. A pair is considered empty if its key equals the empty string and its value is `null`.
+
+~~~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