Download the PHP package iceylan/urlify without Composer

Urlify

Urlify is a lightweight, object-oriented PHP library designed for parsing, manipulating, and reconstructing URLs in a highly modular and intuitive way.

It provides fine-grained access to every component of a URL, such as scheme, authorization, host, path, query, and fragment through dedicated classes. Unlike typical URL parsers that only offer string-based access, Urlify structures these components as first-class objects, enabling more powerful and flexible manipulations.

🧩 Why Use Urlify?

URLs are often treated as plain strings, but in modern applications, we frequently need to:

• Add or remove query parameters
• Modify the fragment (#) portion of the URL
• Update only the path, keeping the query and host untouched
• Serialize the full URL again from its parts

Urlify abstracts all of this with clean, readable, and immutable-friendly interfaces, while giving you full control over the inner structure of the URL.

🧱 Architecture Overview

Urlify is built around a component-based architecture, where each part of the URL is encapsulated in its own class:

All of these classes are designed to be loosely coupled and easily testable.

🔧 Primary Features

• Full URL Parsing
  Create a Url object from a string and instantly access all parts via method calls.
• Immutable-Friendly API
  Most methods support chaining, enabling fluent and predictable transformations.
• Query Intelligence
  Flags (?foo&bar=baz) and key-value entries are separately handled via QueryEntry.
• Path Segments as Query The path segments can be parsed as a query object.
• Fragment as Query
  The fragment part (#...) can be parsed as a query object as well, useful for hash-based routing in SPAs.
• JSON Serializable
  All components can be converted to structured arrays or serialized into JSON easily.
• Object-Oriented Everything
  No need to use parse_url() and http_build_query() manually anymore.

✅ Use Cases

• Modify query parameters in a clean and testable way
• Dynamically generate URLs based on runtime conditions
• Convert fragments into navigable query structures
• Build router-like logic for backend or frontend integration
• Serialize or debug complex URLs in JSON format

📦 Installation

Urlify can be installed via Composer, the standard PHP dependency manager.

After installation, make sure to include Composer’s autoloader in your project:

All Urlify classes are namespaced under Iceylan\Urlify. You can either import specific classes or use them directly with their fully qualified names:

ℹ️ Urlify is compatible with PHP 8.1 or higher.

⚡ Quick Example

Let’s say you have a URL where a query string is embedded inside a path segment. Let's make it more compicated and add another level of nesting with a different separation. Now let's say you want to extract a value from that messy URL.

We can easily chain the above code into a single liner:

This example shows how flexible Urlify can be:

It separates the URL structure cleanly. You can treat path segments as independent values. You can easily re-parse segments, fragments, or query strings as new Query objects.

🔧 Basic Usage

The Url class is the main entry point to working with URL components. Once instantiated, it provides clean access to each part of the URL, and allows full manipulation with method chaining.

🔹 Creating a URL instance

🔹 Accessing URL Components

🔹 Modifying the URL

We can set a value for a segment and the value we give it will be parsed.

All setters return $this, so they support method chaining:

Each component (path, query, fragment) has its own powerful interface. In the next sections, we'll dive deeper into those.

🔹 String Conversion

You can also cast the URL object into string directly:

🔹 Array Conversion

Or you can also convert it to an array:

🔹 JSON Serialization

And finally, you can convert it to JSON:

and output:

🧩 Builder Mode

You can also use Urlify as a URL builder. It's a simple way to create URLs from scratch.

You can also use component methods to modify them more precisely:

We can also keep the chain alive with builder methods, for example:

🔸 Scheme

The scheme (also known as "protocol") represents the beginning of a URL and indicates how resources should be accessed, for example: http, https, ftp, etc.

The Url::$scheme property holds an instance of the Iceylan\Urlify\Scheme class, which allows both manipulation and introspection of the scheme.

📥 Instantiating

Accessing via Url object:

Using Scheme class standalone:

Without an initial value:

👁️ Getting the Scheme

You can retrieve the current scheme:

If not set, it returns null or an empty string on cast.

✍️ Setting the scheme

Set the scheme value:

Or set it through Url:

Urlify reconizes the known schemes and automatically appends the correct suffix.

🧹 Cleaning the scheme

Clear the scheme completely:

Alternative methods:

🔐 Is the scheme secure?

Check whether the scheme is marked as secure:

🤔 Is the scheme known?

Determine if the scheme is one of the known/registered ones:

➕ Registering a custom scheme

Custom schemes can be registered globally:

🔄 JSON Serialization

Scheme objects can be serialized into JSON.

Yields:

🔸 Auth

The auth property holds an instance of the Iceylan\Urlify\Auth class which represents the authentication part of a URL (i.e., username:password@).

📥 Instantiating

You can access the auth part directly via the Url instance:

Or use the Auth class directly:

Or even instantiate without any credentials:

👁️ Reading Username and Password

You can retrieve the username and password values separately.

If either is not set, null is returned.

✍️ Setting Username and Password

Credentials can be set individually or together:

Partial credentials are also supported:

🧹 Cleaning Credentials

Clear all authentication data with:

Or reset via setters:

On Url:

❓ Check If Empty

Determine whether the auth section (both username and password) is currently empty:

📤 JSON Serialization

Auth objects can be converted into JSON.

Result:

🔸 Host

The host component of a URL specifies the domain address that identifies the resource's location on the network. In Urlify, the host property is an instance of the Iceylan\Urlify\Host class, providing methods for manipulation and inspection of the host part.

This library uses a list of top-level domain names to separate the top-level domain names. It doesn't just take the latest part of a string separated by dots and treat it as the main domain. This approach tells us that co.uk is a top-level domain name.

📥 Instantiating

Accessing host instance via Url object:

Using Host class standalone:

Without an initial value:

👁️ Retrieving Host Parts

After setting the host, you can retrieve host parts by meaningful methods.

If any of these is not set, null is returned.

✍️ Manupulating Host

You can manipulate the host parts with powerful methods.

Set Host As a Whole String

Sometimes setting the host with a whole string is can be enough for you. We have a method for this:

When the set method is called, parsing processes will be start for given host and all the getter methods will return the parsed values.

You can also set the host directly on the Url object:

Subdomain Manipulations

Sometimes you need to set the subdomain as a whole string. We have a method for this:

You may also need to append or prepend existing subdomains.

Primary Domain Manipulations

You can also set the primary domain name with the setPrimaryDomainName method:

Top Level Domain Manipulations

You can also set the top-level domain name with the setTopLevelDomainName method:

🧹 Clearing the Host

Clear the host completely:

📤 JSON Serialization

Host objects can be converted into JSON.

Result:

🔸 Port

The port component of a URL specifies the port number used for communication with the resource.

📥 Instantiating

Accessing port instance via Url object:

Using Port class standalone:

Without an initial value:

👁️ Retrieving Port

After setting the port, you can retrieve the port with the get method:

If the port is not set, null is returned.

✍️ Setting Port

You can set the port with the set method:

Checking if Port is Defined

You can check if the port is defined with the isEmpty method:

Retrieving Effective Port

You can retrieve the effective port with the getEffective method. Effective port is the port set or the default port for the scheme if the port is not set.

Default Port

You can use Port class to query the default port for a given scheme:

🧹 Clearing the Port

Clear the port completely:

📤 JSON Serialization

Port objects can be converted into JSON.

Result: