W3cubDocs

/CakePHP 4.1

Class Table

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.

Retrieving data

The primary way to retrieve data is using Table::find(). See that method for more information.

Dynamic finders

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]');

Bulk updates/deletes

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.

Events

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.

Callbacks

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)
Namespace: Cake\ORM

Constants summary

  • string
    BUILD_VALIDATOR_EVENT
    'Model.buildValidator'
  • string
    DEFAULT_VALIDATOR
    'default'
  • string
    IS_UNIQUE_CLASS
    \Cake\ORM\Rule\IsUnique::class
  • string
    RULES_CLASS
    \Cake\ORM\RulesChecker::class
  • string
    VALIDATOR_PROVIDER_NAME
    'table'

Properties summary

  • $_alias protected
    string

    Human name giving to this particular instance. Multiple objects representing the same database table can exist by using different aliases.

  • $_associations protected
    \Cake\ORM\AssociationCollection

    The associations container for this Table.

  • $_behaviors protected
    \Cake\ORM\BehaviorRegistry

    BehaviorRegistry for this table

  • $_connection protected
    \Cake\Database\Connection|null

    Connection instance

  • $_displayField protected
    string|string[]

    The name of the field that represents a human readable representation of a row

  • $_entityClass protected
    string

    The name of the class that represent a single row for this table

  • $_eventClass protected
    string

    Default class name for new event objects.

  • $_eventManager protected
    \Cake\Event\EventManagerInterface

    Instance of the Cake\Event\EventManager this object is using to dispatch inner events.

  • $_primaryKey protected
    string|string[]

    The name of the field that represents the primary key in the table

  • $_registryAlias protected
    string|null

    Registry key used to create this table object

  • $_rulesChecker protected
    \Cake\Datasource\RulesChecker

    The domain rules to be applied to entities saved by this table

  • $_schema protected
    \Cake\Database\Schema\TableSchemaInterface|null

    The schema object containing a description of this table fields

  • $_table protected
    string

    Name of the table as it can be found in the database

  • $_validatorClass protected
    string

    Validator class.

  • $_validators protected
    \Cake\Validation\Validator[]

    A list of validation objects indexed by name

Method Summary

  • __call() public

    Handles behavior delegation + dynamic finders.

  • __construct() public

    Initializes a new instance

  • __debugInfo() public

    Returns an array that can be used to describe the internal state of this object.

  • __get() public

    Returns the association named after the passed value if exists, otherwise throws an exception.

  • __isset() public

    Returns whether an association named after the passed value exists for this table.

  • _deleteMany() protected
  • _dynamicFinder() protected

    Provides the dynamic findBy and findAllBy methods.

  • _executeTransaction() protected

    Handles the logic executing of a worker inside a transaction.

  • _getFindOrCreateQuery() protected

    Gets the query object for findOrCreate().

  • _initializeSchema() protected

    Override this function in order to alter the schema used by this table.

  • _insert() protected

    Auxiliary function to handle the insert of an entity's data in the table

  • _newId() protected

    Generate a primary key value for a new record.

  • _onSaveSuccess() protected

    Handles the saving of children associations and executing the afterSave logic once the entity for this table has been saved successfully.

  • _processDelete() protected

    Perform the delete operation.

  • _processFindOrCreate() protected

    Performs the actual find and/or create of an entity based on the passed options.

  • _processSave() protected

    Performs the actual saving of an entity based on the passed options.

  • _saveMany() protected
  • _setFieldMatchers() protected

    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.

  • _transactionCommitted() protected

    Checks if the caller would have executed a commit on a transaction.

  • _update() protected

    Auxiliary function to handle the update of an entity's data in the table

  • addAssociations() public

    Setup multiple associations.

  • addBehavior() public

    Add a behavior.

  • addBehaviors() public

    Adds an array of behaviors to the table's behavior collection.

  • aliasField() public

    Alias a field with the table's current alias.

  • associations() public

    Get the associations collection for this table.

  • behaviors() public

    Returns the behavior registry for this table.

  • belongsTo() public

    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.

  • belongsToMany() public

    Creates a new BelongsToMany association between this table and a target table. A "belongs to many" association is a M-N relationship.

  • buildRules() public

    Returns a RulesChecker object after modifying the one that was supplied.

  • callFinder() public

    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

  • checkAliasLengths() protected

    Checks if all table name + column name combinations used for queries fit into the max length allowed by database driver.

  • checkRules() public

    Returns whether or not the passed entity complies with all the rules stored in the rules checker.

  • createValidator() protected

    Creates a validator using a custom method inside your class.

  • defaultConnectionName() public static

    Get the default connection name.

  • delete() public

    Delete a single entity.

  • deleteAll() public

    Deletes all records matching the provided conditions.

  • deleteMany() public

    Deletes multiple entities of a table.

  • deleteManyOrFail() public

    Deletes multiple entities of a table.

  • deleteOrFail() public

    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.

  • dispatchEvent() public

    Wrapper for creating and dispatching events.

  • exists() public

    Returns true if there is any record in this repository matching the specified conditions.

  • find() public

    Creates a new Query for this repository and applies some defaults based on the type of search that was selected.

  • findAll() public

    Returns the query as passed.

  • findAssociation() protected

    Returns an association object configured for the specified alias if any.

  • findList() public

    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.

  • findOrCreate() public

    Finds an existing record or creates a new one.

  • findThreaded() public

    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.

  • get() public

    Returns a single record after finding it by its primary key, if no record is found this method throws an exception.

  • getAlias() public

    Returns the table alias.

  • getAssociation() public

    Returns an association object configured for the specified alias.

  • getBehavior() public

    Get a behavior from the registry.

  • getConnection() public

    Returns the connection instance.

  • getDisplayField() public

    Returns the display field.

  • getEntityClass() public

    Returns the class used to hydrate rows for this table.

  • getEventManager() public

    Returns the Cake\Event\EventManager manager instance for this object.

  • getPrimaryKey() public

    Returns the primary key field name.

  • getRegistryAlias() public

    Returns the table registry key used to create this table instance.

  • getSaveOptionsBuilder() public

    Gets a SaveOptionsBuilder instance.

  • getSchema() public

    Returns the schema table object describing this table's properties.

  • getTable() public

    Returns the database table name.

  • getValidator() public

    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.

  • hasAssociation() public

    Checks whether a specific association exists on this Table instance.

  • hasBehavior() public

    Check if a behavior with the given alias has been loaded.

  • hasField() public

    Test to see if a Table has a specific field/column.

  • hasFinder() public

    Returns true if the finder exists for the table

  • hasMany() public

    Creates a new HasMany association between this table and a target table. A "has many" association is a 1-N relationship.

  • hasOne() public

    Creates a new HasOne association between this table and a target table. A "has one" association is a 1-1 relationship.

  • hasValidator() public

    Checks whether or not a validator has been set.

  • implementedEvents() public

    Get the Model callbacks this table is interested in.

  • initialize() public

    Initialize a table instance. Called after the constructor.

  • loadInto() public

    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.

  • marshaller() public

    Get the object used to marshal/convert array data into objects.

  • newEmptyEntity() public

    This creates a new entity object.

  • newEntities() public

    Create a list of entities + associated entities from an array.

  • newEntity() public

    Create a new entity + associated entities from an array.

  • patchEntities() public

    Merges each of the elements passed in $data into the entities found in $entities respecting the accessible fields configured on the entities.

  • patchEntity() public

    Merges the passed $data into $entity respecting the accessible fields configured on the entity. Returns the same entity after being altered.

  • query() public

    Creates a new Query instance for a table.

  • removeBehavior() public

    Removes a behavior from this table's behavior registry.

  • rulesChecker() public

    Returns the RulesChecker for this instance.

  • save() public

    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.

  • saveMany() public

    Persists multiple entities of a table.

  • saveManyOrFail() public

    Persists multiple entities of a table.

  • saveOrFail() public

    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.

  • setAlias() public

    Sets the table alias.

  • setConnection() public

    Sets the connection instance.

  • setDisplayField() public

    Sets the display field.

  • setEntityClass() public

    Sets the class used to hydrate rows for this table.

  • setEventManager() public

    Returns the Cake\Event\EventManagerInterface instance for this object.

  • setPrimaryKey() public

    Sets the primary key field name.

  • setRegistryAlias() public

    Sets the table registry key used to create this table instance.

  • setSchema() public

    Sets the schema table object describing this table's properties.

  • setTable() public

    Sets the database table name.

  • setValidator() public

    This method stores a custom validator under the given name.

  • updateAll() public

    Update all matching records.

  • validateUnique() public

    Validator method used to check the uniqueness of a value for a column.

  • validationDefault() public

    Returns the default validator object. Subclasses can override this function to add a default validation set to the validator object.

  • validationMethodExists() protected

    Checks if validation method exists.

