      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: ?>