ForceDocumentUrlTrait
Adds a computed `url` property to documents returned by a controller.
This trait lets a controller force a canonical URL on a single document or on every
document of a collection, typically within the get() and list() methods. The URL
of a collection item is built by appending the document primary key to a base URL.
Tags
Table of Contents
Properties
- $documentKey : string|null
- The default document primary key used to build per-document URLs.
- $forceUrl : bool
- Indicates if the controller force an url over the resources in the get() and list() methods.
Methods
- initializeForceUrl() : static
- Initializes the document key and the force-url flag from an array.
- forceDocumentsUrl() : void
- Appends a url property on every document of the passed-in collection.
- forceDocumentUrl() : object|array<string|int, mixed>|null
- Appends a url property on the passed-in document reference.
Properties
$documentKey
The default document primary key used to build per-document URLs.
public
string|null
$documentKey
= \oihana\controllers\enums\ControllerParam::ID
$forceUrl
Indicates if the controller force an url over the resources in the get() and list() methods.
public
bool
$forceUrl
= false
Methods
initializeForceUrl()
Initializes the document key and the force-url flag from an array.
public
initializeForceUrl([array<string|int, mixed> $init = [] ]) : static
Parameters
- $init : array<string|int, mixed> = []
-
Initialization array, read from the ControllerParam::DOCUMENT_KEY and ControllerParam::FORCE_URL keys.
Return values
static —Returns the current instance for method chaining.
forceDocumentsUrl()
Appends a url property on every document of the passed-in collection.
protected
forceDocumentsUrl(array<string|int, mixed>|null &$documents, string|null $url[, string|null $key = null ][, string $propertyName = ControllerParam::URL ]) : void
For each document, the URL is built by concatenating the base $url, a slash separator
and the document primary key value. Documents that do not expose the key are left untouched.
Parameters
- $documents : array<string|int, mixed>|null
-
The collection of documents to decorate, passed by reference.
- $url : string|null
-
The base URL used to generate the URL of all documents.
- $key : string|null = null
-
The optional document primary key to use; falls back to $documentKey.
- $propertyName : string = ControllerParam::URL
-
The name of the property to set (defaults to ControllerParam::URL).
forceDocumentUrl()
Appends a url property on the passed-in document reference.
protected
forceDocumentUrl(object|array<string|int, mixed>|null &$document, string|null $url[, string $propertyName = ControllerParam::URL ]) : object|array<string|int, mixed>|null
The property is set in-place: on the array (when associative) or on the object, then the document is returned for convenience.
Parameters
- $document : object|array<string|int, mixed>|null
-
The document to decorate, passed by reference.
- $url : string|null
-
The URL value to assign to the document.
- $propertyName : string = ControllerParam::URL
-
The name of the property to set (defaults to ControllerParam::URL).
Return values
object|array<string|int, mixed>|null —The same document reference, decorated with the url property.