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