PHPackages                             iceylan/urlify - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. iceylan/urlify

ActiveLibrary[Utility & Helpers](/categories/utility)

iceylan/urlify
==============

Modern PHP URL parser with modular components.

v1.0.0(1y ago)11MITPHP

Since Apr 22Pushed 1y ago1 watchersCompare

[ Source](https://github.com/ismailceylan/php-urlify)[ Packagist](https://packagist.org/packages/iceylan/urlify)[ RSS](/packages/iceylan-urlify/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (1)Versions (2)Used By (0)

Urlify
------

[](#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?
-----------------

[](#-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
-----------------------

[](#-architecture-overview)

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

ComponentClassResponsibilityScheme`Scheme`Handles URL scheme (e.g., `http`, `https`, `ftp`, etc.)Host`Host`Handles domain or IP address, subdomains, and portPath`Path`Manages the path portion of the URLQuery`Query`Represents the query string as a structured, iterable objectFragment`Fragment`Represents the URL fragment (`#...`), also compatible with QueryEntry`QueryEntry`Represents an individual key-value pair or flag in the queryURL`Url`Central orchestrator class that ties all parts togetherAll of these classes are designed to be loosely coupled and easily testable.

---

🔧 Primary Features
------------------

[](#-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
-----------

[](#-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
--------------

[](#-installation)

Urlify can be installed via [Composer](https://getcomposer.org/), the standard PHP dependency manager.

```
composer require iceylan/urlify
```

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

```
require 'vendor/autoload.php';
```

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

```
use Iceylan\Urlify\Url;
use Iceylan\Urlify\Query\Query;
use Iceylan\Urlify\Fragment;
```

ℹ️ Urlify is compatible with `PHP 8.1` or higher.

---

⚡ Quick Example
---------------

[](#-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.

```
use Iceylan\Urlify\Url;
use Iceylan\Urlify\Query\Query;

// The URL we're working with
$url = new Url(
    'https://example.com/something/utm_medium=target:readme|foo:bar&utm_source=github/its-me'
);

// Get the dataset as a Query object (we can use negative indexes)
$segmentAsQuery = $url->path->getSegmentAsQuery( -2 );

// Extract the utm_medium value as a Query object
$mediumAsQuery = $segmentAsQuery->getAsQuery( 'utm_medium', '|', ':' );

// access the target key's value
echo $mediumAsQuery->get( 'target' ); // "readme"
```

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

```
echo $url
        ->path
        ->getSegmentAsQuery( -2 )
        ->getAsQuery( 'utm_medium', '|', ':' )
        ->get( 'target' );
// readme
```

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
-------------

[](#-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

[](#-creating-a-url-instance)

```
use Iceylan\Urlify\Url;

$url = new Url( 'https://user:pass@example.com:8080/users//foo/../profile?view=full#section1' );
```

### 🔹 Accessing URL Components

[](#-accessing-url-components)

```
$url->scheme;
$url->auth;
$url->host;
$url->port;
$url->path;
$url->query;
$url->fragment;
```

### 🔹 Modifying the URL

[](#-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:

```
echo $url
    ->setHost( 'iceylan.dev' )
    ->setScheme( 'http' )
    ->setPort( 3000 )
    ->setFragment( 'new-section' );

// Output: http://iceylan.dev:3000/users/profile?view=full#new-section
```

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

### 🔹 String Conversion

[](#-string-conversion)

You can also cast the URL object into string directly:

```
echo $url; // Outputs: https://example.com:8080/users/profile?view=full#section1
```

### 🔹 Array Conversion

[](#-array-conversion)

Or you can also convert it to an array:

```
var_dump( $url->toArray());

// Outputs:
// [
// 	'scheme'   => 'https://',
// 	'user'     => 'user',
// 	'pass'     => 'pass',
// 	'host'     => 'example.com',
// 	'port'     => ':8080',
// 	'path'     => '/user/profile',
// 	'query'    => '?view=full',
// 	'fragment' => '#section1',
// ]
```

### 🔹 JSON Serialization

[](#-json-serialization)

And finally, you can convert it to JSON:

```
echo json_encode( $url );
```

and output:

```
{
    "scheme":{
        "name": "https",
        "isSecure": true,
        "isKnown": true
    },
    "auth": {
        "user": "user",
        "pass": "pass"
    },
    "host": {
        "subdomains": [],
        "subdomainName": null,
        "primaryDomainName": "example",
        "topLevelDomain": "com",
        "rootDomain": "example.com"
    },
    "port": {
        "address": 8080,
        "effective": 8080
    },
    "path": {
        "rawSegments": [ "", "users", "", "foo", "..", "profile" ],
        "resolvedSegments": [ "users", "profile" ]
    },
    "query": {
        "view": [ "full" ]
    },
    "fragment": {
        "fragment": "section1",
        "asQuery": null
    }
}
```

---

🧩 Builder Mode
--------------

[](#-builder-mode)

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

```
use Iceylan\Urlify\Url;

echo ( new Url )
    ->setScheme( 'ws' )
    ->setHost( 'example.com' )
    ->setPath( '/users/profile' )
    ->setQuery( 'view=full&flag' )
    ->setFragment( 'section1' );

// Outputs: wa://example.com/users/profile?view=full&flag#section1
```

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

```
use Iceylan\Urlify\Url;

$url = ( new Url )
    ->setScheme( 'ws' )
    ->setHost( 'example.com' );

$url->path
    ->append( 'profile' )
    ->prepend( 'users' );

echo $url;
// Outputs: ws://example.com/users/profile
```

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

```
$url = ( new Url )
    ->setScheme( 'ws' )
    ->setHost( 'example.com' )
    ->buildPath( fn ( $path ) =>
        $path
            ->append( 'profile' )
            ->prepend( 'users' )
    )
    ->setQuery( 'view=full&flag' );

echo $url;
// Outputs: ws://example.com/users/profile?view=full&flag
```

---

🔸 Scheme
--------

[](#-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

[](#-instantiating)

Accessing via `Url` object:

```
use Iceylan\Urlify\Url;

$scheme = ( new Url( 'https://example.com' ))->scheme;
```

Using `Scheme` class standalone:

```
use Iceylan\Urlify\Scheme;

$scheme = new Scheme( 'https' );
```

Without an initial value:

```
$scheme = new Scheme;
```

### 👁️ Getting the Scheme

[](#️-getting-the-scheme)

You can retrieve the current scheme:

```
$scheme->get(); // 'https'
(string) $scheme; // 'https://'
```

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

### ✍️ Setting the scheme

[](#️-setting-the-scheme)

Set the scheme value:

```
echo $scheme->set( 'tel' ); // 'tel:'
```

Or set it through Url:

```
echo $url->setScheme( 'sms' ); // 'sms:'
```

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

### 🧹 Cleaning the scheme

[](#-cleaning-the-scheme)

Clear the scheme completely:

```
echo $scheme->clean(); // ''
```

Alternative methods:

```
echo $scheme->set( null ); // ''
echo $url->setScheme( null ); // ''
```

### 🔐 Is the scheme secure?

[](#-is-the-scheme-secure)

Check whether the scheme is marked as secure:

```
$scheme->set( 'ftp' )->isSecure(); // false
$scheme->set( 'ftps' )->isSecure(); // true
```

### 🤔 Is the scheme known?

[](#-is-the-scheme-known)

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

```
$scheme->set( 'mysql' )->isKnown(); // true
$scheme->set( 'asgardia' )->isKnown(); // false
```

### ➕ Registering a custom scheme

[](#-registering-a-custom-scheme)

Custom schemes can be registered globally:

```
Scheme::registerScheme( name: 'asgardia', suffix: '://', secure: true );

$scheme->set( 'asgardia' );

$scheme->isKnown(); // true
$scheme->isSecure(); // true

echo $scheme; // 'asgardia://'
```

### 🔄 JSON Serialization

[](#-json-serialization-1)

`Scheme` objects can be serialized into JSON.

```
json_encode( $scheme );
```

Yields:

```
{
	"name": "asgardia",
	"suffix": "://",
	"isSecure": true,
	"isKnown": true
}
```

---

🔸 Auth
------

[](#-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

[](#-instantiating-1)

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

```
use Iceylan\Urlify\Url;

$auth = ( new Url( 'https://username:password@example.com' ))->auth;
```

Or use the `Auth` class directly:

```
use Iceylan\Urlify\Auth;

$auth = new Auth( 'username', 'password' );
```

Or even instantiate without any credentials:

```
$auth = new Auth;
```

### 👁️ Reading Username and Password

[](#️-reading-username-and-password)

You can retrieve the username and password values separately.

```
$auth->getUser(); // 'username'
$auth->getPass(); // 'password'
```

If either is not set, null is returned.

### ✍️ Setting Username and Password

[](#️-setting-username-and-password)

Credentials can be set individually or together:

```
// You can set simultaneously
$auth->set( 'username', 'password' );

// Or separately
$auth->setUser( 'root' );
$auth->setPass( '1234' );

echo $auth; // 'root:1234@'
```

Partial credentials are also supported:

```
echo $url->auth->set( 'username', null ); // 'username@'
echo $url->auth->set( null, 'password' ); // ':password@'
```

### 🧹 Cleaning Credentials

[](#-cleaning-credentials)

Clear all authentication data with:

```
$auth->clean();
```

Or reset via setters:

```
// equivalent to clean method
$auth->set( null, null );

// clear separately
$auth->setUser( null );
$auth->setPass( null );
```

On Url:

```
// echo triggers Url::__toString method
echo $url->setUsername( null )->setPassword( null ); // ''
```

### ❓ Check If Empty

[](#-check-if-empty)

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

```
$auth->isEmpty(); // true or false
```

### 📤 JSON Serialization

[](#-json-serialization-2)

`Auth` objects can be converted into JSON.

```
json_encode( $auth );
```

Result:

```
{
	"user": "username",
	"pass": "password"
}
```

---

🔸 Host
------

[](#-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

[](#-instantiating-2)

Accessing host instance via `Url` object:

```
use Iceylan\Urlify\Url;

$host = ( new Url( 'https://example.com' ))->host;
```

Using Host class standalone:

```
use Iceylan\Urlify\Host;

$host = new Host( 'www.foo.example.co.uk' );
```

Without an initial value:

```
$host = new Host;
```

### 👁️ Retrieving Host Parts

[](#️-retrieving-host-parts)

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

```
$host->getSubdomainName();      // www.foo
$host->getSubdomains();         // ['www', 'foo']
$host->getPrimaryDomainName();  // example
$host->getTopLevelDomainName(); // co.uk
$host->getRootDomainName();     // example.co.uk
```

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

### ✍️ Manupulating Host

[](#️-manupulating-host)

You can manipulate the host parts with powerful methods.

#### Set Host As a Whole String

[](#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:

```
echo $host->set( 'subdomain.example.com' );
// 'subdomain.example.com'
```

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:

```
echo $url->setHost( 'api.example.com' );
// 'https://api.example.com'
```

#### Subdomain Manipulations

[](#subdomain-manipulations)

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

```
echo $host->setSubdomain( null ); // example.com
echo $host->setSubdomain( 'bar.baz' ); // bar.baz.example.com
```

You may also need to append or prepend existing subdomains.

```
echo $host->appendSubdomain( 'zoo' ); // bar.baz.zoo.example.com
echo $host->prependSubdomain( 'chat' ); // chat.bar.baz.zoo.example.com
```

#### Primary Domain Manipulations

[](#primary-domain-manipulations)

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

```
echo $host->setPrimaryDomainName( 'exam' ); // chat.bar.baz.zoo.exam.com
```

#### Top Level Domain Manipulations

[](#top-level-domain-manipulations)

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

```
echo $host->setTopLevelDomainName( 'co.uk' ); // chat.bar.baz.zoo.exam.co.uk
```

### 🧹 Clearing the Host

[](#-clearing-the-host)

Clear the host completely:

```
echo $host->clean(); // ''
// or
echo $host->set( null ); // ''
```

### 📤 JSON Serialization

[](#-json-serialization-3)

`Host` objects can be converted into JSON.

```
json_encode( $host );
```

Result:

```
{
	"subdomainName": "chat.bar.baz.qux.zoo",
	"subdomains": [ "chat", "bar", "baz", "qux", "zoo" ],
	"primaryDomainName": "exam",
	"rootDomain": "exam.co.uk",
	"topLevelDomain": "co.uk"
}
```

---

🔸 Port
------

[](#-port)

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

### 📥 Instantiating

[](#-instantiating-3)

Accessing port instance via `Url` object:

```
use Iceylan\Urlify\Url;

$port = ( new Url( 'https://example.com:8001' ))->port;
```

Using Port class standalone:

```
use Iceylan\Urlify\Port;

$port = new Port( 8001 );
```

Without an initial value:

```
$port = new Port;
```

### 👁️ Retrieving Port

[](#️-retrieving-port)

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

```
$port->get(); // 8001
```

If the port is not set, `null` is returned.

### ✍️ Setting Port

[](#️-setting-port)

You can set the port with the `set` method:

```
echo $port->set( 8001 ); // ':8001'
```

### Checking if Port is Defined

[](#checking-if-port-is-defined)

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

```
echo $port->isEmpty(); // false
```

### Retrieving Effective Port

[](#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.

```
echo $port->getEffective(); // 8001
```

### Default Port

[](#default-port)

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

```
use Iceylan\Urlify\Port;

echo Port::getDefaultPortForScheme( 'https' ); // 443
```

### 🧹 Clearing the Port

[](#-clearing-the-port)

Clear the port completely:

```
echo $port->clean(); // ''
// or
echo $port->set( null ); // ''
```

### 📤 JSON Serialization

[](#-json-serialization-4)

`Port` objects can be converted into JSON.

```
json_encode( $port );
```

Result:

```
{
    "address" => null,
    "effective" => 443
}
```

---

###  Health Score

25

—

LowBetter than 37% of packages

Maintenance47

Moderate activity, may be stable

Popularity3

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity37

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

392d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8c0b08cf02ef675e3989dd80ea4095994d56f50b7abc2c2afaf069766303489e?d=identicon)[ismailceylan](/maintainers/ismailceylan)

---

Top Contributors

[![ismailceylan](https://avatars.githubusercontent.com/u/2580129?v=4)](https://github.com/ismailceylan "ismailceylan (104 commits)")

### Embed Badge

![Health badge](/badges/iceylan-urlify/health.svg)

```
[![Health](https://phpackages.com/badges/iceylan-urlify/health.svg)](https://phpackages.com/packages/iceylan-urlify)
```

###  Alternatives

[bubbstore/correios

Biblioteca que faz cálculo de frete, rastreamento de objetos e consulta de CEP diretamente do Webservice dos Correios.

2589.0k](/packages/bubbstore-correios)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)