A PHP implementation of RFC 4151: The 'tag' URI Scheme.
A Tag URI is an identifier for a specific resource tied to a domain name or e-mail address at a given point in time.
It can look something like tag:example.org,2023:resource
.
It can be used when something should be identified using a human-readable URI, instead of non-resolvable HTTP URIs.
More information at taguri.org and the RFC.
composer require tthe/php-tag-scheme
$te = new \tthe\TagScheme\TaggingEntity('example.org');
$tag = $te->mint('something');
echo $tag; // Prints "tag:example.org,2023-10-22:something"
Tag URIs are created through a TaggingEntity
object based on a domain name or an e-mail address and a date.
The date defaults to today but can be set in various ways using DateUtil
.
use tthe\TagScheme\TaggingEntity;
use tthe\TagScheme\Util\DateUtil;
// The tagging authority can be either domain name or an e-mail address.
$authority = 'example.org';
// If no date is provided it will default to today.
$te1 = new TaggingEntity($authority);
// We can also set it to January 1 of the current year...
$te2 = new TaggingEntity($authority, DateUtil::FIRST_OF_YEAR);
// ...or the first day of the current month...
$te3 = new TaggingEntity($authority, DateUtil::FIRST_OF_MONTH);
// ...or an explicit date.
$te4 = new TaggingEntity($authority, DateUtil::date('2020-04-17'));
Minted tag URIs are objects implementing TagInterface
, and extends Stringable
and JsonSerializable
.
use tthe\TagScheme\TaggingEntity;
use tthe\TagScheme\Util\DateUtil;
$te = new TaggingEntity('demo@example.org', DateUtil::FIRST_OF_YEAR);
$tag = $te->mint('something');
echo $tag->toString();
// tag:demo@example.org,2023:something
echo $tag->getAuthority()->value();
// demo@example.org
echo $tag->getDate()->value()->format('Y-m-d');
// 2023-01-01
echo $tag->getResource()->value();
// something
It's also possible to do it the other way around:
$s = 'tag:example.org,2023:something';
$tag = \tthe\TagScheme\Tag::fromString($s);
echo $tag->getResource()->value();
// something
Tags, like all URIs, support query and fragment components. However, preserving human readability should always be prioritized.
use tthe\TagScheme\TaggingEntity;
use tthe\TagScheme\Util\DateUtil;
$te = new TaggingEntity('demo@example.org', DateUtil::FIRST_OF_YEAR);
echo $te->mint('something')
->withQuery(['param' => 'value'])
->withFragment('subresource');
// tag:demo@example.org,2023:something?param=value#subresource
For convenience, and despite the fact that tag URIs are not resolvable, a conversion method to the PSR-7 UriInterface is provided.
$s = 'tag:example.org,2023:something';
$tag = \tthe\TagScheme\Tag::fromString($s);
$psrImpl = $tag->toPsr7();
\tthe\TagScheme\TaggingEntity
implements \tthe\TagScheme\Contracts\TaggingEntityInterface
\tthe\TagScheme\Tag
implements \tthe\TagScheme\Contracts\TagInterface
A possible pattern can be to initiate a TaggingEntity object centrally in your project and map it to TaggingEntityInterface in your dependency injection container.