README

Web addresses as normalised values, with their kind detected: Facebook, YouTube, Mastodon, a website.

phil/url reads an absolute http or https address into a Url, normalised: lowercase host, default port dropped, international host names in punycode, and a display() form as people read it. Kinds of address are enum cases implementing UrlType, each carrying its own rule: a Facebook page is an address on facebook.com. KnownUrlType holds 26 international kinds, from Facebook and YouTube to Mastodon on any server and a plain website. UrlTypes detects which kind an address is among the enum sets a field accepts, and CookielessVideo turns a YouTube or Vimeo video into its player that writes no cookies. It does not fetch addresses, follow redirects, check that a page exists, or hold the kinds of a region.

It is for applications where people enter links to their profiles and sites: a directory, a member page, an event listing. The kinds of a region, such as a business registry or a government portal, belong to the application as its own enum, accepted next to KnownUrlType. Detection takes the first case that accepts, set by set, so specific cases go first and catch-all ones last.

phil/url is a plain PHP library on ext-intl, ext-mbstring and phil/enums, whose EnumSet carries the accepted kinds. In a Symfony application, reach for phil/url-bundle: a form field that detects the kind, the constraint UrlOfType, a Doctrine column type and Twig filters. The design rests on value types and enums: a TypedUrl is an address with its kind, and a kind is any case of any enum that says whether it accepts an address.

Status

Part	State
`Url`: parsing, normalisation, international hosts, display	Implemented and tested
`UrlType`, and `KnownUrlType`: 26 international kinds	Implemented and tested
`TypedUrl`, and `UrlTypes`: detecting the kind among enum sets	Implemented and tested
`CookielessVideo`: YouTube and Vimeo players without cookies	Implemented and tested
Exceptions under one `UrlException` interface	Implemented and tested

Documentation

Document	What it covers
Installation	Requirements and installing.
Addresses	`Url`: what is accepted, how it is normalised and shown.
Kinds	`UrlType`, the international kinds, an application's own, detection among enum sets, video players without cookies.
Extension points	The ports, arguments and data an application chooses or replaces.
Testing	The library's tests and mutation bar.
Reference	Every type of the library, with its role.

Quick start

composer require phil/url

use Phil\Enums\Collection\EnumSet;
use Phil\Url\KnownUrlType;
use Phil\Url\UrlTypes;

$social = EnumSet::of(KnownUrlType::class, KnownUrlType::Facebook, KnownUrlType::Instagram);

$typed = UrlTypes::type('https://www.instagram.com/shop', $social);
$typed->type;              // KnownUrlType::Instagram
$typed->url->display();    // "instagram.com/shop"

Requirements

PHP 8.5 or later with ext-intl and ext-mbstring; phil/enums 0.3.

Contributing

Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.

phil / url

Package info

Security

Statistics