1: <?php
2: /**
3: * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
4: * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
5: *
6: * Licensed under The MIT License
7: * For full copyright and license information, please see the LICENSE.txt
8: * Redistributions of files must retain the above copyright notice.
9: *
10: * @copyright Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
11: * @link https://cakephp.org CakePHP(tm) Project
12: * @since 3.0.0
13: * @license https://opensource.org/licenses/mit-license.php MIT License
14: */
15: namespace Cake\ORM;
16:
17: use ArrayObject;
18: use BadMethodCallException;
19: use Cake\Core\App;
20: use Cake\Database\Schema\TableSchema;
21: use Cake\Database\Type;
22: use Cake\Datasource\ConnectionInterface;
23: use Cake\Datasource\EntityInterface;
24: use Cake\Datasource\Exception\InvalidPrimaryKeyException;
25: use Cake\Datasource\RepositoryInterface;
26: use Cake\Datasource\RulesAwareTrait;
27: use Cake\Event\EventDispatcherInterface;
28: use Cake\Event\EventDispatcherTrait;
29: use Cake\Event\EventListenerInterface;
30: use Cake\Event\EventManager;
31: use Cake\ORM\Association\BelongsTo;
32: use Cake\ORM\Association\BelongsToMany;
33: use Cake\ORM\Association\HasMany;
34: use Cake\ORM\Association\HasOne;
35: use Cake\ORM\Exception\MissingEntityException;
36: use Cake\ORM\Exception\PersistenceFailedException;
37: use Cake\ORM\Exception\RolledbackTransactionException;
38: use Cake\ORM\Rule\IsUnique;
39: use Cake\Utility\Inflector;
40: use Cake\Validation\ValidatorAwareInterface;
41: use Cake\Validation\ValidatorAwareTrait;
42: use InvalidArgumentException;
43: use RuntimeException;
44:
45: /**
46: * Represents a single database table.
47: *
48: * Exposes methods for retrieving data out of it, and manages the associations
49: * this table has to other tables. Multiple instances of this class can be created
50: * for the same database table with different aliases, this allows you to address
51: * your database structure in a richer and more expressive way.
52: *
53: * ### Retrieving data
54: *
55: * The primary way to retrieve data is using Table::find(). See that method
56: * for more information.
57: *
58: * ### Dynamic finders
59: *
60: * In addition to the standard find($type) finder methods, CakePHP provides dynamic
61: * finder methods. These methods allow you to easily set basic conditions up. For example
62: * to filter users by username you would call
63: *
64: * ```
65: * $query = $users->findByUsername('mark');
66: * ```
67: *
68: * You can also combine conditions on multiple fields using either `Or` or `And`:
69: *
70: * ```
71: * $query = $users->findByUsernameOrEmail('mark', 'mark@example.org');
72: * ```
73: *
74: * ### Bulk updates/deletes
75: *
76: * You can use Table::updateAll() and Table::deleteAll() to do bulk updates/deletes.
77: * You should be aware that events will *not* be fired for bulk updates/deletes.
78: *
79: * ### Callbacks/events
80: *
81: * Table objects provide a few callbacks/events you can hook into to augment/replace
82: * find operations. Each event uses the standard event subsystem in CakePHP
83: *
84: * - `beforeFind(Event $event, Query $query, ArrayObject $options, boolean $primary)`
85: * Fired before each find operation. By stopping the event and supplying a
86: * return value you can bypass the find operation entirely. Any changes done
87: * to the $query instance will be retained for the rest of the find. The
88: * $primary parameter indicates whether or not this is the root query,
89: * or an associated query.
90: *
91: * - `buildValidator(Event $event, Validator $validator, string $name)`
92: * Allows listeners to modify validation rules for the provided named validator.
93: *
94: * - `buildRules(Event $event, RulesChecker $rules)`
95: * Allows listeners to modify the rules checker by adding more rules.
96: *
97: * - `beforeRules(Event $event, EntityInterface $entity, ArrayObject $options, string $operation)`
98: * Fired before an entity is validated using the rules checker. By stopping this event,
99: * you can return the final value of the rules checking operation.
100: *
101: * - `afterRules(Event $event, EntityInterface $entity, ArrayObject $options, bool $result, string $operation)`
102: * Fired after the rules have been checked on the entity. By stopping this event,
103: * you can return the final value of the rules checking operation.
104: *
105: * - `beforeSave(Event $event, EntityInterface $entity, ArrayObject $options)`
106: * Fired before each entity is saved. Stopping this event will abort the save
107: * operation. When the event is stopped the result of the event will be returned.
108: *
109: * - `afterSave(Event $event, EntityInterface $entity, ArrayObject $options)`
110: * Fired after an entity is saved.
111: *
112: * - `afterSaveCommit(Event $event, EntityInterface $entity, ArrayObject $options)`
113: * Fired after the transaction in which the save operation is wrapped has been committed.
114: * It’s also triggered for non atomic saves where database operations are implicitly committed.
115: * The event is triggered only for the primary table on which save() is directly called.
116: * The event is not triggered if a transaction is started before calling save.
117: *
118: * - `beforeDelete(Event $event, EntityInterface $entity, ArrayObject $options)`
119: * Fired before an entity is deleted. By stopping this event you will abort
120: * the delete operation.
121: *
122: * - `afterDelete(Event $event, EntityInterface $entity, ArrayObject $options)`
123: * Fired after an entity has been deleted.
124: *
125: * @see \Cake\Event\EventManager for reference on the events system.
126: */
127: class Table implements RepositoryInterface, EventListenerInterface, EventDispatcherInterface, ValidatorAwareInterface
128: {
129:
130: use EventDispatcherTrait;
131: use RulesAwareTrait;
132: use ValidatorAwareTrait;
133:
134: /**
135: * The alias this object is assigned to validators as.
136: *
137: * @var string
138: */
139: const VALIDATOR_PROVIDER_NAME = 'table';
140:
141: /**
142: * The name of the event dispatched when a validator has been built.
143: *
144: * @var string
145: */
146: const BUILD_VALIDATOR_EVENT = 'Model.buildValidator';
147:
148: /**
149: * The rules class name that is used.
150: *
151: * @var string
152: */
153: const RULES_CLASS = RulesChecker::class;
154:
155: /**
156: * The IsUnique class name that is used.
157: *
158: * @var string
159: */
160: const IS_UNIQUE_CLASS = IsUnique::class;
161:
162: /**
163: * Name of the table as it can be found in the database
164: *
165: * @var string
166: */
167: protected $_table;
168:
169: /**
170: * Human name giving to this particular instance. Multiple objects representing
171: * the same database table can exist by using different aliases.
172: *
173: * @var string
174: */
175: protected $_alias;
176:
177: /**
178: * Connection instance
179: *
180: * @var \Cake\Database\Connection
181: */
182: protected $_connection;
183:
184: /**
185: * The schema object containing a description of this table fields
186: *
187: * @var \Cake\Database\Schema\TableSchema
188: */
189: protected $_schema;
190:
191: /**
192: * The name of the field that represents the primary key in the table
193: *
194: * @var string|array
195: */
196: protected $_primaryKey;
197:
198: /**
199: * The name of the field that represents a human readable representation of a row
200: *
201: * @var string
202: */
203: protected $_displayField;
204:
205: /**
206: * The associations container for this Table.
207: *
208: * @var \Cake\ORM\AssociationCollection
209: */
210: protected $_associations;
211:
212: /**
213: * BehaviorRegistry for this table
214: *
215: * @var \Cake\ORM\BehaviorRegistry
216: */
217: protected $_behaviors;
218:
219: /**
220: * The name of the class that represent a single row for this table
221: *
222: * @var string
223: */
224: protected $_entityClass;
225:
226: /**
227: * Registry key used to create this table object
228: *
229: * @var string
230: */
231: protected $_registryAlias;
232:
233: /**
234: * Initializes a new instance
235: *
236: * The $config array understands the following keys:
237: *
238: * - table: Name of the database table to represent
239: * - alias: Alias to be assigned to this table (default to table name)
240: * - connection: The connection instance to use
241: * - entityClass: The fully namespaced class name of the entity class that will
242: * represent rows in this table.
243: * - schema: A \Cake\Database\Schema\TableSchema object or an array that can be
244: * passed to it.
245: * - eventManager: An instance of an event manager to use for internal events
246: * - behaviors: A BehaviorRegistry. Generally not used outside of tests.
247: * - associations: An AssociationCollection instance.
248: * - validator: A Validator instance which is assigned as the "default"
249: * validation set, or an associative array, where key is the name of the
250: * validation set and value the Validator instance.
251: *
252: * @param array $config List of options for this table
253: */
254: public function __construct(array $config = [])
255: {
256: if (!empty($config['registryAlias'])) {
257: $this->setRegistryAlias($config['registryAlias']);
258: }
259: if (!empty($config['table'])) {
260: $this->setTable($config['table']);
261: }
262: if (!empty($config['alias'])) {
263: $this->setAlias($config['alias']);
264: }
265: if (!empty($config['connection'])) {
266: $this->setConnection($config['connection']);
267: }
268: if (!empty($config['schema'])) {
269: $this->setSchema($config['schema']);
270: }
271: if (!empty($config['entityClass'])) {
272: $this->setEntityClass($config['entityClass']);
273: }
274: $eventManager = $behaviors = $associations = null;
275: if (!empty($config['eventManager'])) {
276: $eventManager = $config['eventManager'];
277: }
278: if (!empty($config['behaviors'])) {
279: $behaviors = $config['behaviors'];
280: }
281: if (!empty($config['associations'])) {
282: $associations = $config['associations'];
283: }
284: if (!empty($config['validator'])) {
285: if (!is_array($config['validator'])) {
286: $this->setValidator(static::DEFAULT_VALIDATOR, $config['validator']);
287: } else {
288: foreach ($config['validator'] as $name => $validator) {
289: $this->setValidator($name, $validator);
290: }
291: }
292: }
293: $this->_eventManager = $eventManager ?: new EventManager();
294: $this->_behaviors = $behaviors ?: new BehaviorRegistry();
295: $this->_behaviors->setTable($this);
296: $this->_associations = $associations ?: new AssociationCollection();
297:
298: $this->initialize($config);
299: $this->_eventManager->on($this);
300: $this->dispatchEvent('Model.initialize');
301: }
302:
303: /**
304: * Get the default connection name.
305: *
306: * This method is used to get the fallback connection name if an
307: * instance is created through the TableLocator without a connection.
308: *
309: * @return string
310: * @see \Cake\ORM\Locator\TableLocator::get()
311: */
312: public static function defaultConnectionName()
313: {
314: return 'default';
315: }
316:
317: /**
318: * Initialize a table instance. Called after the constructor.
319: *
320: * You can use this method to define associations, attach behaviors
321: * define validation and do any other initialization logic you need.
322: *
323: * ```
324: * public function initialize(array $config)
325: * {
326: * $this->belongsTo('Users');
327: * $this->belongsToMany('Tagging.Tags');
328: * $this->setPrimaryKey('something_else');
329: * }
330: * ```
331: *
332: * @param array $config Configuration options passed to the constructor
333: * @return void
334: */
335: public function initialize(array $config)
336: {
337: }
338:
339: /**
340: * Sets the database table name.
341: *
342: * This can include the database schema name in the form 'schema.table'.
343: * If the name must be quoted, enable automatic identifier quoting.
344: *
345: * @param string $table Table name.
346: * @return $this
347: */
348: public function setTable($table)
349: {
350: $this->_table = $table;
351:
352: return $this;
353: }
354:
355: /**
356: * Returns the database table name.
357: *
358: * This can include the database schema name if set using `setTable()`.
359: *
360: * @return string
361: */
362: public function getTable()
363: {
364: if ($this->_table === null) {
365: $table = namespaceSplit(get_class($this));
366: $table = substr(end($table), 0, -5);
367: if (!$table) {
368: $table = $this->getAlias();
369: }
370: $this->_table = Inflector::underscore($table);
371: }
372:
373: return $this->_table;
374: }
375:
376: /**
377: * Returns the database table name or sets a new one.
378: *
379: * @deprecated 3.4.0 Use setTable()/getTable() instead.
380: * @param string|null $table the new table name
381: * @return string
382: */
383: public function table($table = null)
384: {
385: deprecationWarning(
386: get_called_class() . '::table() is deprecated. ' .
387: 'Use setTable()/getTable() instead.'
388: );
389: if ($table !== null) {
390: $this->setTable($table);
391: }
392:
393: return $this->getTable();
394: }
395:
396: /**
397: * Sets the table alias.
398: *
399: * @param string $alias Table alias
400: * @return $this
401: */
402: public function setAlias($alias)
403: {
404: $this->_alias = $alias;
405:
406: return $this;
407: }
408:
409: /**
410: * Returns the table alias.
411: *
412: * @return string
413: */
414: public function getAlias()
415: {
416: if ($this->_alias === null) {
417: $alias = namespaceSplit(get_class($this));
418: $alias = substr(end($alias), 0, -5) ?: $this->_table;
419: $this->_alias = $alias;
420: }
421:
422: return $this->_alias;
423: }
424:
425: /**
426: * {@inheritDoc}
427: * @deprecated 3.4.0 Use setAlias()/getAlias() instead.
428: */
429: public function alias($alias = null)
430: {
431: deprecationWarning(
432: get_called_class() . '::alias() is deprecated. ' .
433: 'Use setAlias()/getAlias() instead.'
434: );
435: if ($alias !== null) {
436: $this->setAlias($alias);
437: }
438:
439: return $this->getAlias();
440: }
441:
442: /**
443: * Alias a field with the table's current alias.
444: *
445: * If field is already aliased it will result in no-op.
446: *
447: * @param string $field The field to alias.
448: * @return string The field prefixed with the table alias.
449: */
450: public function aliasField($field)
451: {
452: if (strpos($field, '.') !== false) {
453: return $field;
454: }
455:
456: return $this->getAlias() . '.' . $field;
457: }
458:
459: /**
460: * Sets the table registry key used to create this table instance.
461: *
462: * @param string $registryAlias The key used to access this object.
463: * @return $this
464: */
465: public function setRegistryAlias($registryAlias)
466: {
467: $this->_registryAlias = $registryAlias;
468:
469: return $this;
470: }
471:
472: /**
473: * Returns the table registry key used to create this table instance.
474: *
475: * @return string
476: */
477: public function getRegistryAlias()
478: {
479: if ($this->_registryAlias === null) {
480: $this->_registryAlias = $this->getAlias();
481: }
482:
483: return $this->_registryAlias;
484: }
485:
486: /**
487: * Returns the table registry key used to create this table instance or sets one.
488: *
489: * @deprecated 3.4.0 Use setRegistryAlias()/getRegistryAlias() instead.
490: * @param string|null $registryAlias the key used to access this object
491: * @return string
492: */
493: public function registryAlias($registryAlias = null)
494: {
495: deprecationWarning(
496: get_called_class() . '::registryAlias() is deprecated. ' .
497: 'Use setRegistryAlias()/getRegistryAlias() instead.'
498: );
499: if ($registryAlias !== null) {
500: $this->setRegistryAlias($registryAlias);
501: }
502:
503: return $this->getRegistryAlias();
504: }
505:
506: /**
507: * Sets the connection instance.
508: *
509: * @param \Cake\Database\Connection $connection The connection instance
510: * @return $this
511: */
512: public function setConnection(ConnectionInterface $connection)
513: {
514: $this->_connection = $connection;
515:
516: return $this;
517: }
518:
519: /**
520: * Returns the connection instance.
521: *
522: * @return \Cake\Database\Connection
523: */
524: public function getConnection()
525: {
526: return $this->_connection;
527: }
528:
529: /**
530: * Returns the connection instance or sets a new one
531: *
532: * @deprecated 3.4.0 Use setConnection()/getConnection() instead.
533: * @param \Cake\Datasource\ConnectionInterface|null $connection The new connection instance
534: * @return \Cake\Datasource\ConnectionInterface
535: */
536: public function connection(ConnectionInterface $connection = null)
537: {
538: deprecationWarning(
539: get_called_class() . '::connection() is deprecated. ' .
540: 'Use setConnection()/getConnection() instead.'
541: );
542: if ($connection !== null) {
543: $this->setConnection($connection);
544: }
545:
546: return $this->getConnection();
547: }
548:
549: /**
550: * Returns the schema table object describing this table's properties.
551: *
552: * @return \Cake\Database\Schema\TableSchema
553: */
554: public function getSchema()
555: {
556: if ($this->_schema === null) {
557: $this->_schema = $this->_initializeSchema(
558: $this->getConnection()
559: ->getSchemaCollection()
560: ->describe($this->getTable())
561: );
562: }
563:
564: return $this->_schema;
565: }
566:
567: /**
568: * Sets the schema table object describing this table's properties.
569: *
570: * If an array is passed, a new TableSchema will be constructed
571: * out of it and used as the schema for this table.
572: *
573: * @param array|\Cake\Database\Schema\TableSchema $schema Schema to be used for this table
574: * @return $this
575: */
576: public function setSchema($schema)
577: {
578: if (is_array($schema)) {
579: $constraints = [];
580:
581: if (isset($schema['_constraints'])) {
582: $constraints = $schema['_constraints'];
583: unset($schema['_constraints']);
584: }
585:
586: $schema = new TableSchema($this->getTable(), $schema);
587:
588: foreach ($constraints as $name => $value) {
589: $schema->addConstraint($name, $value);
590: }
591: }
592:
593: $this->_schema = $schema;
594:
595: return $this;
596: }
597:
598: /**
599: * Returns the schema table object describing this table's properties.
600: *
601: * If a TableSchema is passed, it will be used for this table
602: * instead of the default one.
603: *
604: * If an array is passed, a new TableSchema will be constructed
605: * out of it and used as the schema for this table.
606: *
607: * @deprecated 3.4.0 Use setSchema()/getSchema() instead.
608: * @param array|\Cake\Database\Schema\TableSchema|null $schema New schema to be used for this table
609: * @return \Cake\Database\Schema\TableSchema
610: */
611: public function schema($schema = null)
612: {
613: deprecationWarning(
614: get_called_class() . '::schema() is deprecated. ' .
615: 'Use setSchema()/getSchema() instead.'
616: );
617: if ($schema !== null) {
618: $this->setSchema($schema);
619: }
620:
621: return $this->getSchema();
622: }
623:
624: /**
625: * Override this function in order to alter the schema used by this table.
626: * This function is only called after fetching the schema out of the database.
627: * If you wish to provide your own schema to this table without touching the
628: * database, you can override schema() or inject the definitions though that
629: * method.
630: *
631: * ### Example:
632: *
633: * ```
634: * protected function _initializeSchema(\Cake\Database\Schema\TableSchema $schema) {
635: * $schema->setColumnType('preferences', 'json');
636: * return $schema;
637: * }
638: * ```
639: *
640: * @param \Cake\Database\Schema\TableSchema $schema The table definition fetched from database.
641: * @return \Cake\Database\Schema\TableSchema the altered schema
642: */
643: protected function _initializeSchema(TableSchema $schema)
644: {
645: return $schema;
646: }
647:
648: /**
649: * Test to see if a Table has a specific field/column.
650: *
651: * Delegates to the schema object and checks for column presence
652: * using the Schema\Table instance.
653: *
654: * @param string $field The field to check for.
655: * @return bool True if the field exists, false if it does not.
656: */
657: public function hasField($field)
658: {
659: $schema = $this->getSchema();
660:
661: return $schema->getColumn($field) !== null;
662: }
663:
664: /**
665: * Sets the primary key field name.
666: *
667: * @param string|array $key Sets a new name to be used as primary key
668: * @return $this
669: */
670: public function setPrimaryKey($key)
671: {
672: $this->_primaryKey = $key;
673:
674: return $this;
675: }
676:
677: /**
678: * Returns the primary key field name.
679: *
680: * @return string|array
681: */
682: public function getPrimaryKey()
683: {
684: if ($this->_primaryKey === null) {
685: $key = (array)$this->getSchema()->primaryKey();
686: if (count($key) === 1) {
687: $key = $key[0];
688: }
689: $this->_primaryKey = $key;
690: }
691:
692: return $this->_primaryKey;
693: }
694:
695: /**
696: * Returns the primary key field name or sets a new one
697: *
698: * @deprecated 3.4.0 Use setPrimaryKey()/getPrimaryKey() instead.
699: * @param string|array|null $key Sets a new name to be used as primary key
700: * @return string|array
701: */
702: public function primaryKey($key = null)
703: {
704: deprecationWarning(
705: get_called_class() . '::primaryKey() is deprecated. ' .
706: 'Use setPrimaryKey()/getPrimaryKey() instead.'
707: );
708: if ($key !== null) {
709: $this->setPrimaryKey($key);
710: }
711:
712: return $this->getPrimaryKey();
713: }
714:
715: /**
716: * Sets the display field.
717: *
718: * @param string $key Name to be used as display field.
719: * @return $this
720: */
721: public function setDisplayField($key)
722: {
723: $this->_displayField = $key;
724:
725: return $this;
726: }
727:
728: /**
729: * Returns the display field.
730: *
731: * @return string
732: */
733: public function getDisplayField()
734: {
735: if ($this->_displayField === null) {
736: $schema = $this->getSchema();
737: $primary = (array)$this->getPrimaryKey();
738: $this->_displayField = array_shift($primary);
739: if ($schema->getColumn('title')) {
740: $this->_displayField = 'title';
741: }
742: if ($schema->getColumn('name')) {
743: $this->_displayField = 'name';
744: }
745: }
746:
747: return $this->_displayField;
748: }
749:
750: /**
751: * Returns the display field or sets a new one
752: *
753: * @deprecated 3.4.0 Use setDisplayField()/getDisplayField() instead.
754: * @param string|null $key sets a new name to be used as display field
755: * @return string
756: */
757: public function displayField($key = null)
758: {
759: deprecationWarning(
760: get_called_class() . '::displayField() is deprecated. ' .
761: 'Use setDisplayField()/getDisplayField() instead.'
762: );
763: if ($key !== null) {
764: $this->setDisplayField($key);
765:
766: return $key;
767: }
768:
769: return $this->getDisplayField();
770: }
771:
772: /**
773: * Returns the class used to hydrate rows for this table.
774: *
775: * @return string
776: */
777: public function getEntityClass()
778: {
779: if (!$this->_entityClass) {
780: $default = Entity::class;
781: $self = get_called_class();
782: $parts = explode('\\', $self);
783:
784: if ($self === __CLASS__ || count($parts) < 3) {
785: return $this->_entityClass = $default;
786: }
787:
788: $alias = Inflector::classify(Inflector::underscore(substr(array_pop($parts), 0, -5)));
789: $name = implode('\\', array_slice($parts, 0, -1)) . '\\Entity\\' . $alias;
790: if (!class_exists($name)) {
791: return $this->_entityClass = $default;
792: }
793:
794: $class = App::className($name, 'Model/Entity');
795: if (!$class) {
796: throw new MissingEntityException([$name]);
797: }
798:
799: $this->_entityClass = $class;
800: }
801:
802: return $this->_entityClass;
803: }
804:
805: /**
806: * Sets the class used to hydrate rows for this table.
807: *
808: * @param string $name The name of the class to use
809: * @throws \Cake\ORM\Exception\MissingEntityException when the entity class cannot be found
810: * @return $this
811: */
812: public function setEntityClass($name)
813: {
814: $class = App::className($name, 'Model/Entity');
815: if (!$class) {
816: throw new MissingEntityException([$name]);
817: }
818:
819: $this->_entityClass = $class;
820:
821: return $this;
822: }
823:
824: /**
825: * Returns the class used to hydrate rows for this table or sets
826: * a new one
827: *
828: * @deprecated 3.4.0 Use setEntityClass()/getEntityClass() instead.
829: * @param string|null $name The name of the class to use
830: * @throws \Cake\ORM\Exception\MissingEntityException when the entity class cannot be found
831: * @return string
832: */
833: public function entityClass($name = null)
834: {
835: deprecationWarning(
836: get_called_class() . '::entityClass() is deprecated. ' .
837: 'Use setEntityClass()/getEntityClass() instead.'
838: );
839: if ($name !== null) {
840: $this->setEntityClass($name);
841: }
842:
843: return $this->getEntityClass();
844: }
845:
846: /**
847: * Add a behavior.
848: *
849: * Adds a behavior to this table's behavior collection. Behaviors
850: * provide an easy way to create horizontally re-usable features
851: * that can provide trait like functionality, and allow for events
852: * to be listened to.
853: *
854: * Example:
855: *
856: * Load a behavior, with some settings.
857: *
858: * ```
859: * $this->addBehavior('Tree', ['parent' => 'parentId']);
860: * ```
861: *
862: * Behaviors are generally loaded during Table::initialize().
863: *
864: * @param string $name The name of the behavior. Can be a short class reference.
865: * @param array $options The options for the behavior to use.
866: * @return $this
867: * @throws \RuntimeException If a behavior is being reloaded.
868: * @see \Cake\ORM\Behavior
869: */
870: public function addBehavior($name, array $options = [])
871: {
872: $this->_behaviors->load($name, $options);
873:
874: return $this;
875: }
876:
877: /**
878: * Adds an array of behaviors to the table's behavior collection.
879: *
880: * Example:
881: *
882: * ```
883: * $this->addBehaviors([
884: * 'Timestamp',
885: * 'Tree' => ['level' => 'level'],
886: * ]);
887: * ```
888: *
889: * @param array $behaviors All of the behaviors to load.
890: * @return $this
891: * @throws \RuntimeException If a behavior is being reloaded.
892: */
893: public function addBehaviors(array $behaviors)
894: {
895: foreach ($behaviors as $name => $options) {
896: if (is_int($name)) {
897: $name = $options;
898: $options = [];
899: }
900:
901: $this->addBehavior($name, $options);
902: }
903:
904: return $this;
905: }
906:
907: /**
908: * Removes a behavior from this table's behavior registry.
909: *
910: * Example:
911: *
912: * Remove a behavior from this table.
913: *
914: * ```
915: * $this->removeBehavior('Tree');
916: * ```
917: *
918: * @param string $name The alias that the behavior was added with.
919: * @return $this
920: * @see \Cake\ORM\Behavior
921: */
922: public function removeBehavior($name)
923: {
924: $this->_behaviors->unload($name);
925:
926: return $this;
927: }
928:
929: /**
930: * Returns the behavior registry for this table.
931: *
932: * @return \Cake\ORM\BehaviorRegistry The BehaviorRegistry instance.
933: */
934: public function behaviors()
935: {
936: return $this->_behaviors;
937: }
938:
939: /**
940: * Get a behavior from the registry.
941: *
942: * @param string $name The behavior alias to get from the registry.
943: * @return \Cake\ORM\Behavior
944: * @throws \InvalidArgumentException If the behavior does not exist.
945: */
946: public function getBehavior($name)
947: {
948: /** @var \Cake\ORM\Behavior $behavior */
949: $behavior = $this->_behaviors->get($name);
950: if ($behavior === null) {
951: throw new InvalidArgumentException(sprintf(
952: 'The %s behavior is not defined on %s.',
953: $name,
954: get_class($this)
955: ));
956: }
957:
958: return $behavior;
959: }
960:
961: /**
962: * Check if a behavior with the given alias has been loaded.
963: *
964: * @param string $name The behavior alias to check.
965: * @return bool Whether or not the behavior exists.
966: */
967: public function hasBehavior($name)
968: {
969: return $this->_behaviors->has($name);
970: }
971:
972: /**
973: * Returns an association object configured for the specified alias if any.
974: *
975: * @deprecated 3.6.0 Use getAssociation() and Table::hasAssociation() instead.
976: * @param string $name the alias used for the association.
977: * @return \Cake\ORM\Association|null Either the association or null.
978: */
979: public function association($name)
980: {
981: deprecationWarning('Use Table::getAssociation() and Table::hasAssociation() instead.');
982:
983: return $this->findAssociation($name);
984: }
985:
986: /**
987: * Returns an association object configured for the specified alias.
988: *
989: * The name argument also supports dot syntax to access deeper associations.
990: *
991: * ```
992: * $users = $this->getAssociation('Articles.Comments.Users');
993: * ```
994: *
995: * Note that this method requires the association to be present or otherwise
996: * throws an exception.
997: * If you are not sure, use hasAssociation() before calling this method.
998: *
999: * @param string $name The alias used for the association.
1000: * @return \Cake\ORM\Association The association.
1001: * @throws \InvalidArgumentException
1002: */
1003: public function getAssociation($name)
1004: {
1005: $association = $this->findAssociation($name);
1006: if (!$association) {
1007: throw new InvalidArgumentException("The {$name} association is not defined on {$this->getAlias()}.");
1008: }
1009:
1010: return $association;
1011: }
1012:
1013: /**
1014: * Checks whether a specific association exists on this Table instance.
1015: *
1016: * The name argument also supports dot syntax to access deeper associations.
1017: *
1018: * ```
1019: * $hasUsers = $this->hasAssociation('Articles.Comments.Users');
1020: * ```
1021: *
1022: * @param string $name The alias used for the association.
1023: * @return bool
1024: */
1025: public function hasAssociation($name)
1026: {
1027: return $this->findAssociation($name) !== null;
1028: }
1029:
1030: /**
1031: * Returns an association object configured for the specified alias if any.
1032: *
1033: * The name argument also supports dot syntax to access deeper associations.
1034: *
1035: * ```
1036: * $users = $this->getAssociation('Articles.Comments.Users');
1037: * ```
1038: *
1039: * @param string $name The alias used for the association.
1040: * @return \Cake\ORM\Association|null Either the association or null.
1041: */
1042: protected function findAssociation($name)
1043: {
1044: if (strpos($name, '.') === false) {
1045: return $this->_associations->get($name);
1046: }
1047:
1048: list($name, $next) = array_pad(explode('.', $name, 2), 2, null);
1049: $result = $this->_associations->get($name);
1050:
1051: if ($result !== null && $next !== null) {
1052: $result = $result->getTarget()->getAssociation($next);
1053: }
1054:
1055: return $result;
1056: }
1057:
1058: /**
1059: * Get the associations collection for this table.
1060: *
1061: * @return \Cake\ORM\AssociationCollection|\Cake\ORM\Association[] The collection of association objects.
1062: */
1063: public function associations()
1064: {
1065: return $this->_associations;
1066: }
1067:
1068: /**
1069: * Setup multiple associations.
1070: *
1071: * It takes an array containing set of table names indexed by association type
1072: * as argument:
1073: *
1074: * ```
1075: * $this->Posts->addAssociations([
1076: * 'belongsTo' => [
1077: * 'Users' => ['className' => 'App\Model\Table\UsersTable']
1078: * ],
1079: * 'hasMany' => ['Comments'],
1080: * 'belongsToMany' => ['Tags']
1081: * ]);
1082: * ```
1083: *
1084: * Each association type accepts multiple associations where the keys
1085: * are the aliases, and the values are association config data. If numeric
1086: * keys are used the values will be treated as association aliases.
1087: *
1088: * @param array $params Set of associations to bind (indexed by association type)
1089: * @return $this
1090: * @see \Cake\ORM\Table::belongsTo()
1091: * @see \Cake\ORM\Table::hasOne()
1092: * @see \Cake\ORM\Table::hasMany()
1093: * @see \Cake\ORM\Table::belongsToMany()
1094: */
1095: public function addAssociations(array $params)
1096: {
1097: foreach ($params as $assocType => $tables) {
1098: foreach ($tables as $associated => $options) {
1099: if (is_numeric($associated)) {
1100: $associated = $options;
1101: $options = [];
1102: }
1103: $this->{$assocType}($associated, $options);
1104: }
1105: }
1106:
1107: return $this;
1108: }
1109:
1110: /**
1111: * Creates a new BelongsTo association between this table and a target
1112: * table. A "belongs to" association is a N-1 relationship where this table
1113: * is the N side, and where there is a single associated record in the target
1114: * table for each one in this table.
1115: *
1116: * Target table can be inferred by its name, which is provided in the
1117: * first argument, or you can either pass the to be instantiated or
1118: * an instance of it directly.
1119: *
1120: * The options array accept the following keys:
1121: *
1122: * - className: The class name of the target table object
1123: * - targetTable: An instance of a table object to be used as the target table
1124: * - foreignKey: The name of the field to use as foreign key, if false none
1125: * will be used
1126: * - conditions: array with a list of conditions to filter the join with
1127: * - joinType: The type of join to be used (e.g. INNER)
1128: * - strategy: The loading strategy to use. 'join' and 'select' are supported.
1129: * - finder: The finder method to use when loading records from this association.
1130: * Defaults to 'all'. When the strategy is 'join', only the fields, containments,
1131: * and where conditions will be used from the finder.
1132: *
1133: * This method will return the association object that was built.
1134: *
1135: * @param string $associated the alias for the target table. This is used to
1136: * uniquely identify the association
1137: * @param array $options list of options to configure the association definition
1138: * @return \Cake\ORM\Association\BelongsTo
1139: */
1140: public function belongsTo($associated, array $options = [])
1141: {
1142: $options += ['sourceTable' => $this];
1143:
1144: /** @var \Cake\ORM\Association\BelongsTo $association */
1145: $association = $this->_associations->load(BelongsTo::class, $associated, $options);
1146:
1147: return $association;
1148: }
1149:
1150: /**
1151: * Creates a new HasOne association between this table and a target
1152: * table. A "has one" association is a 1-1 relationship.
1153: *
1154: * Target table can be inferred by its name, which is provided in the
1155: * first argument, or you can either pass the class name to be instantiated or
1156: * an instance of it directly.
1157: *
1158: * The options array accept the following keys:
1159: *
1160: * - className: The class name of the target table object
1161: * - targetTable: An instance of a table object to be used as the target table
1162: * - foreignKey: The name of the field to use as foreign key, if false none
1163: * will be used
1164: * - dependent: Set to true if you want CakePHP to cascade deletes to the
1165: * associated table when an entity is removed on this table. The delete operation
1166: * on the associated table will not cascade further. To get recursive cascades enable
1167: * `cascadeCallbacks` as well. Set to false if you don't want CakePHP to remove
1168: * associated data, or when you are using database constraints.
1169: * - cascadeCallbacks: Set to true if you want CakePHP to fire callbacks on
1170: * cascaded deletes. If false the ORM will use deleteAll() to remove data.
1171: * When true records will be loaded and then deleted.
1172: * - conditions: array with a list of conditions to filter the join with
1173: * - joinType: The type of join to be used (e.g. LEFT)
1174: * - strategy: The loading strategy to use. 'join' and 'select' are supported.
1175: * - finder: The finder method to use when loading records from this association.
1176: * Defaults to 'all'. When the strategy is 'join', only the fields, containments,
1177: * and where conditions will be used from the finder.
1178: *
1179: * This method will return the association object that was built.
1180: *
1181: * @param string $associated the alias for the target table. This is used to
1182: * uniquely identify the association
1183: * @param array $options list of options to configure the association definition
1184: * @return \Cake\ORM\Association\HasOne
1185: */
1186: public function hasOne($associated, array $options = [])
1187: {
1188: $options += ['sourceTable' => $this];
1189:
1190: /** @var \Cake\ORM\Association\HasOne $association */
1191: $association = $this->_associations->load(HasOne::class, $associated, $options);
1192:
1193: return $association;
1194: }
1195:
1196: /**
1197: * Creates a new HasMany association between this table and a target
1198: * table. A "has many" association is a 1-N relationship.
1199: *
1200: * Target table can be inferred by its name, which is provided in the
1201: * first argument, or you can either pass the class name to be instantiated or
1202: * an instance of it directly.
1203: *
1204: * The options array accept the following keys:
1205: *
1206: * - className: The class name of the target table object
1207: * - targetTable: An instance of a table object to be used as the target table
1208: * - foreignKey: The name of the field to use as foreign key, if false none
1209: * will be used
1210: * - dependent: Set to true if you want CakePHP to cascade deletes to the
1211: * associated table when an entity is removed on this table. The delete operation
1212: * on the associated table will not cascade further. To get recursive cascades enable
1213: * `cascadeCallbacks` as well. Set to false if you don't want CakePHP to remove
1214: * associated data, or when you are using database constraints.
1215: * - cascadeCallbacks: Set to true if you want CakePHP to fire callbacks on
1216: * cascaded deletes. If false the ORM will use deleteAll() to remove data.
1217: * When true records will be loaded and then deleted.
1218: * - conditions: array with a list of conditions to filter the join with
1219: * - sort: The order in which results for this association should be returned
1220: * - saveStrategy: Either 'append' or 'replace'. When 'append' the current records
1221: * are appended to any records in the database. When 'replace' associated records
1222: * not in the current set will be removed. If the foreign key is a null able column
1223: * or if `dependent` is true records will be orphaned.
1224: * - strategy: The strategy to be used for selecting results Either 'select'
1225: * or 'subquery'. If subquery is selected the query used to return results
1226: * in the source table will be used as conditions for getting rows in the
1227: * target table.
1228: * - finder: The finder method to use when loading records from this association.
1229: * Defaults to 'all'.
1230: *
1231: * This method will return the association object that was built.
1232: *
1233: * @param string $associated the alias for the target table. This is used to
1234: * uniquely identify the association
1235: * @param array $options list of options to configure the association definition
1236: * @return \Cake\ORM\Association\HasMany
1237: */
1238: public function hasMany($associated, array $options = [])
1239: {
1240: $options += ['sourceTable' => $this];
1241:
1242: /** @var \Cake\ORM\Association\HasMany $association */
1243: $association = $this->_associations->load(HasMany::class, $associated, $options);
1244:
1245: return $association;
1246: }
1247:
1248: /**
1249: * Creates a new BelongsToMany association between this table and a target
1250: * table. A "belongs to many" association is a M-N relationship.
1251: *
1252: * Target table can be inferred by its name, which is provided in the
1253: * first argument, or you can either pass the class name to be instantiated or
1254: * an instance of it directly.
1255: *
1256: * The options array accept the following keys:
1257: *
1258: * - className: The class name of the target table object.
1259: * - targetTable: An instance of a table object to be used as the target table.
1260: * - foreignKey: The name of the field to use as foreign key.
1261: * - targetForeignKey: The name of the field to use as the target foreign key.
1262: * - joinTable: The name of the table representing the link between the two
1263: * - through: If you choose to use an already instantiated link table, set this
1264: * key to a configured Table instance containing associations to both the source
1265: * and target tables in this association.
1266: * - dependent: Set to false, if you do not want junction table records removed
1267: * when an owning record is removed.
1268: * - cascadeCallbacks: Set to true if you want CakePHP to fire callbacks on
1269: * cascaded deletes. If false the ORM will use deleteAll() to remove data.
1270: * When true join/junction table records will be loaded and then deleted.
1271: * - conditions: array with a list of conditions to filter the join with.
1272: * - sort: The order in which results for this association should be returned.
1273: * - strategy: The strategy to be used for selecting results Either 'select'
1274: * or 'subquery'. If subquery is selected the query used to return results
1275: * in the source table will be used as conditions for getting rows in the
1276: * target table.
1277: * - saveStrategy: Either 'append' or 'replace'. Indicates the mode to be used
1278: * for saving associated entities. The former will only create new links
1279: * between both side of the relation and the latter will do a wipe and
1280: * replace to create the links between the passed entities when saving.
1281: * - strategy: The loading strategy to use. 'select' and 'subquery' are supported.
1282: * - finder: The finder method to use when loading records from this association.
1283: * Defaults to 'all'.
1284: *
1285: * This method will return the association object that was built.
1286: *
1287: * @param string $associated the alias for the target table. This is used to
1288: * uniquely identify the association
1289: * @param array $options list of options to configure the association definition
1290: * @return \Cake\ORM\Association\BelongsToMany
1291: */
1292: public function belongsToMany($associated, array $options = [])
1293: {
1294: $options += ['sourceTable' => $this];
1295:
1296: /** @var \Cake\ORM\Association\BelongsToMany $association */
1297: $association = $this->_associations->load(BelongsToMany::class, $associated, $options);
1298:
1299: return $association;
1300: }
1301:
1302: /**
1303: * Creates a new Query for this repository and applies some defaults based on the
1304: * type of search that was selected.
1305: *
1306: * ### Model.beforeFind event
1307: *
1308: * Each find() will trigger a `Model.beforeFind` event for all attached
1309: * listeners. Any listener can set a valid result set using $query
1310: *
1311: * By default, `$options` will recognize the following keys:
1312: *
1313: * - fields
1314: * - conditions
1315: * - order
1316: * - limit
1317: * - offset
1318: * - page
1319: * - group
1320: * - having
1321: * - contain
1322: * - join
1323: *
1324: * ### Usage
1325: *
1326: * Using the options array:
1327: *
1328: * ```
1329: * $query = $articles->find('all', [
1330: * 'conditions' => ['published' => 1],
1331: * 'limit' => 10,
1332: * 'contain' => ['Users', 'Comments']
1333: * ]);
1334: * ```
1335: *
1336: * Using the builder interface:
1337: *
1338: * ```
1339: * $query = $articles->find()
1340: * ->where(['published' => 1])
1341: * ->limit(10)
1342: * ->contain(['Users', 'Comments']);
1343: * ```
1344: *
1345: * ### Calling finders
1346: *
1347: * The find() method is the entry point for custom finder methods.
1348: * You can invoke a finder by specifying the type:
1349: *
1350: * ```
1351: * $query = $articles->find('published');
1352: * ```
1353: *
1354: * Would invoke the `findPublished` method.
1355: *
1356: * @param string $type the type of query to perform
1357: * @param array|\ArrayAccess $options An array that will be passed to Query::applyOptions()
1358: * @return \Cake\ORM\Query The query builder
1359: */
1360: public function find($type = 'all', $options = [])
1361: {
1362: $query = $this->query();
1363: $query->select();
1364:
1365: return $this->callFinder($type, $query, $options);
1366: }
1367:
1368: /**
1369: * Returns the query as passed.
1370: *
1371: * By default findAll() applies no conditions, you
1372: * can override this method in subclasses to modify how `find('all')` works.
1373: *
1374: * @param \Cake\ORM\Query $query The query to find with
1375: * @param array $options The options to use for the find
1376: * @return \Cake\ORM\Query The query builder
1377: */
1378: public function findAll(Query $query, array $options)
1379: {
1380: return $query;
1381: }
1382:
1383: /**
1384: * Sets up a query object so results appear as an indexed array, useful for any
1385: * place where you would want a list such as for populating input select boxes.
1386: *
1387: * When calling this finder, the fields passed are used to determine what should
1388: * be used as the array key, value and optionally what to group the results by.
1389: * By default the primary key for the model is used for the key, and the display
1390: * field as value.
1391: *
1392: * The results of this finder will be in the following form:
1393: *
1394: * ```
1395: * [
1396: * 1 => 'value for id 1',
1397: * 2 => 'value for id 2',
1398: * 4 => 'value for id 4'
1399: * ]
1400: * ```
1401: *
1402: * You can specify which property will be used as the key and which as value
1403: * by using the `$options` array, when not specified, it will use the results
1404: * of calling `primaryKey` and `displayField` respectively in this table:
1405: *
1406: * ```
1407: * $table->find('list', [
1408: * 'keyField' => 'name',
1409: * 'valueField' => 'age'
1410: * ]);
1411: * ```
1412: *
1413: * Results can be put together in bigger groups when they share a property, you
1414: * can customize the property to use for grouping by setting `groupField`:
1415: *
1416: * ```
1417: * $table->find('list', [
1418: * 'groupField' => 'category_id',
1419: * ]);
1420: * ```
1421: *
1422: * When using a `groupField` results will be returned in this format:
1423: *
1424: * ```
1425: * [
1426: * 'group_1' => [
1427: * 1 => 'value for id 1',
1428: * 2 => 'value for id 2',
1429: * ]
1430: * 'group_2' => [
1431: * 4 => 'value for id 4'
1432: * ]
1433: * ]
1434: * ```
1435: *
1436: * @param \Cake\ORM\Query $query The query to find with
1437: * @param array $options The options for the find
1438: * @return \Cake\ORM\Query The query builder
1439: */
1440: public function findList(Query $query, array $options)
1441: {
1442: $options += [
1443: 'keyField' => $this->getPrimaryKey(),
1444: 'valueField' => $this->getDisplayField(),
1445: 'groupField' => null
1446: ];
1447:
1448: if (isset($options['idField'])) {
1449: $options['keyField'] = $options['idField'];
1450: unset($options['idField']);
1451: deprecationWarning('Option "idField" is deprecated, use "keyField" instead.');
1452: }
1453:
1454: if (!$query->clause('select') &&
1455: !is_object($options['keyField']) &&
1456: !is_object($options['valueField']) &&
1457: !is_object($options['groupField'])
1458: ) {
1459: $fields = array_merge(
1460: (array)$options['keyField'],
1461: (array)$options['valueField'],
1462: (array)$options['groupField']
1463: );
1464: $columns = $this->getSchema()->columns();
1465: if (count($fields) === count(array_intersect($fields, $columns))) {
1466: $query->select($fields);
1467: }
1468: }
1469:
1470: $options = $this->_setFieldMatchers(
1471: $options,
1472: ['keyField', 'valueField', 'groupField']
1473: );
1474:
1475: return $query->formatResults(function ($results) use ($options) {
1476: /** @var \Cake\Collection\CollectionInterface $results */
1477: return $results->combine(
1478: $options['keyField'],
1479: $options['valueField'],
1480: $options['groupField']
1481: );
1482: });
1483: }
1484:
1485: /**
1486: * Results for this finder will be a nested array, and is appropriate if you want
1487: * to use the parent_id field of your model data to build nested results.
1488: *
1489: * Values belonging to a parent row based on their parent_id value will be
1490: * recursively nested inside the parent row values using the `children` property
1491: *
1492: * You can customize what fields are used for nesting results, by default the
1493: * primary key and the `parent_id` fields are used. If you wish to change
1494: * these defaults you need to provide the keys `keyField`, `parentField` or `nestingKey` in
1495: * `$options`:
1496: *
1497: * ```
1498: * $table->find('threaded', [
1499: * 'keyField' => 'id',
1500: * 'parentField' => 'ancestor_id'
1501: * 'nestingKey' => 'children'
1502: * ]);
1503: * ```
1504: *
1505: * @param \Cake\ORM\Query $query The query to find with
1506: * @param array $options The options to find with
1507: * @return \Cake\ORM\Query The query builder
1508: */
1509: public function findThreaded(Query $query, array $options)
1510: {
1511: $options += [
1512: 'keyField' => $this->getPrimaryKey(),
1513: 'parentField' => 'parent_id',
1514: 'nestingKey' => 'children'
1515: ];
1516:
1517: if (isset($options['idField'])) {
1518: $options['keyField'] = $options['idField'];
1519: unset($options['idField']);
1520: deprecationWarning('Option "idField" is deprecated, use "keyField" instead.');
1521: }
1522:
1523: $options = $this->_setFieldMatchers($options, ['keyField', 'parentField']);
1524:
1525: return $query->formatResults(function ($results) use ($options) {
1526: /** @var \Cake\Collection\CollectionInterface $results */
1527: return $results->nest($options['keyField'], $options['parentField'], $options['nestingKey']);
1528: });
1529: }
1530:
1531: /**
1532: * Out of an options array, check if the keys described in `$keys` are arrays
1533: * and change the values for closures that will concatenate the each of the
1534: * properties in the value array when passed a row.
1535: *
1536: * This is an auxiliary function used for result formatters that can accept
1537: * composite keys when comparing values.
1538: *
1539: * @param array $options the original options passed to a finder
1540: * @param array $keys the keys to check in $options to build matchers from
1541: * the associated value
1542: * @return array
1543: */
1544: protected function _setFieldMatchers($options, $keys)
1545: {
1546: foreach ($keys as $field) {
1547: if (!is_array($options[$field])) {
1548: continue;
1549: }
1550:
1551: if (count($options[$field]) === 1) {
1552: $options[$field] = current($options[$field]);
1553: continue;
1554: }
1555:
1556: $fields = $options[$field];
1557: $options[$field] = function ($row) use ($fields) {
1558: $matches = [];
1559: foreach ($fields as $field) {
1560: $matches[] = $row[$field];
1561: }
1562:
1563: return implode(';', $matches);
1564: };
1565: }
1566:
1567: return $options;
1568: }
1569:
1570: /**
1571: * {@inheritDoc}
1572: *
1573: * ### Usage
1574: *
1575: * Get an article and some relationships:
1576: *
1577: * ```
1578: * $article = $articles->get(1, ['contain' => ['Users', 'Comments']]);
1579: * ```
1580: *
1581: * @throws \Cake\Datasource\Exception\InvalidPrimaryKeyException When $primaryKey has an
1582: * incorrect number of elements.
1583: */
1584: public function get($primaryKey, $options = [])
1585: {
1586: $key = (array)$this->getPrimaryKey();
1587: $alias = $this->getAlias();
1588: foreach ($key as $index => $keyname) {
1589: $key[$index] = $alias . '.' . $keyname;
1590: }
1591: $primaryKey = (array)$primaryKey;
1592: if (count($key) !== count($primaryKey)) {
1593: $primaryKey = $primaryKey ?: [null];
1594: $primaryKey = array_map(function ($key) {
1595: return var_export($key, true);
1596: }, $primaryKey);
1597:
1598: throw new InvalidPrimaryKeyException(sprintf(
1599: 'Record not found in table "%s" with primary key [%s]',
1600: $this->getTable(),
1601: implode(', ', $primaryKey)
1602: ));
1603: }
1604: $conditions = array_combine($key, $primaryKey);
1605:
1606: $cacheConfig = isset($options['cache']) ? $options['cache'] : false;
1607: $cacheKey = isset($options['key']) ? $options['key'] : false;
1608: $finder = isset($options['finder']) ? $options['finder'] : 'all';
1609: unset($options['key'], $options['cache'], $options['finder']);
1610:
1611: $query = $this->find($finder, $options)->where($conditions);
1612:
1613: if ($cacheConfig) {
1614: if (!$cacheKey) {
1615: $cacheKey = sprintf(
1616: 'get:%s.%s%s',
1617: $this->getConnection()->configName(),
1618: $this->getTable(),
1619: json_encode($primaryKey)
1620: );
1621: }
1622: $query->cache($cacheKey, $cacheConfig);
1623: }
1624:
1625: return $query->firstOrFail();
1626: }
1627:
1628: /**
1629: * Handles the logic executing of a worker inside a transaction.
1630: *
1631: * @param callable $worker The worker that will run inside the transaction.
1632: * @param bool $atomic Whether to execute the worker inside a database transaction.
1633: * @return mixed
1634: */
1635: protected function _executeTransaction(callable $worker, $atomic = true)
1636: {
1637: if ($atomic) {
1638: return $this->getConnection()->transactional(function () use ($worker) {
1639: return $worker();
1640: });
1641: }
1642:
1643: return $worker();
1644: }
1645:
1646: /**
1647: * Checks if the caller would have executed a commit on a transaction.
1648: *
1649: * @param bool $atomic True if an atomic transaction was used.
1650: * @param bool $primary True if a primary was used.
1651: * @return bool Returns true if a transaction was committed.
1652: */
1653: protected function _transactionCommitted($atomic, $primary)
1654: {
1655: return !$this->getConnection()->inTransaction() && ($atomic || (!$atomic && $primary));
1656: }
1657:
1658: /**
1659: * Finds an existing record or creates a new one.
1660: *
1661: * A find() will be done to locate an existing record using the attributes
1662: * defined in $search. If records matches the conditions, the first record
1663: * will be returned.
1664: *
1665: * If no record can be found, a new entity will be created
1666: * with the $search properties. If a callback is provided, it will be
1667: * called allowing you to define additional default values. The new
1668: * entity will be saved and returned.
1669: *
1670: * If your find conditions require custom order, associations or conditions, then the $search
1671: * parameter can be a callable that takes the Query as the argument, or a \Cake\ORM\Query object passed
1672: * as the $search parameter. Allowing you to customize the find results.
1673: *
1674: * ### Options
1675: *
1676: * The options array is passed to the save method with exception to the following keys:
1677: *
1678: * - atomic: Whether to execute the methods for find, save and callbacks inside a database
1679: * transaction (default: true)
1680: * - defaults: Whether to use the search criteria as default values for the new entity (default: true)
1681: *
1682: * @param array|callable|\Cake\ORM\Query $search The criteria to find existing
1683: * records by. Note that when you pass a query object you'll have to use
1684: * the 2nd arg of the method to modify the entity data before saving.
1685: * @param callable|null $callback A callback that will be invoked for newly
1686: * created entities. This callback will be called *before* the entity
1687: * is persisted.
1688: * @param array $options The options to use when saving.
1689: * @return \Cake\Datasource\EntityInterface An entity.
1690: * @throws \Cake\ORM\Exception\PersistenceFailedException When the entity couldn't be saved
1691: */
1692: public function findOrCreate($search, callable $callback = null, $options = [])
1693: {
1694: $options = new ArrayObject($options + [
1695: 'atomic' => true,
1696: 'defaults' => true,
1697: ]);
1698:
1699: $entity = $this->_executeTransaction(function () use ($search, $callback, $options) {
1700: return $this->_processFindOrCreate($search, $callback, $options->getArrayCopy());
1701: }, $options['atomic']);
1702:
1703: if ($entity && $this->_transactionCommitted($options['atomic'], true)) {
1704: $this->dispatchEvent('Model.afterSaveCommit', compact('entity', 'options'));
1705: }
1706:
1707: return $entity;
1708: }
1709:
1710: /**
1711: * Performs the actual find and/or create of an entity based on the passed options.
1712: *
1713: * @param array|callable|\Cake\ORM\Query $search The criteria to find an existing record by, or a callable tha will
1714: * customize the find query.
1715: * @param callable|null $callback A callback that will be invoked for newly
1716: * created entities. This callback will be called *before* the entity
1717: * is persisted.
1718: * @param array $options The options to use when saving.
1719: * @return \Cake\Datasource\EntityInterface An entity.
1720: * @throws \Cake\ORM\Exception\PersistenceFailedException When the entity couldn't be saved
1721: */
1722: protected function _processFindOrCreate($search, callable $callback = null, $options = [])
1723: {
1724: $query = $this->_getFindOrCreateQuery($search);
1725: $row = $query->first();
1726: if ($row !== null) {
1727: return $row;
1728: }
1729:
1730: $entity = $this->newEntity();
1731: if ($options['defaults'] && is_array($search)) {
1732: $accessibleFields = array_combine(array_keys($search), array_fill(0, count($search), true));
1733: $entity = $this->patchEntity($entity, $search, ['accessibleFields' => $accessibleFields]);
1734: }
1735: if ($callback !== null) {
1736: $entity = $callback($entity) ?: $entity;
1737: }
1738: unset($options['defaults']);
1739:
1740: $result = $this->save($entity, $options);
1741:
1742: if ($result === false) {
1743: throw new PersistenceFailedException($entity, ['findOrCreate']);
1744: }
1745:
1746: return $entity;
1747: }
1748:
1749: /**
1750: * Gets the query object for findOrCreate().
1751: *
1752: * @param array|callable|\Cake\ORM\Query $search The criteria to find existing records by.
1753: * @return \Cake\ORM\Query
1754: */
1755: protected function _getFindOrCreateQuery($search)
1756: {
1757: if (is_callable($search)) {
1758: $query = $this->find();
1759: $search($query);
1760: } elseif (is_array($search)) {
1761: $query = $this->find()->where($search);
1762: } elseif ($search instanceof Query) {
1763: $query = $search;
1764: } else {
1765: throw new InvalidArgumentException('Search criteria must be an array, callable or Query');
1766: }
1767:
1768: return $query;
1769: }
1770:
1771: /**
1772: * Creates a new Query instance for a table.
1773: *
1774: * @return \Cake\ORM\Query
1775: */
1776: public function query()
1777: {
1778: return new Query($this->getConnection(), $this);
1779: }
1780:
1781: /**
1782: * {@inheritDoc}
1783: */
1784: public function updateAll($fields, $conditions)
1785: {
1786: $query = $this->query();
1787: $query->update()
1788: ->set($fields)
1789: ->where($conditions);
1790: $statement = $query->execute();
1791: $statement->closeCursor();
1792:
1793: return $statement->rowCount();
1794: }
1795:
1796: /**
1797: * {@inheritDoc}
1798: */
1799: public function deleteAll($conditions)
1800: {
1801: $query = $this->query()
1802: ->delete()
1803: ->where($conditions);
1804: $statement = $query->execute();
1805: $statement->closeCursor();
1806:
1807: return $statement->rowCount();
1808: }
1809:
1810: /**
1811: * {@inheritDoc}
1812: */
1813: public function exists($conditions)
1814: {
1815: return (bool)count(
1816: $this->find('all')
1817: ->select(['existing' => 1])
1818: ->where($conditions)
1819: ->limit(1)
1820: ->disableHydration()
1821: ->toArray()
1822: );
1823: }
1824:
1825: /**
1826: * {@inheritDoc}
1827: *
1828: * ### Options
1829: *
1830: * The options array accepts the following keys:
1831: *
1832: * - atomic: Whether to execute the save and callbacks inside a database
1833: * transaction (default: true)
1834: * - checkRules: Whether or not to check the rules on entity before saving, if the checking
1835: * fails, it will abort the save operation. (default:true)
1836: * - associated: If `true` it will save 1st level associated entities as they are found
1837: * in the passed `$entity` whenever the property defined for the association
1838: * is marked as dirty. If an array, it will be interpreted as the list of associations
1839: * to be saved. It is possible to provide different options for saving on associated
1840: * table objects using this key by making the custom options the array value.
1841: * If `false` no associated records will be saved. (default: `true`)
1842: * - checkExisting: Whether or not to check if the entity already exists, assuming that the
1843: * entity is marked as not new, and the primary key has been set.
1844: *
1845: * ### Events
1846: *
1847: * When saving, this method will trigger four events:
1848: *
1849: * - Model.beforeRules: Will be triggered right before any rule checking is done
1850: * for the passed entity if the `checkRules` key in $options is not set to false.
1851: * Listeners will receive as arguments the entity, options array and the operation type.
1852: * If the event is stopped the rules check result will be set to the result of the event itself.
1853: * - Model.afterRules: Will be triggered right after the `checkRules()` method is
1854: * called for the entity. Listeners will receive as arguments the entity,
1855: * options array, the result of checking the rules and the operation type.
1856: * If the event is stopped the checking result will be set to the result of
1857: * the event itself.
1858: * - Model.beforeSave: Will be triggered just before the list of fields to be
1859: * persisted is calculated. It receives both the entity and the options as
1860: * arguments. The options array is passed as an ArrayObject, so any changes in
1861: * it will be reflected in every listener and remembered at the end of the event
1862: * so it can be used for the rest of the save operation. Returning false in any
1863: * of the listeners will abort the saving process. If the event is stopped
1864: * using the event API, the event object's `result` property will be returned.
1865: * This can be useful when having your own saving strategy implemented inside a
1866: * listener.
1867: * - Model.afterSave: Will be triggered after a successful insert or save,
1868: * listeners will receive the entity and the options array as arguments. The type
1869: * of operation performed (insert or update) can be determined by checking the
1870: * entity's method `isNew`, true meaning an insert and false an update.
1871: * - Model.afterSaveCommit: Will be triggered after the transaction is committed
1872: * for atomic save, listeners will receive the entity and the options array
1873: * as arguments.
1874: *
1875: * This method will determine whether the passed entity needs to be
1876: * inserted or updated in the database. It does that by checking the `isNew`
1877: * method on the entity. If the entity to be saved returns a non-empty value from
1878: * its `errors()` method, it will not be saved.
1879: *
1880: * ### Saving on associated tables
1881: *
1882: * This method will by default persist entities belonging to associated tables,
1883: * whenever a dirty property matching the name of the property name set for an
1884: * association in this table. It is possible to control what associations will
1885: * be saved and to pass additional option for saving them.
1886: *
1887: * ```
1888: * // Only save the comments association
1889: * $articles->save($entity, ['associated' => ['Comments']]);
1890: *
1891: * // Save the company, the employees and related addresses for each of them.
1892: * // For employees do not check the entity rules
1893: * $companies->save($entity, [
1894: * 'associated' => [
1895: * 'Employees' => [
1896: * 'associated' => ['Addresses'],
1897: * 'checkRules' => false
1898: * ]
1899: * ]
1900: * ]);
1901: *
1902: * // Save no associations
1903: * $articles->save($entity, ['associated' => false]);
1904: * ```
1905: *
1906: * @param \Cake\Datasource\EntityInterface $entity
1907: * @param array $options
1908: * @return \Cake\Datasource\EntityInterface|false
1909: * @throws \Cake\ORM\Exception\RolledbackTransactionException If the transaction is aborted in the afterSave event.
1910: */
1911: public function save(EntityInterface $entity, $options = [])
1912: {
1913: if ($options instanceof SaveOptionsBuilder) {
1914: $options = $options->toArray();
1915: }
1916:
1917: $options = new ArrayObject((array)$options + [
1918: 'atomic' => true,
1919: 'associated' => true,
1920: 'checkRules' => true,
1921: 'checkExisting' => true,
1922: '_primary' => true
1923: ]);
1924:
1925: if ($entity->hasErrors($options['associated'])) {
1926: return false;
1927: }
1928:
1929: if ($entity->isNew() === false && !$entity->isDirty()) {
1930: return $entity;
1931: }
1932:
1933: $success = $this->_executeTransaction(function () use ($entity, $options) {
1934: return $this->_processSave($entity, $options);
1935: }, $options['atomic']);
1936:
1937: if ($success) {
1938: if ($this->_transactionCommitted($options['atomic'], $options['_primary'])) {
1939: $this->dispatchEvent('Model.afterSaveCommit', compact('entity', 'options'));
1940: }
1941: if ($options['atomic'] || $options['_primary']) {
1942: $entity->clean();
1943: $entity->isNew(false);
1944: $entity->setSource($this->getRegistryAlias());
1945: }
1946: }
1947:
1948: return $success;
1949: }
1950:
1951: /**
1952: * Try to save an entity or throw a PersistenceFailedException if the application rules checks failed,
1953: * the entity contains errors or the save was aborted by a callback.
1954: *
1955: * @param \Cake\Datasource\EntityInterface $entity the entity to be saved
1956: * @param array|\ArrayAccess $options The options to use when saving.
1957: * @return \Cake\Datasource\EntityInterface
1958: * @throws \Cake\ORM\Exception\PersistenceFailedException When the entity couldn't be saved
1959: * @see \Cake\ORM\Table::save()
1960: */
1961: public function saveOrFail(EntityInterface $entity, $options = [])
1962: {
1963: $saved = $this->save($entity, $options);
1964: if ($saved === false) {
1965: throw new PersistenceFailedException($entity, ['save']);
1966: }
1967:
1968: return $saved;
1969: }
1970:
1971: /**
1972: * Performs the actual saving of an entity based on the passed options.
1973: *
1974: * @param \Cake\Datasource\EntityInterface $entity the entity to be saved
1975: * @param \ArrayObject $options the options to use for the save operation
1976: * @return \Cake\Datasource\EntityInterface|bool
1977: * @throws \RuntimeException When an entity is missing some of the primary keys.
1978: * @throws \Cake\ORM\Exception\RolledbackTransactionException If the transaction
1979: * is aborted in the afterSave event.
1980: */
1981: protected function _processSave($entity, $options)
1982: {
1983: $primaryColumns = (array)$this->getPrimaryKey();
1984:
1985: if ($options['checkExisting'] && $primaryColumns && $entity->isNew() && $entity->has($primaryColumns)) {
1986: $alias = $this->getAlias();
1987: $conditions = [];
1988: foreach ($entity->extract($primaryColumns) as $k => $v) {
1989: $conditions["$alias.$k"] = $v;
1990: }
1991: $entity->isNew(!$this->exists($conditions));
1992: }
1993:
1994: $mode = $entity->isNew() ? RulesChecker::CREATE : RulesChecker::UPDATE;
1995: if ($options['checkRules'] && !$this->checkRules($entity, $mode, $options)) {
1996: return false;
1997: }
1998:
1999: $options['associated'] = $this->_associations->normalizeKeys($options['associated']);
2000: $event = $this->dispatchEvent('Model.beforeSave', compact('entity', 'options'));
2001:
2002: if ($event->isStopped()) {
2003: return $event->getResult();
2004: }
2005:
2006: $saved = $this->_associations->saveParents(
2007: $this,
2008: $entity,
2009: $options['associated'],
2010: ['_primary' => false] + $options->getArrayCopy()
2011: );
2012:
2013: if (!$saved && $options['atomic']) {
2014: return false;
2015: }
2016:
2017: $data = $entity->extract($this->getSchema()->columns(), true);
2018: $isNew = $entity->isNew();
2019:
2020: if ($isNew) {
2021: $success = $this->_insert($entity, $data);
2022: } else {
2023: $success = $this->_update($entity, $data);
2024: }
2025:
2026: if ($success) {
2027: $success = $this->_onSaveSuccess($entity, $options);
2028: }
2029:
2030: if (!$success && $isNew) {
2031: $entity->unsetProperty($this->getPrimaryKey());
2032: $entity->isNew(true);
2033: }
2034:
2035: return $success ? $entity : false;
2036: }
2037:
2038: /**
2039: * Handles the saving of children associations and executing the afterSave logic
2040: * once the entity for this table has been saved successfully.
2041: *
2042: * @param \Cake\Datasource\EntityInterface $entity the entity to be saved
2043: * @param \ArrayObject $options the options to use for the save operation
2044: * @return bool True on success
2045: * @throws \Cake\ORM\Exception\RolledbackTransactionException If the transaction
2046: * is aborted in the afterSave event.
2047: */
2048: protected function _onSaveSuccess($entity, $options)
2049: {
2050: $success = $this->_associations->saveChildren(
2051: $this,
2052: $entity,
2053: $options['associated'],
2054: ['_primary' => false] + $options->getArrayCopy()
2055: );
2056:
2057: if (!$success && $options['atomic']) {
2058: return false;
2059: }
2060:
2061: $this->dispatchEvent('Model.afterSave', compact('entity', 'options'));
2062:
2063: if ($options['atomic'] && !$this->getConnection()->inTransaction()) {
2064: throw new RolledbackTransactionException(['table' => get_class($this)]);
2065: }
2066:
2067: if (!$options['atomic'] && !$options['_primary']) {
2068: $entity->clean();
2069: $entity->isNew(false);
2070: $entity->setSource($this->getRegistryAlias());
2071: }
2072:
2073: return true;
2074: }
2075:
2076: /**
2077: * Auxiliary function to handle the insert of an entity's data in the table
2078: *
2079: * @param \Cake\Datasource\EntityInterface $entity the subject entity from were $data was extracted
2080: * @param array $data The actual data that needs to be saved
2081: * @return \Cake\Datasource\EntityInterface|bool
2082: * @throws \RuntimeException if not all the primary keys where supplied or could
2083: * be generated when the table has composite primary keys. Or when the table has no primary key.
2084: */
2085: protected function _insert($entity, $data)
2086: {
2087: $primary = (array)$this->getPrimaryKey();
2088: if (empty($primary)) {
2089: $msg = sprintf(
2090: 'Cannot insert row in "%s" table, it has no primary key.',
2091: $this->getTable()
2092: );
2093: throw new RuntimeException($msg);
2094: }
2095: $keys = array_fill(0, count($primary), null);
2096: $id = (array)$this->_newId($primary) + $keys;
2097:
2098: // Generate primary keys preferring values in $data.
2099: $primary = array_combine($primary, $id);
2100: $primary = array_intersect_key($data, $primary) + $primary;
2101:
2102: $filteredKeys = array_filter($primary, function ($v) {
2103: return $v !== null;
2104: });
2105: $data += $filteredKeys;
2106:
2107: if (count($primary) > 1) {
2108: $schema = $this->getSchema();
2109: foreach ($primary as $k => $v) {
2110: if (!isset($data[$k]) && empty($schema->getColumn($k)['autoIncrement'])) {
2111: $msg = 'Cannot insert row, some of the primary key values are missing. ';
2112: $msg .= sprintf(
2113: 'Got (%s), expecting (%s)',
2114: implode(', ', $filteredKeys + $entity->extract(array_keys($primary))),
2115: implode(', ', array_keys($primary))
2116: );
2117: throw new RuntimeException($msg);
2118: }
2119: }
2120: }
2121:
2122: $success = false;
2123: if (empty($data)) {
2124: return $success;
2125: }
2126:
2127: $statement = $this->query()->insert(array_keys($data))
2128: ->values($data)
2129: ->execute();
2130:
2131: if ($statement->rowCount() !== 0) {
2132: $success = $entity;
2133: $entity->set($filteredKeys, ['guard' => false]);
2134: $schema = $this->getSchema();
2135: $driver = $this->getConnection()->getDriver();
2136: foreach ($primary as $key => $v) {
2137: if (!isset($data[$key])) {
2138: $id = $statement->lastInsertId($this->getTable(), $key);
2139: $type = $schema->getColumnType($key);
2140: $entity->set($key, Type::build($type)->toPHP($id, $driver));
2141: break;
2142: }
2143: }
2144: }
2145: $statement->closeCursor();
2146:
2147: return $success;
2148: }
2149:
2150: /**
2151: * Generate a primary key value for a new record.
2152: *
2153: * By default, this uses the type system to generate a new primary key
2154: * value if possible. You can override this method if you have specific requirements
2155: * for id generation.
2156: *
2157: * Note: The ORM will not generate primary key values for composite primary keys.
2158: * You can overwrite _newId() in your table class.
2159: *
2160: * @param array $primary The primary key columns to get a new ID for.
2161: * @return null|string|array Either null or the primary key value or a list of primary key values.
2162: */
2163: protected function _newId($primary)
2164: {
2165: if (!$primary || count((array)$primary) > 1) {
2166: return null;
2167: }
2168: $typeName = $this->getSchema()->getColumnType($primary[0]);
2169: $type = Type::build($typeName);
2170:
2171: return $type->newId();
2172: }
2173:
2174: /**
2175: * Auxiliary function to handle the update of an entity's data in the table
2176: *
2177: * @param \Cake\Datasource\EntityInterface $entity the subject entity from were $data was extracted
2178: * @param array $data The actual data that needs to be saved
2179: * @return \Cake\Datasource\EntityInterface|bool
2180: * @throws \InvalidArgumentException When primary key data is missing.
2181: */
2182: protected function _update($entity, $data)
2183: {
2184: $primaryColumns = (array)$this->getPrimaryKey();
2185: $primaryKey = $entity->extract($primaryColumns);
2186:
2187: $data = array_diff_key($data, $primaryKey);
2188: if (empty($data)) {
2189: return $entity;
2190: }
2191:
2192: if (count($primaryColumns) === 0) {
2193: $entityClass = get_class($entity);
2194: $table = $this->getTable();
2195: $message = "Cannot update `$entityClass`. The `$table` has no primary key.";
2196: throw new InvalidArgumentException($message);
2197: }
2198:
2199: if (!$entity->has($primaryColumns)) {
2200: $message = 'All primary key value(s) are needed for updating, ';
2201: $message .= get_class($entity) . ' is missing ' . implode(', ', $primaryColumns);
2202: throw new InvalidArgumentException($message);
2203: }
2204:
2205: $query = $this->query();
2206: $statement = $query->update()
2207: ->set($data)
2208: ->where($primaryKey)
2209: ->execute();
2210:
2211: $success = false;
2212: if ($statement->errorCode() === '00000') {
2213: $success = $entity;
2214: }
2215: $statement->closeCursor();
2216:
2217: return $success;
2218: }
2219:
2220: /**
2221: * Persists multiple entities of a table.
2222: *
2223: * The records will be saved in a transaction which will be rolled back if
2224: * any one of the records fails to save due to failed validation or database
2225: * error.
2226: *
2227: * @param \Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface $entities Entities to save.
2228: * @param array|\ArrayAccess $options Options used when calling Table::save() for each entity.
2229: * @return bool|\Cake\Datasource\EntityInterface[]|\Cake\Datasource\ResultSetInterface False on failure, entities list on success.
2230: * @throws \Exception
2231: */
2232: public function saveMany($entities, $options = [])
2233: {
2234: $isNew = [];
2235: $cleanup = function ($entities) use (&$isNew) {
2236: foreach ($entities as $key => $entity) {
2237: if (isset($isNew[$key]) && $isNew[$key]) {
2238: $entity->unsetProperty($this->getPrimaryKey());
2239: $entity->isNew(true);
2240: }
2241: }
2242: };
2243:
2244: try {
2245: $return = $this->getConnection()
2246: ->transactional(function () use ($entities, $options, &$isNew) {
2247: foreach ($entities as $key => $entity) {
2248: $isNew[$key] = $entity->isNew();
2249: if ($this->save($entity, $options) === false) {
2250: return false;
2251: }
2252: }
2253: });
2254: } catch (\Exception $e) {
2255: $cleanup($entities);
2256:
2257: throw $e;
2258: }
2259:
2260: if ($return === false) {
2261: $cleanup($entities);
2262:
2263: return false;
2264: }
2265:
2266: return $entities;
2267: }
2268:
2269: /**
2270: * {@inheritDoc}
2271: *
2272: * For HasMany and HasOne associations records will be removed based on
2273: * the dependent option. Join table records in BelongsToMany associations
2274: * will always be removed. You can use the `cascadeCallbacks` option
2275: * when defining associations to change how associated data is deleted.
2276: *
2277: * ### Options
2278: *
2279: * - `atomic` Defaults to true. When true the deletion happens within a transaction.
2280: * - `checkRules` Defaults to true. Check deletion rules before deleting the record.
2281: *
2282: * ### Events
2283: *
2284: * - `Model.beforeDelete` Fired before the delete occurs. If stopped the delete
2285: * will be aborted. Receives the event, entity, and options.
2286: * - `Model.afterDelete` Fired after the delete has been successful. Receives
2287: * the event, entity, and options.
2288: * - `Model.afterDeleteCommit` Fired after the transaction is committed for
2289: * an atomic delete. Receives the event, entity, and options.
2290: *
2291: * The options argument will be converted into an \ArrayObject instance
2292: * for the duration of the callbacks, this allows listeners to modify
2293: * the options used in the delete operation.
2294: *
2295: */
2296: public function delete(EntityInterface $entity, $options = [])
2297: {
2298: $options = new ArrayObject((array)$options + [
2299: 'atomic' => true,
2300: 'checkRules' => true,
2301: '_primary' => true,
2302: ]);
2303:
2304: $success = $this->_executeTransaction(function () use ($entity, $options) {
2305: return $this->_processDelete($entity, $options);
2306: }, $options['atomic']);
2307:
2308: if ($success && $this->_transactionCommitted($options['atomic'], $options['_primary'])) {
2309: $this->dispatchEvent('Model.afterDeleteCommit', [
2310: 'entity' => $entity,
2311: 'options' => $options
2312: ]);
2313: }
2314:
2315: return $success;
2316: }
2317:
2318: /**
2319: * Try to delete an entity or throw a PersistenceFailedException if the entity is new,
2320: * has no primary key value, application rules checks failed or the delete was aborted by a callback.
2321: *
2322: * @param \Cake\Datasource\EntityInterface $entity The entity to remove.
2323: * @param array|\ArrayAccess $options The options for the delete.
2324: * @return bool success
2325: * @throws \Cake\ORM\Exception\PersistenceFailedException
2326: * @see \Cake\ORM\Table::delete()
2327: */
2328: public function deleteOrFail(EntityInterface $entity, $options = [])
2329: {
2330: $deleted = $this->delete($entity, $options);
2331: if ($deleted === false) {
2332: throw new PersistenceFailedException($entity, ['delete']);
2333: }
2334:
2335: return $deleted;
2336: }
2337:
2338: /**
2339: * Perform the delete operation.
2340: *
2341: * Will delete the entity provided. Will remove rows from any
2342: * dependent associations, and clear out join tables for BelongsToMany associations.
2343: *
2344: * @param \Cake\Datasource\EntityInterface $entity The entity to delete.
2345: * @param \ArrayObject $options The options for the delete.
2346: * @throws \InvalidArgumentException if there are no primary key values of the
2347: * passed entity
2348: * @return bool success
2349: */
2350: protected function _processDelete($entity, $options)
2351: {
2352: if ($entity->isNew()) {
2353: return false;
2354: }
2355:
2356: $primaryKey = (array)$this->getPrimaryKey();
2357: if (!$entity->has($primaryKey)) {
2358: $msg = 'Deleting requires all primary key values.';
2359: throw new InvalidArgumentException($msg);
2360: }
2361:
2362: if ($options['checkRules'] && !$this->checkRules($entity, RulesChecker::DELETE, $options)) {
2363: return false;
2364: }
2365:
2366: $event = $this->dispatchEvent('Model.beforeDelete', [
2367: 'entity' => $entity,
2368: 'options' => $options
2369: ]);
2370:
2371: if ($event->isStopped()) {
2372: return $event->getResult();
2373: }
2374:
2375: $this->_associations->cascadeDelete(
2376: $entity,
2377: ['_primary' => false] + $options->getArrayCopy()
2378: );
2379:
2380: $query = $this->query();
2381: $conditions = (array)$entity->extract($primaryKey);
2382: $statement = $query->delete()
2383: ->where($conditions)
2384: ->execute();
2385:
2386: $success = $statement->rowCount() > 0;
2387: if (!$success) {
2388: return $success;
2389: }
2390:
2391: $this->dispatchEvent('Model.afterDelete', [
2392: 'entity' => $entity,
2393: 'options' => $options
2394: ]);
2395:
2396: return $success;
2397: }
2398:
2399: /**
2400: * Returns true if the finder exists for the table
2401: *
2402: * @param string $type name of finder to check
2403: *
2404: * @return bool
2405: */
2406: public function hasFinder($type)
2407: {
2408: $finder = 'find' . $type;
2409:
2410: return method_exists($this, $finder) || ($this->_behaviors && $this->_behaviors->hasFinder($type));
2411: }
2412:
2413: /**
2414: * Calls a finder method directly and applies it to the passed query,
2415: * if no query is passed a new one will be created and returned
2416: *
2417: * @param string $type name of the finder to be called
2418: * @param \Cake\ORM\Query $query The query object to apply the finder options to
2419: * @param array $options List of options to pass to the finder
2420: * @return \Cake\ORM\Query
2421: * @throws \BadMethodCallException
2422: */
2423: public function callFinder($type, Query $query, array $options = [])
2424: {
2425: $query->applyOptions($options);
2426: $options = $query->getOptions();
2427: $finder = 'find' . $type;
2428: if (method_exists($this, $finder)) {
2429: return $this->{$finder}($query, $options);
2430: }
2431:
2432: if ($this->_behaviors && $this->_behaviors->hasFinder($type)) {
2433: return $this->_behaviors->callFinder($type, [$query, $options]);
2434: }
2435:
2436: throw new BadMethodCallException(
2437: sprintf('Unknown finder method "%s"', $type)
2438: );
2439: }
2440:
2441: /**
2442: * Provides the dynamic findBy and findByAll methods.
2443: *
2444: * @param string $method The method name that was fired.
2445: * @param array $args List of arguments passed to the function.
2446: * @return mixed
2447: * @throws \BadMethodCallException when there are missing arguments, or when
2448: * and & or are combined.
2449: */
2450: protected function _dynamicFinder($method, $args)
2451: {
2452: $method = Inflector::underscore($method);
2453: preg_match('/^find_([\w]+)_by_/', $method, $matches);
2454: if (empty($matches)) {
2455: // find_by_ is 8 characters.
2456: $fields = substr($method, 8);
2457: $findType = 'all';
2458: } else {
2459: $fields = substr($method, strlen($matches[0]));
2460: $findType = Inflector::variable($matches[1]);
2461: }
2462: $hasOr = strpos($fields, '_or_');
2463: $hasAnd = strpos($fields, '_and_');
2464:
2465: $makeConditions = function ($fields, $args) {
2466: $conditions = [];
2467: if (count($args) < count($fields)) {
2468: throw new BadMethodCallException(sprintf(
2469: 'Not enough arguments for magic finder. Got %s required %s',
2470: count($args),
2471: count($fields)
2472: ));
2473: }
2474: foreach ($fields as $field) {
2475: $conditions[$this->aliasField($field)] = array_shift($args);
2476: }
2477:
2478: return $conditions;
2479: };
2480:
2481: if ($hasOr !== false && $hasAnd !== false) {
2482: throw new BadMethodCallException(
2483: 'Cannot mix "and" & "or" in a magic finder. Use find() instead.'
2484: );
2485: }
2486:
2487: $conditions = [];
2488: if ($hasOr === false && $hasAnd === false) {
2489: $conditions = $makeConditions([$fields], $args);
2490: } elseif ($hasOr !== false) {
2491: $fields = explode('_or_', $fields);
2492: $conditions = [
2493: 'OR' => $makeConditions($fields, $args)
2494: ];
2495: } elseif ($hasAnd !== false) {
2496: $fields = explode('_and_', $fields);
2497: $conditions = $makeConditions($fields, $args);
2498: }
2499:
2500: return $this->find($findType, [
2501: 'conditions' => $conditions,
2502: ]);
2503: }
2504:
2505: /**
2506: * Handles behavior delegation + dynamic finders.
2507: *
2508: * If your Table uses any behaviors you can call them as if
2509: * they were on the table object.
2510: *
2511: * @param string $method name of the method to be invoked
2512: * @param array $args List of arguments passed to the function
2513: * @return mixed
2514: * @throws \BadMethodCallException
2515: */
2516: public function __call($method, $args)
2517: {
2518: if ($this->_behaviors && $this->_behaviors->hasMethod($method)) {
2519: return $this->_behaviors->call($method, $args);
2520: }
2521: if (preg_match('/^find(?:\w+)?By/', $method) > 0) {
2522: return $this->_dynamicFinder($method, $args);
2523: }
2524:
2525: throw new BadMethodCallException(
2526: sprintf('Unknown method "%s"', $method)
2527: );
2528: }
2529:
2530: /**
2531: * Returns the association named after the passed value if exists, otherwise
2532: * throws an exception.
2533: *
2534: * @param string $property the association name
2535: * @return \Cake\ORM\Association
2536: * @throws \RuntimeException if no association with such name exists
2537: */
2538: public function __get($property)
2539: {
2540: $association = $this->_associations->get($property);
2541: if (!$association) {
2542: throw new RuntimeException(sprintf(
2543: 'Undefined property `%s`. ' .
2544: 'You have not defined the `%s` association on `%s`.',
2545: $property,
2546: $property,
2547: static::class
2548: ));
2549: }
2550:
2551: return $association;
2552: }
2553:
2554: /**
2555: * Returns whether an association named after the passed value
2556: * exists for this table.
2557: *
2558: * @param string $property the association name
2559: * @return bool
2560: */
2561: public function __isset($property)
2562: {
2563: return $this->_associations->has($property);
2564: }
2565:
2566: /**
2567: * Get the object used to marshal/convert array data into objects.
2568: *
2569: * Override this method if you want a table object to use custom
2570: * marshalling logic.
2571: *
2572: * @return \Cake\ORM\Marshaller
2573: * @see \Cake\ORM\Marshaller
2574: */
2575: public function marshaller()
2576: {
2577: return new Marshaller($this);
2578: }
2579:
2580: /**
2581: * {@inheritDoc}
2582: *
2583: * By default all the associations on this table will be hydrated. You can
2584: * limit which associations are built, or include deeper associations
2585: * using the options parameter:
2586: *
2587: * ```
2588: * $article = $this->Articles->newEntity(
2589: * $this->request->getData(),
2590: * ['associated' => ['Tags', 'Comments.Users']]
2591: * );
2592: * ```
2593: *
2594: * You can limit fields that will be present in the constructed entity by
2595: * passing the `fields` option, which is also accepted for associations:
2596: *
2597: * ```
2598: * $article = $this->Articles->newEntity($this->request->getData(), [
2599: * 'fields' => ['title', 'body', 'tags', 'comments'],
2600: * 'associated' => ['Tags', 'Comments.Users' => ['fields' => 'username']]
2601: * ]
2602: * );
2603: * ```
2604: *
2605: * The `fields` option lets remove or restrict input data from ending up in
2606: * the entity. If you'd like to relax the entity's default accessible fields,
2607: * you can use the `accessibleFields` option:
2608: *
2609: * ```
2610: * $article = $this->Articles->newEntity(
2611: * $this->request->getData(),
2612: * ['accessibleFields' => ['protected_field' => true]]
2613: * );
2614: * ```
2615: *
2616: * By default, the data is validated before being passed to the new entity. In
2617: * the case of invalid fields, those will not be present in the resulting object.
2618: * The `validate` option can be used to disable validation on the passed data:
2619: *
2620: * ```
2621: * $article = $this->Articles->newEntity(
2622: * $this->request->getData(),
2623: * ['validate' => false]
2624: * );
2625: * ```
2626: *
2627: * You can also pass the name of the validator to use in the `validate` option.
2628: * If `null` is passed to the first param of this function, no validation will
2629: * be performed.
2630: *
2631: * You can use the `Model.beforeMarshal` event to modify request data
2632: * before it is converted into entities.
2633: */
2634: public function newEntity($data = null, array $options = [])
2635: {
2636: if ($data === null) {
2637: $class = $this->getEntityClass();
2638:
2639: return new $class([], ['source' => $this->getRegistryAlias()]);
2640: }
2641: if (!isset($options['associated'])) {
2642: $options['associated'] = $this->_associations->keys();
2643: }
2644: $marshaller = $this->marshaller();
2645:
2646: return $marshaller->one($data, $options);
2647: }
2648:
2649: /**
2650: * {@inheritDoc}
2651: *
2652: * By default all the associations on this table will be hydrated. You can
2653: * limit which associations are built, or include deeper associations
2654: * using the options parameter:
2655: *
2656: * ```
2657: * $articles = $this->Articles->newEntities(
2658: * $this->request->getData(),
2659: * ['associated' => ['Tags', 'Comments.Users']]
2660: * );
2661: * ```
2662: *
2663: * You can limit fields that will be present in the constructed entities by
2664: * passing the `fields` option, which is also accepted for associations:
2665: *
2666: * ```
2667: * $articles = $this->Articles->newEntities($this->request->getData(), [
2668: * 'fields' => ['title', 'body', 'tags', 'comments'],
2669: * 'associated' => ['Tags', 'Comments.Users' => ['fields' => 'username']]
2670: * ]
2671: * );
2672: * ```
2673: *
2674: * You can use the `Model.beforeMarshal` event to modify request data
2675: * before it is converted into entities.
2676: */
2677: public function newEntities(array $data, array $options = [])
2678: {
2679: if (!isset($options['associated'])) {
2680: $options['associated'] = $this->_associations->keys();
2681: }
2682: $marshaller = $this->marshaller();
2683:
2684: return $marshaller->many($data, $options);
2685: }
2686:
2687: /**
2688: * {@inheritDoc}
2689: *
2690: * When merging HasMany or BelongsToMany associations, all the entities in the
2691: * `$data` array will appear, those that can be matched by primary key will get
2692: * the data merged, but those that cannot, will be discarded.
2693: *
2694: * You can limit fields that will be present in the merged entity by
2695: * passing the `fields` option, which is also accepted for associations:
2696: *
2697: * ```
2698: * $article = $this->Articles->patchEntity($article, $this->request->getData(), [
2699: * 'fields' => ['title', 'body', 'tags', 'comments'],
2700: * 'associated' => ['Tags', 'Comments.Users' => ['fields' => 'username']]
2701: * ]
2702: * );
2703: * ```
2704: *
2705: * By default, the data is validated before being passed to the entity. In
2706: * the case of invalid fields, those will not be assigned to the entity.
2707: * The `validate` option can be used to disable validation on the passed data:
2708: *
2709: * ```
2710: * $article = $this->patchEntity($article, $this->request->getData(),[
2711: * 'validate' => false
2712: * ]);
2713: * ```
2714: *
2715: * You can use the `Model.beforeMarshal` event to modify request data
2716: * before it is converted into entities.
2717: *
2718: * When patching scalar values (null/booleans/string/integer/float), if the property
2719: * presently has an identical value, the setter will not be called, and the
2720: * property will not be marked as dirty. This is an optimization to prevent unnecessary field
2721: * updates when persisting entities.
2722: */
2723: public function patchEntity(EntityInterface $entity, array $data, array $options = [])
2724: {
2725: if (!isset($options['associated'])) {
2726: $options['associated'] = $this->_associations->keys();
2727: }
2728: $marshaller = $this->marshaller();
2729:
2730: return $marshaller->merge($entity, $data, $options);
2731: }
2732:
2733: /**
2734: * {@inheritDoc}
2735: *
2736: * Those entries in `$entities` that cannot be matched to any record in
2737: * `$data` will be discarded. Records in `$data` that could not be matched will
2738: * be marshalled as a new entity.
2739: *
2740: * When merging HasMany or BelongsToMany associations, all the entities in the
2741: * `$data` array will appear, those that can be matched by primary key will get
2742: * the data merged, but those that cannot, will be discarded.
2743: *
2744: * You can limit fields that will be present in the merged entities by
2745: * passing the `fields` option, which is also accepted for associations:
2746: *
2747: * ```
2748: * $articles = $this->Articles->patchEntities($articles, $this->request->getData(), [
2749: * 'fields' => ['title', 'body', 'tags', 'comments'],
2750: * 'associated' => ['Tags', 'Comments.Users' => ['fields' => 'username']]
2751: * ]
2752: * );
2753: * ```
2754: *
2755: * You can use the `Model.beforeMarshal` event to modify request data
2756: * before it is converted into entities.
2757: */
2758: public function patchEntities($entities, array $data, array $options = [])
2759: {
2760: if (!isset($options['associated'])) {
2761: $options['associated'] = $this->_associations->keys();
2762: }
2763: $marshaller = $this->marshaller();
2764:
2765: return $marshaller->mergeMany($entities, $data, $options);
2766: }
2767:
2768: /**
2769: * Validator method used to check the uniqueness of a value for a column.
2770: * This is meant to be used with the validation API and not to be called
2771: * directly.
2772: *
2773: * ### Example:
2774: *
2775: * ```
2776: * $validator->add('email', [
2777: * 'unique' => ['rule' => 'validateUnique', 'provider' => 'table']
2778: * ])
2779: * ```
2780: *
2781: * Unique validation can be scoped to the value of another column:
2782: *
2783: * ```
2784: * $validator->add('email', [
2785: * 'unique' => [
2786: * 'rule' => ['validateUnique', ['scope' => 'site_id']],
2787: * 'provider' => 'table'
2788: * ]
2789: * ]);
2790: * ```
2791: *
2792: * In the above example, the email uniqueness will be scoped to only rows having
2793: * the same site_id. Scoping will only be used if the scoping field is present in
2794: * the data to be validated.
2795: *
2796: * @param mixed $value The value of column to be checked for uniqueness.
2797: * @param array $options The options array, optionally containing the 'scope' key.
2798: * May also be the validation context, if there are no options.
2799: * @param array|null $context Either the validation context or null.
2800: * @return bool True if the value is unique, or false if a non-scalar, non-unique value was given.
2801: */
2802: public function validateUnique($value, array $options, array $context = null)
2803: {
2804: if ($context === null) {
2805: $context = $options;
2806: }
2807: $entity = new Entity(
2808: $context['data'],
2809: [
2810: 'useSetters' => false,
2811: 'markNew' => $context['newRecord'],
2812: 'source' => $this->getRegistryAlias()
2813: ]
2814: );
2815: $fields = array_merge(
2816: [$context['field']],
2817: isset($options['scope']) ? (array)$options['scope'] : []
2818: );
2819: $values = $entity->extract($fields);
2820: foreach ($values as $field) {
2821: if ($field !== null && !is_scalar($field)) {
2822: return false;
2823: }
2824: }
2825: $class = static::IS_UNIQUE_CLASS;
2826: $rule = new $class($fields, $options);
2827:
2828: return $rule($entity, ['repository' => $this]);
2829: }
2830:
2831: /**
2832: * Get the Model callbacks this table is interested in.
2833: *
2834: * By implementing the conventional methods a table class is assumed
2835: * to be interested in the related event.
2836: *
2837: * Override this method if you need to add non-conventional event listeners.
2838: * Or if you want you table to listen to non-standard events.
2839: *
2840: * The conventional method map is:
2841: *
2842: * - Model.beforeMarshal => beforeMarshal
2843: * - Model.buildValidator => buildValidator
2844: * - Model.beforeFind => beforeFind
2845: * - Model.beforeSave => beforeSave
2846: * - Model.afterSave => afterSave
2847: * - Model.afterSaveCommit => afterSaveCommit
2848: * - Model.beforeDelete => beforeDelete
2849: * - Model.afterDelete => afterDelete
2850: * - Model.afterDeleteCommit => afterDeleteCommit
2851: * - Model.beforeRules => beforeRules
2852: * - Model.afterRules => afterRules
2853: *
2854: * @return array
2855: */
2856: public function implementedEvents()
2857: {
2858: $eventMap = [
2859: 'Model.beforeMarshal' => 'beforeMarshal',
2860: 'Model.buildValidator' => 'buildValidator',
2861: 'Model.beforeFind' => 'beforeFind',
2862: 'Model.beforeSave' => 'beforeSave',
2863: 'Model.afterSave' => 'afterSave',
2864: 'Model.afterSaveCommit' => 'afterSaveCommit',
2865: 'Model.beforeDelete' => 'beforeDelete',
2866: 'Model.afterDelete' => 'afterDelete',
2867: 'Model.afterDeleteCommit' => 'afterDeleteCommit',
2868: 'Model.beforeRules' => 'beforeRules',
2869: 'Model.afterRules' => 'afterRules',
2870: ];
2871: $events = [];
2872:
2873: foreach ($eventMap as $event => $method) {
2874: if (!method_exists($this, $method)) {
2875: continue;
2876: }
2877: $events[$event] = $method;
2878: }
2879:
2880: return $events;
2881: }
2882:
2883: /**
2884: * {@inheritDoc}
2885: *
2886: * @param \Cake\ORM\RulesChecker $rules The rules object to be modified.
2887: * @return \Cake\ORM\RulesChecker
2888: */
2889: public function buildRules(RulesChecker $rules)
2890: {
2891: return $rules;
2892: }
2893:
2894: /**
2895: * Gets a SaveOptionsBuilder instance.
2896: *
2897: * @param array $options Options to parse by the builder.
2898: * @return \Cake\ORM\SaveOptionsBuilder
2899: */
2900: public function getSaveOptionsBuilder(array $options = [])
2901: {
2902: return new SaveOptionsBuilder($this, $options);
2903: }
2904:
2905: /**
2906: * Loads the specified associations in the passed entity or list of entities
2907: * by executing extra queries in the database and merging the results in the
2908: * appropriate properties.
2909: *
2910: * ### Example:
2911: *
2912: * ```
2913: * $user = $usersTable->get(1);
2914: * $user = $usersTable->loadInto($user, ['Articles.Tags', 'Articles.Comments']);
2915: * echo $user->articles[0]->title;
2916: * ```
2917: *
2918: * You can also load associations for multiple entities at once
2919: *
2920: * ### Example:
2921: *
2922: * ```
2923: * $users = $usersTable->find()->where([...])->toList();
2924: * $users = $usersTable->loadInto($users, ['Articles.Tags', 'Articles.Comments']);
2925: * echo $user[1]->articles[0]->title;
2926: * ```
2927: *
2928: * The properties for the associations to be loaded will be overwritten on each entity.
2929: *
2930: * @param \Cake\Datasource\EntityInterface|array $entities a single entity or list of entities
2931: * @param array $contain A `contain()` compatible array.
2932: * @see \Cake\ORM\Query::contain()
2933: * @return \Cake\Datasource\EntityInterface|array
2934: */
2935: public function loadInto($entities, array $contain)
2936: {
2937: return (new LazyEagerLoader)->loadInto($entities, $contain, $this);
2938: }
2939:
2940: /**
2941: * {@inheritDoc}
2942: */
2943: protected function validationMethodExists($method)
2944: {
2945: return method_exists($this, $method) || $this->behaviors()->hasMethod($method);
2946: }
2947:
2948: /**
2949: * Returns an array that can be used to describe the internal state of this
2950: * object.
2951: *
2952: * @return array
2953: */
2954: public function __debugInfo()
2955: {
2956: $conn = $this->getConnection();
2957: $associations = $this->_associations;
2958: $behaviors = $this->_behaviors;
2959:
2960: return [
2961: 'registryAlias' => $this->getRegistryAlias(),
2962: 'table' => $this->getTable(),
2963: 'alias' => $this->getAlias(),
2964: 'entityClass' => $this->getEntityClass(),
2965: 'associations' => $associations ? $associations->keys() : false,
2966: 'behaviors' => $behaviors ? $behaviors->loaded() : false,
2967: 'defaultConnection' => static::defaultConnectionName(),
2968: 'connectionName' => $conn ? $conn->configName() : null
2969: ];
2970: }
2971: }
2972: