1: <?php
2:
3: namespace Alpha\Model;
4:
5: /**
6: * An interface that defines all of the active record methods that should be
7: * included in a provider that implements this interface.
8: *
9: * @since 1.1
10: *
11: * @author John Collins <dev@alphaframework.org>
12: * @license http://www.opensource.org/licenses/bsd-license.php The BSD License
13: * @copyright Copyright (c) 2015, John Collins (founder of Alpha Framework).
14: * All rights reserved.
15: *
16: * <pre>
17: * Redistribution and use in source and binary forms, with or
18: * without modification, are permitted provided that the
19: * following conditions are met:
20: *
21: * * Redistributions of source code must retain the above
22: * copyright notice, this list of conditions and the
23: * following disclaimer.
24: * * Redistributions in binary form must reproduce the above
25: * copyright notice, this list of conditions and the
26: * following disclaimer in the documentation and/or other
27: * materials provided with the distribution.
28: * * Neither the name of the Alpha Framework nor the names
29: * of its contributors may be used to endorse or promote
30: * products derived from this software without specific
31: * prior written permission.
32: *
33: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
34: * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
35: * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
36: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
37: * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
38: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
39: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
40: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
41: * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
42: * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
43: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
44: * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
45: * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
46: * </pre>
47: */
48: interface ActiveRecordProviderInterface
49: {
50: /**
51: * Gets the current connection singleton, or creates a new one if none exists.
52: *
53: * @return mixed
54: *
55: * @since 1.1
56: */
57: public static function getConnection();
58:
59: /**
60: * Disconnects the current database connection if one exists (self::$connection is set).
61: *
62: * @since 1.1
63: */
64: public static function disconnect();
65:
66: /**
67: * Returns the last database error string for the current connection.
68: *
69: * @since 1.1
70: *
71: * @return string
72: */
73: public static function getLastDatabaseError();
74:
75: /**
76: * Populates the record object with the properties retrived from the database for the record $OID.
77: *
78: * @param int $OID The object ID of the record to load.
79: * @param int $version Optionaly, provide the version to load that version from the [tablename]_history table.
80: *
81: * @since 1.1
82: *
83: * @throws Alpha\Exception\RecordFoundException
84: */
85: public function load($OID, $version = 0);
86:
87: /**
88: * Load all old versions (if any) of this record from the [tablename]_history table.
89: *
90: * @param int $OID The object ID of the record to load.
91: *
92: * @return array An array containing objects of this type of record object, order by version.
93: *
94: * @since 2.0
95: *
96: * @throws Alpha\Exception\RecordFoundException
97: */
98: public function loadAllOldVersions($OID);
99:
100: /**
101: * Populates the record object from the database table by the given attribute value.
102: *
103: * @param string $atribute The name of the attribute to load the record by.
104: * @param string $value The value of the attribute to load the record by.
105: * @param bool $ignoreClassType Default is false, set to true if you want to load from overloaded tables and ignore the class type
106: * @param array $loadAttributes The attributes to load from the database to this object (leave blank to load all attributes)
107: *
108: * @since 1.1
109: *
110: * @throws Alpha\Exception\RecordFoundException
111: */
112: public function loadByAttribute($attribute, $value, $ignoreClassType = false, $loadAttributes = array());
113:
114: /**
115: * Loads all of the record objects of this class into an array which is returned.
116: *
117: * @param int $start The start of the SQL LIMIT clause, useful for pagination.
118: * @param int $limit The amount (limit) of records to load, useful for pagination.
119: * @param string $orderBy The name of the field to sort the records by.
120: * @param string $order The order to sort the records by.
121: * @param bool $ignoreClassType Default is false, set to true if you want to load from overloaded tables and ignore the class type
122: *
123: * @return array An array containing objects of this type of record object.
124: *
125: * @since 1.1
126: *
127: * @throws Alpha\Exception\RecordFoundException
128: */
129: public function loadAll($start = 0, $limit = 0, $orderBy = 'OID', $order = 'ASC', $ignoreClassType = false);
130:
131: /**
132: * Loads all of the objects of this class by the specified attribute into an array which is returned.
133: *
134: * @param string $atribute The attribute to load the objects by.
135: * @param string $value The value of the attribute to load the objects by.
136: * @param int $start The start of the SQL LIMIT clause, useful for pagination.
137: * @param int $limit The amount (limit) of objects to load, useful for pagination.
138: * @param string $orderBy The name of the field to sort the objects by.
139: * @param string $order The order to sort the objects by.
140: * @param bool $ignoreClassType Default is false, set to true if you want to load from overloaded tables and ignore the class type.
141: * @param array $constructorArgs An optional array of contructor arguements to pass to the BOs that will be generated and returned. Supports a maximum of 5 arguements.
142: *
143: * @return array An array containing objects of this type of business object.
144: *
145: * @since 1.1
146: *
147: * @throws Alpha\Exception\RecordFoundException
148: * @throws Alpha\Exception\IllegalArguementException
149: */
150: public function loadAllByAttribute($attribute, $value, $start = 0, $limit = 0, $orderBy = 'OID', $order = 'ASC', $ignoreClassType = false, $constructorArgs = array());
151:
152: /**
153: * Loads all of the record objects of this class by the specified attributes into an array which is returned.
154: *
155: * @param array $atributes The attributes to load the records by.
156: * @param array $values The values of the attributes to load the records by.
157: * @param int $start The start of the SQL LIMIT clause, useful for pagination.
158: * @param int $limit The amount (limit) of records to load, useful for pagination.
159: * @param string $orderBy The name of the field to sort the records by.
160: * @param string $order The order to sort the records by.
161: * @param bool $ignoreClassType Default is false, set to true if you want to load from overloaded tables and ignore the class type
162: * @param array $constructorArgs An optional array of contructor arguements to pass to the BOs that will be generated and returned. Supports a maximum of 5 arguements.
163: *
164: * @return array An array containing objects of this type of record object.
165: *
166: * @since 1.1
167: *
168: * @throws Alpha\Exception\RecordFoundException
169: * @throws Alpha\Exception\IllegalArguementException
170: */
171: public function loadAllByAttributes($attributes = array(), $values = array(), $start = 0, $limit = 0, $orderBy = 'OID', $order = 'ASC', $ignoreClassType = false, $constructorArgs = array());
172:
173: /**
174: * Loads all of the record objects of this class that where updated (updated_ts value) on the date indicated.
175: *
176: * @param string $date The date for which to load the records updated on, in the format 'YYYY-MM-DD'.
177: * @param int $start The start of the SQL LIMIT clause, useful for pagination.
178: * @param int $limit The amount (limit) of records to load, useful for pagination.
179: * @param string $orderBy The name of the field to sort the records by.
180: * @param string $order The order to sort the records by.
181: * @param bool $ignoreClassType Default is false, set to true if you want to load from overloaded tables and ignore the class type
182: *
183: * @return array An array containing objects of this type of record object.
184: *
185: * @since 1.1
186: *
187: * @throws Alpha\Exception\RecordFoundException
188: */
189: public function loadAllByDayUpdated($date, $start = 0, $limit = 0, $orderBy = 'OID', $order = 'ASC', $ignoreClassType = false);
190:
191: /**
192: * Loads all of the specified attribute values of this class by the specified attribute into an
193: * array which is returned.
194: *
195: * @param string $attribute The attribute name to load the field values by.
196: * @param string $value The value of the attribute to load the field values by.
197: * @param string $returnAttribute The name of the attribute to return.
198: * @param string $order The order to sort the records by.
199: * @param bool $ignoreClassType Default is false, set to true if you want to load from overloaded tables and ignore the class type.
200: *
201: * @return array An array of field values.
202: *
203: * @since 1.1
204: *
205: * @throws Alpha\Exception\RecordFoundException
206: */
207: public function loadAllFieldValuesByAttribute($attribute, $value, $returnAttribute, $order = 'ASC', $ignoreClassType = false);
208:
209: /**
210: * Saves the record. If $this->OID is empty or null it will INSERT, otherwise UPDATE.
211: *
212: * @since 1.1
213: *
214: * @throws Alpha\Exception\FailedSaveException
215: * @throws Alpha\Exception\LockingException
216: * @throws Alpha\Exception\ValidationException
217: */
218: public function save();
219:
220: /**
221: * Saves the field specified with the value supplied. Only works for persistent BOs. Note that no Alpha type
222: * validation is performed with this method!
223: *
224: * @param string $attribute The name of the attribute to save.
225: * @param mixed $value The value of the attribute to save.
226: *
227: * @since 1.1
228: *
229: * @throws Alpha\Exception\IllegalArguementException
230: * @throws Alpha\Exception\FailedSaveException
231: */
232: public function saveAttribute($attribute, $value);
233:
234: /**
235: * Saves the object history to the [tablename]_history table. It always does an INSERT.
236: *
237: * @since 1.2
238: *
239: * @throws Alpha\Exception\FailedSaveException
240: */
241: public function saveHistory();
242:
243: /**
244: * Deletes the current object from the database.
245: *
246: * @since 1.1
247: *
248: * @throws Alpha\Exception\FailedDeleteException
249: */
250: public function delete();
251:
252: /**
253: * Gets the version_num of the object from the database (returns 0 if the BO is not saved yet).
254: *
255: * @return int
256: *
257: * @since 1.1
258: *
259: * @throws Alpha\Exception\RecordFoundException
260: */
261: public function getVersion();
262:
263: /**
264: * Builds a new database table for the BO class.
265: *
266: * @since 1.1
267: *
268: * @throws Alpha\Exception\AlphaException
269: */
270: public function makeTable();
271:
272: /**
273: * Builds a new database table for the BO class to store it's history.
274: *
275: * @since 1.2
276: *
277: * @throws AlphaException
278: */
279: public function makeHistoryTable();
280:
281: /**
282: * Re-builds the table if the model requirements have changed. All data is lost!
283: *
284: * @since 1.1
285: *
286: * @throws Alpha\Exception\AlphaException
287: */
288: public function rebuildTable();
289:
290: /**
291: * Drops the table if the model requirements have changed. All data is lost!
292: *
293: * @since 1.1
294: *
295: * @param string $tableName Optional table name, leave blank for the defined table for this class to be dropped
296: *
297: * @throws Alpha\Exception\AlphaException
298: */
299: public function dropTable($tableName = null);
300:
301: /**
302: * Adds in a new class property without loosing existing data (does an ALTER TABLE query on the
303: * database).
304: *
305: * @param string $propName The name of the new field to add to the database table.
306: *
307: * @since 1.1
308: *
309: * @throws Alpha\Exception\AlphaException
310: */
311: public function addProperty($propName);
312:
313: /**
314: * Gets the maximum OID value from the database for this class type.
315: *
316: * @return int The maximum OID value in the class table.
317: *
318: * @since 1.1
319: *
320: * @throws Alpha\Exception\AlphaException
321: */
322: public function getMAX();
323:
324: /**
325: * Gets the count from the database for the amount of objects of this class.
326: *
327: * @param array $atributes The attributes to count the objects by (optional).
328: * @param array $values The values of the attributes to count the objects by (optional).
329: *
330: * @return int
331: *
332: * @since 1.1
333: *
334: * @throws Alpha\Exception\AlphaException
335: */
336: public function getCount($attributes = array(), $values = array());
337:
338: /**
339: * Gets the count from the database for the amount of entries in the [tableName]_history table for this business object. Only call
340: * this method on classes where maintainHistory = true, otherwise an exception will be thrown.
341: *
342: * @return int
343: *
344: * @since 1.2
345: *
346: * @throws Alpha\Exception\AlphaException
347: */
348: public function getHistoryCount();
349:
350: /**
351: * Populate all of the enum options for this object from the database.
352: *
353: * @since 1.1
354: *
355: * @throws Alpha\Exception\AlphaException
356: */
357: public function setEnumOptions();
358:
359: /**
360: * Checks to see if the table exists in the database for the current business class.
361: *
362: * @param bool $checkHistoryTable Set to true if you want to check for the existance of the _history table for this DAO.
363: *
364: * @return bool
365: *
366: * @since 1.1
367: *
368: * @throws Alpha\Exception\AlphaException
369: */
370: public function checkTableExists($checkHistoryTable = false);
371:
372: /**
373: * Static method to check the database and see if the table for the indicated BO class name
374: * exists (assumes table name will be $BOClassName less "Object").
375: *
376: * @param string $BOClassName The name of the business object class we are checking.
377: * @param bool $checkHistoryTable Set to true if you want to check for the existance of the _history table for this DAO.
378: *
379: * @return bool
380: *
381: * @since 1.1
382: *
383: * @throws Alpha\Exception\AlphaException
384: * @throws Alpha\Exception\IllegalArguementException
385: */
386: public static function checkBOTableExists($BOClassName, $checkHistoryTable = false);
387:
388: /**
389: * Checks to see if the table in the database matches (for fields) the business class definition, i.e. if the
390: * database table is in sync with the class definition.
391: *
392: * @return bool
393: *
394: * @since 1.1
395: *
396: * @throws Alpha\Exception\AlphaException
397: */
398: public function checkTableNeedsUpdate();
399:
400: /**
401: * Returns an array containing any properties on the class which have not been created on the database
402: * table yet.
403: *
404: * @return array An array of missing fields in the database table.
405: *
406: * @since 1.1
407: *
408: * @throws Alpha\Exception\AlphaException
409: */
410: public function findMissingFields();
411:
412: /**
413: * Gets an array of all of the names of the active database indexes for this class.
414: *
415: * @return array An array of database indexes on this table.
416: *
417: * @since 1.1
418: *
419: * @throws Alpha\Exception\AlphaException
420: */
421: public function getIndexes();
422:
423: /**
424: * Creates a foreign key constraint (index) in the database on the given attribute.
425: *
426: * @param string $attributeName The name of the attribute to apply the index on.
427: * @param string $relatedClass The fully-qualified name of the related class.
428: * @param string $relatedClassAttribute The name of the field to relate to on the related class.
429: * @param bool $allowNullValues For foreign key indexes that don't allow null values, set this to false (default is true).
430: * @param string $indexName The optional name for the index, will calculate if not provided.
431: *
432: * @since 1.1
433: *
434: * @throws Alpha\Exception\FailedIndexCreateException
435: */
436: public function createForeignIndex($attributeName, $relatedClass, $relatedClassAttribute, $indexName = null);
437:
438: /**
439: * Creates a unique index in the database on the given attribute(s).
440: *
441: * @param string $attribute1Name The first attribute to mark unique in the database.
442: * @param string $attribute2Name The second attribute to mark unique in the databse (optional, use only for composite keys).
443: * @param string $attribute3Name The third attribute to mark unique in the databse (optional, use only for composite keys).
444: *
445: * @since 1.1
446: *
447: * @throws Alpha\Exception\FailedIndexCreateException
448: */
449: public function createUniqueIndex($attribute1Name, $attribute2Name = '', $attribute3Name = '');
450:
451: /**
452: * Reloads the object from the database, overwritting any attribute values in memory.
453: *
454: * @since 1.1
455: *
456: * @throws Alpha\Exception\AlphaException
457: */
458: public function reload();
459:
460: /**
461: * Checks that a record exists for the BO in the database.
462: *
463: * @param int $OID The Object ID of the object we want to see whether it exists or not.
464: *
465: * @return bool
466: *
467: * @since 1.1
468: *
469: * @throws Alpha\Exception\AlphaException
470: */
471: public function checkRecordExists($OID);
472:
473: /**
474: * Checks to see if the table name matches the classname, and if not if the table
475: * name matches the classname name of another BO, i.e. the table is used to store
476: * multiple types of BOs.
477: *
478: * @return bool
479: *
480: * @since 1.1
481: *
482: * @throws Alpha\Exception\BadBOTableNameException
483: */
484: public function isTableOverloaded();
485:
486: /**
487: * Starts a new database transaction.
488: *
489: * @since 1.1
490: *
491: * @throws Alpha\Exception\AlphaException
492: */
493: public static function begin();
494:
495: /**
496: * Commits the current database transaction.
497: *
498: * @since 1.1
499: *
500: * @throws Alpha\Exception\FailedSaveException
501: */
502: public static function commit();
503:
504: /**
505: * Aborts the current database transaction.
506: *
507: * @since 1.1
508: *
509: * @throws Alpha\Exception\AlphaException
510: */
511: public static function rollback();
512:
513: /**
514: * Provide the BO that we are going to map the data to from this provider.
515: *
516: * @param Alpha\Model\ActiveRecord $BO
517: *
518: * @since 1.1
519: */
520: public function setBO($BO);
521:
522: /**
523: * Returns a 2d array, where each element in the array is another array
524: * representing a database row.
525: *
526: * @param string $sqlQuery
527: *
528: * @throws Alpha\Exception\CustomQueryException
529: *
530: * @return array
531: *
532: * @since 1.1
533: */
534: public function query($sqlQuery);
535:
536: /**
537: * Check to see if the configured database exists.
538: *
539: * @return bool
540: *
541: * @since 2.0
542: */
543: public static function checkDatabaseExists();
544:
545: /**
546: * Creates the configured database.
547: *
548: * @throws Alpha\Exception\AlphaException
549: *
550: * @since 2.0
551: */
552: public static function createDatabase();
553:
554: /**
555: * Drops the configured database.
556: *
557: * @throws Alpha\Exception\AlphaException
558: *
559: * @since 2.0
560: */
561: public static function dropDatabase();
562: }
563: