Wern Ancheta

Adventures in Web Development.

URL Manipulation With Purl

| Comments

In PHP projects, there’s often a need to construct URL’s to be used for making requests to API’s. Normally we would concatenate the different pieces of the URL together in order to make up a complete URL where the request is made. In this tutorial, I’ll be talking about Purl. This library reduces the need for concatenation. With this library, you can manipulate a specific URL anyway you want. You can do things like parsing the URL so you can get it’s individual parts such as the scheme, port, path, query parameters and even fragments. These parts can then be modified any way you want.

Installation

You can use Composer to install Purl.

1
composer require jwage/purl

Usage

To use Purl, you have to include the vendor autoload file and then use the Url class in the Purl namespace. Optionally, you can give it an alias so you only have to use it instead of the namespace + class syntax.

1
2
3
4
5
<?php
require_once 'vendor/autoload.php';

use Purl\Url as purl;
?>

Getting a URL

To use Purl, create a new instance of it using the alias you’ve assigned earlier and then pass in the URL that you want to manipulate. In order to get the modified URL back, call the getUrl method.

1
2
3
4
<?php
$url = new purl('http://wern-ancheta.com');
echo $url->getUrl(); //http://wern-ancheta.com
?>

In the above code, the URL wasn’t really manipulated yet so it will return the same thing that you passed.

Getting Parts of the URL

You can use any of the following properties to extract different parts of the URL. Note that the subdomain in this specific URL will return an empty string since there’s no subdomain. If the URL was http://blog.wern-ancheta.com then the value for subdomain will be blog. Another thing to note is the canonical property. This returns everything in the URL except the scheme and the fragment. Also the publicSuffix is the first value, followed by the registerableDomain. So instead of wern-ancheta.com, you will see com.wern-ancheta. Lastly, the port is an empty string since it wasn’t explicitly specified in the URL. By default, website uses port 80 and it doesn’t need to be explicitly specified.

1
2
3
4
5
6
7
8
9
10
11
12
13
<?php
$url = new purl('http://wern-ancheta.com/some/path?query=some_query&another=query#fragment');

echo $url->scheme; // http
echo $url->port; // empty string
echo $url->publicSuffix; // com
echo $url->registerableDomain; // wern-ancheta.com
echo $url->subdomain; // empty string
echo $url->canonical; // com.wern-ancheta/some/path?query=some_query&another=query
echo $url->path; // /some/path
echo $url->query; // query=some_query&another=query
echo $url->fragment; // fragment
?>

Setting Parts of the URL

If you want to set the different parts of the URL, you have to use the static method parse and then pass in the URL you want to manipulate. This allows you to chain the set methods. If you initialize a new instance of the purl class instead, you will get an error.

1
2
3
4
5
6
7
8
9
10
11
12
<?php
$url = purl::parse('http://wern-ancheta.com')
    ->set('scheme', 'https')
    ->set('port', '1122')
    ->set('user', 'wern')
    ->set('pass', 'ancheta')
    ->set('path', 'some/path')
    ->set('query', 'query1=value1&query2=value2')
    ->set('fragment', 'my-fragment');

echo $url->getUrl(); // https://wern:ancheta@wern-ancheta.com:1122/some/path?query1=value1&query2=value2#my-fragment
?>

If you want to individually add paths to the URL, you have to initialize a new instance of the purl class.

1
2
3
4
5
<?php
$url = new purl('http://wern-ancheta.com');
$url->path->add('my')->add('awesome')->add('page');
echo $url->getUrl(); //http://wern-ancheta.com/my/awesome/page
?>

If you need to individually set the query parameters, you can use teh setData method. This allows you to pass in an associative array with its key being the query and the value being the value for that query.

1
2
3
4
5
6
7
8
<?php
$url = new purl('http://wern-ancheta.com');
$url->query->setData(array(
    'query1' => 'value1',
    'query2' => 'value2'
));
echo $url->getUrl(); //http://wern-ancheta.com/?query1=value1&query2=value2
?>

If it’s the other way around, and you want to extract the query parameters from a specific URL. Here’s the way you do it.

1
2
3
4
<?php
$url = new purl('http://wern-ancheta.com?query1=value1&query2=value2');
print_r($url->query->getData()); // Array ( [query1] => value1 [query2] => value2 )
?>

Extracting URL’s

One bonus feature of this library is that it allows you to extract URL’s in a specific string of text. Call the static extract method to use this. You can then extract each individual URL by using the key.

1
2
3
4
5
6
<?php
$str = "Hey I'm a string with url's in it http://google.com and another one http://github.com";
$urls = purl::extract($str);
echo $urls[0] . "<br>";
echo $urls[1];
?>

Note that each extracted URL’s are Purl URL instances of their own. So you can actually extract or manipulate individual parts as well.

1
2
3
4
5
6
<?php
echo $urls[0]->registerableDomain; //google.com

$urls[0]->path->add('my')->add('awesome')->add('path');
echo $urls[0]->getUrl(); //http://google.com/my/awesome/path
?>

Conclusion

In this tutorial, you’ve learned about Purl, a URL manipulation library for PHP. For more information, check out their official Github project page.

Comments