Permalink
Generate and resolve permalinks: short random hex codes that each stand in for a database entity, given by an item type and an item id. A permalink lets you refer to a row without exposing its underlying database id. Every permalink string is globally unique, so one string identifies at most one entity.
This page is a pure reference. For how the framework fits together, see the Guide.
Permalink- compare permalink data and test a permalink string.PermalinkData- immutable data for a resolved permalink.PermalinkDatabase- create, read and count permalinks in the database.PermalinkIs- test whether a string is a permalink.PermalinkRoute- route a path segment as a permalink of a given item type.PermalinkSecurity- validate and pass through a permalink string from input.
Permalink
Compare two permalink data objects, and test whether a string is a clean permalink of hex characters and at least a given length.
Equals
Permalink::Equals(PermalinkData $first, PermalinkData $second): bool
Whether two permalink data objects have the same permalink string.
| Name | Type | Description |
|---|---|---|
$first | PermalinkData | The first permalink to compare. |
$second | PermalinkData | The second permalink to compare. |
Returns bool True when both permalink strings are equal.
IsCleanString
Permalink::IsCleanString(string $permalinkString, int $minLength): bool
Whether a string contains only hex characters (0 to 9 and a to f) and is at least the given minimum length.
| Name | Type | Description |
|---|---|---|
$permalinkString | string | The string to test. |
$minLength | int | The minimum length the string must reach. |
Returns bool True when the string is all hex and long enough.
PermalinkData
Immutable data for a resolved permalink: its own id and string, and the item type, item type id and item id it points to. Fields and constructor only.
Properties
| Property | Type | Description |
|---|---|---|
$data->id | int | The permalink's own database id (readonly). |
$data->string | string | The permalink string itself (readonly). |
$data->itemType | string | The name of the item type the permalink points to (readonly). |
$data->itemTypeId | int | The id of the item type (readonly). |
$data->itemId | int | The id of the item the permalink points to (readonly). |
__construct
new PermalinkData(int $id = 0, string $string = '', string $itemType = '', int $itemTypeId = 0, int $itemId = 0)
Create permalink data from its id, string, item type, item type id and item id.
| Name | Type | Description |
|---|---|---|
$id | int | The permalink's own database id. |
$string | string | The permalink string. |
$itemType | string | The name of the item type. |
$itemTypeId | int | The id of the item type. |
$itemId | int | The id of the item pointed to. |
Returns PermalinkData
PermalinkDatabase
Create, read and count permalinks in the database. Add makes a new random permalink for an entity (or returns the existing one), the Get family resolves permalinks back to entities, and item types are recorded and reused automatically.
Add
PermalinkDatabase::Add(string $itemType, int $itemId, string $entropy = '', int $minLength = 16, int $lengthIncrement = 1): PermalinkData
Add a permalink for the item of the given type and id. When the item already has a permalink the existing one is returned, otherwise a new random one is generated, growing in length as more permalinks exist.
| Name | Type | Description |
|---|---|---|
$itemType | string | The item type name, for example clip_project. |
$itemId | int | The id of the item to make a permalink for. |
$entropy | string | Extra entropy mixed into the generated string. |
$minLength | int | The shortest length to try, from 1 to 16. |
$lengthIncrement | int | How much to grow the length by when a length is too full, from 1 to 16. |
Returns PermalinkData The new or existing permalink.
AddString
PermalinkDatabase::AddString(string $itemType, int $itemId, string $permalinkString): PermalinkData
Create a permalink with a known string for the item of the given type and id.
| Name | Type | Description |
|---|---|---|
$itemType | string | The item type name. |
$itemId | int | The id of the item. |
$permalinkString | string | The exact permalink string to store. |
Returns PermalinkData The created permalink.
Count
PermalinkDatabase::Count(): int
The total number of permalinks that already exist.
Returns int The number of permalinks.
CreatePermalinkString
PermalinkDatabase::CreatePermalinkString(string $entropy, int $length): string
Create a random hex permalink string of the given length.
| Name | Type | Description |
|---|---|---|
$entropy | string | Extra entropy to mix into the string. |
$length | int | The length of the string, from 1 to 16. |
Returns string A random hex string.
Get
PermalinkDatabase::Get(string $itemType, string $permalinkString): PermalinkData
The permalink data when the given permalink string points to an item of the given type. Throws when no such row exists.
| Name | Type | Description |
|---|---|---|
$itemType | string | The item type the permalink must belong to. |
$permalinkString | string | The permalink string to find. |
Returns PermalinkData The resolved permalink.
GetByItemId
PermalinkDatabase::GetByItemId(string $itemType, int $itemId): PermalinkData
The permalink for the item of the given type and id.
| Name | Type | Description |
|---|---|---|
$itemType | string | The item type name. |
$itemId | int | The id of the item. |
Returns PermalinkData The permalink for that item.
GetByString
PermalinkDatabase::GetByString(string $permalinkString): PermalinkData
The permalink data for a permalink string, regardless of item type.
| Name | Type | Description |
|---|---|---|
$permalinkString | string | The permalink string to find. |
Returns PermalinkData The resolved permalink.
GetItemID
PermalinkDatabase::GetItemID(string $itemType, string $permalinkString): int
The id of the item pointed to by the given permalink string of the given type.
| Name | Type | Description |
|---|---|---|
$itemType | string | The item type the permalink must belong to. |
$permalinkString | string | The permalink string to resolve. |
Returns int The item id.
GetList
PermalinkDatabase::GetList(string $itemType, array $itemIds): array
The permalinks for a list of item ids of the given type, keyed by item id.
| Name | Type | Description |
|---|---|---|
$itemType | string | The item type name. |
$itemIds | array | A list of item ids. |
Returns array A map of item id to PermalinkData.
GetListByItemIDs
PermalinkDatabase::GetListByItemIDs(string $itemType, array $itemIds): array
The permalinks for a list of item ids of the given type, returned as a list in a single query.
| Name | Type | Description |
|---|---|---|
$itemType | string | The item type name. |
$itemIds | array | A list of item ids. |
Returns array A list of PermalinkData.
OptionalGetByString
PermalinkDatabase::OptionalGetByString(string $permalinkString): PermalinkData|null
The permalink data for a permalink string, or null when no permalink with that string exists.
| Name | Type | Description |
|---|---|---|
$permalinkString | string | The permalink string to find. |
Returns PermalinkData|null The resolved permalink, or null.
PermalinkIs
A boolean test for whether a string is a permalink.
Permalink
PermalinkIs::Permalink(string $permalinkString): bool
Whether the given string is a clean permalink string.
| Name | Type | Description |
|---|---|---|
$permalinkString | string | The string to test. |
Returns bool True when the string is a permalink.
PermalinkRoute
Route the next path segment as a permalink of a specific item type. The segment is resolved with a single lookup and, only when it exists and is of the requested type, the callback is invoked with the permalink data. On any miss the route declines and leaves the segment unconsumed, so several Type calls for different item types can share the same parent directory.
Type
PermalinkRoute::Type(string $itemType, callable $callback): void
Route the next path segment as a permalink of the given item type, calling the callback with the permalink data on a match and declining otherwise.
| Name | Type | Description |
|---|---|---|
$itemType | string | The permalink item type, for example ClipSnapshot. |
$callback | callable | Called as fn(PermalinkData $permalink): void when the segment matches. |
Returns void
PermalinkSecurity
Validate a permalink string coming from input and pass it through, throwing when it is not a valid permalink.
Permalink
PermalinkSecurity::Permalink(string $permalinkString): string
Check that a value is a string and a valid permalink, then return it. Throws when it is invalid.
| Name | Type | Description |
|---|---|---|
$permalinkString | string | The permalink string to validate. |
Returns string The validated permalink string.
PermalinkOrNull
PermalinkSecurity::PermalinkOrNull(string|null $permalinkString = null): string|null
Validate a permalink string the same way, but allow null and pass null straight through. Throws when a non-null value is not a valid permalink.
| Name | Type | Description |
|---|---|---|
$permalinkString | string|null | The permalink string to validate, or null. |
Returns string|null The validated permalink string, or null.