Oihana PHP

AlterUrlPropertyTrait uses trait:short

Generates URL strings from document properties, with support for base URL resolution from a DI container.

This trait is typically used as part of the AlterDocumentTrait workflow to transform document properties into complete URLs. It leverages joinPaths() for robust path joining that handles various path types (Unix, Windows, scheme-based URLs, etc.).

Features:

  • Combines base URLs (from container or parameters) with path segments
  • Extracts property values from arrays or objects using getKeyValue()
  • Optionally resolves base URL from a DI container
  • Adds trailing slashes when needed
  • Handles multiple URL formats (relative paths, absolute URLs, Windows paths, Phar archives)

Usage Examples:

Simple relative URL:

$document = ['id' => 42, 'slug' => 'product-name'];
$url = $this->alterUrlProperty($document, ['/api/products']);
// Result: '/api/products/42'

With custom property:

$url = $this->alterUrlProperty($document, ['/api/products', 'slug']);
// Result: '/api/products/product-name'

Skip container resolution explicitly:

$url = $this->alterUrlProperty($document, ['/api/products', 'id', false]);
// Result: '/api/products/42'  (no base URL prepended)

With container-resolved base URL and trailing slash:

// Assumes container has 'baseUrl' => 'https://example.com'
$url = $this->alterUrlProperty(
    $document,
    ['/api/products', 'id', 'baseUrl', true],
    $container,
    $modified,
    'id'
);
// Result: 'https://example.com/api/products/42/'

In AlterDocumentTrait configuration:

$this->alters =
[
    'url'  => [Alter::URL, '/places', 'id'],
    'link' => [Alter::URL, '/products', 'slug', 'baseUrl', true],
];
Tags
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Properties

$alterKey  : string
The default property key used when an alteration needs to read a value from the document.

Methods

alterUrlProperty()  : string
Generates a complete URL by combining path segments and document properties.
initializeAlterKey()  : static
Initializes the {@see $alterKey} property from an initialization array.

Properties

$alterKey

The default property key used when an alteration needs to read a value from the document.

public string $alterKey = \org\schema\constants\Schema::ID

Consumed for instance by AlterUrlPropertyTrait to pick which property provides the final URL segment when none is given explicitly. Defaults to Schema::ID.

Tags
see
AlterUrlPropertyTrait

Methods

alterUrlProperty()

Generates a complete URL by combining path segments and document properties.

public alterUrlProperty(array<string|int, mixed>|object $document[, array<string|int, mixed> $options = [] ][, Container|null $container = null ][, bool &$modified = false ][, string|null $propertyName = null ][, string $containerKey = 'baseUrl' ]) : string

The method builds a URL in the following order:

  1. Resolves the base URL from the container (if containerKey is provided and not false)
  2. Joins the base URL with the provided path segment
  3. Appends the property value from the document
  4. Optionally adds a trailing slash

Parameters via $options array:

  • [0] (string) — Path segment to append after base URL (e.g., '/products', '/api/v1/users')
  • [1] (string) — Document property name containing the final segment (default: 'id')
  • [2] (string|bool) — Container service key for base URL resolution or false to skip (default: 'baseUrl')
  • [3] (bool) — Add trailing slash to the result (default: false)
Parameters
$document : array<string|int, mixed>|object

The document (array or object) to read property values from.

$options : array<string|int, mixed> = []

Configuration array [ path , propertyName , containerKey , trailingSlash ]; missing entries fall back to the method arguments and defaults described above.

$container : Container|null = null

DI container used to resolve the base URL from a service definition; ignored when null or when the key is false.

$modified : bool = false

Reference flag; always set to true since a URL is always built.

$propertyName : string|null = null

Default property name to read when none is given in $options[1] (otherwise falls back to $alterKey then Schema::ID).

$containerKey : string = 'baseUrl'

Default container service key for the base URL when none is given in $options[2] (default 'baseUrl').

Tags
throws
DependencyException

If the dependency cannot be resolved by the container.

NotFoundException

If no entry is found for the given identifier in the container.

Complete Example:

class DocumentMapper
{
    use AlterUrlPropertyTrait ;

    public function mapPlace( $document , $container )
    {
        $modified = false;
        return $this->alterUrlProperty
        (
            $document ,
            [ '/places' , 'id' , 'baseUrl' , true ] ,
            $container ,
            $modified ,
            'id' ,
            'baseUrl'
        );
    }
}

// With container containing: 'baseUrl' => 'https://api.example.com'
// And document: ['id' => 123]
// Result: 'https://api.example.com/places/123/'
Return values
string —

The generated URL.

initializeAlterKey()

Initializes the {@see $alterKey} property from an initialization array.

public initializeAlterKey([array<string|int, mixed> $init = [] ]) : static

Reads ModelParam::ALTER_KEY from $init; when absent, the key falls back to Schema::ID. Returns the current instance for fluent chaining.

Parameters
$init : array<string|int, mixed> = []

Initialization options; the ModelParam::ALTER_KEY entry, when present, overrides the default alter key.

Tags
example 
use oihana\models\enums\ModelParam;

$this->initializeAlterKey( [ ModelParam::ALTER_KEY => 'slug' ] );
// $this->alterKey === 'slug'

$this->initializeAlterKey();
// $this->alterKey === Schema::ID  (default)
Return values
static —

The current instance, for method chaining.

On this page

Search results