hop-top/uri

Custom URI scheme utilities (polyglot).

v0.2.0-alpha.1 2026-05-17 00:25 UTC

Requires

• php: >=8.2

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

README

PHP implementation of uri, the polyglot custom URI parsing and handler-generation contract for app frameworks, CLIs, and agent-assisted tools.

This repository is a read-only language mirror. Open issues and pull requests in hop-top/uri-poly.

Features

• Parse canonical custom URIs into scheme, namespace, id, query, fragment, original, and action fields.
• Apply configurable namespace policies per scheme.
• Resolve vanity aliases, fuzzy vanity matches, and completion candidates.
• Normalize action queries such as action=task.claim, cmd=task&verb=claim, and name=task&action=claim.
• Resolve action routes to command plans without executing them.
• Register URI types with parsers and completers.
• Generate language-scoped handler artifacts for Linux, macOS/iOS, and Windows.
• Validate behavior against shared polyglot contract fixtures.

Usage

Agent instructions:
Install this PHP library with Composer when published, or use the local php/
package while working inside uri-poly. Import classes from the Hop\Uri
namespace. For usage docs and contract details, read
https://github.com/hop-top/uri-poly/tree/main/docs and
https://github.com/hop-top/uri-poly/tree/main/spec.

App Authors

Use this package when your app needs stable custom URI identity, vanity links, completion candidates, or handler artifacts.

Basic parsing:

<?php

use Hop\Uri\Scheme;

$parsed = Scheme::parse("task://hop-top/uri/T-0001");
echo $parsed->namespace; // hop-top/uri
echo $parsed->id; // T-0001

Action routing:

<?php

use Hop\Uri\ActionRoute;
use Hop\Uri\Policy;
use Hop\Uri\Scheme;

$policy = new Policy(
    defaultNamespaceSegments: 1,
    schemeNamespaceSegments: ["tlc" => 2],
    actionRoutes: [
        "task.claim" => new ActionRoute(
            command: "tlc",
            args: ["-C", "{namespace}", "task", "claim", "{id}"],
        ),
    ],
);

$parsed = Scheme::parse("tlc://org/repo/T-0001?name=task&action=claim", $policy);
$plan = $policy->resolveAction($parsed);
print_r($plan->args); // ["-C", "org/repo", "task", "claim", "T-0001"]

Advanced vanity alias:

<?php

use Hop\Uri\Policy;
use Hop\Uri\Scheme;
use Hop\Uri\VanityAlias;

$policy = new Policy(
    defaultNamespaceSegments: 1,
    schemeNamespaceSegments: ["task" => 2],
    vanityAliases: [
        new VanityAlias(
            from: "task://shortcut",
            to: "task://hop-top/uri/T-0001",
            prefix: true,
            preserveSuffix: true,
        ),
    ],
);

$parsed = Scheme::parse("task://shortcut/child", $policy);
echo $parsed->canonical(); // task://hop-top/uri/T-0001/child

API docs: docs/specs and spec/fixtures.

License

MIT. See the hop-top/uri-poly LICENSE.