Represents a single database table.
Exposes methods for retrieving data out of it, and manages the associations this table has to other tables. Multiple instances of this class can be created for the same database table with different aliases, this allows you to address your database structure in a richer and more expressive way.
The primary way to retrieve data is using Table::find(). See that method for more information.
In addition to the standard find($type) finder methods, CakePHP provides dynamic finder methods. These methods allow you to easily set basic conditions up. For example to filter users by username you would call
$query = $users->findByUsername('mark');
You can also combine conditions on multiple fields using either Or
or And
:
$query = $users->findByUsernameOrEmail('mark', '[email protected]');
You can use Table::updateAll() and Table::deleteAll() to do bulk updates/deletes. You should be aware that events will not be fired for bulk updates/deletes.
Table objects emit several events during as life-cycle hooks during find, delete and save operations. All events use the CakePHP event package:
Model.beforeFind
Fired before each find operation. By stopping the event and supplying a return value you can bypass the find operation entirely. Any changes done to the $query instance will be retained for the rest of the find. The $primary
parameter indicates whether or not this is the root query, or an associated query.
Model.buildValidator
Allows listeners to modify validation rules for the provided named validator.
Model.buildRules
Allows listeners to modify the rules checker by adding more rules.
Model.beforeRules
Fired before an entity is validated using the rules checker. By stopping this event, you can return the final value of the rules checking operation.
Model.afterRules
Fired after the rules have been checked on the entity. By stopping this event, you can return the final value of the rules checking operation.
Model.beforeSave
Fired before each entity is saved. Stopping this event will abort the save operation. When the event is stopped the result of the event will be returned.
Model.afterSave
Fired after an entity is saved.
Model.afterSaveCommit
Fired after the transaction in which the save operation is wrapped has been committed. It’s also triggered for non atomic saves where database operations are implicitly committed. The event is triggered only for the primary table on which save() is directly called. The event is not triggered if a transaction is started before calling save.
Model.beforeDelete
Fired before an entity is deleted. By stopping this event you will abort the delete operation.
Model.afterDelete
Fired after an entity has been deleted.
You can subscribe to the events listed above in your table classes by implementing the lifecycle methods below:
beforeFind(EventInterface $event, Query $query, ArrayObject $options, boolean $primary)
beforeMarshal(EventInterface $event, ArrayObject $data, ArrayObject $options)
afterMarshal(EventInterface $event, EntityInterface $entity, ArrayObject $options)
buildValidator(EventInterface $event, Validator $validator, string $name)
buildRules(RulesChecker $rules)
beforeRules(EventInterface $event, EntityInterface $entity, ArrayObject $options, string $operation)
afterRules(EventInterface $event, EntityInterface $entity, ArrayObject $options, bool $result, string $operation)
beforeSave(EventInterface $event, EntityInterface $entity, ArrayObject $options)
afterSave(EventInterface $event, EntityInterface $entity, ArrayObject $options)
afterSaveCommit(EventInterface $event, EntityInterface $entity, ArrayObject $options)
beforeDelete(EventInterface $event, EntityInterface $entity, ArrayObject $options)
afterDelete(EventInterface $event, EntityInterface $entity, ArrayObject $options)
afterDeleteCommit(EventInterface $event, EntityInterface $entity, ArrayObject $options)
string
'Model.buildValidator'
string
'default'
string
\Cake\ORM\Rule\IsUnique::class
string
\Cake\ORM\RulesChecker::class
string
'table'
string
Human name giving to this particular instance. Multiple objects representing the same database table can exist by using different aliases.
\Cake\ORM\AssociationCollection
The associations container for this Table.
\Cake\ORM\BehaviorRegistry
BehaviorRegistry for this table
\Cake\Database\Connection|null
Connection instance
string|string[]
The name of the field that represents a human readable representation of a row
string
The name of the class that represent a single row for this table
string
Default class name for new event objects.
\Cake\Event\EventManagerInterface
Instance of the Cake\Event\EventManager this object is using to dispatch inner events.
string|string[]
The name of the field that represents the primary key in the table
string|null
Registry key used to create this table object
\Cake\Datasource\RulesChecker
The domain rules to be applied to entities saved by this table
\Cake\Database\Schema\TableSchemaInterface|null
The schema object containing a description of this table fields
string
Name of the table as it can be found in the database
string
Validator class.
\Cake\Validation\Validator[]
A list of validation objects indexed by name
Returns an array that can be used to describe the internal state of this object.
Returns the association named after the passed value if exists, otherwise throws an exception.
Override this function in order to alter the schema used by this table.
Handles the saving of children associations and executing the afterSave logic once the entity for this table has been saved successfully.
Performs the actual find and/or create of an entity based on the passed options.
Out of an options array, check if the keys described in $keys
are arrays and change the values for closures that will concatenate the each of the properties in the value array when passed a row.
Checks if the caller would have executed a commit on a transaction.
Creates a new BelongsTo association between this table and a target table. A "belongs to" association is a N-1 relationship where this table is the N side, and where there is a single associated record in the target table for each one in this table.
Creates a new BelongsToMany association between this table and a target table. A "belongs to many" association is a M-N relationship.
Calls a finder method directly and applies it to the passed query, if no query is passed a new one will be created and returned
Checks if all table name + column name combinations used for queries fit into the max length allowed by database driver.
Returns whether or not the passed entity complies with all the rules stored in the rules checker.
Try to delete an entity or throw a PersistenceFailedException if the entity is new, has no primary key value, application rules checks failed or the delete was aborted by a callback.
Returns true if there is any record in this repository matching the specified conditions.
Creates a new Query for this repository and applies some defaults based on the type of search that was selected.
Returns an association object configured for the specified alias if any.
Sets up a query object so results appear as an indexed array, useful for any place where you would want a list such as for populating input select boxes.
Results for this finder will be a nested array, and is appropriate if you want to use the parent_id field of your model data to build nested results.
Returns a single record after finding it by its primary key, if no record is found this method throws an exception.
Returns the validation rules tagged with $name. It is possible to have multiple different named validation sets, this is useful when you need to use varying rules when saving from different routines in your system.
Creates a new HasMany association between this table and a target table. A "has many" association is a 1-N relationship.
Creates a new HasOne association between this table and a target table. A "has one" association is a 1-1 relationship.
Loads the specified associations in the passed entity or list of entities by executing extra queries in the database and merging the results in the appropriate properties.
Merges each of the elements passed in $data
into the entities found in $entities
respecting the accessible fields configured on the entities.
Merges the passed $data
into $entity
respecting the accessible fields configured on the entity. Returns the same entity after being altered.
Persists an entity based on the fields that are marked as dirty and returns the same entity after a successful save or false in case of any error.
Try to save an entity or throw a PersistenceFailedException if the application rules checks failed, the entity contains errors or the save was aborted by a callback.
Returns the default validator object. Subclasses can override this function to add a default validation set to the validator object.
__call(mixed $method, mixed $args)
Handles behavior delegation + dynamic finders.
If your Table uses any behaviors you can call them as if they were on the table object.
string
$method name of the method to be invoked
array
$args List of arguments passed to the function
mixed
BadMethodCallException
__construct(array $config)
Initializes a new instance
The $config array understands the following keys:
array
$config optional List of options for this table
__debugInfo()
Returns an array that can be used to describe the internal state of this object.
array
__get(mixed $property)
Returns the association named after the passed value if exists, otherwise throws an exception.
string
$property the association name
\Cake\ORM\Association
RuntimeException
__isset(mixed $property)
Returns whether an association named after the passed value exists for this table.
string
$property the association name
bool
_deleteMany(iterable $entities, mixed $options)
\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface
$entities Entities to delete.
array|\ArrayAccess
$options optional Options used.
\Cake\Datasource\EntityInterface|null
_dynamicFinder(string $method, array $args)
Provides the dynamic findBy and findAllBy methods.
string
$method The method name that was fired.
array
$args List of arguments passed to the function.
\Cake\ORM\Query
BadMethodCallException
_executeTransaction(callable $worker, bool $atomic)
Handles the logic executing of a worker inside a transaction.
callable
$worker The worker that will run inside the transaction.
bool
$atomic optional Whether to execute the worker inside a database transaction.
mixed
_getFindOrCreateQuery(mixed $search)
Gets the query object for findOrCreate().
array|callable|\Cake\ORM\Query
$search The criteria to find existing records by.
\Cake\ORM\Query
_initializeSchema(\Cake\Database\Schema\TableSchemaInterface $schema)
Override this function in order to alter the schema used by this table.
This function is only called after fetching the schema out of the database. If you wish to provide your own schema to this table without touching the database, you can override schema() or inject the definitions though that method.
protected function _initializeSchema(\Cake\Database\Schema\TableSchemaInterface $schema) { $schema->setColumnType('preferences', 'json'); return $schema; }
\Cake\Database\Schema\TableSchemaInterface
$schema The table definition fetched from database.
\Cake\Database\Schema\TableSchemaInterface
the altered schema
_insert(\Cake\Datasource\EntityInterface $entity, array $data)
Auxiliary function to handle the insert of an entity's data in the table
\Cake\Datasource\EntityInterface
$entity the subject entity from were $data was extracted
array
$data The actual data that needs to be saved
\Cake\Datasource\EntityInterface|false
RuntimeException
_newId(array $primary)
Generate a primary key value for a new record.
By default, this uses the type system to generate a new primary key value if possible. You can override this method if you have specific requirements for id generation.
Note: The ORM will not generate primary key values for composite primary keys. You can overwrite _newId() in your table class.
string[]
$primary The primary key columns to get a new ID for.
string|null
Either null or the primary key value or a list of primary key values.
_onSaveSuccess(\Cake\Datasource\EntityInterface $entity, \ArrayObject $options)
Handles the saving of children associations and executing the afterSave logic once the entity for this table has been saved successfully.
\Cake\Datasource\EntityInterface
$entity the entity to be saved
\ArrayObject
$options the options to use for the save operation
bool
True on success
Cake\ORM\Exception\RolledbackTransactionException
_processDelete(\Cake\Datasource\EntityInterface $entity, \ArrayObject $options)
Perform the delete operation.
Will delete the entity provided. Will remove rows from any dependent associations, and clear out join tables for BelongsToMany associations.
\Cake\Datasource\EntityInterface
$entity The entity to delete.
\ArrayObject
$options The options for the delete.
bool
success
InvalidArgumentException
_processFindOrCreate(mixed $search, ?callable $callback, mixed $options)
Performs the actual find and/or create of an entity based on the passed options.
array|callable|\Cake\ORM\Query
$search The criteria to find an existing record by, or a callable tha will customize the find query.
callable|null
$callback optional A callback that will be invoked for newly created entities. This callback will be called before the entity is persisted.
array
$options optional The options to use when saving.
\Cake\Datasource\EntityInterface|array
An entity.
Cake\ORM\Exception\PersistenceFailedException
InvalidArgumentException
_processSave(\Cake\Datasource\EntityInterface $entity, \ArrayObject $options)
Performs the actual saving of an entity based on the passed options.
\Cake\Datasource\EntityInterface
$entity the entity to be saved
\ArrayObject
$options the options to use for the save operation
\Cake\Datasource\EntityInterface|false
RuntimeException
Cake\ORM\Exception\RolledbackTransactionException
_saveMany(iterable $entities, mixed $options)
\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface
$entities Entities to save.
array|\ArrayAccess|\Cake\ORM\SaveOptionsBuilder
$options optional Options used when calling Table::save() for each entity.
\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface
Entities list.
Cake\ORM\Exception\PersistenceFailedException
Exception
_setFieldMatchers(array $options, array $keys)
Out of an options array, check if the keys described in $keys
are arrays and change the values for closures that will concatenate the each of the properties in the value array when passed a row.
This is an auxiliary function used for result formatters that can accept composite keys when comparing values.
array
$options the original options passed to a finder
string[]
$keys the keys to check in $options to build matchers from the associated value
array
_transactionCommitted(bool $atomic, bool $primary)
Checks if the caller would have executed a commit on a transaction.
bool
$atomic True if an atomic transaction was used.
bool
$primary True if a primary was used.
bool
Returns true if a transaction was committed.
_update(\Cake\Datasource\EntityInterface $entity, array $data)
Auxiliary function to handle the update of an entity's data in the table
\Cake\Datasource\EntityInterface
$entity the subject entity from were $data was extracted
array
$data The actual data that needs to be saved
\Cake\Datasource\EntityInterface|false
InvalidArgumentException
addAssociations(array $params)
Setup multiple associations.
It takes an array containing set of table names indexed by association type as argument:
$this->Posts->addAssociations([ 'belongsTo' => [ 'Users' => ['className' => 'App\Model\Table\UsersTable'] ], 'hasMany' => ['Comments'], 'belongsToMany' => ['Tags'] ]);
Each association type accepts multiple associations where the keys are the aliases, and the values are association config data. If numeric keys are used the values will be treated as association aliases.
array
$params Set of associations to bind (indexed by association type)
$this
addBehavior(string $name, array $options)
Add a behavior.
Adds a behavior to this table's behavior collection. Behaviors provide an easy way to create horizontally re-usable features that can provide trait like functionality, and allow for events to be listened to.
Example:
Load a behavior, with some settings.
$this->addBehavior('Tree', ['parent' => 'parentId']);
Behaviors are generally loaded during Table::initialize().
string
$name The name of the behavior. Can be a short class reference.
array
$options optional The options for the behavior to use.
$this
RuntimeException
addBehaviors(array $behaviors)
Adds an array of behaviors to the table's behavior collection.
Example:
$this->addBehaviors([ 'Timestamp', 'Tree' => ['level' => 'level'], ]);
array
$behaviors All of the behaviors to load.
$this
RuntimeException
aliasField(string $field)
Alias a field with the table's current alias.
If field is already aliased it will result in no-op.
string
$field The field to alias.
string
The field prefixed with the table alias.
associations()
Get the associations collection for this table.
\Cake\ORM\AssociationCollection
The collection of association objects.
behaviors()
Returns the behavior registry for this table.
\Cake\ORM\BehaviorRegistry
The BehaviorRegistry instance.
belongsTo(string $associated, array $options)
Creates a new BelongsTo association between this table and a target table. A "belongs to" association is a N-1 relationship where this table is the N side, and where there is a single associated record in the target table for each one in this table.
Target table can be inferred by its name, which is provided in the first argument, or you can either pass the to be instantiated or an instance of it directly.
The options array accept the following keys:
This method will return the association object that was built.
string
$associated the alias for the target table. This is used to uniquely identify the association
array
$options optional list of options to configure the association definition
\Cake\ORM\Association\BelongsTo
belongsToMany(string $associated, array $options)
Creates a new BelongsToMany association between this table and a target table. A "belongs to many" association is a M-N relationship.
Target table can be inferred by its name, which is provided in the first argument, or you can either pass the class name to be instantiated or an instance of it directly.
The options array accept the following keys:
This method will return the association object that was built.
string
$associated the alias for the target table. This is used to uniquely identify the association
array
$options optional list of options to configure the association definition
\Cake\ORM\Association\BelongsToMany
buildRules(\Cake\ORM\RulesChecker $rules)
Returns a RulesChecker object after modifying the one that was supplied.
Subclasses should override this method in order to initialize the rules to be applied to entities saved by this instance.
\Cake\ORM\RulesChecker
$rules The rules object to be modified.
\Cake\ORM\RulesChecker
callFinder(string $type, \Cake\ORM\Query $query, array $options)
Calls a finder method directly and applies it to the passed query, if no query is passed a new one will be created and returned
string
$type name of the finder to be called
\Cake\ORM\Query
$query The query object to apply the finder options to
array
$options optional List of options to pass to the finder
\Cake\ORM\Query
BadMethodCallException
checkAliasLengths()
Checks if all table name + column name combinations used for queries fit into the max length allowed by database driver.
RuntimeException
checkRules(\Cake\Datasource\EntityInterface $entity, string $operation, mixed $options)
Returns whether or not the passed entity complies with all the rules stored in the rules checker.
\Cake\Datasource\EntityInterface
$entity The entity to check for validity.
string
$operation optional The operation being run. Either 'create', 'update' or 'delete'.
\ArrayObject|array|null
$options optional The options To be passed to the rules.
bool
createValidator(string $name)
Creates a validator using a custom method inside your class.
This method is used only to build a new validator and it does not store it in your object. If you want to build and reuse validators, use getValidator() method instead.
string
$name The name of the validation set to create.
\Cake\Validation\Validator
RuntimeException
defaultConnectionName()
Get the default connection name.
This method is used to get the fallback connection name if an instance is created through the TableLocator without a connection.
string
delete(\Cake\Datasource\EntityInterface $entity, mixed $options)
Delete a single entity.
Deletes an entity and possibly related associations from the database based on the 'dependent' option used when defining the association.
\Cake\Datasource\EntityInterface
$entity The entity to remove.
array|\ArrayAccess
$options optional The options for the delete.
bool
success
deleteAll(mixed $conditions)
Deletes all records matching the provided conditions.
This method will not trigger beforeDelete/afterDelete events. If you need those first load a collection of records and delete them.
This method will not execute on associations' cascade
attribute. You should use database foreign keys + ON CASCADE rules if you need cascading deletes combined with this method.
mixed
$conditions Conditions to be used, accepts anything Query::where() can take.
int
Returns the number of affected rows.
deleteMany(iterable $entities, mixed $options)
Deletes multiple entities of a table.
The records will be deleted in a transaction which will be rolled back if any one of the records fails to delete due to failed validation or database error.
\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface
$entities Entities to delete.
array|\ArrayAccess
$options optional Options used when calling Table::save() for each entity.
\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface|false
Entities list on success, false on failure.
deleteManyOrFail(iterable $entities, mixed $options)
Deletes multiple entities of a table.
The records will be deleted in a transaction which will be rolled back if any one of the records fails to delete due to failed validation or database error.
\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface
$entities Entities to delete.
array|\ArrayAccess
$options optional Options used when calling Table::save() for each entity.
\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface
Entities list.
Cake\ORM\Exception\PersistenceFailedException
deleteOrFail(\Cake\Datasource\EntityInterface $entity, mixed $options)
Try to delete an entity or throw a PersistenceFailedException if the entity is new, has no primary key value, application rules checks failed or the delete was aborted by a callback.
\Cake\Datasource\EntityInterface
$entity The entity to remove.
array|\ArrayAccess
$options optional The options for the delete.
true
Cake\ORM\Exception\PersistenceFailedException
dispatchEvent(string $name, ?array $data, ?object $subject)
Wrapper for creating and dispatching events.
Returns a dispatched event.
string
$name Name of the event.
array|null
$data optional Any value you wish to be transported with this event to it can be read by listeners.
object|null
$subject optional The object that this event applies to ($this by default).
\Cake\Event\EventInterface
exists(mixed $conditions)
Returns true if there is any record in this repository matching the specified conditions.
array
$conditions list of conditions to pass to the query
bool
find(string $type, array $options)
Creates a new Query for this repository and applies some defaults based on the type of search that was selected.
Each find() will trigger a Model.beforeFind
event for all attached listeners. Any listener can set a valid result set using $query
By default, $options
will recognize the following keys:
Using the options array:
$query = $articles->find('all', [ 'conditions' => ['published' => 1], 'limit' => 10, 'contain' => ['Users', 'Comments'] ]);
Using the builder interface:
$query = $articles->find() ->where(['published' => 1]) ->limit(10) ->contain(['Users', 'Comments']);
The find() method is the entry point for custom finder methods. You can invoke a finder by specifying the type:
$query = $articles->find('published');
Would invoke the findPublished
method.
string
$type optional the type of query to perform
array
$options optional An array that will be passed to Query::applyOptions()
\Cake\ORM\Query
The query builder
findAll(\Cake\ORM\Query $query, array $options)
Returns the query as passed.
By default findAll() applies no conditions, you can override this method in subclasses to modify how find('all')
works.
\Cake\ORM\Query
$query The query to find with
array
$options The options to use for the find
\Cake\ORM\Query
The query builder
findAssociation(string $name)
Returns an association object configured for the specified alias if any.
The name argument also supports dot syntax to access deeper associations.
$users = $this->getAssociation('Articles.Comments.Users');
string
$name The alias used for the association.
\Cake\ORM\Association|null
Either the association or null.
findList(\Cake\ORM\Query $query, array $options)
Sets up a query object so results appear as an indexed array, useful for any place where you would want a list such as for populating input select boxes.
When calling this finder, the fields passed are used to determine what should be used as the array key, value and optionally what to group the results by. By default the primary key for the model is used for the key, and the display field as value.
The results of this finder will be in the following form:
[ 1 => 'value for id 1', 2 => 'value for id 2', 4 => 'value for id 4' ]
You can specify which property will be used as the key and which as value by using the $options
array, when not specified, it will use the results of calling primaryKey
and displayField
respectively in this table:
$table->find('list', [ 'keyField' => 'name', 'valueField' => 'age' ]);
Results can be put together in bigger groups when they share a property, you can customize the property to use for grouping by setting groupField
:
$table->find('list', [ 'groupField' => 'category_id', ]);
When using a groupField
results will be returned in this format:
[ 'group_1' => [ 1 => 'value for id 1', 2 => 'value for id 2', ] 'group_2' => [ 4 => 'value for id 4' ] ]
\Cake\ORM\Query
$query The query to find with
array
$options The options for the find
\Cake\ORM\Query
The query builder
findOrCreate(mixed $search, ?callable $callback, mixed $options)
Finds an existing record or creates a new one.
A find() will be done to locate an existing record using the attributes defined in $search. If records matches the conditions, the first record will be returned.
If no record can be found, a new entity will be created with the $search properties. If a callback is provided, it will be called allowing you to define additional default values. The new entity will be saved and returned.
If your find conditions require custom order, associations or conditions, then the $search parameter can be a callable that takes the Query as the argument, or a \Cake\ORM\Query object passed as the $search parameter. Allowing you to customize the find results.
The options array is passed to the save method with exception to the following keys:
array|callable|\Cake\ORM\Query
$search The criteria to find existing records by. Note that when you pass a query object you'll have to use the 2nd arg of the method to modify the entity data before saving.
callable|null
$callback optional A callback that will be invoked for newly created entities. This callback will be called before the entity is persisted.
array
$options optional The options to use when saving.
\Cake\Datasource\EntityInterface
An entity.
Cake\ORM\Exception\PersistenceFailedException
findThreaded(\Cake\ORM\Query $query, array $options)
Results for this finder will be a nested array, and is appropriate if you want to use the parent_id field of your model data to build nested results.
Values belonging to a parent row based on their parent_id value will be recursively nested inside the parent row values using the children
property
You can customize what fields are used for nesting results, by default the primary key and the parent_id
fields are used. If you wish to change these defaults you need to provide the keys keyField
, parentField
or nestingKey
in $options
:
$table->find('threaded', [ 'keyField' => 'id', 'parentField' => 'ancestor_id' 'nestingKey' => 'children' ]);
\Cake\ORM\Query
$query The query to find with
array
$options The options to find with
\Cake\ORM\Query
The query builder
get(mixed $primaryKey, array $options)
Returns a single record after finding it by its primary key, if no record is found this method throws an exception.
$id = 10; $article = $articles->get($id); $article = $articles->get($id, ['contain' => ['Comments]]);
mixed
$primaryKey primary key value to find
array
$options optional options accepted by Table::find()
\Cake\Datasource\EntityInterface
Cake\Datasource\Exception\RecordNotFoundException
Cake\Datasource\Exception\InvalidPrimaryKeyException
Cake\Datasource\Exception\RecordNotFoundException
getAlias()
Returns the table alias.
string
getAssociation(string $name)
Returns an association object configured for the specified alias.
The name argument also supports dot syntax to access deeper associations.
$users = $this->getAssociation('Articles.Comments.Users');
Note that this method requires the association to be present or otherwise throws an exception. If you are not sure, use hasAssociation() before calling this method.
string
$name The alias used for the association.
\Cake\ORM\Association
The association.
InvalidArgumentException
getBehavior(string $name)
Get a behavior from the registry.
string
$name The behavior alias to get from the registry.
\Cake\ORM\Behavior
InvalidArgumentException
getConnection()
Returns the connection instance.
\Cake\Database\Connection
getDisplayField()
Returns the display field.
string|string[]|null
getEntityClass()
Returns the class used to hydrate rows for this table.
string
getEventManager()
Returns the Cake\Event\EventManager manager instance for this object.
You can use this instance to register any new listeners or callbacks to the object events, or create your own events and trigger them at will.
\Cake\Event\EventManagerInterface
getPrimaryKey()
Returns the primary key field name.
string|string[]
getRegistryAlias()
Returns the table registry key used to create this table instance.
string
getSaveOptionsBuilder(array $options)
Gets a SaveOptionsBuilder instance.
array
$options optional Options to parse by the builder.
\Cake\ORM\SaveOptionsBuilder
getSchema()
Returns the schema table object describing this table's properties.
\Cake\Database\Schema\TableSchemaInterface
getTable()
Returns the database table name.
This can include the database schema name if set using setTable()
.
string
getValidator(?string $name)
Returns the validation rules tagged with $name. It is possible to have multiple different named validation sets, this is useful when you need to use varying rules when saving from different routines in your system.
If a validator has not been set earlier, this method will build a valiator using a method inside your class.
For example, if you wish to create a validation set called 'forSubscription', you will need to create a method in your Table subclass as follows:
public function validationForSubscription($validator) { return $validator ->add('email', 'valid-email', ['rule' => 'email']) ->add('password', 'valid', ['rule' => 'notBlank']) ->requirePresence('username'); } $validator = $this->getValidator('forSubscription');
You can implement the method in validationDefault
in your Table subclass should you wish to have a validation set that applies in cases where no other set is specified.
If a $name argument has not been provided, the default validator will be returned. You can configure your default validator name in a DEFAULT_VALIDATOR
class constant.
string|null
$name optional The name of the validation set to return.
\Cake\Validation\Validator
hasAssociation(string $name)
Checks whether a specific association exists on this Table instance.
The name argument also supports dot syntax to access deeper associations.
$hasUsers = $this->hasAssociation('Articles.Comments.Users');
string
$name The alias used for the association.
bool
hasBehavior(string $name)
Check if a behavior with the given alias has been loaded.
string
$name The behavior alias to check.
bool
Whether or not the behavior exists.
hasField(string $field)
Test to see if a Table has a specific field/column.
Delegates to the schema object and checks for column presence using the Schema\Table instance.
string
$field The field to check for.
bool
True if the field exists, false if it does not.
hasFinder(string $type)
Returns true if the finder exists for the table
string
$type name of finder to check
bool
hasMany(string $associated, array $options)
Creates a new HasMany association between this table and a target table. A "has many" association is a 1-N relationship.
Target table can be inferred by its name, which is provided in the first argument, or you can either pass the class name to be instantiated or an instance of it directly.
The options array accept the following keys:
cascadeCallbacks
as well. Set to false if you don't want CakePHP to remove associated data, or when you are using database constraints.dependent
is true records will be orphaned.This method will return the association object that was built.
string
$associated the alias for the target table. This is used to uniquely identify the association
array
$options optional list of options to configure the association definition
\Cake\ORM\Association\HasMany
hasOne(string $associated, array $options)
Creates a new HasOne association between this table and a target table. A "has one" association is a 1-1 relationship.
Target table can be inferred by its name, which is provided in the first argument, or you can either pass the class name to be instantiated or an instance of it directly.
The options array accept the following keys:
cascadeCallbacks
as well. Set to false if you don't want CakePHP to remove associated data, or when you are using database constraints.This method will return the association object that was built.
string
$associated the alias for the target table. This is used to uniquely identify the association
array
$options optional list of options to configure the association definition
\Cake\ORM\Association\HasOne
hasValidator(string $name)
Checks whether or not a validator has been set.
string
$name The name of a validator.
bool
implementedEvents()
Get the Model callbacks this table is interested in.
By implementing the conventional methods a table class is assumed to be interested in the related event.
Override this method if you need to add non-conventional event listeners. Or if you want you table to listen to non-standard events.
The conventional method map is:
array
initialize(array $config)
Initialize a table instance. Called after the constructor.
You can use this method to define associations, attach behaviors define validation and do any other initialization logic you need.
public function initialize(array $config) { $this->belongsTo('Users'); $this->belongsToMany('Tagging.Tags'); $this->setPrimaryKey('something_else'); }
array
$config Configuration options passed to the constructor
loadInto(mixed $entities, array $contain)
Loads the specified associations in the passed entity or list of entities by executing extra queries in the database and merging the results in the appropriate properties.
$user = $usersTable->get(1); $user = $usersTable->loadInto($user, ['Articles.Tags', 'Articles.Comments']); echo $user->articles[0]->title;
You can also load associations for multiple entities at once
$users = $usersTable->find()->where([...])->toList(); $users = $usersTable->loadInto($users, ['Articles.Tags', 'Articles.Comments']); echo $user[1]->articles[0]->title;
The properties for the associations to be loaded will be overwritten on each entity.
\Cake\Datasource\EntityInterface|\Cake\Datasource\EntityInterface[]
$entities a single entity or list of entities
array
$contain A contain()
compatible array.
\Cake\Datasource\EntityInterface|\Cake\Datasource\EntityInterface[]
marshaller()
Get the object used to marshal/convert array data into objects.
Override this method if you want a table object to use custom marshalling logic.
\Cake\ORM\Marshaller
newEmptyEntity()
This creates a new entity object.
Careful: This does not trigger any field validation. This entity can be persisted without validation error as empty record. Always patch in required fields before saving.
\Cake\Datasource\EntityInterface
newEntities(array $data, array $options)
Create a list of entities + associated entities from an array.
This is most useful when hydrating request data back into entities. For example, in your controller code:
$articles = $this->Articles->newEntities($this->request->getData());
The hydrated entities can then be iterated and saved.
array
$data The data to build an entity with.
array
$options optional A list of options for the objects hydration.
\Cake\Datasource\EntityInterface[]
An array of hydrated records.
newEntity(array $data, array $options)
Create a new entity + associated entities from an array.
This is most useful when hydrating request data back into entities. For example, in your controller code:
$article = $this->Articles->newEntity($this->request->getData());
The hydrated entity will correctly do an insert/update based on the primary key data existing in the database when the entity is saved. Until the entity is saved, it will be a detached record.
array
$data The data to build an entity with.
array
$options optional A list of options for the object hydration.
\Cake\Datasource\EntityInterface
patchEntities(iterable $entities, array $data, array $options)
Merges each of the elements passed in $data
into the entities found in $entities
respecting the accessible fields configured on the entities.
Merging is done by matching the primary key in each of the elements in $data
and $entities
.
This is most useful when editing a list of existing entities using request data:
$article = $this->Articles->patchEntities($articles, $this->request->getData());
\Cake\Datasource\EntityInterface[]|\Traversable
$entities the entities that will get the data merged in
array
$data list of arrays to be merged into the entities
array
$options optional A list of options for the objects hydration.
\Cake\Datasource\EntityInterface[]
patchEntity(\Cake\Datasource\EntityInterface $entity, array $data, array $options)
Merges the passed $data
into $entity
respecting the accessible fields configured on the entity. Returns the same entity after being altered.
This is most useful when editing an existing entity using request data:
$article = $this->Articles->patchEntity($article, $this->request->getData());
\Cake\Datasource\EntityInterface
$entity the entity that will get the data merged in
array
$data key value list of fields to be merged into the entity
array
$options optional A list of options for the object hydration.
\Cake\Datasource\EntityInterface
query()
Creates a new Query instance for a table.
\Cake\ORM\Query
removeBehavior(string $name)
Removes a behavior from this table's behavior registry.
Example:
Remove a behavior from this table.
$this->removeBehavior('Tree');
string
$name The alias that the behavior was added with.
$this
rulesChecker()
Returns the RulesChecker for this instance.
A RulesChecker object is used to test an entity for validity on rules that may involve complex logic or data that needs to be fetched from relevant datasources.
\Cake\Datasource\RulesChecker
save(\Cake\Datasource\EntityInterface $entity, mixed $options)
Persists an entity based on the fields that are marked as dirty and returns the same entity after a successful save or false in case of any error.
\Cake\Datasource\EntityInterface
$entity the entity to be saved
array|\ArrayAccess|\Cake\ORM\SaveOptionsBuilder
$options optional The options to use when saving.
\Cake\Datasource\EntityInterface|false
Cake\ORM\Exception\RolledbackTransactionException
saveMany(iterable $entities, mixed $options)
Persists multiple entities of a table.
The records will be saved in a transaction which will be rolled back if any one of the records fails to save due to failed validation or database error.
\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface
$entities Entities to save.
array|\ArrayAccess|\Cake\ORM\SaveOptionsBuilder
$options optional Options used when calling Table::save() for each entity.
\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface|false
False on failure, entities list on success.
Exception
saveManyOrFail(iterable $entities, mixed $options)
Persists multiple entities of a table.
The records will be saved in a transaction which will be rolled back if any one of the records fails to save due to failed validation or database error.
\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface
$entities Entities to save.
array|\ArrayAccess
$options optional Options used when calling Table::save() for each entity.
\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface
Entities list.
Exception
Cake\ORM\Exception\PersistenceFailedException
saveOrFail(\Cake\Datasource\EntityInterface $entity, mixed $options)
Try to save an entity or throw a PersistenceFailedException if the application rules checks failed, the entity contains errors or the save was aborted by a callback.
\Cake\Datasource\EntityInterface
$entity the entity to be saved
array|\ArrayAccess
$options optional The options to use when saving.
\Cake\Datasource\EntityInterface
Cake\ORM\Exception\PersistenceFailedException
setAlias(string $alias)
Sets the table alias.
string
$alias Table alias
$this
setConnection(\Cake\Database\Connection $connection)
Sets the connection instance.
\Cake\Database\Connection
$connection The connection instance
$this
setDisplayField(mixed $field)
Sets the display field.
string|string[]
$field Name to be used as display field.
$this
setEntityClass(string $name)
Sets the class used to hydrate rows for this table.
string
$name The name of the class to use
$this
Cake\ORM\Exception\MissingEntityException
setEventManager(\Cake\Event\EventManagerInterface $eventManager)
Returns the Cake\Event\EventManagerInterface instance for this object.
You can use this instance to register any new listeners or callbacks to the object events, or create your own events and trigger them at will.
\Cake\Event\EventManagerInterface
$eventManager the eventManager to set
$this
setPrimaryKey(mixed $key)
Sets the primary key field name.
string|string[]
$key Sets a new name to be used as primary key
$this
setRegistryAlias(string $registryAlias)
Sets the table registry key used to create this table instance.
string
$registryAlias The key used to access this object.
$this
setSchema(mixed $schema)
Sets the schema table object describing this table's properties.
If an array is passed, a new TableSchemaInterface will be constructed out of it and used as the schema for this table.
array|\Cake\Database\Schema\TableSchemaInterface
$schema Schema to be used for this table
$this
setTable(string $table)
Sets the database table name.
This can include the database schema name in the form 'schema.table'. If the name must be quoted, enable automatic identifier quoting.
string
$table Table name.
$this
setValidator(string $name, \Cake\Validation\Validator $validator)
This method stores a custom validator under the given name.
You can build the object by yourself and store it in your object:
$validator = new \Cake\Validation\Validator($table); $validator ->add('email', 'valid-email', ['rule' => 'email']) ->add('password', 'valid', ['rule' => 'notBlank']) ->allowEmpty('bio'); $this->setValidator('forSubscription', $validator);
string
$name The name of a validator to be set.
\Cake\Validation\Validator
$validator Validator object to be set.
$this
updateAll(mixed $fields, mixed $conditions)
Update all matching records.
Sets the $fields to the provided values based on $conditions. This method will not trigger beforeSave/afterSave events. If you need those first load a collection of records and update them.
string|array|\Closure|\Cake\Database\Expression\QueryExpression
$fields A hash of field => new value.
mixed
$conditions Conditions to be used, accepts anything Query::where() can take.
int
Count Returns the affected rows.
validateUnique(mixed $value, array $options, ?array $context)
Validator method used to check the uniqueness of a value for a column.
This is meant to be used with the validation API and not to be called directly.
$validator->add('email', [ 'unique' => ['rule' => 'validateUnique', 'provider' => 'table'] ])
Unique validation can be scoped to the value of another column:
$validator->add('email', [ 'unique' => [ 'rule' => ['validateUnique', ['scope' => 'site_id']], 'provider' => 'table' ] ]);
In the above example, the email uniqueness will be scoped to only rows having the same site_id. Scoping will only be used if the scoping field is present in the data to be validated.
mixed
$value The value of column to be checked for uniqueness.
array
$options The options array, optionally containing the 'scope' key. May also be the validation context, if there are no options.
array|null
$context optional Either the validation context or null.
bool
True if the value is unique, or false if a non-scalar, non-unique value was given.
validationDefault(\Cake\Validation\Validator $validator)
Returns the default validator object. Subclasses can override this function to add a default validation set to the validator object.
\Cake\Validation\Validator
$validator The validator that can be modified to add some rules to it.
\Cake\Validation\Validator
validationMethodExists(string $name)
Checks if validation method exists.
string
$name Validation method name.
bool
Human name giving to this particular instance. Multiple objects representing the same database table can exist by using different aliases.
string
The associations container for this Table.
\Cake\ORM\AssociationCollection
BehaviorRegistry for this table
\Cake\ORM\BehaviorRegistry
Connection instance
\Cake\Database\Connection|null
The name of the field that represents a human readable representation of a row
string|string[]
The name of the class that represent a single row for this table
string
Default class name for new event objects.
string
Instance of the Cake\Event\EventManager this object is using to dispatch inner events.
\Cake\Event\EventManagerInterface
The name of the field that represents the primary key in the table
string|string[]
Registry key used to create this table object
string|null
The domain rules to be applied to entities saved by this table
\Cake\Datasource\RulesChecker
The schema object containing a description of this table fields
\Cake\Database\Schema\TableSchemaInterface|null
Name of the table as it can be found in the database
string
Validator class.
string
A list of validation objects indexed by name
\Cake\Validation\Validator[]
© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.1/class-Cake.ORM.Table.html