Method Detail

__call() public

__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.

Parameters

string $method

name of the method to be invoked

array $args

List of arguments passed to the function

Returns

mixed

Throws

BadMethodCallException

__construct() public

__construct(array $config)

Initializes a new instance

The $config array understands the following keys:

  • table: Name of the database table to represent
  • alias: Alias to be assigned to this table (default to table name)
  • connection: The connection instance to use
  • entityClass: The fully namespaced class name of the entity class that will represent rows in this table.
  • schema: A \Cake\Database\Schema\TableSchemaInterface object or an array that can be passed to it.
  • eventManager: An instance of an event manager to use for internal events
  • behaviors: A BehaviorRegistry. Generally not used outside of tests.
  • associations: An AssociationCollection instance.
  • validator: A Validator instance which is assigned as the "default" validation set, or an associative array, where key is the name of the validation set and value the Validator instance.

Parameters

array $config optional

List of options for this table

__debugInfo() public

__debugInfo()

Returns an array that can be used to describe the internal state of this object.

Returns

array

__get() public

__get(mixed $property)

Returns the association named after the passed value if exists, otherwise throws an exception.

Parameters

string $property

the association name

Returns

\Cake\ORM\Association

Throws

RuntimeException
if no association with such name exists

__isset() public

__isset(mixed $property)

Returns whether an association named after the passed value exists for this table.

Parameters

string $property

the association name

Returns

bool

_deleteMany() protected

_deleteMany(iterable $entities, mixed $options)

Parameters

\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface $entities

Entities to delete.

array|\ArrayAccess $options optional

Options used.

Returns

\Cake\Datasource\EntityInterface|null

_dynamicFinder() protected

_dynamicFinder(string $method, array $args)

Provides the dynamic findBy and findAllBy methods.

Parameters

string $method

The method name that was fired.

array $args

List of arguments passed to the function.

Returns

\Cake\ORM\Query

Throws

BadMethodCallException
when there are missing arguments, or when and & or are combined.

_executeTransaction() protected

_executeTransaction(callable $worker, bool $atomic)

Handles the logic executing of a worker inside a transaction.

Parameters

callable $worker

The worker that will run inside the transaction.

bool $atomic optional

Whether to execute the worker inside a database transaction.

Returns

mixed

_getFindOrCreateQuery() protected

_getFindOrCreateQuery(mixed $search)

Gets the query object for findOrCreate().

Parameters

array|callable|\Cake\ORM\Query $search

The criteria to find existing records by.

Returns

\Cake\ORM\Query

_initializeSchema() protected

_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.

Example:

protected function _initializeSchema(\Cake\Database\Schema\TableSchemaInterface $schema) {
 $schema->setColumnType('preferences', 'json');
 return $schema;
}

Parameters

\Cake\Database\Schema\TableSchemaInterface $schema

The table definition fetched from database.

Returns

\Cake\Database\Schema\TableSchemaInterface

the altered schema

_insert() protected

_insert(\Cake\Datasource\EntityInterface $entity, array $data)

Auxiliary function to handle the insert of an entity's data in the table

Parameters

\Cake\Datasource\EntityInterface $entity

the subject entity from were $data was extracted

array $data

The actual data that needs to be saved

Returns

\Cake\Datasource\EntityInterface|false

Throws

RuntimeException
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() protected

_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.

Parameters

string[] $primary

The primary key columns to get a new ID for.

Returns

string|null

Either null or the primary key value or a list of primary key values.

_onSaveSuccess() protected

_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.

Parameters

\Cake\Datasource\EntityInterface $entity

the entity to be saved

\ArrayObject $options

the options to use for the save operation

Returns

bool

True on success

Throws

Cake\ORM\Exception\RolledbackTransactionException
If the transaction is aborted in the afterSave event.

_processDelete() protected

_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.

Parameters

\Cake\Datasource\EntityInterface $entity

The entity to delete.

\ArrayObject $options

The options for the delete.

Returns

bool

success

Throws

InvalidArgumentException
if there are no primary key values of the passed entity

_processFindOrCreate() protected

_processFindOrCreate(mixed $search, ?callable $callback, mixed $options)

Performs the actual find and/or create of an entity based on the passed options.

Parameters

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.

Returns

\Cake\Datasource\EntityInterface|array

An entity.

Throws

Cake\ORM\Exception\PersistenceFailedException
When the entity couldn't be saved
InvalidArgumentException

_processSave() protected

_processSave(\Cake\Datasource\EntityInterface $entity, \ArrayObject $options)

Performs the actual saving of an entity based on the passed options.

Parameters

\Cake\Datasource\EntityInterface $entity

the entity to be saved

\ArrayObject $options

the options to use for the save operation

Returns

\Cake\Datasource\EntityInterface|false

Throws

RuntimeException
When an entity is missing some of the primary keys.
Cake\ORM\Exception\RolledbackTransactionException
If the transaction is aborted in the afterSave event.

_saveMany() protected

_saveMany(iterable $entities, mixed $options)

Parameters

\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.

Returns

\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface

Entities list.

Throws

Cake\ORM\Exception\PersistenceFailedException
If an entity couldn't be saved.
Exception
If an entity couldn't be saved.

_setFieldMatchers() protected

_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.

Parameters

array $options

the original options passed to a finder

string[] $keys

the keys to check in $options to build matchers from the associated value

Returns

array

_transactionCommitted() protected

_transactionCommitted(bool $atomic, bool $primary)

Checks if the caller would have executed a commit on a transaction.

Parameters

bool $atomic

True if an atomic transaction was used.

bool $primary

True if a primary was used.

Returns

bool

Returns true if a transaction was committed.

_update() protected

_update(\Cake\Datasource\EntityInterface $entity, array $data)

Auxiliary function to handle the update of an entity's data in the table

Parameters

\Cake\Datasource\EntityInterface $entity

the subject entity from were $data was extracted

array $data

The actual data that needs to be saved

Returns

\Cake\Datasource\EntityInterface|false

Throws

InvalidArgumentException
When primary key data is missing.

addAssociations() public

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.

Parameters

array $params

Set of associations to bind (indexed by association type)

Returns

$this

See Also

\Cake\ORM\Table::belongsTo()

\Cake\ORM\Table::hasOne()

\Cake\ORM\Table::hasMany()

\Cake\ORM\Table::belongsToMany()

addBehavior() public

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().

Parameters

string $name

The name of the behavior. Can be a short class reference.

array $options optional

The options for the behavior to use.

Returns

$this

Throws

RuntimeException
If a behavior is being reloaded.

See Also

\Cake\ORM\Behavior

addBehaviors() public

addBehaviors(array $behaviors)

Adds an array of behaviors to the table's behavior collection.

Example:

$this->addBehaviors([
     'Timestamp',
     'Tree' => ['level' => 'level'],
]);

Parameters

array $behaviors

All of the behaviors to load.

Returns

$this

Throws

RuntimeException
If a behavior is being reloaded.

aliasField() public

aliasField(string $field)

Alias a field with the table's current alias.

If field is already aliased it will result in no-op.

Parameters

string $field

The field to alias.

Returns

string

The field prefixed with the table alias.

associations() public

associations()

Get the associations collection for this table.

Returns

\Cake\ORM\AssociationCollection

The collection of association objects.

behaviors() public

behaviors()

Returns the behavior registry for this table.

Returns

\Cake\ORM\BehaviorRegistry

The BehaviorRegistry instance.

belongsTo() public

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:

  • className: The class name of the target table object
  • targetTable: An instance of a table object to be used as the target table
  • foreignKey: The name of the field to use as foreign key, if false none will be used
  • conditions: array with a list of conditions to filter the join with
  • joinType: The type of join to be used (e.g. INNER)
  • strategy: The loading strategy to use. 'join' and 'select' are supported.
  • finder: The finder method to use when loading records from this association. Defaults to 'all'. When the strategy is 'join', only the fields, containments, and where conditions will be used from the finder.

This method will return the association object that was built.

Parameters

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

Returns

\Cake\ORM\Association\BelongsTo

