Aplus Framework Docs

Model
in package
implements ModelInterface

Class Model.

Interfaces, Classes, Traits and Enums

ModelInterface
Interface ModelInterface.

Table of Contents

$allowedFields  : array<string|int, mixed>
Allowed columns for INSERT and UPDATE.
$autoTimestamps  : bool
Auto set timestamp fields.
$cacheActive  : bool
$cacheDataNotFound  : int|string
$cacheInstance  : string
$cacheTtl  : int
$columnCase  : string
$connectionRead  : string
Database connection instance name for read operations.
$connectionWrite  : string
Database connection instance name for write operations.
$fieldCreated  : string
The timestamp field for 'created at' time when $autoTimestamps is true.
$fieldUpdated  : string
The timestamp field for 'updated at' time when $autoTimestamps is true.
$languageInstance  : string
$pager  : Pager
The Pager instance.
$pagerAllowedQueries  : array<string|int, mixed>|null
$pagerQuery  : string
$pagerUrl  : string
Pager URL.
$pagerView  : string
Default pager view.
$primaryKey  : string
Table Primary Key.
$protectPrimaryKey  : bool
Prevents Primary Key changes on INSERT and UPDATE.
$returnType  : string
Fetched item return type.
$table  : string
Table name.
$timestampFormat  : string
The timestamp format used on database write operations.
$validation  : Validation
The Model Validation instance.
$validationLabels  : array<string|int, mixed>
Validation field labels.
$validationMessages  : array<string|int, mixed>
Validation error messages.
$validationRules  : array<string|int, mixed>
Validation rules.
$validationValidators  : array<string|int, mixed>
Validation Validators.
__call()  : mixed
count()  : int
A basic function to count rows in the table.
create()  : false|int|string
Insert a new row.
createBy()  : false|int|string
Insert a new row and return the inserted column value.
createById()  :
delete()  : false|int|string
Delete based on Primary Key.
deleteBy()  : false|int|string
Delete based on column value.
deleteById()  :
find()  : array<string|int, mixed>|Entity|array<string|int, float>|array<string|int, int>|array<string|int, null>|stdClass|array<string|int, string>|null
findAll()  : array<int, array|\Framework\MVC\Entity|\stdClass>
Find all rows with limit and offset.
findBy()  : array<string, float|int|string|null>|Entity|stdClass|null
Find a row by column name and value.
getErrors()  : array<string, string>
Get Validation errors.
getPager()  : Pager
Get the Pager.
getValidationMessages()  : array<string, array<string, string>>
getValidationValidators()  : array<int, string>
list()  : array<int, array|\Framework\MVC\Entity|\stdClass>
List rows, optionally with limit and offset.
paginate()  : array<int, array|\Framework\MVC\Entity|\stdClass>
A basic function to paginate all rows of the table.
read()  : array<string, float|int|string|null>|Entity|stdClass|null
Read a row based on Primary Key.
readBy()  : array<string, float|int|string|null>|Entity|stdClass|null
Read a row by column name and value.
readById()  :
replace()  : false|int|string
Replace based on Primary Key and return the number of affected rows.
replaceBy()  : false|int|string
Replace based on column value and return the number of affected rows.
replaceById()  :
save()  : false|int|string
Save a row. Update if the Primary Key is present, otherwise insert a new row.
update()  : false|int|string
Update based on Primary Key and return the number of affected rows.
updateBy()  : false|int|string
Update based on column value and return the number of affected rows.
updateById()  :
checkMysqliException()  : void
checkPrimaryKey()  : void
convertCase()  : string
Convert a value to specific case.
filterAllowedFields()  : array<string, T>
findRow()  : array<string, float|int|string|null>|null
findWithCache()  : array<string, float|int|string|null>|Entity|stdClass|null
getAllowedFields()  : array<int, string>
getCache()  : Cache
getCacheDataNotFound()  : int|string
getCacheInstance()  : string
getCacheKey()  : string
getCacheTtl()  : int
getConnectionRead()  : string
getConnectionWrite()  : string
getDatabaseToRead()  : Database
getDatabaseToWrite()  : Database
getFieldCreated()  : string
getFieldUpdated()  : string
getLanguage()  : Language
getLanguageInstance()  : string
getPagerAllowedQueries()  : array<string|int, string>|null
Get allowed queries to be used in the Pager.
getPagerQuery()  : string|null
Get the custom query to be used in the Pager.
getPagerUrl()  : string|null
Get the custom URL to be used in the Pager.
getPagerView()  : string|null
Get the custom view to be used in the Pager.
getPrimaryKey()  : string
getReturnType()  : string
getTable()  : string
getTimestamp()  : string
Used to auto set the timestamp fields.
getTimestampFormat()  : string
getValidation()  : Validation
getValidationLabels()  : array<string, string>
getValidationRules()  : array<string, string[]|string>
isAutoTimestamps()  : bool
isCacheActive()  : bool
isProtectPrimaryKey()  : bool
makeArray()  : array<string, mixed>
makeEntity()  : array<string, float|int|string|null>|Entity|stdClass
makePageLimitAndOffset()  : array<int, int|null>
makeTableName()  : string
readRow()  : array<string, float|int|string|null>|null
readWithCache()  : array<string, float|int|string|null>|Entity|stdClass|null
sanitizePageNumber()  : int
setDuplicateEntryError()  : void
Set "Duplicate entry" as 'unique' error in the Validation.
setPager()  : static
Set the Pager.
timezone()  : DateTimeZone
Get the timezone from database write connection config. As fallback, uses the UTC timezone.
updateCachedRow()  : void

Properties

$allowedFields

Allowed columns for INSERT and UPDATE.

protected array<string|int, mixed> $allowedFields

$autoTimestamps

Auto set timestamp fields.

protected bool $autoTimestamps = false

$cacheActive

protected bool $cacheActive = false

$cacheDataNotFound

protected int|string $cacheDataNotFound = 0

$cacheInstance

protected string $cacheInstance = 'default'

$cacheTtl

protected int $cacheTtl = 60

$columnCase

protected string $columnCase = 'camel'

$connectionRead

Database connection instance name for read operations.

protected string $connectionRead = 'default'

$connectionWrite

Database connection instance name for write operations.

protected string $connectionWrite = 'default'

$fieldCreated

The timestamp field for 'created at' time when $autoTimestamps is true.

protected string $fieldCreated = 'createdAt'

$fieldUpdated

The timestamp field for 'updated at' time when $autoTimestamps is true.

protected string $fieldUpdated = 'updatedAt'

$languageInstance

protected string $languageInstance = 'default'

$pager

The Pager instance.

protected Pager $pager

Instantiated when calling the paginate method.

Tags
see
Model::paginate

$pagerAllowedQueries

protected array<string|int, mixed>|null $pagerAllowedQueries = null

$pagerQuery

protected string $pagerQuery

$pagerUrl

Pager URL.

protected string $pagerUrl

$pagerView

Default pager view.

protected string $pagerView

$primaryKey

Table Primary Key.

protected string $primaryKey = 'id'

$protectPrimaryKey

Prevents Primary Key changes on INSERT and UPDATE.

protected bool $protectPrimaryKey = true

$returnType

Fetched item return type.

protected string $returnType = \stdClass::class

Array, object or the classname of an Entity instance.

Tags
see
Entity

$table

Table name.

protected string $table

$timestampFormat

The timestamp format used on database write operations.

protected string $timestampFormat = 'Y-m-d H:i:s'

$validationLabels

Validation field labels.

protected array<string|int, mixed> $validationLabels

$validationMessages

Validation error messages.

protected array<string|int, mixed> $validationMessages

$validationRules

Validation rules.

protected array<string|int, mixed> $validationRules
Tags
see
Validation::setRules

$validationValidators

Validation Validators.

protected array<string|int, mixed> $validationValidators = [\Framework\MVC\Validator::class, \Framework\Validation\FilesValidator::class]

Methods

__call()

public __call(string $method, array<string, mixed> $arguments) : mixed
Parameters
$method : string
$arguments : array<string, mixed>
Return values
mixed

count()

A basic function to count rows in the table.

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

Array in this format: [['id', '=', 25]]

