Logo
URI toolkit

Please consider using the the latest stable version for any production code.

Components common API

Instantiation

Each URI component objects can be instantiated from a URI object using the createFromUri named constructor.

public static function UriComponent::createFromUri($uri): UriComponentInterface;

This method accepts a single $uri parameter which can be an object implementing a:

  • League League\Uri\Contracts\UriInterface or
  • PSR-7 Psr\Http\Message\UriInterface
use League\Uri\Components\Host;
use League\Uri\Components\Path;
use League\Uri\Components\Port;
use League\Uri\Components\Query;
use League\Uri\Uri;

$uri = Uri::createFromString('http://example.com?q=value#fragment');
$host = Host::createFromUri($uri)->getContent();   //displays 'example.com'
$query = Query::createFromUri($uri)->getContent(); //displays 'q=value'
$port = Port::createFromUri($uri)->getContent();   //displays null
$path = Path::createFromUri($uri)->getContent();   //displays ''

Depending on the URI component the default constructor and other named constructors can be use for instantiation.

Accessing URI component representation

Once instantiated, all URI component objects expose the following methods.

public function UriComponent::__toString(): string;
public function UriComponent::jsonSerialize(): ?string;
public function UriComponent::getContent(): ?string;
public function UriComponent::getUriComponent(): string;

Which will lead to the following results:

$scheme = new Scheme('HtTp');
echo $scheme->__toString(); //displays 'http'
echo $scheme->getUriComponent(); //display 'http:'

$userinfo = new UserInfo('john');
echo $userinfo->__toString(); //displays 'john'
echo $userinfo->getUriComponent(); //displays 'john@'

$host = new Host('bébé.be');
echo $host; //displays 'xn--bb-bjab.be'
echo $host->getContent(); //displays 'xn--bb-bjab.be'

$query = Query::createFromRFC6986();
echo $query; //displays ''
echo $query->getContent(); //displays null

$port = new Port(23);
echo $port->getContent(); //displays '23';
  • __toString returns the normalized and RFC3986 encoded string version of the component.
  • getUriComponent returns the same output as __toString with the component optional delimiter.
  • jsonSerialize returns the normalized and RFC1738 encoded string version of the component for better interoperability with JavaScript URL standard.

For a more generalized representation you must use the getContent method. If the component is undefined, the method returns null.

Normalization and encoding are component specific.

Modifying URI component object

All URI component objects can be modified with the withContent method. This method returns a new instance with the modified content.

public function UriComponent::withContent(?string $content): static;

submitted input is normalized to be RFC3986 compliant.

$query = Query::createFromRFC3986();
$newQuery = $query->withContent('');
echo $query->getContent(); //returns null
echo $newQuery->getContent(); //returns ''

$host = new Host('thephpleague.com');
$newHost = $host->withContent('bébé.be');
echo $newHost->getContent(); //displays 'xn--bb-bjab.be';
echo $newHost->toUnicode(); //displays 'bébé.be';

If the submitted value is not valid an League\Uri\Exceptions\UriException exception is thrown.

List of URI component objects

The following URI component objects are defined (order alphabetically):

In addition to the common API, the classes expose specific methods to improve URI component manipulation.