Oihana PHP

helpers

Table of Contents

Functions

cacheCollection()  : SimpleCache|null
Creates a namespaced cache collection from a Key/Value store definition registered in the dependency injection container.
documentUrl()  : string
Generates a full document URL based on the project's base URL.
getDocumentsModel()  : DocumentsModel|null
Resolves a {@see DocumentsModel} instance from a PSR-11 container or returns a default.
getModel()  : Model|null
Resolves a model instance from a PSR-11 container or returns a default.

Functions

cacheCollection()

Creates a namespaced cache collection from a Key/Value store definition registered in the dependency injection container.

cacheCollection(Container $container, string $collection, string $definition) : SimpleCache|null

A cache collection is an isolated namespace within the same backend, allowing logical separation of cached values (e.g. per feature, domain, or module). This helper function retrieves a KeyValueStore from the container, and wraps its collection in a PSR-16 SimpleCache implementation.

Example usage:

// Retrieve a cache collection named "users"
$userCache = cacheCollection( $container , "users" , 'cache:memory' );

// Store and retrieve values
$userCache->set("id:42", ["name" => "Alice"]);
$data = $userCache->get("id:42");
Parameters
$container : Container

The DI container used to resolve the cache store definition.

$collection : string

The collection name (namespace) to create inside the cache store.

$definition : string

The container entry identifier of the base key/value store in the DI container.

Tags
throws
DependencyException

If the container fails to resolve the cache definition.

NotFoundException

If the cache definition is not registered in the container.

see
https://www.scrapbook.cash
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
SimpleCache|null —

A PSR-16 cache instance scoped to the given collection, or null if the definition is not found or not compatible.

documentUrl()

Generates a full document URL based on the project's base URL.

documentUrl([string $path = Char::EMPTY ][, ContainerInterface|null $container = null ][, string|null $definition = 'baseUrl' ][, bool $trailingSlash = false ]) : string

This helper function is commonly used in IoC container definitions of models to generate the accessible URL of a document or resource.

The function:

  1. Retrieves the base URL from the DI container using the provided definition key (default 'baseUrl').
  2. Joins the base URL with the provided relative path.
  3. Optionally appends a trailing slash.

Example usage:

use Psr\Container\ContainerInterface;

$url = documentUrl('uploads/image.png', $container);
// returns something like 'https://example.com/uploads/image.png'

$urlWithSlash = documentUrl('uploads', $container, 'baseUrl', true);
// returns 'https://example.com/uploads/'
Parameters
$path : string = Char::EMPTY

Relative path of the document (default: empty string).

$container : ContainerInterface|null = null

Optional DI container to fetch the base URL from.

$definition : string|null = 'baseUrl'

Key used to fetch the base URL from the container (default: 'baseUrl').

$trailingSlash : bool = false

Whether to append a trailing slash to the resulting URL (default: false).

Tags
throws
ContainerExceptionInterface

If an error occurs while retrieving the base URL from the container.

NotFoundExceptionInterface

If the base URL definition is not found in the container.

author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
string —

The fully resolved document URL.

getDocumentsModel()

Resolves a {@see DocumentsModel} instance from a PSR-11 container or returns a default.

getDocumentsModel([string|DocumentsModel|null $definition = null ][, ContainerInterface|null $container = null ][, DocumentsModel|null $default = null ]) : DocumentsModel|null

This helper function provides a flexible way to obtain a DocumentsModel instance:

  • If $definition is already a DocumentsModel, it is returned as-is.
  • If $definition is a string and $container implements ContainerInterface, the function attempts to resolve the corresponding service from the container.
  • If resolution fails, the provided $default (if any) is returned instead.

This pattern allows for safe dependency resolution in controllers or services, without requiring explicit type-checking or container awareness in user code.

Parameters
$definition : string|DocumentsModel|null = null

The model definition — either:

  • a DocumentsModel instance (returned directly),
  • a string service identifier (resolved from $container),
  • or null (uses $default).
$container : ContainerInterface|null = null

Optional PSR-11 container to resolve string identifiers.

$default : DocumentsModel|null = null

Optional fallback model if no valid instance is found.

Tags
throws
ContainerExceptionInterface

If the container encounters an internal error.

NotFoundExceptionInterface

If $definition is a string not found in the container.

example 
use oihana\models\helpers\getDocumentsModel;
use oihana\models\interfaces\DocumentsModel;
use Psr\Container\ContainerInterface;

// Case 1: Direct instance
$model = new MyDocumentsModel();
echo getDocumentsModel( $model ) === $model ? 'ok' : 'fail' ; // ok

// Case 2: String identifier resolved via container
$container = new Container(); // implements ContainerInterface
$container->set( 'mainModel', new MyDocumentsModel() );

$resolved = getDocumentsModel( 'mainModel', $container );
echo $resolved instanceof DocumentsModel ? 'ok' : 'fail' ;   // ok

// Case 3: Fallback to default model
$default = new DefaultDocumentsModel();
echo getDocumentsModel( 'unknown', $container, $default ) === $default ? 'ok' : 'fail' ; // ok
author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
DocumentsModel|null —

The resolved model, the provided default, or null if none.

getModel()

Resolves a model instance from a PSR-11 container or returns a default.

getModel([array<string|int, mixed>|string|Model|null $definition = null ][, ContainerInterface|null $container = null ][, Model|null $default = null ]) : Model|null

This function attempts to retrieve a Model instance based on the provided definition. The definition can be:

  • A Model instance (returned directly),
  • An array containing a ModelParam::MODEL key,
  • A string identifier for a model in a PSR-11 container.
Parameters
$definition : array<string|int, mixed>|string|Model|null = null

The model definition, which can be:

  • a Model instance,
  • an array with key ModelParam::MODEL,
  • a string identifier in the container,
  • or null.
$container : ContainerInterface|null = null

Optional PSR-11 container used to resolve a string definition.

$default : Model|null = null

Optional fallback model returned if none could be resolved.

Tags
throws
ContainerExceptionInterface

If an error occurs while retrieving the model from the container.

NotFoundExceptionInterface

If a string definition is provided but not found in the container.

author

Marc Alcaraz (ekameleon)

since
1.0.0
Return values
Model|null —

The resolved Model instance, the provided default, or null if none found.

On this page

Search results