Tags
see
Where
Return values
int

create()

Insert a new row.

public create(array<string, float|int|string|null>|Entity|stdClass $data) : false|int|string
Parameters
$data : array<string, float|int|string|null>|Entity|stdClass
Return values
false|int|string

The LAST_INSERT_ID() on success or false if validation fail

createBy()

Insert a new row and return the inserted column value.

public createBy(string $column, array<string, float|int|string|null>|Entity|stdClass $data) : false|int|string
Parameters
$column : string

Column name

$data : array<string, float|int|string|null>|Entity|stdClass
Return values
false|int|string

The value from the column data or false if validation fail

createById()

public createById(array<string|int, mixed>|Entity|stdClass $data) :

Create a new row and return the id.

Parameters
$data : array<string|int, mixed>|Entity|stdClass
Return values

delete()

Delete based on Primary Key.

public delete(int|string $id) : false|int|string
Parameters
$id : int|string
Return values
false|int|string

The number of affected rows

deleteBy()

Delete based on column value.

public deleteBy(string $column, int|string $value) : false|int|string
Parameters
$column : string
$value : int|string
Return values
false|int|string

The number of affected rows

deleteById()

public deleteById(int|string $id) :

Delete rows by id.

Parameters
$id : int|string
Return values

find()

public find(int|string $id) : array<string|int, mixed>|Entity|array<string|int, float>|array<string|int, int>|array<string|int, null>|stdClass|array<string|int, string>|null
Parameters
$id : int|string
Tags
deprecated
codeCoverageIgnore
Return values
array<string|int, mixed>|Entity|array<string|int, float>|array<string|int, int>|array<string|int, null>|stdClass|array<string|int, string>|null

findAll()

Find all rows with limit and offset.

public findAll([int|null $limit = null ][, int|null $offset = null ]) : array<int, array|\Framework\MVC\Entity|\stdClass>
Parameters
$limit : int|null = null
$offset : int|null = null
Tags
deprecated
codeCoverageIgnore
Return values
array<int, array|\Framework\MVC\Entity|\stdClass>

findBy()

Find a row by column name and value.

public findBy(string $column, int|string $value) : array<string, float|int|string|null>|Entity|stdClass|null
Parameters
$column : string
$value : int|string
Tags
deprecated
codeCoverageIgnore
Return values
array<string, float|int|string|null>|Entity|stdClass|null

getErrors()

Get Validation errors.

public getErrors() : array<string, string>
Return values
array<string, string>

getValidationMessages()

public getValidationMessages() : array<string, array<string, string>>
Return values
array<string, array<string, string>>

getValidationValidators()

public getValidationValidators() : array<int, string>
Return values
array<int, string>

list()

List rows, optionally with limit and offset.

public list([int|null $limit = null ][, int|null $offset = null ]) : array<int, array|\Framework\MVC\Entity|\stdClass>
Parameters
$limit : int|null = null
$offset : int|null = null
Tags
since
3.6
Return values
array<int, array|\Framework\MVC\Entity|\stdClass>

paginate()

A basic function to paginate all rows of the table.

public paginate(mixed $page[, mixed $perPage = 10 ][, array<string|int, array<string|int, mixed>> $where = [] ][, array<string|int, string>|string $orderBy = null ][, string $orderByDirection = 'asc' ]) : array<int, array|\Framework\MVC\Entity|\stdClass>
Parameters
$page : mixed

The current page

$perPage : mixed = 10

Items per page

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

Array in this format: [['id', '=', 25]]

$orderBy : array<string|int, string>|string = null

Order by columns

$orderByDirection : string = 'asc'

asc or desc

Tags
see
Where
Return values
array<int, array|\Framework\MVC\Entity|\stdClass>

read()

Read a row based on Primary Key.

public read(int|string $id) : array<string, float|int|string|null>|Entity|stdClass|null
Parameters
$id : int|string
Tags
since
3.6
Return values
array<string, float|int|string|null>|Entity|stdClass|null

The selected row as configured on $returnType property or null if row was not found

readBy()

Read a row by column name and value.

