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\Datasource;
16:
17: /**
18: * Describes the methods that any class representing a data storage should
19: * comply with.
20: *
21: * @method $this setAlias(string $alias)
22: * @method string getAlias()
23: * @method $this setRegistryAlias(string $alias)
24: * @method string getRegistryAlias()
25: */
26: interface RepositoryInterface
27: {
28: /**
29: * Returns the table alias or sets a new one
30: *
31: * @deprecated 3.4.0 Use setAlias()/getAlias() instead.
32: * @param string|null $alias the new table alias
33: * @return string
34: */
35: public function alias($alias = null);
36:
37: /**
38: * Test to see if a Repository has a specific field/column.
39: *
40: * @param string $field The field to check for.
41: * @return bool True if the field exists, false if it does not.
42: */
43: public function hasField($field);
44:
45: /**
46: * Creates a new Query for this repository and applies some defaults based on the
47: * type of search that was selected.
48: *
49: * @param string $type the type of query to perform
50: * @param array|\ArrayAccess $options An array that will be passed to Query::applyOptions()
51: * @return \Cake\Datasource\QueryInterface
52: */
53: public function find($type = 'all', $options = []);
54:
55: /**
56: * Returns a single record after finding it by its primary key, if no record is
57: * found this method throws an exception.
58: *
59: * ### Example:
60: *
61: * ```
62: * $id = 10;
63: * $article = $articles->get($id);
64: *
65: * $article = $articles->get($id, ['contain' => ['Comments]]);
66: * ```
67: *
68: * @param mixed $primaryKey primary key value to find
69: * @param array|\ArrayAccess $options options accepted by `Table::find()`
70: * @throws \Cake\Datasource\Exception\RecordNotFoundException if the record with such id
71: * could not be found
72: * @return \Cake\Datasource\EntityInterface
73: * @see \Cake\Datasource\RepositoryInterface::find()
74: */
75: public function get($primaryKey, $options = []);
76:
77: /**
78: * Creates a new Query instance for this repository
79: *
80: * @return \Cake\Datasource\QueryInterface
81: */
82: public function query();
83:
84: /**
85: * Update all matching records.
86: *
87: * Sets the $fields to the provided values based on $conditions.
88: * This method will *not* trigger beforeSave/afterSave events. If you need those
89: * first load a collection of records and update them.
90: *
91: * @param string|array|callable|\Cake\Database\Expression\QueryExpression $fields A hash of field => new value.
92: * @param mixed $conditions Conditions to be used, accepts anything Query::where()
93: * can take.
94: * @return int Count Returns the affected rows.
95: */
96: public function updateAll($fields, $conditions);
97:
98: /**
99: * Deletes all records matching the provided conditions.
100: *
101: * This method will *not* trigger beforeDelete/afterDelete events. If you
102: * need those first load a collection of records and delete them.
103: *
104: * This method will *not* execute on associations' `cascade` attribute. You should
105: * use database foreign keys + ON CASCADE rules if you need cascading deletes combined
106: * with this method.
107: *
108: * @param mixed $conditions Conditions to be used, accepts anything Query::where()
109: * can take.
110: * @return int Returns the number of affected rows.
111: * @see \Cake\Datasource\RepositoryInterface::delete()
112: */
113: public function deleteAll($conditions);
114:
115: /**
116: * Returns true if there is any record in this repository matching the specified
117: * conditions.
118: *
119: * @param array|\ArrayAccess $conditions list of conditions to pass to the query
120: * @return bool
121: */
122: public function exists($conditions);
123:
124: /**
125: * Persists an entity based on the fields that are marked as dirty and
126: * returns the same entity after a successful save or false in case
127: * of any error.
128: *
129: * @param \Cake\Datasource\EntityInterface $entity the entity to be saved
130: * @param array|\ArrayAccess $options The options to use when saving.
131: * @return \Cake\Datasource\EntityInterface|false
132: */
133: public function save(EntityInterface $entity, $options = []);
134:
135: /**
136: * Delete a single entity.
137: *
138: * Deletes an entity and possibly related associations from the database
139: * based on the 'dependent' option used when defining the association.
140: *
141: * @param \Cake\Datasource\EntityInterface $entity The entity to remove.
142: * @param array|\ArrayAccess $options The options for the delete.
143: * @return bool success
144: */
145: public function delete(EntityInterface $entity, $options = []);
146:
147: /**
148: * Create a new entity + associated entities from an array.
149: *
150: * This is most useful when hydrating request data back into entities.
151: * For example, in your controller code:
152: *
153: * ```
154: * $article = $this->Articles->newEntity($this->request->getData());
155: * ```
156: *
157: * The hydrated entity will correctly do an insert/update based
158: * on the primary key data existing in the database when the entity
159: * is saved. Until the entity is saved, it will be a detached record.
160: *
161: * @param array|null $data The data to build an entity with.
162: * @param array $options A list of options for the object hydration.
163: * @return \Cake\Datasource\EntityInterface
164: */
165: public function newEntity($data = null, array $options = []);
166:
167: /**
168: * Create a list of entities + associated entities from an array.
169: *
170: * This is most useful when hydrating request data back into entities.
171: * For example, in your controller code:
172: *
173: * ```
174: * $articles = $this->Articles->newEntities($this->request->getData());
175: * ```
176: *
177: * The hydrated entities can then be iterated and saved.
178: *
179: * @param array $data The data to build an entity with.
180: * @param array $options A list of options for the objects hydration.
181: * @return \Cake\Datasource\EntityInterface[] An array of hydrated records.
182: */
183: public function newEntities(array $data, array $options = []);
184:
185: /**
186: * Merges the passed `$data` into `$entity` respecting the accessible
187: * fields configured on the entity. Returns the same entity after being
188: * altered.
189: *
190: * This is most useful when editing an existing entity using request data:
191: *
192: * ```
193: * $article = $this->Articles->patchEntity($article, $this->request->getData());
194: * ```
195: *
196: * @param \Cake\Datasource\EntityInterface $entity the entity that will get the
197: * data merged in
198: * @param array $data key value list of fields to be merged into the entity
199: * @param array $options A list of options for the object hydration.
200: * @return \Cake\Datasource\EntityInterface
201: */
202: public function patchEntity(EntityInterface $entity, array $data, array $options = []);
203:
204: /**
205: * Merges each of the elements passed in `$data` into the entities
206: * found in `$entities` respecting the accessible fields configured on the entities.
207: * Merging is done by matching the primary key in each of the elements in `$data`
208: * and `$entities`.
209: *
210: * This is most useful when editing a list of existing entities using request data:
211: *
212: * ```
213: * $article = $this->Articles->patchEntities($articles, $this->request->getData());
214: * ```
215: *
216: * @param \Cake\Datasource\EntityInterface[]|\Traversable $entities the entities that will get the
217: * data merged in
218: * @param array $data list of arrays to be merged into the entities
219: * @param array $options A list of options for the objects hydration.
220: * @return \Cake\Datasource\EntityInterface[]
221: */
222: public function patchEntities($entities, array $data, array $options = []);
223: }
224: