Download the PHP package jstewmc/url without Composer

Url

A class to create, parse, and manipulate Uniform Resource Locators (URL).

A Uniform Resource Locator (URL) is a string that identifies a resource and describes how to locate it.

Most of the time, PHP (or your PHP framework) will handle creating, parsing, and manipulating URLs for you. However, every once in a while, you'll need to work with a URL manually.

I've always found working with a URL as a string can be a little cumbersome. So, I created a URL class:

These examples are a little contrived (a string might be faster for some of these) and verbose (you can chain most of the methods). However, I think you get the point.

Feel free to check out the API documentation, report an issue, contribute, or ask a question.

Url

This class is based on (and makes use of) PHP's parse_url() function.

As far as this class (and that function) are concerned, a URL is composed of the following parts:

• scheme - the protocol (e.g., http or https)
• username - a username for authentication
• password - a password for authentication
• host - the domain or IP address (e.g., example.com or 123.123.123.123)
• port - the server's port (e.g., 80 for http or 443 for https)
• path - the file's path on the server (e.g., path/to/file)
• query - a string of key-value pairs (aka, ?foo=bar)
• fragment - an anchor within the page (e.g., #example)

Putting it all together:

Format

As far as this class is concerned, URLs come in two formats: relative and absolute. An absolute URL includes all its non-empty parts. On the other hand, a relative URL includes the URL's path, query, and fragment.

When used as a string, this class will return its absolute URL. However, you can use the format() method to return its relative URL:

Case

In line with W3 guidelines, the Url class is case-sensitive. According to the W3:

URLs in general are case-sensitive (with the exception of machine names). There may be URLs, or parts of URLs, where case doesn't matter, but identifying these may not be easy. Users should always consider that URLs are case-sensitive.

Scheme, Host, Port, and Fragment

The Url's scheme, host, port, and fragment are simple strings:

Path

The Url's path can be treated as a string or Path object:

A path is composed of segments. For example, the path foo/bar/baz has three segments: foo, bar, and baz.

Segments are indexed started with 0. So, in the path foo/bar/baz, the index of foo is 0. The index of bar is 1, and the index of baz is 2.

Most methods that use a segment's index as an argument will accept an offset. An offset can be positive (that many places from the beginning of the path) or negative (that many places from the end of the path). In addition, most methods accept the special strings first and last.

You can append, prepend, insert, set, and unset a path's segments:

You can also get, find, and verify a segment by value or offset:

Finally, you can slice and reverse a path:

The Url class depends on my Path class. See that README.md for details.

Query

A query can be treated as a string or Query object:

A query is composed of parameters. For example, in the query foo=bar&baz=qux, there are two parameters, foo and baz. The value of foo is bar, and the value of baz is qux. A query is commonly thought of as a list of key-value pairs.

Unlike a path, where order matters, order does not matter in a query string. A parameter is there, or it is not.

You can set or unset a query's parameters:

You can also get or verify a parameter:

Separators

The Url class parses paths and queries under the assumption that you're using the default separators: the forward-slash character ("/") for paths and the ampersand character ("&") for query parameters.

If you are using a different parameter, you should avoid parsing the url on instantiation. Instead, you should set the separators manually and then parse the url:

Customizing

In most of the examples above, I have to set the scheme and host explicitly every time. That can get annoying.

One solution is to extend the Url class to create a MyUrl class with your default settings:

One-liner

Of course, we wouldn't be cool if we couldn't whip out a cryptic one-liner (using PHP 5.4+ method chaining):

Tests

I've written unit tests with an average of 93% code coverage. I'm still learning how to write great tests. So, feel free to check them out and tell me what you think.

Contributing

Feel free to contribute your own improvements:

1. Fork
2. Clone
3. PHPUnit
4. Branch
5. PHPUnit
6. Code
7. PHPUnit
8. Commit
9. Push
10. Pull request
11. Relax and eat a Paleo muffin

See contributing.md for details.

Author

Jack Clayton - [email protected].

License

Url is released under the MIT License. See the LICENSE file for details.

History

You can view the (short) history of the Url project in the changelog.md file.