kuria/url

Parsing, modifying and building URLs

v5.0.0 2019-02-03 16:02 UTC

Requires

• php: >=7.1

Requires (Dev)

• kuria/dev-meta: ^0.6

MIT

• build
• url
• parse
• parameter
• url-parser
• parse_url
• query-string
• parse_str
• url-parsing
• url-building
• url-builder

README

Parsing, modifying and building URLs.

Contents

• Features
• Requirements
• Usage
  • Creating a new URL
  • Parsing an URL
  • Getting URL components
  • Getting query parameters
  • Manipulating query parameters
    • Setting a single parameter
    • Removing a single parameter
    • Setting multiple parameters
    • Replacing all parameters
    • Removing all parameters
  • Building URLs
    • Using build() or __toString()
    • Using buildAbsolute()
    • Using buildRelative()

Features

• parsing URLs
• building relative and absolute URLs, including protocol-relative URLs
• getting, checking and setting individual URL components:
  • scheme
  • host
  • port
  • path
  • query parameters
  • fragment

Requirements

• PHP 7.1+

Usage

Creating a new URL

Create a new instance of Url and use constructor arguments or setters to define the components:

<?php

use Kuria\Url\Url;

$url = new Url();

$url->setScheme('http');
$url->setHost('example.com');
$url->setPath('/test');
// many more setters are available..

echo $url;

Output:

http://example.com/test

Parsing an URL

<?php

use Kuria\Url\Url;

$url = Url::parse('http://example.com:8080/test?foo=bar&lorem=ipsum#fragment');

Tip

If you wish to determine the current request URL, you may use the kuria/request-info component, which integrates with kuria/url.

Note

Parsing URLs that contain username and a password is supported, but these components are ignored.

Such URLs are deprecated according to RFC 3986.

Getting URL components

var_dump(
    $url->getScheme(),
    $url->getHost(),
    $url->getFullHost(),
    $url->getPort(),
    $url->getPath(),
    $url->getQuery(),
    $url->getFragment()
);

// checking whether a certain component is defined
var_dump(
    $url->hasScheme(),
    $url->hasHost(),
    $url->hasPort(),
    $url->hasPath(),
    $url->hasQuery(),
    $url->hasFragment()
);

Output:

string(4) "http"
string(11) "example.com"
string(16) "example.com:8080"
int(8080)
string(5) "/test"
array(2) {
  ["foo"]=>
  string(3) "bar"
  ["lorem"]=>
  string(5) "ipsum"
}
string(8) "fragment"
bool(true)
bool(true)
bool(true)
bool(true)
bool(true)
bool(true)

Getting query parameters

<?php

use Kuria\Url\Url;

$url = Url::parse('/test?foo=bar&lorem%5B0%5D=ipsum&lorem%5B1%5D=dolor');

var_dump(
    $url->has('foo'),
    $url->has('nonexistent'),
    $url->get('foo'),
    $url->get('lorem'),
    $url->get('nonexistent')
);

Output:

bool(true)
bool(false)
string(3) "bar"
array(2) {
  [0]=>
  string(5) "ipsum"
  [1]=>
  string(5) "dolor"
}
NULL

Manipulating query parameters

Setting a single parameter

<?php

$url->set('parameter', 'value');

Removing a single parameter

<?php

$url->remove('foo');

Setting multiple parameters

<?php

$url->add(['foo' => 'bar', 'lorem' => 'ipsum']);

Replacing all parameters

<?php

$url->setQuery(['foo' => 'bar']);

Removing all parameters

<?php

$url->removeAll();

Building URLs

Using build() or __toString()

These methods will return an absolute or relative URL.

• if no host is specified, a relative URL will be returned
• if the host is specified, an absolute URL will be returned (unless the preferred format option is set to relative)

<?php

use Kuria\Url\Url;

$url = new Url();

$url->setPath('/test');

var_dump($url->build());

$url->setScheme('http');
$url->setHost('example.com');

var_dump($url->build());

Output:

string(5) "/test"
string(23) "http://example.com/test"

Specifying a preferred format

By default, build() and __toString() return an absolute URL if the host is specified.

This behavior can be changed by passing the $preferredFormat parameter to the constructor, Url::parse() or the setPreferredFormat() method.

• Url::RELATIVE - prefer generating a relative URL even if the host is specified
• Url::ABSOLUTE - prefer generating an absolute URL if a host is specified

<?php

use Kuria\Url\Url;

$url = Url::parse('http://example.com/foo');

// print URL using the default preferred format (absolute)
echo $url, "\n";

// set the preferred format to relative
$url->setPreferredFormat(Url::RELATIVE);

echo $url, "\n";

Output:

http://example.com/foo
/foo

Using buildAbsolute()

This method will always return an absolute URL.

If the host is not defined, Kuria\Url\Exception\IncompleteUrlException will be thrown.

<?php

use Kuria\Url\Url;

$url = new Url();

$url->setScheme('http');
$url->setHost('example.com');
$url->setPath('/test');

var_dump($url->buildAbsolute());

Output:

string(23) "http://example.com/test"

Note

Building an absolute URL with undefined scheme will yield a protocol-relative URL.

Example: //localhost/test

Using buildRelative()

This method will always return a relative URL regardless of whether the host is defined or not.

<?php

use Kuria\Url\Url;

$url = new Url();

$url->setScheme('http');
$url->setHost('example.com');
$url->setPath('/test');

var_dump($url->buildRelative());

Output:

string(5) "/test"