Oihana PHP System

PDOTrait uses trait:short, trait:short, trait:short, trait:short, trait:short

Provides methods for binding values, executing queries, and retrieving results using PDO.

Supports schema-based result mapping and integration with dependency injection.

Requires the following traits:

  • AlterDocumentTrait
  • BindsTrait
  • DebugTrait
  • ToStringTrait
Tags
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Constants

BINDS  = 'binds'
The 'binds' parameter constant.
THROWABLE  = 'throwable'
Key used in initialization arrays to set throwable behavior.

Properties

$alters  : array<string|int, mixed>
The enumeration of all definitions to alter on the array or object key/value properties.
$binds  : array<string|int, mixed>|null
The default bind values definition of the model.
$container  : Container
The DI container reference.
$deferAssignment  : bool|null
Indicates if the the constructor is called before setting properties.
$pdo  : PDO|null
The PDO reference.
$schema  : null|string|Closure|SchemaResolver
The internal schema to use to hydrate the resources.
$throwable  : bool
Determines if methods should throw exceptions.

Methods

alter()  : mixed
Applies defined alterations to a document (array or object) based on a set of rules.
bindValues()  : void
Bind named parameters to a prepared PDO statement.
fetch()  : mixed|null
Execute a SELECT query and fetch a single result.
fetchAll()  : array<string|int, mixed>
Execute a query and fetch all results.
fetchAllAsGenerator()  : Generator<string|int, object>
Execute a SELECT query and fetch all results as a generator.
fetchColumn()  : mixed
Execute a query and return the value of a single column from the first row.
fetchColumnArray()  : array<int, string>
Fetch a list of single-column results.
getSchema()  : string|null
Get the resolved schema value.
hasSchema()  : bool
Check if schema is defined (either as string or callable).
initializeAlters()  : static
Initialize the 'alters' property.
initializeBinds()  : static
Initialize the 'binds' property.
initializeDefaultFetchMode()  : void
Set the default fetch mode on the statement.
initializeDeferAssignment()  : static
Initialize the 'deferAssignment' property.
initializePDO()  : static
Initialize the PDO instance from a config array or dependency injection container.
initializeSchema()  : static
Initialize the 'schema' property.
initializeThrowable()  : static
Initializes the throwable property from an array of options.
isConnected()  : bool
Indicates if the PDO is connected.
prepareBindVars()  : array<string|int, mixed>
Prepares the binding parameters to inject in a PDO statement.

Constants

BINDS

The 'binds' parameter constant.

public mixed BINDS = 'binds'

THROWABLE

Key used in initialization arrays to set throwable behavior.

public mixed THROWABLE = 'throwable'

Properties

$alters

The enumeration of all definitions to alter on the array or object key/value properties.

public array<string|int, mixed> $alters = []

$binds

The default bind values definition of the model.

public array<string|int, mixed>|null $binds = []

$container

The DI container reference.

public Container $container

$deferAssignment

Indicates if the the constructor is called before setting properties.

public bool|null $deferAssignment = false

Only if the schema property is defined.

$pdo

The PDO reference.

public PDO|null $pdo = null

$schema

The internal schema to use to hydrate the resources.

public null|string|Closure|SchemaResolver $schema = null

$throwable

Determines if methods should throw exceptions.

public bool $throwable = false

Methods

alter()

Applies defined alterations to a document (array or object) based on a set of rules.

public alter(mixed $document[, array<string|int, mixed>|null $alters = null ]) : mixed

This method inspects the input document and applies transformations according to the provided $alters definitions:

  • If the document is a sequential array (list), the alteration is recursively applied to each element.
  • If the document is an associative array or an object, only the keys defined in $alters are processed.
  • If a key in $alters is associated with a chained alteration (array of alters), each alteration is applied sequentially, passing the output of one as input to the next.
  • Scalar values (string, int, float, bool, resource, null) are returned unchanged unless specifically targeted in $alters.

The $alters parameter allows temporarily overriding or extending the internal $this->alters property for the current method call. Passing null will use the trait's internal $this->alters array.

Parameters
$document : mixed

The input to transform. Can be an associative array, object, or a list of items.

$alters : array<string|int, mixed>|null = null

Optional temporary alter definitions for this call. Keys are property names, values are Alter:: constants or arrays of chained alters.

Tags
throws
ContainerExceptionInterface

If a DI container error occurs during alteration.

throws
DependencyException

If a dependency cannot be resolved during alteration.

throws
NotFoundException

If a container service is not found during alteration.

throws
NotFoundExceptionInterface

If a container service is not found during alteration.

throws
ReflectionException

If a reflection operation fails during alteration (e.g., Hydrate or Get).

example 
class Example
{
    use AlterDocumentTrait;

    public function __construct()
    {
        $this->alters = [
            'price' => Alter::FLOAT,
            'tags'  => [ Alter::ARRAY, Alter::CLEAN ],
            'name'  => [ Alter::TRIM, Alter::UPPERCASE ], // Chained alterations
        ];
    }
}

$input = [
    'price' => '19.99',
    'tags'  => 'foo,bar',
    'name'  => '  john  '
];

$processor = new Example();
$output = $processor->alter($input);

// $output:
// [
//     'price' => 19.99,
//     'tags'  => ['foo', 'bar'],
//     'name'  => 'JOHN',
// ]
Return values
mixed —

The transformed document, preserving the input structure (array, object, or list of arrays/objects).

bindValues()

Bind named parameters to a prepared PDO statement.

public bindValues(PDOStatement $statement[, array<string|int, mixed> $bindVars = [] ]) : void
Parameters
$statement : PDOStatement

The PDO statement.

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

Associative array of bindings. Supports:

  • ['id' => 5]
  • ['id' => [5, PDO::PARAM_INT]]

fetch()