belongsToMany() public

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:

  • className: The class name of the target table object.
  • targetTable: An instance of a table object to be used as the target table.
  • foreignKey: The name of the field to use as foreign key.
  • targetForeignKey: The name of the field to use as the target foreign key.
  • joinTable: The name of the table representing the link between the two
  • through: If you choose to use an already instantiated link table, set this key to a configured Table instance containing associations to both the source and target tables in this association.
  • dependent: Set to false, if you do not want junction table records removed when an owning record is removed.
  • cascadeCallbacks: Set to true if you want CakePHP to fire callbacks on cascaded deletes. If false the ORM will use deleteAll() to remove data. When true join/junction table records will be loaded and then deleted.
  • conditions: array with a list of conditions to filter the join with.
  • sort: The order in which results for this association should be returned.
  • strategy: The strategy to be used for selecting results Either 'select' or 'subquery'. If subquery is selected the query used to return results in the source table will be used as conditions for getting rows in the target table.
  • saveStrategy: Either 'append' or 'replace'. Indicates the mode to be used for saving associated entities. The former will only create new links between both side of the relation and the latter will do a wipe and replace to create the links between the passed entities when saving.
  • strategy: The loading strategy to use. 'select' and 'subquery' are supported.
  • finder: The finder method to use when loading records from this association. Defaults to 'all'.

This method will return the association object that was built.

Parameters

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

Returns

\Cake\ORM\Association\BelongsToMany

buildRules() public

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.

Parameters

\Cake\ORM\RulesChecker $rules

The rules object to be modified.

Returns

\Cake\ORM\RulesChecker

callFinder() public

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

Parameters

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

Returns

\Cake\ORM\Query

Throws

BadMethodCallException

checkAliasLengths() protected

checkAliasLengths()

Checks if all table name + column name combinations used for queries fit into the max length allowed by database driver.

Throws

RuntimeException
When an alias combination is too long

checkRules() public

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.

Parameters

\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.

Returns

bool

createValidator() protected

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.

Parameters

string $name

The name of the validation set to create.

Returns

\Cake\Validation\Validator

Throws

RuntimeException

defaultConnectionName() public static

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.

Returns

string

See Also

\Cake\ORM\Locator\TableLocator::get()

delete() public

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.

Parameters

\Cake\Datasource\EntityInterface $entity

The entity to remove.

array|\ArrayAccess $options optional

The options for the delete.

Returns

bool

success

deleteAll() public

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.

Parameters

mixed $conditions

Conditions to be used, accepts anything Query::where() can take.

Returns

int

Returns the number of affected rows.

See Also

\Cake\Datasource\RepositoryInterface::delete()

deleteMany() public

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.

Parameters

\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface $entities

Entities to delete.

array|\ArrayAccess $options optional

Options used when calling Table::save() for each entity.

Returns

\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface|false

Entities list on success, false on failure.

See Also

\Cake\ORM\Table::delete()
for options and events related to this method.

deleteManyOrFail() public

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.

Parameters

\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface $entities

Entities to delete.

array|\ArrayAccess $options optional

Options used when calling Table::save() for each entity.

Returns

\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface

Entities list.

Throws

Cake\ORM\Exception\PersistenceFailedException

See Also

\Cake\ORM\Table::delete()
for options and events related to this method.

deleteOrFail() public

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.

Parameters

\Cake\Datasource\EntityInterface $entity

The entity to remove.

array|\ArrayAccess $options optional

The options for the delete.

Returns

true

Throws

Cake\ORM\Exception\PersistenceFailedException

See Also

\Cake\ORM\Table::delete()

dispatchEvent() public

dispatchEvent(string $name, ?array $data, ?object $subject)

Wrapper for creating and dispatching events.

Returns a dispatched event.

Parameters

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).

Returns

\Cake\Event\EventInterface

exists() public

exists(mixed $conditions)

Returns true if there is any record in this repository matching the specified conditions.

Parameters

array $conditions

list of conditions to pass to the query

Returns

bool

find() public

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.

Model.beforeFind event

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:

  • fields
  • conditions
  • order
  • limit
  • offset
  • page
  • group
  • having
  • contain
  • join

Usage

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']);

Calling finders

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.

Parameters

string $type optional

the type of query to perform

array $options optional

An array that will be passed to Query::applyOptions()

Returns

\Cake\ORM\Query

The query builder

findAll() public

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.

Parameters

\Cake\ORM\Query $query

The query to find with

array $options

The options to use for the find

Returns

\Cake\ORM\Query

The query builder

findAssociation() protected

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');

Parameters

string $name

The alias used for the association.

Returns

\Cake\ORM\Association|null

Either the association or null.

findList() public

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'
 ]
]

Parameters

\Cake\ORM\Query $query

The query to find with

array $options

The options for the find

Returns

\Cake\ORM\Query

The query builder

findOrCreate() public

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.

Options

The options array is passed to the save method with exception to the following keys:

  • atomic: Whether to execute the methods for find, save and callbacks inside a database transaction (default: true)
  • defaults: Whether to use the search criteria as default values for the new entity (default: true)

Parameters

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.

Returns

\Cake\Datasource\EntityInterface

An entity.

Throws

Cake\ORM\Exception\PersistenceFailedException
When the entity couldn't be saved

findThreaded() public

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'
]);

Parameters

\Cake\ORM\Query $query

The query to find with

array $options

The options to find with

Returns

\Cake\ORM\Query

The query builder

get() public

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.

Example:

$id = 10;
$article = $articles->get($id);

$article = $articles->get($id, ['contain' => ['Comments]]);

Parameters

mixed $primaryKey

primary key value to find

array $options optional

options accepted by Table::find()

Returns

\Cake\Datasource\EntityInterface

Throws

Cake\Datasource\Exception\RecordNotFoundException
if the record with such id could not be found
Cake\Datasource\Exception\InvalidPrimaryKeyException
When $primaryKey has an incorrect number of elements.
Cake\Datasource\Exception\RecordNotFoundException
if the record with such id could not be found

See Also

\Cake\Datasource\RepositoryInterface::find()

\Cake\Datasource\RepositoryInterface::find()

getAlias() public

getAlias()

Returns the table alias.

Returns

string

getAssociation() public

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.

Parameters

string $name

The alias used for the association.

Returns

\Cake\ORM\Association

The association.

Throws

InvalidArgumentException

getBehavior() public

getBehavior(string $name)

Get a behavior from the registry.

Parameters

string $name

The behavior alias to get from the registry.

Returns

\Cake\ORM\Behavior

Throws

InvalidArgumentException
If the behavior does not exist.

getConnection() public

getConnection()

Returns the connection instance.

Returns

\Cake\Database\Connection

getDisplayField() public

getDisplayField()

Returns the display field.

Returns

string|string[]|null

getEntityClass() public

getEntityClass()

Returns the class used to hydrate rows for this table.

Returns

string

getEventManager() public

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.

Returns

\Cake\Event\EventManagerInterface

getPrimaryKey() public

getPrimaryKey()

Returns the primary key field name.

Returns

string|string[]

getRegistryAlias() public

getRegistryAlias()

Returns the table registry key used to create this table instance.

Returns

string

getSaveOptionsBuilder() public

getSaveOptionsBuilder(array $options)

Gets a SaveOptionsBuilder instance.

Parameters

array $options optional

Options to parse by the builder.

Returns

\Cake\ORM\SaveOptionsBuilder

getSchema() public

getSchema()

Returns the schema table object describing this table's properties.

Returns

\Cake\Database\Schema\TableSchemaInterface

getTable() public

getTable()

Returns the database table name.

This can include the database schema name if set using setTable().

Returns

string

getValidator() public

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.

Parameters

string|null $name optional

The name of the validation set to return.

Returns

\Cake\Validation\Validator

hasAssociation() public

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');

Parameters

string $name

The alias used for the association.

Returns

bool

hasBehavior() public

hasBehavior(string $name)

Check if a behavior with the given alias has been loaded.

Parameters

string $name

The behavior alias to check.

Returns

bool

Whether or not the behavior exists.

hasField() public

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.

Parameters

string $field

The field to check for.

Returns

bool

True if the field exists, false if it does not.

hasFinder() public

hasFinder(string $type)

Returns true if the finder exists for the table

Parameters

string $type

name of finder to check

Returns

bool

hasMany() public

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:

  • className: The class name of the target table object
  • targetTable: An instance of a table object to be used as the target table
  • foreignKey: The name of the field to use as foreign key, if false none will be used
  • dependent: Set to true if you want CakePHP to cascade deletes to the associated table when an entity is removed on this table. The delete operation on the associated table will not cascade further. To get recursive cascades enable cascadeCallbacks as well. Set to false if you don't want CakePHP to remove associated data, or when you are using database constraints.
  • cascadeCallbacks: Set to true if you want CakePHP to fire callbacks on cascaded deletes. If false the ORM will use deleteAll() to remove data. When true records will be loaded and then deleted.
  • conditions: array with a list of conditions to filter the join with
  • sort: The order in which results for this association should be returned
  • saveStrategy: Either 'append' or 'replace'. When 'append' the current records are appended to any records in the database. When 'replace' associated records not in the current set will be removed. If the foreign key is a null able column or if dependent is true records will be orphaned.
  • strategy: The strategy to be used for selecting results Either 'select' or 'subquery'. If subquery is selected the query used to return results in the source table will be used as conditions for getting rows in the target table.
  • finder: The finder method to use when loading records from this association. Defaults to 'all'.

This method will return the association object that was built.

Parameters

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

Returns

\Cake\ORM\Association\HasMany

hasOne() public

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:

  • className: The class name of the target table object
  • targetTable: An instance of a table object to be used as the target table
  • foreignKey: The name of the field to use as foreign key, if false none will be used
  • dependent: Set to true if you want CakePHP to cascade deletes to the associated table when an entity is removed on this table. The delete operation on the associated table will not cascade further. To get recursive cascades enable cascadeCallbacks as well. Set to false if you don't want CakePHP to remove associated data, or when you are using database constraints.
  • cascadeCallbacks: Set to true if you want CakePHP to fire callbacks on cascaded deletes. If false the ORM will use deleteAll() to remove data. When true records will be loaded and then deleted.
  • conditions: array with a list of conditions to filter the join with
  • joinType: The type of join to be used (e.g. LEFT)
  • strategy: The loading strategy to use. 'join' and 'select' are supported.
  • finder: The finder method to use when loading records from this association. Defaults to 'all'. When the strategy is 'join', only the fields, containments, and where conditions will be used from the finder.

This method will return the association object that was built.

Parameters

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

Returns

\Cake\ORM\Association\HasOne

hasValidator() public

hasValidator(string $name)

Checks whether or not a validator has been set.

Parameters

string $name

The name of a validator.

Returns

bool

implementedEvents() public

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:

  • Model.beforeMarshal => beforeMarshal
  • Model.afterMarshal => afterMarshal
  • Model.buildValidator => buildValidator
  • Model.beforeFind => beforeFind
  • Model.beforeSave => beforeSave
  • Model.afterSave => afterSave
  • Model.afterSaveCommit => afterSaveCommit
  • Model.beforeDelete => beforeDelete
  • Model.afterDelete => afterDelete
  • Model.afterDeleteCommit => afterDeleteCommit
  • Model.beforeRules => beforeRules
  • Model.afterRules => afterRules

Returns

array

initialize() public

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');
 }

Parameters

array $config

Configuration options passed to the constructor

loadInto() public

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.

Example:

$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

Example:

$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.

Parameters

\Cake\Datasource\EntityInterface|\Cake\Datasource\EntityInterface[] $entities

a single entity or list of entities

array $contain

A contain() compatible array.

Returns

\Cake\Datasource\EntityInterface|\Cake\Datasource\EntityInterface[]

See Also

\Cake\ORM\Query::contain()

marshaller() public

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.

Returns

\Cake\ORM\Marshaller

See Also

\Cake\ORM\Marshaller

newEmptyEntity() public

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.

Returns

\Cake\Datasource\EntityInterface

newEntities() public

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.

Parameters

array $data

The data to build an entity with.

array $options optional

A list of options for the objects hydration.

Returns

\Cake\Datasource\EntityInterface[]

An array of hydrated records.

newEntity() public

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.

Parameters

array $data

The data to build an entity with.

array $options optional

A list of options for the object hydration.

Returns

\Cake\Datasource\EntityInterface

patchEntities() public

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());

Parameters

\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.

Returns

\Cake\Datasource\EntityInterface[]

patchEntity() public

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());

