decodelabs/singularity

Consolidated URI parsing and resolving

v0.2.9 2024-09-04 21:31 UTC

Requires

• php: ^8.1
• decodelabs/archetype: ^0.3.7
• decodelabs/collections: ^0.9
• decodelabs/compass: ^0.2
• decodelabs/exceptional: ^0.4.4
• decodelabs/glitch-support: ^0.4.4
• psr/http-factory: ^1.0
• psr/http-message: ^2.0

Requires (Dev)

• decodelabs/phpstan-decodelabs: ^0.6.7

MIT

• Tom Wright

README

Consolidated URI parsing and resolving

Singularity provides a unified interface for parsing and resolving URIs, PSR-7 URLs and file paths.

Get news and updates on the DecodeLabs blog.

Installation

Install via Composer:

composer require decodelabs/singularity

Usage

Parse and normalize URIs:

use DecodeLabs\Singularity;

dd(
    // ::uri() will parse any valid URI
    Singularity::uri('mailto:[e-mail]'),

    // ::url() will parse any valid URL
    Singularity::url('http://user:[e-mail]:8080/resource/page.html?param1=value1&param2=value2#section1'),
    Singularity::url('ftp://ftp.example.com/files/document.pdf'),
    Singularity::url('mailto:[e-mail]?subject=Hello&body=Hi%20there')->getEmailAddress(),
    Singularity::url('tel:[phone]'),

    // ::urn() will parse any valid URN
    Singularity::urn('urn:isbn:0-486-27557-4'),
    Singularity::urn('urn:ietf:rfc:3986')->getNamespace(), // ietf
    Singularity::urn('urn:oid:2.16.840')->getIdentifier(), // 2.16.840
);

Parse query strings to Tree:

use DecodeLabs\Singularity;

$url = Singularity::uri('http://www.example.com?param1=value1&param2=value2');
$tree = $url->parseQuery();
echo $tree->param2->as('string'); // value2

// Update query
$newUrl = $url->withQuery(function($tree, $url) {
    $tree->param2 = 'newValue2';
    $tree->param3 = 'value3';
    return $tree;
});

Parse and normalize file paths:

use DecodeLabs\Singularity;

dd(
    // ::path() will parse any valid file path
    Singularity::path('/path/to/file.txt'),
    Singularity::path('C:\path\to\file.txt'),
    Singularity::path('file:///path/to/file.txt'),
    Singularity::path('file://C:/path/to/file.txt'),

    // ::canonicalPath() will parse any valid file path and normalize it
    Singularity::canonicalPath('/path/to/inner/./directory/../../file.txt'), // /path/to/file.txt
);

$url = Singularity::uri('http://www.example.com?param1=value1&param2=value2');
$url->withPath(function($path) {
    $path->setFileName('file.txt');
    return $path;
});

Licensing

Singularity is licensed under the proprietary License. See LICENSE for the full license text.