Execute a SELECT query and fetch a single result.

public fetch(string $query[, array<string|int, mixed> $bindVars = [] ][, bool $throwable = false ]) : mixed|null

The result is returned as an object or as a mapped schema class if defined. Alteration is applied via AlterDocumentTrait.

Parameters
$query : string

The SQL SELECT query to execute.

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

Optional named parameter bindings for the query. Supports:

  • ['id' => 5]
  • ['id' => [5, PDO::PARAM_INT]]
$throwable : bool = false

Whether to rethrow exceptions instead of handling them internally (default: false).

Tags
throws
ContainerExceptionInterface

If dependency resolution fails.

throws
DependencyException
throws
NotFoundException
throws
NotFoundExceptionInterface

If a required service is not found.

throws
ReflectionException
Return values
mixed|null —

The mapped result object, or null if no row is found.

fetchAll()

Execute a query and fetch all results.

public fetchAll(string $query[, array<string|int, mixed> $bindVars = [] ][, bool $throwable = false ]) : array<string|int, mixed>

Results are returned as an array of associative arrays or schema instances.

Alteration is applied via AlterDocumentTrait.

Parameters
$query : string

The query to execute.

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

Optional named parameter bindings for the query. Supports:

  • ['id' => 5]
  • ['id' => [5, PDO::PARAM_INT]]
$throwable : bool = false

Whether to rethrow exceptions instead of handling them internally (default: false).

Tags
throws
ContainerExceptionInterface
throws
NotFoundExceptionInterface
throws
DependencyException
throws
NotFoundException
throws
ReflectionException
Return values
array<string|int, mixed> —

An array of results. Returns an empty array if the query fails and $throwable is false.

fetchAllAsGenerator()

Execute a SELECT query and fetch all results as a generator.

public fetchAllAsGenerator(string $query[, array<string|int, mixed> $bindVars = [] ][, bool $throwable = false ]) : Generator<string|int, object>

Results are yielded one by one as objects or schema instances. Alteration is applied via AlterDocumentTrait.

Parameters
$query : string

The SQL query to execute.

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

Optional bindings for the query.

$throwable : bool = false

Whether to rethrow exceptions instead of handling them internally (default: false).

Tags
throws
ContainerExceptionInterface
throws
DependencyException
throws
NotFoundException
throws
NotFoundExceptionInterface
throws
ReflectionException
Return values
Generator<string|int, object> —

A generator yielding results one by one.

fetchColumn()

Execute a query and return the value of a single column from the first row.

public fetchColumn(string $query[, array<string|int, mixed> $bindVars = [] ][, int $column = 0 ][, bool $throwable = false ]) : mixed
Parameters
$query : string

The SQL query to execute.

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

Optional bindings for the query.

$column : int = 0

Column index (0-based) to return from the first row.

$throwable : bool = false

Whether to rethrow exceptions instead of handling them internally (default: false).

Tags
throws
Exception
Return values
mixed —

The column value or null if the query fails.

fetchColumnArray()

Fetch a list of single-column results.

public fetchColumnArray(string $query[, array<string|int, mixed> $bindVars = [] ][, bool $throwable = false ]) : array<int, string>
Parameters
$query : string

The SQL query to execute.

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

Optional bindings for the query.

$throwable : bool = false

Whether to rethrow exceptions instead of handling them internally (default: false).

Tags
throws
Exception
Return values
array<int, string>

getSchema()

Get the resolved schema value.

public getSchema([mixed $target = null ]) : string|null
Parameters
$target : mixed = null

Optional target to pass if the schema is invokable (like SchemaResolver)

Return values
string|null

hasSchema()

Check if schema is defined (either as string or callable).

public hasSchema() : bool
Return values
bool

initializeAlters()

Initialize the 'alters' property.

public initializeAlters([array<string|int, mixed> $init = [] ]) : static
Parameters
$init : array<string|int, mixed> = []
Return values
static

initializeBinds()

Initialize the 'binds' property.

public initializeBinds([array<string|int, mixed> $init = [] ]) : static
Parameters
$init : array<string|int, mixed> = []
Return values
static

initializeDefaultFetchMode()

Set the default fetch mode on the statement.

public initializeDefaultFetchMode(PDOStatement $statement) : void

Uses FETCH_ASSOC by default or FETCH_CLASS (with optional FETCH_PROPS_LATE) if a schema class is defined and exists.

Parameters
$statement : PDOStatement

The PDO statement to configure.

initializeDeferAssignment()

Initialize the 'deferAssignment' property.

public initializeDeferAssignment([array<string|int, mixed> $init = [] ]) : static
Parameters
$init : array<string|int, mixed> = []
Return values
static

initializePDO()

Initialize the PDO instance from a config array or dependency injection container.

public initializePDO([array<string|int, mixed> $init = [] ][, Container|null $container = null ]) : static
Parameters
$init : array<string|int, mixed> = []

Configuration array. Expects ModelParam::PDO ('pdo') as key.

$container : Container|null = null

Optional DI container to resolve the PDO service.

Tags
throws
ContainerExceptionInterface
throws
NotFoundExceptionInterface
Return values
static

initializeSchema()

Initialize the 'schema' property.

public initializeSchema([array<string|int, mixed> $init = [] ]) : static
Parameters
$init : array<string|int, mixed> = []
Return values
static

initializeThrowable()

Initializes the throwable property from an array of options.

public initializeThrowable([array<string, mixed> $init = [] ]) : static
Parameters
$init : array<string, mixed> = []

Initialization options

Return values
static

isConnected()

Indicates if the PDO is connected.

public isConnected() : bool
Return values
bool

prepareBindVars()

Prepares the binding parameters to inject in a PDO statement.

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

The binding parameters to push in the default binds associative array definition.

Return values
array<string|int, mixed> 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results