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.

It returns null when the definition is not registered in the container, or when the resolved entry is not a KeyValueStore — making it safe to use as an optional cache layer.

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 dependency cannot be resolved by the container.

NotFoundException

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

example 
use function oihana\models\helpers\cacheCollection;

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

if ( $userCache !== null )
{
    $userCache->set( 'id:42', [ 'name' => 'Alice' ] ) ;
    $data = $userCache->get( 'id:42' ) ; // [ 'name' => 'Alice' ]
}
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.

When no container is given, or when the base URL definition is absent, the base URL falls back to an empty string and only the relative path is returned.

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 an entry from the dependency-injection container.

NotFoundExceptionInterface

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

example 
use Psr\Container\ContainerInterface;

use function oihana\models\helpers\documentUrl;

// Assuming the container resolves 'baseUrl' to 'https://example.com'
$url = documentUrl( 'uploads/image.png', $container ) ;
// 'https://example.com/uploads/image.png'

$urlWithSlash = documentUrl( 'uploads', $container, 'baseUrl', true ) ;
// 'https://example.com/uploads/'

// Without a container, only the relative path is returned.
$relative = documentUrl( 'uploads/image.png' ) ;
// 'uploads/image.png'
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 an error occurs while retrieving an entry from the dependency-injection container.

NotFoundExceptionInterface

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

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

use function oihana\models\helpers\getDocumentsModel;

// 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 an entry from the dependency-injection container.

NotFoundExceptionInterface

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

example 
use oihana\models\Model;
use oihana\models\enums\ModelParam;
use Psr\Container\ContainerInterface;

use function oihana\models\helpers\getModel;

// Case 1: a Model instance is returned as-is.
$model = new MyModel() ;
getModel( $model ) === $model ; // true

// Case 2: an array carrying a ModelParam::MODEL entry.
$resolved = getModel( [ ModelParam::MODEL => 'mainModel' ], $container ) ;

// Case 3: a string identifier resolved from the container.
$resolved = getModel( 'mainModel', $container ) ;

// Case 4: nothing resolvable, the default is returned.
$fallback = new MyModel() ;
getModel( 'unknown', $container, $fallback ) === $fallback ; // true
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