The Formatter
The Formatter service class helps you format your URI according to your output.
Formatting URI and URI parts
<?php
public Formatter::format(mixed $input): string
public Formatter::__invoke(mixed $input): string
The method which process the formatting action is Formatter::format
.
This methods expect one of the following input:
- an Uri object (which implements PSR-7
UriInterface
or theLeague\Interfaces\Uri
interface); - a
League\Interfaces\UriPart
Interface.
Formatter Properties
Host encoding strategy
<?php
public Formatter::setHostEncoding(int $format): void
public Formatter::getHostEncoding(void): int
A host can be output as encoded in ascii or in unicode. By default the formatter encode the host in unicode. To set the encoding you need to specify one of the predefined constant:
Formatter::HOST_AS_UNICODE
to set the host encoding to IDN;Formatter::HOST_AS_ASCII
to set the host encoding to ascii;
<?php
use League\Uri\Formatter;
use League\Uri\Components\Host;
$formatter = new Formatter();
$formatter->setHostEncoding(Formatter::HOST_AS_UNICODE);
echo $formatter->getHostEncoding(); //display the value of Formatter::HOST_AS_ASCII
$host = new Host('рф.ru');
echo $host; //displays 'xn--p1ai.ru'
echo $formatter->format($host); //displays 'рф.ru'
echo $formatter($host); //displays 'рф.ru'
Query encoding strategy
<?php
public Formatter::setQueryEncoding(int $encoding): void
public Formatter::getQueryEncoding(void): int
A League\Uri\Components\Query
object is by default encoded by following RFC 3986. If you need to change this encoding to the old RFC 1738, you just need to update the query encoding as shown below using the following predefined constant:
PHP_QUERY_RFC3986
to set the query encoding as per RFC 3986;PHP_QUERY_RFC1738
to set the query encoding as per RFC 1738;
<?php
use League\Uri\Formatter;
use League\Uri\Components\Query;
$formatter = new Formatter();
$formatter->setQueryEncoding(PHP_QUERY_RFC1738);
echo $formatter->getQueryEncoding(); //display the value of PHP_QUERY_RFC1738;
$query = Query::createFromArray(['foo' => 'ba r', "baz" => "bar"]);
echo $query; //displays foo=ba%20&baz=bar
echo $formatter->format($query); //displays foo=ba+r&baz=bar
echo $formatter($query); //displays foo=ba+r&baz=bar
Query separator strategy
<?php
public Formatter::setQuerySeparator(string $separator): void
public Formatter::getQuerySeparator(void): string
<?php
use League\Uri\Formatter;
use League\Uri\Components\Query;
$formatter = new Formatter();
$formatter->setQuerySeparator('&');
echo $formatter->getQuerySeparator(); //return &
$query = Query::createFromArray(['foo' => 'ba r', "baz" => "bar"]);
echo $query; //displays foo=ba%20&baz=bar
echo $formatter->format($query); //displays foo=ba%20r&baz=bar
echo $formatter($query); //displays foo=ba%20r&baz=bar
Preserving URI components
<?php
public Formatter::preserveQuery(bool $status): void
public Formatter::preserveFragment(bool $status): void
According to PSR-7 UriInterface, when a component is empty and optional, this is the case of the query and the fragment components, it is completely removed from the object representation. The following URIs will all produced the same string representation:
<?php
use League\Uri\Schemes\Http;
$uri = Http::createFromString('http://uri.thephpleague.com?#');
$altUri = Http::createFromString('http://uri.thephpleague.com#');
$otherUri = Http::createFromString('http://uri.thephpleague.com?');
echo $uri->__toString(); //return 'http://uri.thephpleague.com';
echo $altUri->__toString(); //return 'http://uri.thephpleague.com';
echo $otherUri->__toString(); //return 'http://uri.thephpleague.com';
If you need to preserve these URI parts you are required to specify it to the formatter as shown below:
<?php
use League\Uri\Formatter;
use League\Uri\Schemes\Http;
$formatter = new Formatter();
$formatter->preserveQuery(true);
$formatter->preserveFragment(true);
echo $formatter($uri); //return 'http://uri.thephpleague.com?#';
$formatter->preserveQuery(false);
$formatter->preserveFragment(true);
echo $formatter($altUri); //return 'http://uri.thephpleague.com#';
$formatter->preserveQuery(true);
$formatter->preserveFragment(false);
echo $formatter($altUri); //return 'http://uri.thephpleague.com?';
Using the Formatter with a complete URI
Apart form URI component classes, the Formatter::format
method can modify the string representation of any Uri object class.
Concrete example
<?php
use League\Uri\Formatter;
use League\Uri\Schemes\Http;
$formatter = new Formatter();
$formatter->setHostEncoding(Formatter::HOST_AS_ASCII);
$formatter->setQueryEncoding(PHP_QUERY_RFC3986);
$formatter->setQuerySeparator('&');
$formatter->preserveFragment(true);
echo $formatter->format(Http::createFromString('https://рф.ru:81?foo=ba%20r&baz=bar'));
echo $formatter(Http::createFromString('https://рф.ru:81?foo=ba%20r&baz=bar'));
//displays https://xn--p1ai.ru:81?foo=ba%20r&baz=bar#