Oihana PHP System

MysqlDatabaseTrait uses trait:short, trait:short

Provides high-level operations for managing MySQL databases.

Includes methods to create, drop, inspect, and maintain databases, as well as retrieve metadata like charset, collation, and size.

Requires a connected PDO instance and uses helper traits for assertions and bindings.

Tags
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Constants

DEFER_ASSIGNMENT  = 'deferAssignment'
The 'deferAssignment' parameter constant.
PDO  = 'pdo'
The 'pdo' parameter constant.
SCHEMA  = 'schema'
The 'schema' parameter constant.

Properties

$deferAssignment  : bool|null
Indicates if the the constructor is called before setting properties.
$pdo  : PDO|null
The PDO reference.
$schema  : string|mixed|null
The internal schema to use in the PDO fetch processes.

Methods

bindValues()  : void
Bind named parameters to a prepared PDO statement.
createDatabase()  : bool
Creates a new MySQL database with given charset and collation.
databaseExists()  : bool
Checks if a MySQL database exists.
dropDatabase()  : bool
Drops a database if it exists.
fetch()  : mixed|null
Execute a SELECT query and fetch a single result.
fetchAll()  : array<string|int, mixed>
Execute a SELECT query and fetch all results.
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.
getDatabaseCharset()  : array{Charset: string, Collation: string}|null
Returns the default character set and collation of a database.
getDatabaseSize()  : int
Returns the size of a database in bytes.
initializeDefaultFetchMode()  : void
Set the default fetch mode on the statement.
initPDO()  : PDO|null
Initialize the PDO instance from a config array or dependency injection container.
isConnected()  : bool
Indicates if the PDO is connected.
listDatabases()  : array<int, string>
Lists all available databases.
optimizeDatabase()  : bool
Optimizes all tables in a database.
repairDatabase()  : bool
Repairs all tables in a database.
assertHost()  : void
Validates a MySQL host string.
assertIdentifier()  : void
Validates a MySQL identifier such as a database name, user name, or table name.
getRecommendedCollation()  : string
Returns the recommended collation for the given charset and server version.

Constants

DEFER_ASSIGNMENT

The 'deferAssignment' parameter constant.

public mixed DEFER_ASSIGNMENT = 'deferAssignment'

PDO

The 'pdo' parameter constant.

public mixed PDO = 'pdo'

SCHEMA

The 'schema' parameter constant.

public mixed SCHEMA = 'schema'

Properties

$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 in the PDO fetch processes.

public string|mixed|null $schema = null

Methods

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]]

createDatabase()

Creates a new MySQL database with given charset and collation.

public createDatabase(string $name[, string|null $charset = null ][, string|null $collation = null ]) : bool
Parameters
$name : string

The name of the database.

$charset : string|null = null

The character set to use (default: 'utf8mb4').

$collation : string|null = null

The collation to use (auto-selected if null).

Return values
bool —

True on success, false otherwise.

databaseExists()

Checks if a MySQL database exists.

public databaseExists(string $name) : bool
Parameters
$name : string

Database name.

Return values
bool —

True if the database exists.

dropDatabase()

Drops a database if it exists.

public dropDatabase(string $name) : bool
Parameters
$name : string

The name of the database to drop.

Return values
bool —

True on success, false otherwise.

fetch()

Execute a SELECT query and fetch a single result.

public fetch(string $query[, array<string|int, mixed> $bindVars = [] ]) : 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 query to execute.

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

Optional bindings for the query.

Tags
throws
ContainerExceptionInterface
throws
NotFoundExceptionInterface
Return values
mixed|null —

The result object or null if not found.

fetchAll()

Execute a SELECT query and fetch all results.

public fetchAll(string $query[, array<string|int, mixed> $bindVars = [] ]) : 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 SQL query to execute.

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

Optional bindings for the query.

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

An array of results.

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 ]) : 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.

Return values
mixed —

The column value or 0 if the query fails.

fetchColumnArray()

Fetch a list of single-column results.

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

The SQL query to execute.

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

Optional bindings for the query.

Return values
array<int, string>

getDatabaseCharset()

Returns the default character set and collation of a database.

public getDatabaseCharset(string $dbname) : array{Charset: string, Collation: string}|null
Parameters
$dbname : string
Tags
throws
ContainerExceptionInterface
throws
NotFoundExceptionInterface
Return values
array{Charset: string, Collation: string}|null

getDatabaseSize()

Returns the size of a database in bytes.

public getDatabaseSize(string $dbname) : int
Parameters
$dbname : string
Return values
int —

Size in bytes.

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.

initPDO()

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

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

Configuration array. Expects Param::PDO as key.

$container : Container|null = null

Optional DI container to resolve the PDO service.

Tags
throws
ContainerExceptionInterface
throws
NotFoundExceptionInterface
Return values
PDO|null —

The resolved PDO instance or null.

isConnected()

Indicates if the PDO is connected.

public isConnected() : bool
Return values
bool

listDatabases()

Lists all available databases.

public listDatabases([bool $excludeSystem = true ]) : array<int, string>
Parameters
$excludeSystem : bool = true

Exclude system databases like 'information_schema', 'mysql', etc.

Return values
array<int, string> —

List of database names.

optimizeDatabase()

Optimizes all tables in a database.

public optimizeDatabase(string $dbname) : bool
Parameters
$dbname : string
Return values
bool —

True if all tables optimized successfully.

repairDatabase()

Repairs all tables in a database.

public repairDatabase(string $dbname) : bool
Parameters
$dbname : string
Return values
bool —

True if all tables repaired successfully.

assertHost()

Validates a MySQL host string.

protected assertHost(string $host) : void

A valid host string may contain:

  • letters (a–z, A–Z)
  • digits (0–9)
  • dots (.)
  • hyphens (-)
  • underscores (_) and percent signs (%) for wildcards
Parameters
$host : string

The host name or IP to validate (e.g., 'localhost', '127.0.0.1', '%.example.com').

Tags
throws
InvalidArgumentException

If the host string contains disallowed characters.

assertIdentifier()

Validates a MySQL identifier such as a database name, user name, or table name.

protected assertIdentifier(string $name) : void

A valid identifier consists of letters (a–z, A–Z), digits (0–9), and underscores (_). This ensures safe usage in SQL queries without risk of injection or syntax errors.

Parameters
$name : string

The identifier to validate.

Tags
throws
InvalidArgumentException

If the identifier contains invalid characters.

getRecommendedCollation()

Returns the recommended collation for the given charset and server version.

protected getRecommendedCollation(string $charset) : string
Parameters
$charset : string
Return values
string 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results