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