VELOX API Docs

DBAL
in package

An abstract class that serves as a DBAL for models.

NOTE: This class is not meant to be used directly.

Tags
since
1.5.1

Table of Contents

$columns  : array<string|int, mixed>|null
Model table columns. If not set, the model will fall back to the default primary key `['id']`.
$database  : Database|null
The database instance/connection.
$primaryKey  : string|null
Model table primary key. If not set, `id` will be used by default.
$table  : string|null
Model table name. If not set, an auto-generated name will be used instead.
fetch()  : array<string|int, static>|array<string|int, array<string|int, mixed>>
Executes a query (a prepared statement) and returns the result.
getColumns()  : array<string|int, mixed>
Returns model table columns and sets `static::$columns` with a default value and returns it if it's not set.
getDatabase()  : Database
Returns model database connection and sets `static::$database` with a default value if it's not set.
getPrimaryKey()  : string
Returns model table primary key and sets `static::$primaryKey` with a default value and returns it if it's not set.
getTable()  : string
Returns model table name and sets `static::$table` with a default value and returns it if it's not set.
isMigrated()  : bool
Checks whether the model table is migrated to the database or not.
migrate()  : void
Migrates model table to the database.
schema()  : string
The SQL code to create the model table from. Has to match `self::$table`, `self::$columns`, and `self::$primaryKey`.
where()  : array<string|int, static>|array<string|int, array<string|int, mixed>>
Finds a single or multiple models by the passed condition.
buildNestedQuery()  : array<string|int, mixed>
Builds a nested query.
buildWhereClause()  : array<string|int, mixed>
validateCondition()  : array<string|int, mixed>
Validates the passed condition.
validateOperator()  : string
Validates the passed operator.

Properties

$columns

Model table columns. If not set, the model will fall back to the default primary key `['id']`.

protected static array<string|int, mixed>|null $columns = ['id']

For good practice, keep the table columns in snake_case. Model attribute names match table columns.

$database

The database instance/connection.

protected static Database|null $database

$primaryKey

Model table primary key. If not set, `id` will be used by default.

protected static string|null $primaryKey = 'id'

$table

Model table name. If not set, an auto-generated name will be used instead.

protected static string|null $table = null

For good practice, keep the model name in singular form and make the table name in plural form.

Methods

fetch()

Executes a query (a prepared statement) and returns the result.

public static fetch(string $query[, array<string|int, mixed>|null $variables = [] ][, bool $raw = false ]) : array<string|int, static>|array<string|int, array<string|int, mixed>>
Parameters
$query : string

The query to execute. The @table can be used to inject the current model table name into the query.

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

[optional] The variables needed for the query.

$raw : bool = false

[optional] Whether fetch the models as arrays (raw) or as hydrated objects.

Tags
throws
BadMethodCallException

If called in an abstract class context.

Example:

  • Model::fetch('SELECT * FROM `users` WHERE `name` = :name OR `age` = :age', ['name' => 'Doe', 'age' => 27], true)
Return values
array<string|int, static>|array<string|int, array<string|int, mixed>> —

The result as an array of objects or array of arrays depending on the passed parameters.

getColumns()

Returns model table columns and sets `static::$columns` with a default value and returns it if it's not set.

public static getColumns() : array<string|int, mixed>
Return values
array<string|int, mixed> —

getDatabase()

Returns model database connection and sets `static::$database` with a default value if it's not set.

public static getDatabase() : Database
Return values
Database —

getPrimaryKey()

Returns model table primary key and sets `static::$primaryKey` with a default value and returns it if it's not set.

public static getPrimaryKey() : string
Return values
string —

getTable()

Returns model table name and sets `static::$table` with a default value and returns it if it's not set.

public static getTable() : string
Return values
string —

isMigrated()

Checks whether the model table is migrated to the database or not.

public static isMigrated() : bool

You can override this method and return always true to disable auto migration.

NOTE: For compatibility reasons, the return value of this method true if it fails to connect to the database.

Return values
bool —

migrate()

Migrates model table to the database.

public final static migrate() : void
Tags
throws
BadMethodCallException

If called in an abstract class context.

Return values
void —

schema()

The SQL code to create the model table from. Has to match `self::$table`, `self::$columns`, and `self::$primaryKey`.

public abstract static schema() : string

Example: CREATE TABLE IF NOT EXISTS `table` (`id` INT NOT NULL AUTO_INCREMENT PRIMARY KEY, `text` VARCHAR(255));

Return values
string —

where()

Finds a single or multiple models by the passed condition.

public static where(string $column, string $operator, mixed $value[, array<string|int, array<string|int, mixed>> $additional = null ][, string|null $order = null ][, int|null $limit = null ][, int|null $offset = null ]) : array<string|int, static>|array<string|int, array<string|int, mixed>>
Parameters
$column : string

The column/attribute name.

$operator : string

Condition operator, can be: =, !=, <>, <, >, <=, >=, LIKE, NOT LIKE, IN, NOT IN.

$value : mixed

The value to compare to.

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

[optional] Additional conditions. Can be used to add more conditions to the WHERE clause. Deep nesting can be achieved by simply using a child array.

$order : string|null = null

[optional] SQL order expression (like: id or id ASC).

$limit : int|null = null

[optional] To how many items the result should be limited.

$offset : int|null = null

[optional] From which item the result should start.

Tags
throws
InvalidArgumentException

If operator is not supported or a condition is invalid.

throws
BadMethodCallException

If called in an abstract class context.

Examples:

  • Model::where('name', '=', 'Doe').
  • Model::where('age', '>', 27, [['AND', 'name', 'LIKE', 'Doe%'], $query, ..., [$subQuery, ...]], $order, $limit, $offset).
Return values
array<string|int, static>|array<string|int, array<string|int, mixed>> —

buildNestedQuery()

Builds a nested query.

private static buildNestedQuery(array<string|int, mixed> $condition, int|string $index) : array<string|int, mixed>
Parameters
$condition : array<string|int, mixed>

The condition in the form of ['OPERATOR1', 'COLUMN', 'OPERATOR2', 'VALUE', ], ..., [..., ...].

$index : int|string

The index of the condition.

Return values
array<string|int, mixed> —

An associative array containing the SQL query and its needed variables.

buildWhereClause()

private static buildWhereClause(array<string|int, mixed> $conditions) : array<string|int, mixed>
Parameters
$conditions : array<string|int, mixed>
Return values
array<string|int, mixed> —

validateCondition()

Validates the passed condition.

private static validateCondition(array<string|int, mixed> $condition, int|string $index) : array<string|int, mixed>
Parameters
$condition : array<string|int, mixed>

The condition to validate. in the form of ['OPERATOR1', 'COLUMN', 'OPERATOR2', 'VALUE']

$index : int|string

The index of the condition (used to make more user-friendly exception).

Tags
throws
InvalidArgumentException

If the condition is invalid.

Return values
array<string|int, mixed> —

An array containing the validated condition.

validateOperator()

Validates the passed operator.

private static validateOperator(string $operator, int|string $index) : string
Parameters
$operator : string

The operator to validate.

$index : int|string

The index of the condition (used to make more user-friendly exception).

Tags
throws
InvalidArgumentException

If the operator is invalid.

Return values
string —

The validated operator.

Search results