Orpheus

PermanentEntity
in package

AbstractYes

The permanent entity class

A permanent entity class with EntityDescriptor's features.

Table of Contents

Constants

OUTPUT_MODEL_ALL  = 'all'
OUTPUT_MODEL_MINIMALS  = 'min'
OUTPUT_MODEL_PUBLIC  = 'public'

Properties

$checkFieldIntegrity  : bool
Should check fields integrity when load one element ?
$data  : array<string|int, mixed>
The object's data
$entityMetadata  : array<string|int, mixed>
$instanceName  : string|null
The instance to use, see config file, if null, use default
$isDeleted  : bool
Is this object deleted ?
$knownEntities  : array<string|int, mixed>
Known entities (but may be not loaded & initialized)
$mappingEntityClass  : array<string|int, mixed>
Entity classes
$onSavedInProgress  : bool
Is this object called onSaved ? It prevents recursive calls
$originalData  : array<string|int, mixed>
The original data of object Only filled when edited to store previous data (first loaded, got from db)

Methods

__construct()  : mixed
__destruct()  : mixed
Destructor
__get()  : mixed
Magic getter
__isset()  : bool
Magic isset
__set()  : mixed
Magic setter for entity's property
__toString()  : string
Magic toString
_text()  : void
Translate text according to the object domain
asArray()  : array<string|int, mixed>
buildRaw()  : static
cacheInstances()  : array<string|int, mixed>
Cache an array of objects
checkIntegrity()  : mixed
Check object integrity & validity
checkUserInput()  : array<string|int, mixed>
Check if the class could generate a valid object from $input.
create()  : int
Create a new permanent object from ths input data.
createAndGet()  : static
Create a new permanent object
ei()  : string
Escape identifier through instance
equals()  : bool
Verify equality with another object
escapeIdentifier()  : string
Escape identifier through instance
fillLogEvent()  : void
Add an $event log in this $array
findEntityObject()  : PermanentEntity
Get entity instance by type and id
formatValue()  : string
Escape value through instance
free()  : bool
Free the object (remove)
get()  : SqlSelectRequest|array<string|int, mixed>|PermanentEntity|null
Get some permanent objects Get an objects' list using this class' table.
getCachedInstance()  : static|null
getClass()  : string
Get the name of this class
getCreateOperation()  : CreateTransactionOperation
Get the create operation
getDeleteOperation()  : DeleteTransactionOperation
Get the delete operation for this object
getDescriptor()  : EntityDescriptor
getDomain()  : string
Get the domain of this class, can be guessed from $table or specified in $domain.
getEntity()  : string
Get this entity name
getEntityWhereClause()  : string
Helper method to get whereClause string from an entity
getField()  : FieldDescriptor
Get field descriptor from field name
getFields()  : array<string|int, string>
Get the available fields of this entity
getIdField()  : string
Get the ID field name of this entity
getLabel()  : string
getLogEvent()  : array<string|int, mixed>
Build a new log event for $event for this time and the user IP address.
getMetadata()  : EntityMetadata|null
getReference()  : string
getSqlAdapter()  : AbstractSqlAdapter
Get the SQL Adapter of this class
getTable()  : string
Get the table of this class
getUpdateOperation()  : UpdateTransactionOperation
Get the update operation
getValue()  : mixed
Get the value of field $key or all data values if $key is null.
hasChanges()  : bool
id()  : string
Get this permanent object's ID
initialize()  : void
Initialize entity class You must call this method after the class declaration
initializeWithDescriptor()  : void
isDeleted()  : bool
Check if this object is deleted
isValid()  : bool
Check if this object is valid
listKnownEntities()  : array<string|int, string>
List all known entities
load()  : PermanentEntity|null
Loads the object with the ID $id or the array data.
loadEntity()  : PermanentEntity|null
Try to load entity from an entity string and an id integer
logEvent()  : void
Log an event
markAsDeleted()  : static
Mark this object as deleted
object()  : static|int|null
Get the object whatever we give to it
onEdit()  : void
onSaved()  : void
Callback when object was saved
onValidCreate()  : bool
Callback when validating create
onValidEdit()  : bool
Callback when validating create
onValidUpdate()  : bool
Callback when validating update
putValue()  : void
Validate field value and set it
registerEntity()  : void
Register an entity
reload()  : bool
Reload fields from database Also it removes the reloaded fields from the modified ones list.
remove()  : bool
What do you think it does ?
reportException()  : void
Report an UserException
requestInsert()  : SqlInsertRequest
Get insert query
requestSelect()  : SqlSelectRequest
Get select query
requestUpdate()  : SqlUpdateRequest
Get update query
revert()  : PermanentEntity
save()  : bool|int
Save current changes of this entity to the database Input is NOT validated here, we recommend it for programming changes only
setCheckFieldIntegrity()  : void
Serve to bypass the integrity check, should be only used while developing
setValue()  : $this
Set the field $key with the new $value.
testUserInput()  : bool
Test user input
text()  : string
Translate text according to the object domain
throwException()  : void
Throws an UserException with the current domain
throwNotFound()  : mixed
Throws an NotFoundException with the current domain
uid()  : string
Get this permanent object's unique ID
update()  : bool
Update this permanent entity from input data array Parameter $fields is really useful to allow partial modification only (against form hack).
validateValue()  : void
Validate field value from the validator using this entity
verifyConflicts()  : mixed
Check for object This function is called by create() after checking user input data and before running for them.
checkCache()  : static
Check if this object is cached and cache it
formatFieldSqlValue()  : mixed
Format the value from PHP type to SQL scalar
getExportData()  : array<string|int, mixed>
Get data with an exportable format.
instantiate()  : static
Instantiate object from data, allowing you to instantiate child class
parseFieldSqlValue()  : mixed
Parse the value from SQL scalar to PHP type
setCachedInstance()  : void
setData()  : void
Set all data of object (internal use only)