public readBy(string $column, int|string $value) : array<string, float|int|string|null>|Entity|stdClass|null
Parameters
$column : string
$value : int|string
Tags
since
3.6
Return values
array<string, float|int|string|null>|Entity|stdClass|null

readById()

public readById(int|string $id) :

Read a row by id.

Parameters
$id : int|string
Return values

replace()

Replace based on Primary Key and return the number of affected rows.

public replace(int|string $id, array<string, float|int|string|null>|Entity|stdClass $data) : false|int|string

Most used with HTTP PUT method.

Parameters
$id : int|string
$data : array<string, float|int|string|null>|Entity|stdClass
Return values
false|int|string

The number of affected rows or false if validation fails

replaceBy()

Replace based on column value and return the number of affected rows.

public replaceBy(string $column, int|string $value, array<string, float|int|string|null>|Entity|stdClass $data) : false|int|string
Parameters
$column : string
$value : int|string
$data : array<string, float|int|string|null>|Entity|stdClass
Return values
false|int|string

The number of affected rows or false if validation fails

replaceById()

public replaceById(int|string $id, array<string|int, mixed>|Entity|stdClass $data) :

Replace rows by id.

Parameters
$id : int|string
$data : array<string|int, mixed>|Entity|stdClass
Return values

save()

Save a row. Update if the Primary Key is present, otherwise insert a new row.

public save(array<string, float|int|string|null>|Entity|stdClass $data) : false|int|string
Parameters
$data : array<string, float|int|string|null>|Entity|stdClass
Return values
false|int|string

The number of affected rows on updates as int, the LAST_INSERT_ID() as int on inserts or false if validation fails

update()

Update based on Primary Key and return the number of affected rows.

public update(int|string $id, array<string, float|int|string|null>|Entity|stdClass $data) : false|int|string
Parameters
$id : int|string
$data : array<string, float|int|string|null>|Entity|stdClass
Return values
false|int|string

The number of affected rows or false if validation fails

updateBy()

Update based on column value and return the number of affected rows.

public updateBy(string $column, int|string $value, array<string, float|int|string|null>|Entity|stdClass $data) : false|int|string
Parameters
$column : string
$value : int|string
$data : array<string, float|int|string|null>|Entity|stdClass
Return values
false|int|string

The number of affected rows or false if validation fails

updateById()

public updateById(int|string $id, array<string|int, mixed>|Entity|stdClass $data) :

Update rows by id.

Parameters
$id : int|string
$data : array<string|int, mixed>|Entity|stdClass
Return values

checkMysqliException()

protected checkMysqliException(mysqli_sql_exception $exception) : void
Parameters
$exception : mysqli_sql_exception
Tags
throws
mysqli_sql_exception

if message is not for duplicate entry

Return values
void

checkPrimaryKey()

protected checkPrimaryKey(int|string $id) : void
Parameters
$id : int|string
Return values
void

convertCase()

Convert a value to specific case.

protected convertCase(string $value, string $case) : string
Parameters
$value : string
$case : string

camel, pascal or snake

Return values
string

The converted value

filterAllowedFields()

protected filterAllowedFields(array<string, T$data) : array<string, T>
Parameters
$data : array<string, T>
Tags
template

T

Return values
array<string, T>

findRow()

protected findRow(string $column, int|string $value) : array<string, float|int|string|null>|null
Parameters
$column : string
$value : int|string
Tags
deprecated
codeCoverageIgnore
Return values
array<string, float|int|string|null>|null

findWithCache()

protected findWithCache(string $column, int|string $value) : array<string, float|int|string|null>|Entity|stdClass|null
Parameters
$column : string
$value : int|string
Tags
deprecated
codeCoverageIgnore
Return values
array<string, float|int|string|null>|Entity|stdClass|null

getAllowedFields()

protected getAllowedFields() : array<int, string>
Return values
array<int, string>

getCacheDataNotFound()

protected getCacheDataNotFound() : int|string
Return values
int|string

getCacheInstance()

protected getCacheInstance() : string
Return values
string

getCacheKey()

protected getCacheKey(array<string, float|int|string> $fields) : string
Parameters
$fields : array<string, float|int|string>
Return values
string