Parameters

\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.

Returns

\Cake\Datasource\EntityInterface

query() public

query()

Creates a new Query instance for a table.

Returns

\Cake\ORM\Query

removeBehavior() public

removeBehavior(string $name)

Removes a behavior from this table's behavior registry.

Example:

Remove a behavior from this table.

$this->removeBehavior('Tree');

Parameters

string $name

The alias that the behavior was added with.

Returns

$this

See Also

\Cake\ORM\Behavior

rulesChecker() public

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.

Returns

\Cake\Datasource\RulesChecker

See Also

\Cake\Datasource\RulesChecker

save() public

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.

Parameters

\Cake\Datasource\EntityInterface $entity

the entity to be saved

array|\ArrayAccess|\Cake\ORM\SaveOptionsBuilder $options optional

The options to use when saving.

Returns

\Cake\Datasource\EntityInterface|false

Throws

Cake\ORM\Exception\RolledbackTransactionException
If the transaction is aborted in the afterSave event.

saveMany() public

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.

Parameters

\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.

Returns

\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface|false

False on failure, entities list on success.

Throws

Exception

saveManyOrFail() public

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.

Parameters

\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface $entities

Entities to save.

array|\ArrayAccess $options optional

Options used when calling Table::save() for each entity.

Returns

\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface

Entities list.

Throws

Exception

Cake\ORM\Exception\PersistenceFailedException
If an entity couldn't be saved.

saveOrFail() public

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.

Parameters

\Cake\Datasource\EntityInterface $entity

the entity to be saved

array|\ArrayAccess $options optional

The options to use when saving.

Returns

\Cake\Datasource\EntityInterface

Throws

Cake\ORM\Exception\PersistenceFailedException
When the entity couldn't be saved

See Also

\Cake\ORM\Table::save()

setAlias() public

setAlias(string $alias)

Sets the table alias.

Parameters

string $alias

Table alias

Returns

$this

setConnection() public

setConnection(\Cake\Database\Connection $connection)

Sets the connection instance.

Parameters

\Cake\Database\Connection $connection

The connection instance

Returns

$this

setDisplayField() public

setDisplayField(mixed $field)

Sets the display field.

Parameters

string|string[] $field

Name to be used as display field.

Returns

$this

setEntityClass() public

setEntityClass(string $name)

Sets the class used to hydrate rows for this table.

Parameters

string $name

The name of the class to use

Returns

$this

Throws

Cake\ORM\Exception\MissingEntityException
when the entity class cannot be found

setEventManager() public

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.

Parameters

\Cake\Event\EventManagerInterface $eventManager

the eventManager to set

Returns

$this

setPrimaryKey() public

setPrimaryKey(mixed $key)

Sets the primary key field name.

Parameters

string|string[] $key

Sets a new name to be used as primary key

Returns

$this

setRegistryAlias() public

setRegistryAlias(string $registryAlias)

Sets the table registry key used to create this table instance.

Parameters

string $registryAlias

The key used to access this object.

Returns

$this

setSchema() public

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.

Parameters

array|\Cake\Database\Schema\TableSchemaInterface $schema

Schema to be used for this table

Returns

$this

setTable() public

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.

Parameters

string $table

Table name.

Returns

$this

setValidator() public

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);

Parameters

string $name

The name of a validator to be set.

\Cake\Validation\Validator $validator

Validator object to be set.

Returns

$this

updateAll() public

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.

Parameters

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.

Returns

int

Count Returns the affected rows.

validateUnique() public

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.

Example:

$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.

Parameters

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.

Returns

bool

True if the value is unique, or false if a non-scalar, non-unique value was given.

validationDefault() public

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.

Parameters

\Cake\Validation\Validator $validator

The validator that can be modified to add some rules to it.

Returns

\Cake\Validation\Validator

validationMethodExists() protected

validationMethodExists(string $name)

Checks if validation method exists.

Parameters

string $name

Validation method name.

Returns

bool

Property Detail

$_alias protected

Human name giving to this particular instance. Multiple objects representing the same database table can exist by using different aliases.

Type

string

$_associations protected

The associations container for this Table.

Type

\Cake\ORM\AssociationCollection

$_behaviors protected

BehaviorRegistry for this table

Type

\Cake\ORM\BehaviorRegistry

$_connection protected

Connection instance

Type

\Cake\Database\Connection|null

$_displayField protected

The name of the field that represents a human readable representation of a row

Type

string|string[]

$_entityClass protected

The name of the class that represent a single row for this table

Type

string

$_eventClass protected

Default class name for new event objects.

Type

string

$_eventManager protected

Instance of the Cake\Event\EventManager this object is using to dispatch inner events.

Type

\Cake\Event\EventManagerInterface

$_primaryKey protected

The name of the field that represents the primary key in the table

Type

string|string[]

$_registryAlias protected

Registry key used to create this table object

Type

string|null

$_rulesChecker protected

The domain rules to be applied to entities saved by this table

Type

\Cake\Datasource\RulesChecker

$_schema protected

The schema object containing a description of this table fields

Type

\Cake\Database\Schema\TableSchemaInterface|null

$_table protected

Name of the table as it can be found in the database

Type

string

$_validatorClass protected

Validator class.

Type

string

$_validators protected

A list of validation objects indexed by name

Type

\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