Constants

Properties

$checkFieldIntegrity

Should check fields integrity when load one element ?

protected static bool $checkFieldIntegrity = !!ENTITY_CLASS_CHECK

$data

The object's data

protected array<string|int, mixed> $data = []

$entityMetadata

protected static array<string|int, mixed> $entityMetadata = []

Array with metadata of all entities mapped by class name

$instanceName

The instance to use, see config file, if null, use default

protected static string|null $instanceName = null
Tags
deprecated

TODO Remove it

$isDeleted

Is this object deleted ?

protected bool $isDeleted = false

$knownEntities

Known entities (but may be not loaded & initialized)

protected static array<string|int, mixed> $knownEntities = []

$mappingEntityClass

Entity classes

protected static array<string|int, mixed> $mappingEntityClass = []

$onSavedInProgress

Is this object called onSaved ? It prevents recursive calls

protected bool $onSavedInProgress = false

$originalData

The original data of object Only filled when edited to store previous data (first loaded, got from db)

protected array<string|int, mixed> $originalData = []

Methods

__construct()

public __construct(array<string|int, mixed> $data) : mixed
Parameters
$data : array<string|int, mixed>

__destruct()

Destructor

public __destruct() : mixed

If something was modified, it saves the new data.

__get()

Magic getter

public __get(string $name) : mixed
Parameters
$name : string

Name of the property to get

Return values
mixed —

The value of field $name

Get the value of field $name. 'all' returns all fields.

__isset()

Magic isset

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

Name of the property to check is set

Return values
bool —

Checks if the field $name is set.

__set()

Magic setter for entity's property

public __set(string $name, mixed $value) : mixed
Parameters
$name : string

Name of the property to set

$value : mixed

New value of the property

Tags
throws
Exception

__toString()

Magic toString

public __toString() : string
Return values
string —

The string value of the object.

_text()

Translate text according to the object domain

public static _text(string $text[, array<string|int, mixed> $values = [] ]) : void
Parameters
$text : string

The text to translate

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

The values array to replace in text. Could be used as second parameter.

Tags
deprecated

Use static::text() or t()

asArray()

public asArray([string $model = self::OUTPUT_MODEL_ALL ]) : array<string|int, mixed>
Parameters
$model : string = self::OUTPUT_MODEL_ALL
Return values
array<string|int, mixed>

buildRaw()

public static buildRaw(array<string|int, mixed> $data[, bool $useCache = true ]) : static
Parameters
$data : array<string|int, mixed>
$useCache : bool = true
Return values
static

cacheInstances()

Cache an array of objects

public static cacheInstances(array<string|int, static> &$instances) : array<string|int, mixed>
Parameters
$instances : array<string|int, static>
Return values
array<string|int, mixed>

checkIntegrity()

Check object integrity & validity

public checkIntegrity() : mixed

checkUserInput()

Check if the class could generate a valid object from $input.

public static checkUserInput(array<string|int, mixed> $input[, array<string|int, string>|null $fields = null ][, PermanentEntity|null $ref = null ][, int &$errCount = 0 ][, bool $ignoreRequired = false ]) : array<string|int, mixed>

The method could modify the user input to fix it, but it must return the data. The data are passed through the validator, for different cases:

  • If empty, this function return an empty array.
  • If an array, it uses a field => checkMethod association.
Parameters
$input : array<string|int, mixed>

The user input data to check.

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

The array of fields to check. Default value is null.

$ref : PermanentEntity|null = null

The referenced object (update only). Default value is null.

$errCount : int = 0

The resulting error count, as pointer. Output parameter.

$ignoreRequired : bool = false
Return values
array<string|int, mixed> —

The valid data.

create()

Create a new permanent object from ths input data.

public static create([array<string|int, mixed> $input = [] ][, array<string|int, mixed>|null $fields = null ][, int &$errCount = 0 ]) : int

To create an object, we expect that it is valid, else we throw an exception.

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

The input data we will check, extract and create the new object.

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

The array of fields to check. Default value is null.

$errCount : int = 0

Output parameter to get the number of found errors. Default value is 0

Tags
see
testUserInput()
see
createAndGet()
Return values
int —

The ID of the new permanent object.

createAndGet()

Create a new permanent object

public static createAndGet([array<string|int, mixed> $input = [] ][, array<string|int, mixed>|null $fields = null ][, int &$errCount = 0 ]) : static
Parameters
$input : array<string|int, mixed> = []

The input data we will check, extract and create the new object.

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

The array of fields to check. Default value is null.

$errCount : int = 0

Output parameter to get the number of found errors. Default value is 0

Tags
see
testUserInput()
see
create()

Create a new permanent object from ths input data. To create an object, we expect that it is valid, else we throw an exception.

Return values
static —

The new permanent object

ei()

Escape identifier through instance

public static ei([string|null $identifier = null ]) : string
Parameters
$identifier : string|null = null

The identifier to escape. Default is table name.

Tags
see
static::escapeIdentifier()
deprecated

Use SqlSelectRequest

Return values
string —

The escaped identifier

equals()

Verify equality with another object

public equals(mixed $other) : bool
Parameters
$other : mixed

The object to compare.

Return values
bool —

True if this object represents the same data, else False.

Compare the class and the ID field value of the 2 objects.

escapeIdentifier()

Escape identifier through instance

public static escapeIdentifier([string|null $identifier = null ]) : string
Parameters
$identifier : string|null = null

The identifier to escape. Default is table name.

Tags
see
AbstractSqlAdapter::escapeIdentifier()
see
static::ei()
deprecated

Use SqlSelectRequest

Return values
string —

The escaped identifier

fillLogEvent()

Add an $event log in this $array

public static fillLogEvent(array<string|int, mixed> &$array, string $event) : void
Parameters
$array : array<string|int, mixed>
$event : string

findEntityObject()

Get entity instance by type and id

public static findEntityObject(string $entityType, string $entityId) : PermanentEntity
Parameters
$entityType : string
$entityId : string
Return values
PermanentEntity

free()

Free the object (remove)

public free() : bool
Tags
see
remove()
Return values
bool

get()

Get some permanent objects Get an objects' list using this class' table.

public static get([null $options = null ]) : SqlSelectRequest|array<string|int, mixed>|PermanentEntity|null

Take care that output=AbstractSqlAdapter::ARR_OBJECTS and number=1 is different from output=AbstractSqlAdapter::OBJECT

Parameters
$options : null = null

The options used to get the permanents object

Tags
see
AbstractSqlAdapter
deprecated

Use static::getSelectRequest()

Return values
SqlSelectRequest|array<string|int, mixed>|PermanentEntity|null —

An array of array containing object's data

getCachedInstance()

public static getCachedInstance(string $id) : static|null
Parameters
$id : string
Return values
static|null

getClass()

Get the name of this class

public static getClass() : string
Tags
deprecated

USe static::class instead

Return values
string —

The name of this class.

getCreateOperation()

Get the create operation

public static getCreateOperation(array<string|int, mixed> $input, array<string|int, string> $fields) : CreateTransactionOperation
Parameters
$input : array<string|int, mixed>

The input data we will check and extract, used by children

$fields : array<string|int, string>

The array of fields to check

Return values
CreateTransactionOperation

getDomain()

Get the domain of this class, can be guessed from $table or specified in $domain.

public static getDomain() : string
Return values
string —

The domain of this class.

getEntity()

Get this entity name

public static getEntity() : string
Return values
string

getEntityWhereClause()

Helper method to get whereClause string from an entity

public getEntityWhereClause([string $prefix = '' ]) : string
Parameters
$prefix : string = ''

