The Query component
The library provides a Query
class to ease complex query manipulation.
Query creation
Using the default constructor
<?php
public function __contruct(string $query = null)
The constructor accepts:
- a valid string according to RFC3986 rules;
- the
null
value;
Example
<?php
use League\Uri\Components\Query;
$query = new Query('foo=bar&p=yolo&z=');
echo $query->getContent(); //display 'foo=bar&p=yolo&z'
echo $query; //display 'foo=bar&p=yolo&z'
echo $query->getUriComponent(); //display '?foo=bar&p=yolo&z'
Using a League Uri object
<?php
use League\Uri\Ws as WsUri;
$uri = WsUri::createFromString('wss://uri.thephpleague.com/path/to/here?foo=bar');
$query = $uri->query; //$query is a League\Uri\Components\Query object;
Using a named constructor
Returns a new Query
object from an array
or a Traversable
object.
<?php
public static function Query::createFromPairs(array $pairs): Query
$pairs
: The submitted data must be anarray
or aTraversable
key/value structure similar to the result of QueryParser::parse.
Examples
<?php
use League\Uri\Components\Query;
$query = Query::createFromPairs([
'foo' => 'bar',
'p' => 'yolo',
'z' => ''
]);
echo $query; //display 'foo=bar&p=yolo&z='
$query = Query::createFromPairs([
'foo' => 'bar',
'p' => null,
'z' => ''
]);
echo $query; //display 'foo=bar&p&z='
- If a given parameter value is
null
it will be rendered without any value in the resulting query string; - If a given parameter value is an empty string il will be rendered without any value but with a
=
sign appended to it;
Properties and methods
The component representation, comparison and manipulation is done using the package UriPart and the Component interfaces methods.
Accessing query pairs
<?php
public function Query::getIterator(): ArrayIterator
public function Query::count(): int
public function Query::getPairs(): array
public function Query::keys(mixed $value = null): array
public function Query::hasKey(string $offset): bool
public function Query::getValue(string $offset, $default = null): mixed
Countable and IteratorAggregate
The class provides several methods to work with its parameters. The class implements PHP’s Countable
and IteratorAggregate
interfaces. This means that you can count the number of parameters and use the foreach
construct to iterate over them.
<?php
use League\Uri\Components\Query;
$query = new Query('foo=bar&p=y+olo&z=');
count($query); //return 4
foreach ($query as $key => $value) {
//do something meaningful here
}
Query::getPairs
A query can be represented as an array of its internal key/value pairs. Through the use of the Query::getPairs
method the class returns the object’s array representation. This method uses QueryParser::parse
to create the array.
<?php
use League\Uri\Components\Query;
$query = new Query('foo=bar&p=y+olo&z=');
$query->getPairs();
// returns [
// 'foo' => 'bar',
// 'p' => 'y olo',
// 'z' => '',
// ]
Query::keys
Returns the decoded query keys as shown below:
<?php
use League\Uri\Components\Query;
$query = new Query('foo=bar&p=y+olo&z=');
$query->keys(); //return ['foo', 'p', 'z'];
$query->keys('bar'); //return ['foo'];
$query->keys('gweta'); //return [];
By default, the method returns all the keys names, but if you supply a value, only the keys whose value equals the value are returned.
Query::hasKey
Tells whether the submitted key exists in the current Query
object.
<?php
use League\Uri\Components\Query;
$query = new Query('foo=bar&p=y+olo&z=');
$query->hasKey('p'); //return true
$query->hasKey('john'); //return false
Query::getValue
Returns the decoded query value of a specified pair key as shown below:
<?php
use League\Uri\Components\Query;
$query = new Query('foo=bar&p=y+olo&z=');
$query->getValue('foo'); //return 'bar'
$query->getValue('gweta'); //return null
$query->getValue('gweta', 'now'); //return 'now'
The method returns the value of a specific parameter name. If the offset does not exist it will return the value specified by the second argument which defaults to null
.
Modifying a query
Query::ksort
Returns a Query
object with its pairs sorted according to its keys.
<?php
public function Query::ksort(mixed $sort): Query
The single argument sort
can be:
One of PHP’s sorting constant used by the sort function. In this case the query parameters are sorted from low to high like PHP’s ksort function
<?php
use League\Uri\Components\Query;
$query = new Query('foo=bar&baz=toto');
$newQuery = $query->ksort(SORT_STRING);
$newQuery->__toString(); //return baz=toto&foo=bar
A user-defined comparison function which must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second, like PHP’s uksort function
<?php
use League\Uri\Components\Query;
$query = new Query('foo=bar&baz=toto');
$newQuery = $query->ksort('strcmp');
$newQuery->__toString(); //return baz=toto&foo=bar
Query::merge
Returns a new Query
object with its data merged.
<?php
public function Query::merge(mixed $query): Query
This method expects a single argument which can be:
A string or a stringable object:
<?php
use League\Uri\Components\Query;
$query = new Query('foo=bar&baz=toto');
$newQuery = $query->merge('foo=jane&r=stone');
$newQuery->__toString(); //return foo=jane&baz=toto&r=stone
// the 'foo' parameter was updated
// the 'r' parameter was added
Another Query
object
<?php
use League\Uri\Components\Query;
$query = Query::createFromPairs(['foo' => 'bar', 'baz' => 'toto']);
$newQuery = $query->merge(new Query('foo=jane&r=stone'));
$newQuery->__toString(); //return foo=jane&baz=toto&r=stone
// the 'foo' parameter was updated
// the 'r' parameter was added
<?php
use League\Uri\Components\Query;
$query = Query::createFromPairs(['foo' => 'bar', 'baz' => 'toto']);
$newQuery = $query->merge('baz=&r');
$newQuery->__toString(); //return foo=bar&baz=&r
// the 'r' parameter was added without any value
// the 'baz' parameter was updated to an empty string and its = sign remains
Query::without
Returns a new Query
object with deleted pairs according to their keys.
<?php
public function Query::without(array $keys): Query
This method expects an array containing a list of keys to remove as its single argument.
<?php
use League\Uri\Components\Query;
$query = new Query('foo=bar&p=y+olo&z=');
$newQuery = $query->without(['foo', 'p']);
echo $newQuery; //displays 'z='
Query::filter
Returns a new Query
object with filtered pairs.
<?php
public function Query::filter(callable $filter, $flag = Query::FILTER_USE_VALUE): Query
Filtering is done using the same arguments as PHP’s array_filter
.
You can filter the query by the pairs values:
<?php
use League\Uri\Components\Query;
$query = new Query('foo=bar&p=y+olo&z=');
$filter = function ($value) {
return !empty($value);
};
$newQuery = $query->filter($filter, Query::FILTER_USE_VALUE);
echo $newQuery; //displays 'foo=bar&p=y+olo'
You can filter the query by the pairs keys:
<?php
use League\Uri\Components\Query;
$query = new Query('foo=bar&p=y+olo&z=');
$filter = function ($key) {
return strpos($key, 'f');
};
$newQuery = $query->filter($filter, Query::FILTER_USE_KEY);
echo $newQuery; //displays 'foo=bar'
You can filter the query by pairs
<?php
use League\Uri\Components\Query;
$query = new Query('toto=foo&bar=foo&john=jane');
$filter = function ($value, $key) {
return (strpos($value, 'o') !== false && strpos($key, 'o') !== false);
};
$newQuery = $query->filter($filter, Query::FILTER_USE_BOTH);
echo $newQuery; //displays 'toto=foo'
By specifying the second argument flag you can change how filtering is done:
- use
Query::FILTER_USE_VALUE
to filter by pairs value; - use
Query::FILTER_USE_KEY
to filter by pairs key; - use
Query::FILTER_USE_BOTH
to filter by pairs value and key;
By default, if no flag is specified the method will filter the query using the Query::FILTER_USE_VALUE
flag.