X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=CRM%2FCore%2FDAO.php;h=54f85cc25fe33d859eafdc00eb2d58455da2aa75;hb=0f9476b93e5fcac5d5486cdf4471efc2008f28d5;hp=e374d15e7424505471124b52868b295b9355c0d2;hpb=8ea180b7e15f28bc58a8cffa5378fb6337cb955c;p=civicrm-core.git

diff --git a/CRM/Core/DAO.php b/CRM/Core/DAO.php
index e374d15e74..54f85cc25f 100644
--- a/CRM/Core/DAO.php
+++ b/CRM/Core/DAO.php
@@ -23,7 +23,7 @@
   | GNU Affero General Public License or the licensing of CiviCRM,     |
   | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
   +--------------------------------------------------------------------+
-*/
+ */
 
 /**
  * Our base DAO class. All DAO classes should inherit from this class.
@@ -81,7 +81,6 @@ class CRM_Core_DAO extends DB_DataObject {
    * Class constructor
    *
    * @return \CRM_Core_DAO
-   * @access public
    */
   public function __construct() {
     $this->initialize();
@@ -130,7 +129,7 @@ class CRM_Core_DAO extends DB_DataObject {
       $required = TRUE;
     }
     if (!$required && $dbName != 'contact_id') {
-      $fkDAO = new $FKClassName;
+      $fkDAO = new $FKClassName();
       if ($fkDAO->find(TRUE)) {
         $this->$dbName = $fkDAO->id;
       }
@@ -222,8 +221,8 @@ class CRM_Core_DAO extends DB_DataObject {
 
         case CRM_Utils_Type::T_TIME:
           CRM_Core_Error::fatal('T_TIME shouldnt be used.');
-        //$object->$dbName='000000';
-        //break;
+          //$object->$dbName='000000';
+          //break;
         case CRM_Utils_Type::T_CCNUM:
           $this->$dbName = '4111 1111 1111 1111';
           break;
@@ -410,7 +409,7 @@ class CRM_Core_DAO extends DB_DataObject {
    *
    * @return array
    */
-  static function &fields() {
+  public static function &fields() {
     $result = NULL;
     return $result;
   }
@@ -418,7 +417,6 @@ class CRM_Core_DAO extends DB_DataObject {
   /**
    * Get/set an associative array of table columns
    *
-   * @param array key=>type array
    * @return array
    *   (associative)
    */
@@ -461,6 +459,31 @@ class CRM_Core_DAO extends DB_DataObject {
     return $this;
   }
 
+  /**
+   * Deletes items from table which match current objects variables
+   *
+   * Returns the true on success
+   *
+   * for example
+   *
+   * Designed to be extended
+   *
+   * $object = new mytable();
+   * $object->ID=123;
+   * echo $object->delete(); // builds a conditon
+   *
+   * $object = new mytable();
+   * $object->whereAdd('age > 12');
+   * $object->limit(1);
+   * $object->orderBy('age DESC');
+   * $object->delete(true); // dont use object vars, use the conditions, limit and order.
+   *
+   * @param bool $useWhere (optional) If DB_DATAOBJECT_WHEREADD_ONLY is passed in then
+   *             we will build the condition only using the whereAdd's.  Default is to
+   *             build the condition only using the object parameters.
+   *
+   *     * @return mixed Int (No. of rows affected) on success, false on failure, 0 on no data affected
+   */
   public function delete($useWhere = FALSE) {
     $result = parent::delete($useWhere);
 
@@ -505,8 +528,8 @@ class CRM_Core_DAO extends DB_DataObject {
    * @param array $params
    *   (reference ) associative array of name/value pairs.
    *
-   * @return boolean
-   *   did we copy all null values into the object
+   * @return bool
+   *   Did we copy all null values into the object
    */
   public function copyValues(&$params) {
     $fields = &$this->fields();
@@ -614,7 +637,7 @@ class CRM_Core_DAO extends DB_DataObject {
   }
 
   /**
-   * Get the size and maxLength attributes for this text field
+   * Get the size and maxLength attributes for this text field.
    * (or for all text fields) in the DAO object.
    *
    * @param string $class
@@ -671,7 +694,7 @@ class CRM_Core_DAO extends DB_DataObject {
    * @param string $fieldName
    *   The name of the field in the DAO.
    *
-   * @return boolean
+   * @return bool
    *   true if object exists
    */
   public static function objectExists($value, $daoName, $daoID, $fieldName = 'name') {
@@ -696,7 +719,7 @@ class CRM_Core_DAO extends DB_DataObject {
    * @param bool $i18nRewrite
    *   Whether to rewrite the query on multilingual setups.
    *
-   * @return boolean
+   * @return bool
    *   true if exists, else false
    */
   public static function checkFieldExists($tableName, $columnName, $i18nRewrite = TRUE) {
@@ -780,7 +803,7 @@ LIKE %1
    * @param string $tableName
    * @param string $constraint
    *
-   * @return boolean
+   * @return bool
    *   true if constraint exists, false otherwise
    */
   public static function checkConstraintExists($tableName, $constraint) {
@@ -808,7 +831,7 @@ LIKE %1
    *
    * @throws Exception
    *
-   * @return boolean
+   * @return bool
    *   true if CONSTRAINT keyword exists, false otherwise
    */
   public static function schemaRequiresRebuilding($tables = array("civicrm_contact")) {
@@ -844,7 +867,7 @@ LIKE %1
    * @param string $tableName
    * @param string $columnName
    *
-   * @return boolean
+   * @return bool
    *   true if in format, false otherwise
    */
   public static function checkFKConstraintInFormat($tableName, $columnName) {
@@ -873,7 +896,7 @@ LIKE %1
    * @param string $columnName
    * @param string $columnValue
    *
-   * @return boolean
+   * @return bool
    *   true if the value is always $columnValue, false otherwise
    */
   public static function checkFieldHasAlwaysValue($tableName, $columnName, $columnValue) {
@@ -890,7 +913,7 @@ LIKE %1
    * @param string $tableName
    * @param string $columnName
    *
-   * @return boolean
+   * @return bool
    *   true if if the value is always NULL, false otherwise
    */
   public static function checkFieldIsAlwaysNull($tableName, $columnName) {
@@ -906,7 +929,7 @@ LIKE %1
    *
    * @param string $tableName
    *
-   * @return boolean
+   * @return bool
    *   true if exists, else false
    */
   public static function checkTableExists($tableName) {
@@ -1018,7 +1041,7 @@ FROM   civicrm_domain
    * @param string $searchColumn
    *   Name of the column you want to search by.
    *
-   * @return boolean
+   * @return bool
    *   true if we found and updated the object, else false
    */
   public static function setFieldValue($daoName, $searchValue, $setColumn, $setValue, $searchColumn = 'id') {
@@ -1126,10 +1149,12 @@ FROM   civicrm_domain
    * @param bool $i18nRewrite
    * @param bool $trapException
    *
-   * @return CRM_Core_DAO
+   * @return CRM_Core_DAO|object
    *   object that holds the results of the query
+   *   NB - if this is defined as just returning a DAO phpstorm keeps pointing
+   *   out all the properties that are not part of the DAO
    */
-  static function &executeQuery(
+  public static function &executeQuery(
     $query,
     $params = array(),
     $abort = TRUE,
@@ -1160,7 +1185,7 @@ FROM   civicrm_domain
     if ($freeDAO ||
       preg_match('/^(insert|update|delete|create|drop|replace)/i', $queryStr)
     ) {
-      // we typically do this for insert/update/delete stataments OR if explicitly asked to
+      // we typically do this for insert/update/delete statements OR if explicitly asked to
       // free the dao
       $dao->free();
     }
@@ -1179,7 +1204,7 @@ FROM   civicrm_domain
    *   the result of the query if any
    *
    */
-  static function &singleValueQuery(
+  public static function &singleValueQuery(
     $query,
     $params = array(),
     $abort = TRUE,
@@ -1289,7 +1314,7 @@ FROM   civicrm_domain
   }
 
   /**
-   * make a shallow copy of an object
+   * make a shallow copy of an object.
    * and all the fields in the object
    *
    * @param string $daoName
@@ -1310,7 +1335,7 @@ FROM   civicrm_domain
    * @return CRM_Core_DAO
    *   the newly created copy of the object
    */
-  static function &copyGeneric($daoName, $criteria, $newData = NULL, $fieldsFix = NULL, $blockCopyOfDependencies = NULL) {
+  public static function &copyGeneric($daoName, $criteria, $newData = NULL, $fieldsFix = NULL, $blockCopyOfDependencies = NULL) {
     $object = new $daoName();
     if (!$newData) {
       $object->id = $criteria['id'];
@@ -1383,6 +1408,16 @@ FROM   civicrm_domain
     return $newObject;
   }
 
+  /**
+   * Cascade update through related entities.
+   *
+   * @param string $daoName
+   * @param $fromId
+   * @param $toId
+   * @param array $newData
+   *
+   * @return null
+   */
   public static function cascadeUpdate($daoName, $fromId, $toId, $newData = array()) {
     $object = new $daoName();
     $object->id = $fromId;
@@ -1463,7 +1498,7 @@ SELECT contact_id
    *   an object of type referenced by daoName
    */
   public static function commonRetrieveAll($daoName, $fieldIdName = 'id', $fieldId, &$details, $returnProperities = NULL) {
-    require_once(str_replace('_', DIRECTORY_SEPARATOR, $daoName) . ".php");
+    require_once str_replace('_', DIRECTORY_SEPARATOR, $daoName) . ".php";
     $object = new $daoName();
     $object->$fieldIdName = $fieldId;
 
@@ -1584,9 +1619,10 @@ SELECT contact_id
    * @param int $numObjects
    * @param bool $createOnly
    *
-   * @return
+   * @return object|array|NULL
+   *   NULL if $createOnly. A single object if $numObjects==1. Otherwise, an array of multiple objects.
    */
-  static function createTestObject(
+  public static function createTestObject(
     $daoName,
     $params = array(),
     $numObjects = 1,
@@ -1603,7 +1639,7 @@ SELECT contact_id
       'CRM_Core_DAO_StateProvince',
       'CRM_Core_DAO_Country',
       'CRM_Core_DAO_Domain',
-      'CRM_Financial_DAO_FinancialType'
+      'CRM_Financial_DAO_FinancialType',
       //because valid ones exist & we use pick them due to pseudoconstant can't reliably create & delete these
     );
 
@@ -1652,7 +1688,7 @@ SELECT contact_id
     }
 
     if ($createOnly) {
-      return;
+      return NULL;
     }
     elseif ($numObjects == 1) {
       return $objects[0];
@@ -1824,7 +1860,7 @@ SELECT contact_id
   public static function triggerRebuild($tableName = NULL, $force = FALSE) {
     $info = array();
 
-    $logging = new CRM_Logging_Schema;
+    $logging = new CRM_Logging_Schema();
     $logging->triggerInfo($info, $tableName, $force);
 
     CRM_Core_I18n_Schema::triggerInfo($info, $tableName);
@@ -1865,7 +1901,7 @@ SELECT contact_id
   public static function dropTriggers($tableName = NULL) {
     $info = array();
 
-    $logging = new CRM_Logging_Schema;
+    $logging = new CRM_Logging_Schema();
     $logging->triggerInfo($info, $tableName);
 
     // drop all existing triggers on all tables
@@ -2123,11 +2159,11 @@ SELECT contact_id
    *
    * @param string $fieldName
    * @param string $context
-   *   @see CRM_Core_DAO::buildOptionsContext.
+   * @see CRM_Core_DAO::buildOptionsContext
    * @param array $props
    *   whatever is known about this bao object.
    *
-   * @return Array|bool
+   * @return array|bool
    */
   public static function buildOptions($fieldName, $context = NULL, $props = array()) {
     // If a given bao does not override this function
@@ -2143,7 +2179,7 @@ SELECT contact_id
   public function getOptionLabels() {
     $fields = $this->fields();
     if ($fields === NULL) {
-      throw new Exception ('Cannot call getOptionLabels on CRM_Core_DAO');
+      throw new Exception('Cannot call getOptionLabels on CRM_Core_DAO');
     }
     foreach ($fields as $field) {
       $name = CRM_Utils_Array::value('name', $field);
@@ -2271,13 +2307,12 @@ SELECT contact_id
             }
             $escapedCriteria = array_map(array(
               'CRM_Core_DAO',
-              'escapeString'
+              'escapeString',
             ), $criteria);
             if (!$returnSanitisedArray) {
               return (sprintf('%s %s ("%s")', $fieldName, $operator, implode('", "', $escapedCriteria)));
             }
             return $escapedCriteria;
-            break;
 
           // binary operators
 
@@ -2314,7 +2349,7 @@ SELECT contact_id
       'BETWEEN',
       'NOT BETWEEN',
       'IS NOT NULL',
-      'IS NULL'
+      'IS NULL',
     );
   }