The prefix for fields, e.g "table." (with dot)

Return values
string —

Helper method to get whereClause string from an entity. The related entity should have entity_type and entity_id fields.

getFields()

Get the available fields of this entity

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

The available fields in entity

getIdField()

Get the ID field name of this entity

public static getIdField() : string
Return values
string —

The ID field

getLogEvent()

Build a new log event for $event for this time and the user IP address.

public static getLogEvent(string $event[, mixed|null $time = null ][, string|null $ipAddress = null ]) : array<string|int, mixed>
Parameters
$event : string

The event to log in this object

$time : mixed|null = null

A specified time to use for logging event

$ipAddress : string|null = null

A specified IP Address to use for logging event

Tags
throws
Exception
see
logEvent()
deprecated
Return values
array<string|int, mixed>

getTable()

Get the table of this class

public static getTable() : string
Return values
string —

The table of this class.

getUpdateOperation()

Get the update operation

public getUpdateOperation(array<string|int, mixed> $input, array<string|int, string> $fields) : UpdateTransactionOperation
Parameters
$input : array<string|int, mixed>

The input data we will check and extract, used by children

$fields : array<string|int, string>

The array of fields to check

Return values
UpdateTransactionOperation

getValue()

Get the value of field $key or all data values if $key is null.

public getValue([string|null $key = null ]) : mixed
Parameters
$key : string|null = null

Name of the field to get.

id()

Get this permanent object's ID

public id() : string
Return values
string —

The id of this object.

initialize()

Initialize entity class You must call this method after the class declaration

public static initialize(string $name) : void
Parameters
$name : string
Tags
throws
CacheException

isDeleted()

Check if this object is deleted

public isDeleted() : bool
Return values
bool —

True if this object is deleted

Checks if this object is known as deleted.

isValid()

Check if this object is valid

public isValid() : bool
Return values
bool —

True if this object is valid

Check if this object is not deleted. May be used for others cases.

listKnownEntities()

List all known entities

public static listKnownEntities() : array<string|int, string>
Return values
array<string|int, string>

load()

Loads the object with the ID $id or the array data.

public static load(mixed $id[, bool $nullable = true ][, bool $useCache = true ]) : PermanentEntity|null

The return value is always a static object (no null, no array, no other object).

Parameters
$id : mixed

The object ID to load or a valid array of the object's data

$nullable : bool = true

True to silent errors row and return null

$useCache : bool = true

True to cache load and set cache, false to not cache

Tags
see
static::get()
Return values
PermanentEntity|null —

The object loaded from database

loadEntity()

Try to load entity from an entity string and an id integer

public static loadEntity(string $entity, string $id) : PermanentEntity|null
Parameters
$entity : string
$id : string
Return values
PermanentEntity|null

logEvent()

Log an event

public logEvent(string $event[, mixed $time = null ][, string|null $ipAdd = null ]) : void
Parameters
$event : string

The event to log in this object

$time : mixed = null

A specified time to use for logging event

$ipAdd : string|null = null

A specified IP Address to use for logging event

Tags
throws
Exception
see
getLogEvent()
deprecated

USe another function or update this one

markAsDeleted()

Mark this object as deleted

public markAsDeleted() : static
Tags
see
isDeleted()
warning

