alizharb/php85-uri-utils

A robust URL manipulation library for PHP 8.5 leveraging the new URI extension features.

v1.0.0 2025-11-20 22:59 UTC

Requires

• php: >=8.5

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

• Ali Harb

README

A modern, immutable, and type-safe URI manipulation library designed exclusively for PHP 8.5.

🚀 Introduction

Handling URLs in PHP has historically been messy, relying on parse_url, parse_str, and string concatenation. PHP 8.5 URI Utils changes that.

It provides a robust, object-oriented interface for parsing, modifying, and building URIs. With strict typing and immutability at its core, you can manipulate URLs with confidence and clarity.

Why use this package?

• Immutable Design: Every modification returns a new instance, preventing side-effects.
• Fluent Interface: Chain methods for readable, expressive code.
• Type Safety: Built for PHP 8.5 with strict typing and modern standards.
• Zero Dependencies: Lightweight, fast, and easy to drop into any project.
• Routing Helper: Includes a lightweight router for extracting dynamic path segments.

📦 Installation

composer require alizharb/php85-uri-utils

⚠️ Requirement: This library requires PHP 8.5 or higher.

🔧 Usage

Fluent URI Modification

Stop messing with string concatenation. Use the fluent API to modify parts of a URI safely.

use UriUtils\Uri;

$uri = Uri::parse('https://api.example.com/v1/users?active=true');

$newUri = $uri
    ->withScheme('http')
    ->withPort(8080)
    ->withPath('/v2/users')
    ->withQuery('active=false&sort=desc');

echo $newUri;
// Output: http://api.example.com:8080/v2/users?active=false&sort=desc

Query String Manipulation

The Query helper makes adding, removing, or merging parameters a breeze.

use UriUtils\Query;

$queryString = 'page=1&filters[status]=active';

// Add a parameter
$q1 = Query::withParam($queryString, 'sort', 'created_at');

// Remove a parameter
$q2 = Query::withoutParam($q1, 'page');

// Merge multiple parameters
$final = Query::merge($q2, ['limit' => 50, 'page' => 2]);

echo $final;
// Output: filters%5Bstatus%5D=active&sort=created_at&limit=50&page=2

Simple Routing

Extract dynamic segments from paths without complex regex.

use UriUtils\Router;

$route = '/users/{id}/posts/{slug}';
$path = '/users/42/posts/hello-world';

$params = Router::match($path, $route);

// Result:
// [
//     'id' => '42',
//     'slug' => 'hello-world'
// ]

📚 API Reference

Uri Class

Method	Description
parse(string $uri): self	Static factory to create a Uri instance.
getScheme(): string	Returns the scheme (e.g., 'https').
withScheme(string $scheme): self	Returns a new instance with the specified scheme.
getHost(): string	Returns the host.
withHost(string $host): self	Returns a new instance with the specified host.
getPath(): string	Returns the path.
withPath(string $path): self	Returns a new instance with the specified path.
getQuery(): string	Returns the query string.
withQuery(string $query): self	Returns a new instance with the specified query.
__toString(): string	Converts the object back to a string.

Query Class

Method	Description
parse(string $query): array	Parses a query string into an array.
build(array $params): string	Builds a query string from an array.
withParam(string $query, string $key, mixed $value): string	Adds/updates a parameter.
withoutParam(string $query, string $key): string	Removes a parameter.
merge(string $query, array $params): string	Merges an array of parameters.

🧪 Testing

Run the test suite with PHPUnit:

composer test

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

1. Fork the repository.
2. Create a feature branch.
3. Commit your changes.
4. Push to the branch.
5. Open a Pull Request.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Made with ❤️ by Ali Harb