URI info and full manipulation

The League\Uri\BaseUri class is build to ease gathering information regarding a specific URI. The class makes it easier to transform and crawl pages containing URIs (ie: a web page, or an HTTP client for instance).

While the class does manipulate URI it does not implement any URI related interface.

If a PSR-7 UriInterface implementing instance is given then the return value will also be a PSR-7 UriInterface implementing instance.

Instantiation

Instantiation is done via the BaseUri::from named constructor which accepts string and stringable objects alike. Once instantiated you can get access to its underlying URI as a string via the BaseUri::getUriString() method .

<?php

use League\Uri\BaseUri;

$baseUri = BaseUri::from('http://www.ExaMPle.com');
$baseUri->getUriString(); // return 'http://www.example.com';
echo $baseUri; // display 'http://www.example.com'

The instance also implements PHP’s Stringable and JsonSerializable interface.

In addition to all the non-destructive rules from RFC3968, duting instantiation, the class will convert the host if possible:

to its IPv4 decimal representation
to its compressed IPv6 representation (since version 7.5)

BaseUri::from('https://0:443/')->getUriString(); // returns 'https://0.0.0.0/
BaseUri::from('FtP://[1050:0000:0000:0000:0005:0000:300c:326b]/path')->getUriString(); // returns 'ftp://[1050::5:0:300c:326b]/path

URI resolution

The BaseUri::resolve resolves a URI as a browser would for a relative URI while the BaseUri::relativize does the opposite.

$baseUri = BaseUri::from('http://www.ExaMPle.com');
$uri = 'http://www.example.com/?foo=toto#~typo';

$relativeUri = $baseUri->relativize($uri);
echo $relativeUri; // display "/?foo=toto#~typo
echo $baseUri->resolve($relativeUri);
echo $baseUri; // display 'http://www.example.com'
// display 'http://www.example.com/?foo=toto#~typo'
echo $baseUri->getUri()::class; //display \League\Uri\Uri

Out of the box when submitting an object other than a PSR-7 UriInterface the returned URI object will be a League\Uri\Uri instance. You can control this behaviour by registering a PSR-7 UriFactoryInterface on BaseUri instantiation

<?php

use League\Uri\BaseUri;
use GuzzleHttp\Psr7\HttpFactory;

$baseUri = BaseUri::from('http://www.ExaMPle.com', new HttpFactory());
$uri = 'http://www.example.com/?foo=toto#~typo';

$relativeUri = $baseUri->relativize($uri);
echo $relativeUri;               // display "/?foo=toto#~typo"
echo $relativeUri::class;        // display '\Leage\Uri\BaseUri'
echo $relativeUri->getUri()::class; //display \GuzzleHttp\Psr7\Uri

$resolvedUri = $baseUri->withoutUriFactory()->resolve("/?foo=toto#~typo");
echo $resolvedUri;               // display 'http://www.example.com/?foo=toto#~typo'
echo $resolvedUri::class;        // display '\Leage\Uri\BaseUri'
echo $resolvedUri->getUri()::class; // display \League\Uri\Uri

You can always switch back to using the Uri object by unregistering the factory using BaseUri::withoutUriFactory.

URI information

The class also exposes a list of public methods which returns the URI state.

BaseUri::isAbsolute

Tells whether the URI represents an absolute URI.

BaseUri::from(Uri::fromServer($_SERVER))->isAbsoulte(); //returns true
BaseUri::from("/🍣🍺")->isAbsolute(); //returns false

BaseUri::isAbsolutePath

Tells whether the URI represents an absolute URI path.

BaseUri::from(Uri::fromServer($_SERVER))->isAbsolutePath(); //returns false
BaseUri::from(Http::new("/🍣🍺"))->isAbsolutePath(); //returns true

BaseUri::isNetworkPath

Tells whether the URI represents a network path URI.

BaseUri::from("//example.com/toto")->isNetworkPath(); //returns true
BaseUri::from("/🍣🍺")->isNetworkPath(); //returns false

BaseUri::isOpaque

since version 7.5.0

Tells whether the given URI object represents an opaque URI. An URI is said to be opaque if and only if it is absolute but does not have an authority

BaseUri::from("email:john@example.com?subject=🏳️‍🌈"))->isOpaque(); //returns true
BaseUri::from("/🍣🍺")->isOpaque(); //returns false

BaseUri::isRelativePath

Tells whether the given URI object represents a relative path.

BaseUri::from("🏳️‍🌈")->isRelativePath(); //returns true
BaseUri::from("/🍣🍺")->isRelativePath(); //returns false

BaseUri::isSameDocument

Tells whether the given URI object represents the same document.

BaseUri::from(Http::new("example.com?foo=bar#🏳️‍🌈"))->isSameDocument("exAMpLE.com?foo=bar#🍣🍺"); //returns true

BaseUri::hasIDN

since version 7.2.0

Tells whether the given URI object contains a IDN host.

BaseUri::from(Http::new("https://bébé.be"))->hasIdn(); //returns true

BaseUri::isCrossOrigin

Tells whether the given URI object represents different origins. According to RFC9110 The “origin” for a given URI is the triple of scheme, host, and port after normalizing the scheme and host to lowercase and normalizing the port to remove any leading zeros.

<?php

use GuzzleHttp\Psr7\Utils;
use League\Uri\BaseUri;
use Nyholm\Psr7\Uri;

BaseUri::from(Utils::uriFor('blob:http://xn--bb-bjab.be./path'))
    ->isCrossOrigin(new Uri('http://Bébé.BE./path')); // returns false

BaseUri::from('https://example.com/123')
    ->isCrossOrigin(new Uri('https://www.example.com/')); // returns true

The method takes into account i18n while comparing both URI if the PHP’s idn_* functions can be used.

BaseUri::origin

Returns the URI origin used for comparison when calling the isCrossOrigin method. The algorithm used is defined by the WHATWG URL Living standard

echo BaseUri::from(Http::new('https://uri.thephpleague.com/uri/6.0/info/'))->origin(); //display 'https://uri.thephpleague.com';
echo BaseUri::from('blob:https://mozilla.org:443')->origin();       //display 'https://mozilla.org'
BaseUri::from(Uri::new('file:///usr/bin/php'))->origin();           //returns null
BaseUri::from('data:text/plain,Bonjour%20le%20monde%21')->origin(); //returns null

For absolute URI with the file scheme the method will return null (as this is left to the implementation decision)

Because the origin property does not exist in the RFC3986 specification this additional steps is implemented:

For non-absolute URI the method will return null

BaseUri::from((Http::new('/path/to/endpoint'))->origin(); //returns null

BaseUri::unixPath and BaseUri::windowsPath

since version 7.3.0

Returns the OS specific path from a URI.

BaseUri::from('file://server/share/My%20Documents%20100%2520/foo.txt')->windowsPath();
//returns '\\server\share\My Documents 100%20\foo.txt'

BaseUri::from('file:///path%20empty/bar')->unixPath();
//returns '/path empty/bar'

If the URI scheme is present and is not the file scheme, null will be returned.

BaseUri::toRfc8089

since version 7.4.0

Returns the RFC8089 representation of a file URI

BaseUri::from('file://localhost/etc/fstab')->toRfc8089();
//returns 'file:/etc/fstab'

BaseUri::from('file:///path%20empty/bar')->toRfc8089();
//returns 'file:/path empty/bar'

If the URI scheme is not the file scheme, null will be returned.

BaseUri::isLocalFile

since version 7.4.0

Tells whether the given URI object represents a local file path.

BaseUri::from("file://localhost/etc/fstab")->isLocalFile(); //returns true