Be sure what you are doing before calling this function (never out of this class' context).

Mark this object as deleted

Return values
static

onValidCreate()

Callback when validating create

public static onValidCreate(array<string|int, mixed> &$input, int &$newErrors) : bool
Parameters
$input : array<string|int, mixed>
$newErrors : int
Return values
bool

onValidEdit()

Callback when validating create

public static onValidEdit(array<string|int, mixed> $input, PermanentEntity|null $object, int &$newErrors) : bool
Parameters
$input : array<string|int, mixed>
$object : PermanentEntity|null
$newErrors : int
Return values
bool

onValidUpdate()

Callback when validating update

public static onValidUpdate(array<string|int, mixed> &$input, int $newErrors) : bool
Parameters
$input : array<string|int, mixed>
$newErrors : int
Return values
bool

putValue()

Validate field value and set it

public putValue(string $field, mixed $value) : void
Parameters
$field : string
$value : mixed
Tags
throws
Exception

registerEntity()

Register an entity

public static registerEntity(string $class) : void
Parameters
$class : string

reload()

Reload fields from database Also it removes the reloaded fields from the modified ones list.

public reload() : bool
Return values
bool

remove()

What do you think it does ?

public remove() : bool
Return values
bool

save()

Save current changes of this entity to the database Input is NOT validated here, we recommend it for programming changes only

public save() : bool|int
Tags
throws
Exception
see
static::update()
Return values
bool|int —

True in case of success

setCheckFieldIntegrity()

Serve to bypass the integrity check, should be only used while developing

public static setCheckFieldIntegrity(bool $checkFieldIntegrity) : void
Parameters
$checkFieldIntegrity : bool

setValue()

Set the field $key with the new $value.

public setValue(string $key, mixed $value) : $this
Parameters
$key : string

Name of the field to set

$value : mixed

New value of the field

Tags
throws
Exception
Return values
$this

testUserInput()

Test user input

public static testUserInput(array<string|int, mixed> $input[, array<string|int, mixed>|null $fields = null ][, PermanentEntity|null $ref = null ][, int &$errCount = 0 ][, array<string|int, mixed>|bool $ignoreRequired = false ]) : bool
Parameters
$input : array<string|int, mixed>

The new data to process.

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

The array of fields to check. Default value is null.

$ref : PermanentEntity|null = null

The referenced object (update only). Default value is null.

$errCount : int = 0

The resulting error count, as pointer. Output parameter.

$ignoreRequired : array<string|int, mixed>|bool = false
Tags
throws
DuplicateException
see
create()
see
checkUserInput()
Return values
bool

text()

Translate text according to the object domain

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

The text to translate

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

The values array to replace in text. Could be used as second parameter.

Tags
see
t()
Return values
string —

The translated text

throwException()

Throws an UserException with the current domain

public static throwException(string $message) : void
Parameters
$message : string

the text message, may be a translation string

Tags
throws
UserException
see
UserException

throwNotFound()

Throws an NotFoundException with the current domain

public static throwNotFound([string|null $message = null ]) : mixed
Parameters
$message : string|null = null

the text message, may be a translation string

Tags
see
NotFoundException

uid()

Get this permanent object's unique ID

public uid() : string
Return values
string —

The uid of this object.

Get this object ID according to the table and id.

update()

Update this permanent entity from input data array Parameter $fields is really useful to allow partial modification only (against form hack).

public update(array<string|int, mixed> $input, array<string|int, string> $fields[, int &$errCount = 0 ]) : bool

Input is validated here, we recommend it for forms

Parameters
$input : array<string|int, mixed>

The input data we will check and extract, used by children

$fields : array<string|int, string>

The array of fields to check

$errCount : int = 0

Output parameter for the number of occurred errors validating fields.

Return values
bool

validateValue()

Validate field value from the validator using this entity

public validateValue(string $field, mixed $value) : void
Parameters
$field : string
$value : mixed

verifyConflicts()

Check for object This function is called by create() after checking user input data and before running for them.

public static verifyConflicts(array<string|int, mixed> $data[, PermanentEntity|null $object = null ]) : mixed

In the base class, this method does nothing.

Parameters
$data : array<string|int, mixed>

The new data to process.

$object : PermanentEntity|null = null

The referenced object (update only). Default value is null.

Tags
throws
UserException

checkCache()

Check if this object is cached and cache it

protected checkCache() : static
Return values
static

formatFieldSqlValue()

Format the value from PHP type to SQL scalar

protected static formatFieldSqlValue(string $name, mixed $value) : mixed
Parameters
$name : string

The field name to format

$value : mixed

The field value to format

Return values
mixed —

The formatted $Value

getExportData()

Get data with an exportable format.

protected getExportData([array<string|int, string>|null $filterKeys = null ]) : array<string|int, mixed>

We recommend to filter only data you need using $filterKeys

Parameters
$filterKeys : array<string|int, string>|null = null

The key to filter, else all

Return values
array<string|int, mixed>

instantiate()

Instantiate object from data, allowing you to instantiate child class

protected static instantiate(array<string|int, mixed> $data[, bool $useCache = true ]) : static
Parameters
$data : array<string|int, mixed>
$useCache : bool = true
Return values
static

parseFieldSqlValue()

Parse the value from SQL scalar to PHP type

protected static parseFieldSqlValue(string $name, string|null $value) : mixed
Parameters
$name : string

The field name to parse

$value : string|null

The field value to parse

Return values
mixed —

The parsed value

setData()

Set all data of object (internal use only)

protected setData(array<string|int, mixed> $data) : void
Parameters
$data : array<string|int, mixed>
Tags
warning

Internal use only, to load & reload


							

							
						

					

					
					
				
				

			

			

				
				

					On this page
					
					
				

			
			

		

		

			

				

					
Search results