1: <?php
2: /**
3: * PHP version 5
4: * @package generalDriver
5: * @author Christian Schiffler <c.schiffler@cyberspectrum.de>
6: * @author Stefan Heimes <stefan_heimes@hotmail.com>
7: * @author Tristan Lins <tristan.lins@bit3.de>
8: * @copyright The MetaModels team.
9: * @license LGPL.
10: * @filesource
11: */
12:
13: namespace DcGeneral\Data;
14:
15: use DcGeneral\Exception\DcGeneralRuntimeException;
16:
17: /**
18: * Interface DataProviderInterface.
19: *
20: * This interface describes a data provider in DcGeneral.
21: *
22: * @package DcGeneral\Data
23: */
24: interface DataProviderInterface
25: {
26: /**
27: * Set base config with source and other necessary parameter.
28: *
29: * @param array $arrConfig The configuration to use.
30: *
31: * @return void
32: *
33: * @throws DcGeneralRuntimeException When no source has been defined.
34: */
35: public function setBaseConfig(array $arrConfig);
36:
37: /**
38: * Return an empty configuration object.
39: *
40: * @return ConfigInterface
41: */
42: public function getEmptyConfig();
43:
44: /**
45: * Fetch an empty single record (new model).
46: *
47: * @return ModelInterface
48: */
49: public function getEmptyModel();
50:
51: /**
52: * Fetch an empty single collection (new model list).
53: *
54: * @return CollectionInterface
55: */
56: public function getEmptyCollection();
57:
58: /**
59: * Fetch a single or first record by id or filter.
60: *
61: * If the model shall be retrieved by id, use $objConfig->setId() to populate the config with an Id.
62: *
63: * If the model shall be retrieved by filter, use $objConfig->setFilter() to populate the config with a filter.
64: *
65: * @param ConfigInterface $objConfig The configuration to use.
66: *
67: * @return ModelInterface
68: */
69: public function fetch(ConfigInterface $objConfig);
70:
71: /**
72: * Fetch all records (optional filtered, sorted and limited).
73: *
74: * This returns a collection of all models matching the config object. If idOnly is true, an array containing all
75: * matching ids is returned.
76: *
77: * @param ConfigInterface $objConfig The configuration to use.
78: *
79: * @return CollectionInterface|array
80: */
81: public function fetchAll(ConfigInterface $objConfig);
82:
83: /**
84: * Retrieve all unique values for the given property.
85: *
86: * The result set will be an array containing all unique values contained in the data provider.
87: * Note: this only re-ensembles really used values for at least one data set.
88: *
89: * The only information being interpreted from the passed config object is the first property to fetch and the
90: * filter definition.
91: *
92: * @param ConfigInterface $objConfig The filter config options.
93: *
94: * @return CollectionInterface
95: */
96: public function getFilterOptions(ConfigInterface $objConfig);
97:
98: /**
99: * Return the amount of total items (filtering may be used in the config).
100: *
101: * @param ConfigInterface $objConfig The configuration to use.
102: *
103: * @return int
104: */
105: public function getCount(ConfigInterface $objConfig);
106:
107: /**
108: * Save an item to the data provider.
109: *
110: * If the item does not have an Id yet, the save operation will add it as a new row to the database and
111: * populate the Id of the model accordingly.
112: *
113: * @param ModelInterface $objItem The model to save back.
114: *
115: * @return ModelInterface The passed model.
116: */
117: public function save(ModelInterface $objItem);
118:
119: /**
120: * Save a collection of items to the data provider.
121: *
122: * @param CollectionInterface $objItems The collection containing all items to be saved.
123: *
124: * @return void
125: */
126: public function saveEach(CollectionInterface $objItems);
127:
128: /**
129: * Delete an item.
130: *
131: * The given value may be either integer, string or an instance of Model
132: *
133: * @param mixed $item Id or the model itself, to delete.
134: *
135: * @return void
136: *
137: * @throws DcGeneralRuntimeException When an unusable object has been passed.
138: */
139: public function delete($item);
140:
141: /**
142: * Save a new version of a model.
143: *
144: * @param ModelInterface $objModel The model for which a new version shall be created.
145: *
146: * @param string $strUsername The username to attach to the version as creator.
147: *
148: * @return void
149: */
150: public function saveVersion(ModelInterface $objModel, $strUsername);
151:
152: /**
153: * Return a model based of the version information.
154: *
155: * @param mixed $mixID The ID of the record.
156: *
157: * @param mixed $mixVersion The ID of the version.
158: *
159: * @return ModelInterface
160: */
161: public function getVersion($mixID, $mixVersion);
162:
163: /**
164: * Return a list with all versions for the model with the given Id.
165: *
166: * @param mixed $mixID The ID of the row.
167: *
168: * @param boolean $blnOnlyActive If true, only active versions will get returned, if false all version will get
169: * returned.
170: *
171: * @return CollectionInterface
172: */
173: public function getVersions($mixID, $blnOnlyActive = false);
174:
175: /**
176: * Set a version as active.
177: *
178: * @param mixed $mixID The ID of the model.
179: *
180: * @param mixed $mixVersion The version number to set active.
181: *
182: * @return void
183: */
184: public function setVersionActive($mixID, $mixVersion);
185:
186: /**
187: * Retrieve the current active version for a model.
188: *
189: * @param mixed $mixID The ID of the model.
190: *
191: * @return mixed The current version number of the requested row.
192: */
193: public function getActiveVersion($mixID);
194:
195: /**
196: * Reset the fallback field.
197: *
198: * This clears the given property in all items in the data provider to an empty value.
199: *
200: * Documentation:
201: * Evaluation - fallback => If true the field can only be assigned once per table.
202: *
203: * @param string $strField The field to reset.
204: *
205: * @return void
206: */
207: public function resetFallback($strField);
208:
209: /**
210: * Check if the value is unique in the data provider.
211: *
212: * @param string $strField The field in which to test.
213: *
214: * @param mixed $varNew The value about to be saved.
215: *
216: * @param int $intId The (optional) id of the item currently in scope - pass null for new items.
217: *
218: * Documentation:
219: * Evaluation - unique => If true the field value cannot be saved if it exists already.
220: *
221: * @return boolean
222: */
223: public function isUniqueValue($strField, $varNew, $intId = null);
224:
225: /**
226: * Check if a property with the given name exists in the data provider.
227: *
228: * @param string $strField The name of the property to search.
229: *
230: * @return boolean
231: */
232: public function fieldExists($strField);
233:
234: /**
235: * Check if two models have the same values in all properties.
236: *
237: * @param ModelInterface $objModel1 The first model to compare.
238: *
239: * @param ModelInterface $objModel2 The second model to compare.
240: *
241: * @return boolean True - If both models are same, false if not.
242: */
243: public function sameModels($objModel1 , $objModel2);
244: }
245: