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: use ArrayAccess;
18: use JsonSerializable;
19:
20: /**
21: * Describes the methods that any class representing a data storage should
22: * comply with.
23: *
24: * In 4.x the following methods will officially be added to the interface:
25: *
26: * @method $this setHidden(array $properties, $merge = false)
27: * @method array getHidden()
28: * @method $this setVirtual(array $properties, $merge = false)
29: * @method array getVirtual()
30: * @method $this setDirty($property, $isDirty = true)
31: * @method bool isDirty($property = null)
32: * @method bool hasErrors($includeNested = true)
33: * @method array getErrors()
34: * @method array getError($field)
35: * @method array setErrors(array $fields, $overwrite = false)
36: * @method array setError($field, $errors, $overwrite = false)
37: * @method $this setAccess($property, $set)
38: * @method bool isAccessible($property)
39: * @method $this setSource($source)
40: * @method string getSource()
41: * @method array extractOriginal(array $properties)
42: * @method array extractOriginalChanged(array $properties)
43: * @method array getVisible()
44: *
45: * @property mixed $id Alias for commonly used primary key.
46: */
47: interface EntityInterface extends ArrayAccess, JsonSerializable
48: {
49: /**
50: * Sets one or multiple properties to the specified value
51: *
52: * @param string|array $property the name of property to set or a list of
53: * properties with their respective values
54: * @param mixed $value The value to set to the property or an array if the
55: * first argument is also an array, in which case will be treated as $options
56: * @param array $options options to be used for setting the property. Allowed option
57: * keys are `setter` and `guard`
58: * @return \Cake\Datasource\EntityInterface
59: */
60: public function set($property, $value = null, array $options = []);
61:
62: /**
63: * Returns the value of a property by name
64: *
65: * @param string $property the name of the property to retrieve
66: * @return mixed
67: */
68: public function &get($property);
69:
70: /**
71: * Returns whether this entity contains a property named $property
72: * regardless of if it is empty.
73: *
74: * @param string|array $property The property to check.
75: * @return bool
76: */
77: public function has($property);
78:
79: /**
80: * Removes a property or list of properties from this entity
81: *
82: * @param string|array $property The property to unset.
83: * @return \Cake\Datasource\EntityInterface
84: */
85: public function unsetProperty($property);
86:
87: /**
88: * Get/Set the hidden properties on this entity.
89: *
90: * If the properties argument is null, the currently hidden properties
91: * will be returned. Otherwise the hidden properties will be set.
92: *
93: * @param array|null $properties Either an array of properties to hide or null to get properties
94: * @return array|\Cake\Datasource\EntityInterface
95: */
96: public function hiddenProperties($properties = null);
97:
98: /**
99: * Get/Set the virtual properties on this entity.
100: *
101: * If the properties argument is null, the currently virtual properties
102: * will be returned. Otherwise the virtual properties will be set.
103: *
104: * @param array|null $properties Either an array of properties to treat as virtual or null to get properties
105: * @return array|\Cake\Datasource\EntityInterface
106: */
107: public function virtualProperties($properties = null);
108:
109: /**
110: * Get the list of visible properties.
111: *
112: * @return array A list of properties that are 'visible' in all representations.
113: */
114: public function visibleProperties();
115:
116: /**
117: * Returns an array with all the visible properties set in this entity.
118: *
119: * *Note* hidden properties are not visible, and will not be output
120: * by toArray().
121: *
122: * @return array
123: */
124: public function toArray();
125:
126: /**
127: * Returns an array with the requested properties
128: * stored in this entity, indexed by property name
129: *
130: * @param array $properties list of properties to be returned
131: * @param bool $onlyDirty Return the requested property only if it is dirty
132: * @return array
133: */
134: public function extract(array $properties, $onlyDirty = false);
135:
136: /**
137: * Sets the dirty status of a single property. If called with no second
138: * argument, it will return whether the property was modified or not
139: * after the object creation.
140: *
141: * When called with no arguments it will return whether or not there are any
142: * dirty property in the entity
143: *
144: * @deprecated 3.4.0 Use setDirty() and isDirty() instead.
145: * @param string|null $property the field to set or check status for
146: * @param bool|null $isDirty true means the property was changed, false means
147: * it was not changed and null will make the function return current state
148: * for that property
149: * @return bool whether the property was changed or not
150: */
151: public function dirty($property = null, $isDirty = null);
152:
153: /**
154: * Sets the entire entity as clean, which means that it will appear as
155: * no properties being modified or added at all. This is an useful call
156: * for an initial object hydration
157: *
158: * @return void
159: */
160: public function clean();
161:
162: /**
163: * Returns whether or not this entity has already been persisted.
164: * This method can return null in the case there is no prior information on
165: * the status of this entity.
166: *
167: * If called with a boolean, this method will set the status of this instance.
168: * Using `true` means that the instance has not been persisted in the database, `false`
169: * that it already is.
170: *
171: * @param bool|null $new Indicate whether or not this instance has been persisted.
172: * @return bool If it is known whether the entity was already persisted
173: * null otherwise
174: */
175: public function isNew($new = null);
176:
177: /**
178: * Sets the error messages for a field or a list of fields. When called
179: * without the second argument it returns the validation
180: * errors for the specified fields. If called with no arguments it returns
181: * all the validation error messages stored in this entity.
182: *
183: * When used as a setter, this method will return this entity instance for method
184: * chaining.
185: *
186: * @deprecated 3.4.0 Use setErrors() and getErrors() instead.
187: * @param string|array|null $field The field to get errors for.
188: * @param string|array|null $errors The errors to be set for $field
189: * @param bool $overwrite Whether or not to overwrite pre-existing errors for $field
190: * @return array|\Cake\Datasource\EntityInterface
191: */
192: public function errors($field = null, $errors = null, $overwrite = false);
193:
194: /**
195: * Stores whether or not a property value can be changed or set in this entity.
196: * The special property `*` can also be marked as accessible or protected, meaning
197: * that any other property specified before will take its value. For example
198: * `$entity->accessible('*', true)` means that any property not specified already
199: * will be accessible by default.
200: *
201: * @deprecated 3.4.0 Use setAccess() and isAccessible() instead.
202: * @param string|array $property Either a single or list of properties to change its accessibility.
203: * @param bool|null $set true marks the property as accessible, false will
204: * mark it as protected.
205: * @return \Cake\Datasource\EntityInterface|bool
206: */
207: public function accessible($property, $set = null);
208: }
209: