VALIDATOR_PROVIDER_NAME
VALIDATOR_PROVIDER_NAME = 'table' : string
The alias this object is assigned to validators as.
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', 'mark@example.org');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 provide a few callbacks/events you can hook into to augment/replace find operations. Each event uses the standard event subsystem in CakePHP
beforeFind(Event $event, Query $query, ArrayObject $options, boolean $primary)
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.
buildValidator(Event $event, Validator $validator, string $name)
Allows listeners to modify validation rules for the provided named validator.
buildRules(Event $event, RulesChecker $rules)
Allows listeners to modify the rules checker by adding more rules.
beforeRules(Event $event, EntityInterface $entity, ArrayObject $options, string $operation)
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.
afterRules(Event $event, EntityInterface $entity, ArrayObject $options, bool $result, string $operation)
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.
beforeSave(Event $event, EntityInterface $entity, ArrayObject $options)
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.
afterSave(Event $event, EntityInterface $entity, ArrayObject $options)
Fired after an entity is saved.
afterSaveCommit(Event $event, EntityInterface $entity, ArrayObject $options)
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.
beforeDelete(Event $event, EntityInterface $entity, ArrayObject $options)
Fired before an entity is deleted. By stopping this event you will abort
the delete operation.
afterDelete(Event $event, EntityInterface $entity, ArrayObject $options)
Fired after an entity has been deleted.$_eventManager : \Cake\Event\EventManagerInterface|\Cake\Event\EventManager
Instance of the Cake\Event\EventManager this object is using to dispatch inner events.
$_rulesChecker : \Cake\Datasource\RulesChecker
The domain rules to be applied to entities saved by this table
$_validators : array<mixed,\Cake\Validation\Validator>
A list of validation objects indexed by name
$_connection : \Cake\Database\Connection
Connection instance
$_schema : \Cake\Database\Schema\TableSchema
The schema object containing a description of this table fields
$_associations : \Cake\ORM\AssociationCollection
The associations container for this Table.
$_behaviors : \Cake\ORM\BehaviorRegistry
BehaviorRegistry for this table
eventManager(\Cake\Event\EventManager|null $eventManager = null) : \Cake\Event\EventManager
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\EventManager|null | $eventManager | the eventManager to set |
getEventManager() : \Cake\Event\EventManager
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.
setEventManager(\Cake\Event\EventManager $eventManager) : $this
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\EventManager | $eventManager | the eventManager to set |
dispatchEvent(string $name, array|null $data = null, object|null $subject = null) : \Cake\Event\Event
Wrapper for creating and dispatching events.
Returns a dispatched event.
| string | $name | Name of the event. |
| array|null | $data | Any value you wish to be transported with this event to it can be read by listeners. |
| object|null | $subject | The object that this event applies to ($this by default). |
checkRules(\Cake\Datasource\EntityInterface $entity, string $operation = \Cake\Datasource\RulesChecker::CREATE, \ArrayObject|array|null $options = null) : boolean
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 | The operation being run. Either 'create', 'update' or 'delete'. |
| \ArrayObject|array|null | $options | The options To be passed to the rules. |
rulesChecker() : \Cake\Datasource\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.
buildRules(\Cake\ORM\RulesChecker $rules) : \Cake\ORM\RulesChecker
{@inheritDoc}
| \Cake\ORM\RulesChecker | $rules | The rules object to be modified. |
validator(string|null $name = null, \Cake\Validation\Validator|null $validator = null) : \Cake\Validation\Validator
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.
There are two different ways of creating and naming validation sets: by creating a new method inside your own Table subclass, or by building the validator object yourself and storing it using this method.
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');
}Otherwise, you can build the object by yourself and store it in the Table object:
$validator = new \Cake\Validation\Validator($table);
$validator
->add('email', 'valid-email', ['rule' => 'email'])
->add('password', 'valid', ['rule' => 'notBlank'])
->allowEmpty('bio');
$table->setValidator('forSubscription', $validator);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.
| string|null | $name | the name of the validation set to return |
| \Cake\Validation\Validator|null | $validator | The validator instance to store, use null to get a validator. |
getValidator(string|null $name = null) : \Cake\Validation\Validator
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 | The name of the validation set to return. |
setValidator(string $name, \Cake\Validation\Validator $validator) : $this
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. |
validationDefault(\Cake\Validation\Validator $validator) : \Cake\Validation\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. |
__construct(array $config = array())
Initializes a new instance
The $config array understands the following keys:
| array | $config | List of options for this table |
initialize(array $config) : void
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 |
setConnection(\Cake\Database\Connection $connection) : $this
Sets the connection instance.
| \Cake\Database\Connection | $connection | The connection instance |
getConnection() : \Cake\Database\Connection
Returns the connection instance.
connection(\Cake\Datasource\ConnectionInterface|null $connection = null) : \Cake\Datasource\ConnectionInterface
Returns the connection instance or sets a new one
| \Cake\Datasource\ConnectionInterface|null | $connection | The new connection instance |
getSchema() : \Cake\Database\Schema\TableSchema
Returns the schema table object describing this table's properties.
setSchema(array|\Cake\Database\Schema\TableSchema $schema) : $this
Sets the schema table object describing this table's properties.
If an array is passed, a new TableSchema will be constructed out of it and used as the schema for this table.
| array|\Cake\Database\Schema\TableSchema | $schema | Schema to be used for this table |
schema(array|\Cake\Database\Schema\TableSchema|null $schema = null) : \Cake\Database\Schema\TableSchema
Returns the schema table object describing this table's properties.
If a TableSchema is passed, it will be used for this table instead of the default one.
If an array is passed, a new TableSchema will be constructed out of it and used as the schema for this table.
| array|\Cake\Database\Schema\TableSchema|null | $schema | New schema to be used for this table |
hasField(string $field) : boolean
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. |
True if the field exists, false if it does not.
addBehavior(string $name, array $options = array()) : $this
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 | The options for the behavior to use. |
If a behavior is being reloaded.
addBehaviors(array $behaviors) : $this
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. |
If a behavior is being reloaded.
behaviors() : \Cake\ORM\BehaviorRegistry
Returns the behavior registry for this table.
The BehaviorRegistry instance.
getBehavior(string $name) : \Cake\ORM\Behavior
Get a behavior from the registry.
| string | $name | The behavior alias to get from the registry. |
If the behavior does not exist.
association(string $name) : \Cake\ORM\Association|null
Returns an association object configured for the specified alias if any.
| string | $name | the alias used for the association. |
Either the association or null.
getAssociation(string $name) : \Cake\ORM\Association
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. |
The association.
hasAssociation(string $name) : boolean
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. |
associations() : \Cake\ORM\AssociationCollection|array<mixed,\Cake\ORM\Association>
Get the associations collection for this table.
The collection of association objects.
addAssociations(array $params) : $this
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) |
belongsTo(string $associated, array $options = array()) : \Cake\ORM\Association\BelongsTo
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 | list of options to configure the association definition |
hasOne(string $associated, array $options = array()) : \Cake\ORM\Association\HasOne
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 | list of options to configure the association definition |
hasMany(string $associated, array $options = array()) : \Cake\ORM\Association\HasMany
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 | list of options to configure the association definition |
belongsToMany(string $associated, array $options = array()) : \Cake\ORM\Association\BelongsToMany
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 | list of options to configure the association definition |
find(string $type = 'all', array|\ArrayAccess $options = array()) : \Cake\ORM\Query
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 | the type of query to perform |
| array|\ArrayAccess | $options | An array that will be passed to Query::applyOptions() |
The query builder
findAll(\Cake\ORM\Query $query, array $options) : \Cake\ORM\Query
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 |
The query builder
findList(\Cake\ORM\Query $query, array $options) : \Cake\ORM\Query
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 |
The query builder
findThreaded(\Cake\ORM\Query $query, array $options) : \Cake\ORM\Query
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 |
The query builder
get(mixed $primaryKey, array|\ArrayAccess $options = array()) : \Cake\Datasource\EntityInterface
Returns a single record after finding it by its primary key, if no record is found this method throws an exception.
Get an article and some relationships:
$article = $articles->get(1, ['contain' => ['Users', 'Comments']]);| mixed | $primaryKey | primary key value to find |
| array|\ArrayAccess | $options | options accepted by |
When $primaryKey has an incorrect number of elements.
findOrCreate(array|\Cake\ORM\Query $search, callable|null $callback = null, array $options = array()) : \Cake\Datasource\EntityInterface
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|\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 | A callback that will be invoked for newly created entities. This callback will be called before the entity is persisted. |
| array | $options | The options to use when saving. |
An entity.
query() : \Cake\ORM\Query
Creates a new Query instance for a table.
updateAll(string|array|callable|\Cake\Database\Expression\QueryExpression $fields, mixed $conditions) : integer
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|callable|\Cake\Database\Expression\QueryExpression | $fields | A hash of field => new value. |
| mixed | $conditions | Conditions to be used, accepts anything Query::where() can take. |
Count Returns the affected rows.
deleteAll(mixed $conditions) : integer
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. |
Returns the number of affected rows.
save(\Cake\Datasource\EntityInterface $entity, array $options = array()) : \Cake\Datasource\EntityInterface|false
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.
The options array accepts the following keys:
true it will save 1st level associated entities as they are found
in the passed $entity whenever the property defined for the association
is marked as dirty. If an array, it will be interpreted as the list of associations
to be saved. It is possible to provide different options for saving on associated
table objects using this key by making the custom options the array value.
If false no associated records will be saved. (default: true)When saving, this method will trigger four events:
checkRules key in $options is not set to false.
Listeners will receive as arguments the entity, options array and the operation type.
If the event is stopped the rules check result will be set to the result of the event itself.checkRules() method is
called for the entity. Listeners will receive as arguments the entity,
options array, the result of checking the rules and the operation type.
If the event is stopped the checking result will be set to the result of
the event itself.result property will be returned.
This can be useful when having your own saving strategy implemented inside a
listener.isNew, true meaning an insert and false an update.This method will determine whether the passed entity needs to be
inserted or updated in the database. It does that by checking the isNew
method on the entity. If the entity to be saved returns a non-empty value from
its errors() method, it will not be saved.
This method will by default persist entities belonging to associated tables, whenever a dirty property matching the name of the property name set for an association in this table. It is possible to control what associations will be saved and to pass additional option for saving them.
// Only save the comments association
$articles->save($entity, ['associated' => ['Comments']]);
// Save the company, the employees and related addresses for each of them.
// For employees do not check the entity rules
$companies->save($entity, [
'associated' => [
'Employees' => [
'associated' => ['Addresses'],
'checkRules' => false
]
]
]);
// Save no associations
$articles->save($entity, ['associated' => false]);| \Cake\Datasource\EntityInterface | $entity | the entity to be saved |
| array | $options | The options to use when saving. |
If the transaction is aborted in the afterSave event.
saveOrFail(\Cake\Datasource\EntityInterface $entity, array|\ArrayAccess $options = array()) : \Cake\Datasource\EntityInterface
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 | The options to use when saving. |
When the entity couldn't be saved
saveMany(array<mixed,\Cake\Datasource\EntityInterface>|\Cake\ORM\ResultSet $entities, array|\ArrayAccess $options = array()) : boolean|array<mixed,\Cake\Datasource\EntityInterface>|\Cake\ORM\ResultSet
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.
| array<mixed,\Cake\Datasource\EntityInterface>|\Cake\ORM\ResultSet | $entities | Entities to save. |
| array|\ArrayAccess | $options | Options used when calling Table::save() for each entity. |
False on failure, entities list on success.
delete(\Cake\Datasource\EntityInterface $entity, array|\ArrayAccess $options = array()) : boolean
Delete a single entity.
For HasMany and HasOne associations records will be removed based on
the dependent option. Join table records in BelongsToMany associations
will always be removed. You can use the cascadeCallbacks option
when defining associations to change how associated data is deleted.
atomic Defaults to true. When true the deletion happens within a transaction.checkRules Defaults to true. Check deletion rules before deleting the record.Model.beforeDelete Fired before the delete occurs. If stopped the delete
will be aborted. Receives the event, entity, and options.Model.afterDelete Fired after the delete has been successful. Receives
the event, entity, and options.Model.afterDeleteCommit Fired after the transaction is committed for
an atomic delete. Receives the event, entity, and options.The options argument will be converted into an \ArrayObject instance for the duration of the callbacks, this allows listeners to modify the options used in the delete operation.
| \Cake\Datasource\EntityInterface | $entity | The entity to remove. |
| array|\ArrayAccess | $options | The options for the delete. |
success
deleteOrFail(\Cake\Datasource\EntityInterface $entity, array|\ArrayAccess $options = array()) : boolean
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 | The options for the delete. |
success
callFinder(string $type, \Cake\ORM\Query $query, array $options = array()) : \Cake\ORM\Query
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 | List of options to pass to the finder |
__call(string $method, array $args) : mixed
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 |
__get(string $property) : \Cake\ORM\Association
Returns the association named after the passed value if exists, otherwise throws an exception.
| string | $property | the association name |
if no association with such name exists
marshaller() : \Cake\ORM\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.
newEntity(array|null $data = null, array $options = array()) : \Cake\Datasource\EntityInterface
Create a new entity + associated entities from an array.
By default all the associations on this table will be hydrated. You can limit which associations are built, or include deeper associations using the options parameter:
$article = $this->Articles->newEntity(
$this->request->getData(),
['associated' => ['Tags', 'Comments.Users']]
);You can limit fields that will be present in the constructed entity by
passing the fields option, which is also accepted for associations:
$article = $this->Articles->newEntity($this->request->getData(), [
'fields' => ['title', 'body', 'tags', 'comments'],
'associated' => ['Tags', 'Comments.Users' => ['fields' => 'username']]
]
);The fields option lets remove or restrict input data from ending up in
the entity. If you'd like to relax the entity's default accessible fields,
you can use the accessibleFields option:
$article = $this->Articles->newEntity(
$this->request->getData(),
['accessibleFields' => ['protected_field' => true]]
);By default, the data is validated before being passed to the new entity. In
the case of invalid fields, those will not be present in the resulting object.
The validate option can be used to disable validation on the passed data:
$article = $this->Articles->newEntity(
$this->request->getData(),
['validate' => false]
);You can also pass the name of the validator to use in the validate option.
If null is passed to the first param of this function, no validation will
be performed.
You can use the Model.beforeMarshal event to modify request data
before it is converted into entities.
| array|null | $data | The data to build an entity with. |
| array | $options | A list of options for the object hydration. |
newEntities(array $data, array $options = array()) : array<mixed,\Cake\Datasource\EntityInterface>
Create a list of entities + associated entities from an array.
By default all the associations on this table will be hydrated. You can limit which associations are built, or include deeper associations using the options parameter:
$articles = $this->Articles->newEntities(
$this->request->getData(),
['associated' => ['Tags', 'Comments.Users']]
);You can limit fields that will be present in the constructed entities by
passing the fields option, which is also accepted for associations:
$articles = $this->Articles->newEntities($this->request->getData(), [
'fields' => ['title', 'body', 'tags', 'comments'],
'associated' => ['Tags', 'Comments.Users' => ['fields' => 'username']]
]
);You can use the Model.beforeMarshal event to modify request data
before it is converted into entities.
| array | $data | The data to build an entity with. |
| array | $options | A list of options for the objects hydration. |
An array of hydrated records.
patchEntity(\Cake\Datasource\EntityInterface $entity, array $data, array $options = array()) : \Cake\Datasource\EntityInterface
Merges the passed `$data` into `$entity` respecting the accessible fields configured on the entity. Returns the same entity after being altered.
When merging HasMany or BelongsToMany associations, all the entities in the
$data array will appear, those that can be matched by primary key will get
the data merged, but those that cannot, will be discarded.
You can limit fields that will be present in the merged entity by
passing the fields option, which is also accepted for associations:
$article = $this->Articles->patchEntity($article, $this->request->getData(), [
'fields' => ['title', 'body', 'tags', 'comments'],
'associated' => ['Tags', 'Comments.Users' => ['fields' => 'username']]
]
);By default, the data is validated before being passed to the entity. In
the case of invalid fields, those will not be assigned to the entity.
The validate option can be used to disable validation on the passed data:
$article = $this->patchEntity($article, $this->request->getData(),[
'validate' => false
]);You can use the Model.beforeMarshal event to modify request data
before it is converted into entities.
When patching scalar values (null/booleans/string/integer/float), if the property presently has an identical value, the setter will not be called, and the property will not be marked as dirty. This is an optimization to prevent unnecessary field updates when persisting entities.
| \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 | A list of options for the object hydration. |
patchEntities(array<mixed,\Cake\Datasource\EntityInterface>|\Traversable $entities, array $data, array $options = array()) : array<mixed,\Cake\Datasource\EntityInterface>
Merges each of the elements passed in `$data` into the entities found in `$entities` respecting the accessible fields configured on the entities.
Those entries in $entities that cannot be matched to any record in
$data will be discarded. Records in $data that could not be matched will
be marshalled as a new entity.
When merging HasMany or BelongsToMany associations, all the entities in the
$data array will appear, those that can be matched by primary key will get
the data merged, but those that cannot, will be discarded.
You can limit fields that will be present in the merged entities by
passing the fields option, which is also accepted for associations:
$articles = $this->Articles->patchEntities($articles, $this->request->getData(), [
'fields' => ['title', 'body', 'tags', 'comments'],
'associated' => ['Tags', 'Comments.Users' => ['fields' => 'username']]
]
);You can use the Model.beforeMarshal event to modify request data
before it is converted into entities.
| array<mixed,\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 | A list of options for the objects hydration. |
validateUnique(mixed $value, array $options, array|null $context = null) : boolean
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 | Either the validation context or null. |
True if the value is unique, or false if a non-scalar, non-unique value was given.
implementedEvents() : array
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:
getSaveOptionsBuilder(array $options = array()) : \Cake\ORM\SaveOptionsBuilder
Gets a SaveOptionsBuilder instance.
| array | $options | Options to parse by the builder. |
loadInto(\Cake\Datasource\EntityInterface|array $entities, array $contain) : \Cake\Datasource\EntityInterface|array
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|array | $entities | a single entity or list of entities |
| array | $contain | A |
createValidator(string $name) : \Cake\Validation\Validator
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. |
_initializeSchema(\Cake\Database\Schema\TableSchema $schema) : \Cake\Database\Schema\TableSchema
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\TableSchema $schema) {
$schema->setColumnType('preferences', 'json');
return $schema;
}| \Cake\Database\Schema\TableSchema | $schema | The table definition fetched from database. |
the altered schema
findAssociation(string $name) : \Cake\ORM\Association|null
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. |
Either the association or null.
_setFieldMatchers(array $options, array $keys) : array
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 |
| array | $keys | the keys to check in $options to build matchers from the associated value |
_executeTransaction(callable $worker, boolean $atomic = true) : mixed
Handles the logic executing of a worker inside a transaction.
| callable | $worker | The worker that will run inside the transaction. |
| boolean | $atomic | Whether to execute the worker inside a database transaction. |
_transactionCommitted(boolean $atomic, boolean $primary) : boolean
Checks if the caller would have executed a commit on a transaction.
| boolean | $atomic | True if an atomic transaction was used. |
| boolean | $primary | True if a primary was used. |
Returns true if a transaction was committed.
_processFindOrCreate(array|callable $search, callable|null $callback = null, array $options = array()) : \Cake\Datasource\EntityInterface
Performs the actual find and/or create of an entity based on the passed options.
| array|callable | $search | The criteria to find an existing record by, or a callable tha will customize the find query. |
| callable|null | $callback | A callback that will be invoked for newly created entities. This callback will be called before the entity is persisted. |
| array | $options | The options to use when saving. |
An entity.
_getFindOrCreateQuery(array|\Cake\ORM\Query|string $search) : \Cake\ORM\Query
Gets the query object for findOrCreate().
| array|\Cake\ORM\Query|string | $search | The criteria to find existing records by. |
_processSave(\Cake\Datasource\EntityInterface $entity, \ArrayObject $options) : \Cake\Datasource\EntityInterface|boolean
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 |
When an entity is missing some of the primary keys.
If the transaction is aborted in the afterSave event.
_onSaveSuccess(\Cake\Datasource\EntityInterface $entity, \ArrayObject $options) : boolean
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 |
If the transaction is aborted in the afterSave event.
True on success
_insert(\Cake\Datasource\EntityInterface $entity, array $data) : \Cake\Datasource\EntityInterface|boolean
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 |
if not all the primary keys where supplied or could be generated when the table has composite primary keys. Or when the table has no primary key.
_newId(array $primary) : null|string|array
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.
| array | $primary | The primary key columns to get a new ID for. |
Either null or the primary key value or a list of primary key values.
_update(\Cake\Datasource\EntityInterface $entity, array $data) : \Cake\Datasource\EntityInterface|boolean
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 |
When primary key data is missing.
_processDelete(\Cake\Datasource\EntityInterface $entity, \ArrayObject $options) : boolean
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. |
if there are no primary key values of the passed entity
success
_dynamicFinder(string $method, array $args) : mixed
Provides the dynamic findBy and findByAll methods.
| string | $method | The method name that was fired. |
| array | $args | List of arguments passed to the function. |
when there are missing arguments, or when and & or are combined.