getCacheTtl()

protected getCacheTtl() : int
Return values
int

getConnectionRead()

protected getConnectionRead() : string
Return values
string

getConnectionWrite()

protected getConnectionWrite() : string
Return values
string

getFieldCreated()

protected getFieldCreated() : string
Return values
string

getFieldUpdated()

protected getFieldUpdated() : string
Return values
string

getLanguageInstance()

protected getLanguageInstance() : string
Return values
string

getPagerAllowedQueries()

Get allowed queries to be used in the Pager.

protected getPagerAllowedQueries() : array<string|int, string>|null
Return values
array<string|int, string>|null

getPagerQuery()

Get the custom query to be used in the Pager.

protected getPagerQuery() : string|null
Return values
string|null

getPagerUrl()

Get the custom URL to be used in the Pager.

protected getPagerUrl() : string|null
Return values
string|null

getPagerView()

Get the custom view to be used in the Pager.

protected getPagerView() : string|null
Return values
string|null

getPrimaryKey()

protected getPrimaryKey() : string
Return values
string

getReturnType()

protected getReturnType() : string
Return values
string

getTable()

protected getTable() : string
Return values
string

getTimestamp()

Used to auto set the timestamp fields.

protected getTimestamp() : string
Tags
throws
Exception

if a DateTime error occur

Return values
string

The timestamp in the $timestampFormat property format

getTimestampFormat()

protected getTimestampFormat() : string
Return values
string

getValidationLabels()

protected getValidationLabels() : array<string, string>
Return values
array<string, string>

getValidationRules()

protected getValidationRules() : array<string, string[]|string>
Return values
array<string, string[]|string>

isAutoTimestamps()

protected isAutoTimestamps() : bool
Return values
bool

isCacheActive()

protected isCacheActive() : bool
Return values
bool

isProtectPrimaryKey()

protected isProtectPrimaryKey() : bool
Return values
bool

makeArray()

protected makeArray(array<string, mixed>|Entity|stdClass $data) : array<string, mixed>
Parameters
$data : array<string, mixed>|Entity|stdClass
Return values
array<string, mixed>

makeEntity()

protected makeEntity(array<string, float|int|string|null> $data) : array<string, float|int|string|null>|Entity|stdClass
Parameters
$data : array<string, float|int|string|null>
Return values
array<string, float|int|string|null>|Entity|stdClass

makePageLimitAndOffset()

protected makePageLimitAndOffset(int $page[, int $perPage = 10 ]) : array<int, int|null>
Parameters
$page : int
$perPage : int = 10
Tags
see
Model::paginate
Return values
array<int, int|null>

makeTableName()

protected makeTableName() : string
Return values
string

readRow()

protected readRow(string $column, int|string $value) : array<string, float|int|string|null>|null
Parameters
$column : string
$value : int|string
Tags
since
3.6
Return values
array<string, float|int|string|null>|null

readWithCache()

protected readWithCache(string $column, int|string $value) : array<string, float|int|string|null>|Entity|stdClass|null
Parameters
$column : string
$value : int|string
Tags
since
3.6
Return values
array<string, float|int|string|null>|Entity|stdClass|null

sanitizePageNumber()

protected sanitizePageNumber(int $number) : int
Parameters
$number : int
Return values
int

setDuplicateEntryError()

Set "Duplicate entry" as 'unique' error in the Validation.

protected setDuplicateEntryError(string $message) : void

NOTE: We will get the index key name and not the column name. Usually the names are the same. If table have different column and index names, override this method and get the column name from the information_schema table.

Parameters
$message : string

The "Duplicate entry" message from the mysqli_sql_exception

Return values
void

setPager()

Set the Pager.

protected setPager(Pager $pager) : static
Parameters
$pager : Pager
Return values
static

timezone()

Get the timezone from database write connection config. As fallback, uses the UTC timezone.

protected timezone() : DateTimeZone
Tags
throws
Exception

if database config has a bad timezone

Return values
DateTimeZone

updateCachedRow()

protected updateCachedRow(string $column, int|string $value) : void
Parameters
$column : string
$value : int|string
Return values
void

Search results