X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=api%2Fv3%2FJob.php;h=f1cc4997dee97583df954389a98c7666112bf485;hb=8319cf114f26e04bb7586cd253af9d97b8cb3859;hp=fff53bc31c8bd471ea846feaf39823e1672c4c01;hpb=6f2500ee7589360102875df4367568fe87485df6;p=civicrm-core.git

diff --git a/api/v3/Job.php b/api/v3/Job.php
index fff53bc31c..f1cc4997de 100644
--- a/api/v3/Job.php
+++ b/api/v3/Job.php
@@ -25,12 +25,11 @@
  | GNU Affero General Public License or the licensing of CiviCRM,     |
  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  +--------------------------------------------------------------------+
-*/
+ */
 
 /**
- * new version of civicrm apis. See blog post at
+ * new version of civicrm APIs. See blog post at
  * http://civicrm.org/node/131
- * @todo Write sth
  *
  * @package CiviCRM_APIv3
  * @subpackage API_Job
@@ -62,10 +61,9 @@ function _civicrm_api3_job_create_spec(&$params) {
  * @param array $params
  *   Associative array of property name/value pairs to insert in new job.
  *
- * @return success or error
- * {@getfields Job_create}
- * @access public
- * {@schema Core/Job.xml}
+ * @return array
+ *
+ *   {@getfields Job_create}
  */
 function civicrm_api3_job_create($params) {
   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -73,10 +71,12 @@ function civicrm_api3_job_create($params) {
 
 /**
  * Retrieve one or more job
- * @param array input parameters
- * @return  array api result array
- * {@getfields email_get}
- * @access public
+ *
+ * @param array $params
+ *   input parameters
+ * @return array
+ *
+ *   {@getfields email_get}
  */
 function civicrm_api3_job_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -87,10 +87,7 @@ function civicrm_api3_job_get($params) {
  *
  * @param array $params
  *
- * @return array API Result Array
  * {@getfields Job_delete}
- * @static void
- * @access public
  */
 function civicrm_api3_job_delete($params) {
   _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -101,15 +98,14 @@ function civicrm_api3_job_delete($params) {
  * and results are handled in the job log.
  *
  * @param array $params
- *   (reference ) input parameters.
- *
- * @return array API Result Array
- *
- * @static void
- * @access public
+ *   input parameters (unused).
  *
+ * @return array
+ *   API Result Array
  */
 function civicrm_api3_job_execute($params) {
+  // @noinspection PhpUnusedParameterInspection
+
   $facility = new CRM_Core_JobManager();
   $facility->execute(FALSE);
 
@@ -130,20 +126,14 @@ function _civicrm_api3_job_execute_spec(&$params) {
  * Geocode group of contacts based on given params
  *
  * @param array $params
- *   (reference ) input parameters.
- *
- * @return array API Result Array
- * {@getfields contact_geocode}
- *
- * @static void
- * @access public
- *
+ *   input parameters.
  *
+ * @return array
+ *   API Result Array
  */
 function civicrm_api3_job_geocode($params) {
   $gc = new CRM_Utils_Address_BatchUpdate($params);
 
-
   $result = $gc->run();
 
   if ($result['is_error'] == 0) {
@@ -164,7 +154,7 @@ function _civicrm_api3_job_geocode_spec(&$params) {
   $params['end'] = array('title' => 'End Date');
   $params['geocoding'] = array('title' => 'Geocode address?');
   $params['parse'] = array('title' => 'Parse street address?');
-  $params['throttle'] = array('title' => 'Throttle? if enabled, geocodes at a slow rate');
+  $params['throttle'] = array('title' => 'Throttle? if enabled, geo-codes at a slow rate');
 }
 
 /**
@@ -175,15 +165,12 @@ function _civicrm_api3_job_geocode_spec(&$params) {
  *                        now - the time to use, in YmdHis format
  *                            - makes testing a bit simpler since we can simulate past/future time
  *
- * @return boolean        true if success, else false
- * @static void
- * @access public
- *
+ * @return array
  */
 function civicrm_api3_job_send_reminder($params) {
   //note that $params['rowCount' can be overridden by one of the preferred syntaxes ($options['limit'] = x
   //It's not clear whether than syntax can be passed in via the UI config - but this keeps the pre 4.4.4 behaviour
-  // in that case (ie. makes it unconfigurable via the UI). Another approach would be to set a default of 0
+  // in that case (ie. makes it non-configurable via the UI). Another approach would be to set a default of 0
   // in the _spec function - but since that is a deprecated value it seems more contentious than this approach
   $params['rowCount'] = 0;
   $lock = new CRM_Core_Lock('civimail.job.EmailProcessor');
@@ -225,10 +212,7 @@ function _civicrm_api3_job_send_reminder(&$params) {
  *                        instanceId - Integer - the report instance ID
  *                        resetVal - Integer - should we reset form state (always true)?
  *
- * @return boolean        true if success, else false
- * @static void
- * @access public
- *
+ * @return array
  */
 function civicrm_api3_job_mail_report($params) {
   $result = CRM_Report_Utils_Report::processReport($params);
@@ -252,46 +236,33 @@ function civicrm_api3_job_mail_report($params) {
  *
  * @param array $params
  *
- * @return boolean        true if success, else false
- * @static
- * @access public
+ * @return array
  */
 function civicrm_api3_job_update_greeting($params) {
-
   if (isset($params['ct']) && isset($params['gt'])) {
-    $ct = $gt = array();
     $ct = explode(',', $params['ct']);
     $gt = explode(',', $params['gt']);
     foreach ($ct as $ctKey => $ctValue) {
       foreach ($gt as $gtKey => $gtValue) {
         $params['ct'] = trim($ctValue);
         $params['gt'] = trim($gtValue);
-        $result[] = CRM_Contact_BAO_Contact_Utils::updateGreeting($params);
+        CRM_Contact_BAO_Contact_Utils::updateGreeting($params);
       }
     }
   }
   else {
-    $result = CRM_Contact_BAO_Contact_Utils::updateGreeting($params);
-  }
-
-  foreach ($result as $resultKey => $resultValue) {
-    if ($resultValue['is_error'] == 0) {
-      //really we should rely on the exception mechanism here - but we need to test that before removing this line
-      return civicrm_api3_create_success();
-    }
-    else {
-      return civicrm_api3_create_error($resultValue['messages']);
-    }
+    CRM_Contact_BAO_Contact_Utils::updateGreeting($params);
   }
+  return civicrm_api3_create_success();
 }
 
 /**
  * Adjust Metadata for Get action
-*
-* The metadata is used for setting defaults, documentation & validation
-* @param array $params
-*   Array or parameters determined by getfields.
-*/
+ *
+ * The metadata is used for setting defaults, documentation & validation
+ * @param array $params
+ *   Array or parameters determined by getfields.
+ */
 function _civicrm_api3_job_update_greeting_spec(&$params) {
   $params['ct'] = array(
     'api.required' => 1,
@@ -299,9 +270,9 @@ function _civicrm_api3_job_update_greeting_spec(&$params) {
     'type' => CRM_Utils_Type::T_STRING,
   );
   $params['gt'] = array(
-      'api.required' => 1,
-      'title' => 'Greeting Type',
-      'type' => CRM_Utils_Type::T_STRING,
+    'api.required' => 1,
+    'title' => 'Greeting Type',
+    'type' => CRM_Utils_Type::T_STRING,
   );
 }
 
@@ -309,12 +280,7 @@ function _civicrm_api3_job_update_greeting_spec(&$params) {
  * Mass update pledge statuses
  *
  * @param array $params
- *   (reference ) input parameters.
- *
- * @return boolean        true if success, else false
- * @static
- * @access public
- *
+ * @return array
  */
 function civicrm_api3_job_process_pledge($params) {
   // *** Uncomment the next line if you want automated reminders to be sent
@@ -366,7 +332,7 @@ function civicrm_api3_job_process_sms($params) {
 }
 
 /**
- * Job to get mail responses from civimailing
+ * Job to get mail responses from civiMailing
  *
  * @param array $params
  *
@@ -405,7 +371,7 @@ function civicrm_api3_job_fetch_activities($params) {
     CRM_Utils_Mail_EmailProcessor::processActivities();
     $values = array();
     $lock->release();
-    return civicrm_api3_create_success($values, $params,'mailing','activities');
+    return civicrm_api3_create_success($values, $params, 'mailing', 'activities');
   }
   catch (Exception $e) {
     $lock->release();
@@ -419,8 +385,8 @@ function civicrm_api3_job_fetch_activities($params) {
  * @param array $params
  *   (reference ) input parameters.
  *
- * @return array (reference )        array of properties, if error an array with an error id and error message
- * @access public
+ * @return array
+ *   array of properties, if error an array with an error id and error message
  */
 function civicrm_api3_job_process_participant($params) {
   $result = CRM_Event_BAO_ParticipantStatusType::process($params);
@@ -444,9 +410,8 @@ function civicrm_api3_job_process_participant($params) {
  * @param array $params
  *   Input parameters NOT USED.
  *
- * @return boolean true if success, else false
- * @static void
- * @access public
+ * @return bool
+ *   true if success, else false
  */
 function civicrm_api3_job_process_membership($params) {
   $lock = new CRM_Core_Lock('civimail.job.updateMembership');
@@ -466,14 +431,13 @@ function civicrm_api3_job_process_membership($params) {
 }
 
 /**
- * This api checks and updates the status of all survey respondants.
+ * This api checks and updates the status of all survey respondents.
  *
  * @param array $params
  *   (reference ) input parameters.
  *
- * @return boolean        true if success, else false
- * @static void
- * @access public
+ * @return bool
+ *   true if success, else false
  */
 function civicrm_api3_job_process_respondent($params) {
   $result = CRM_Campaign_BAO_Survey::releaseRespondent($params);
@@ -492,17 +456,9 @@ function civicrm_api3_job_process_respondent($params) {
  * @param array $params
  *   Input parameters.
  *
- * Allowed @params array keys are:
- * {int     $rgid        rule group id}
- * {int     $gid         group id}
- * {string  mode        helps decide how to behave when there are conflicts.
- *                      A 'safe' value skips the merge if there are no conflicts. Does a force merge otherwise.}
- * {boolean auto_flip   wether to let api decide which contact to retain and which to delete.}
- *
- * @return array  API Result Array
+ * @return array
+ *   API Result Array
  *
- * @static void
- * @access public
  */
 function civicrm_api3_job_process_batch_merge($params) {
   $rgid = CRM_Utils_Array::value('rgid', $params);
@@ -521,6 +477,30 @@ function civicrm_api3_job_process_batch_merge($params) {
   }
 }
 
+/**
+ * @param $params
+ */
+function _civicrm_api3_job_process_batch_merge_spec(&$params) {
+  $params['rgid'] = array(
+    'title' => 'rule group id',
+    'type' => CRM_Utils_Type::T_INT,
+  );
+  $params['gid'] = array(
+    'title' => 'group id',
+    'type' => CRM_Utils_Type::T_INT,
+  );
+  $params['mode'] = array(
+    'title' => 'Mode',
+    'description' => 'helps decide how to behave when there are conflicts. A \'safe\' value skips the merge if there are no conflicts. Does a force merge otherwise.',
+    'type' => CRM_Utils_Type::T_STRING,
+  );
+  $params['auto_flip'] = array(
+    'title' => 'Auto Flip',
+    'description' => 'let the api decide which contact to retain and which to delete?',
+    'type' => CRM_Utils_Type::T_BOOLEAN,
+  );
+}
+
 /**
  * Runs handlePaymentCron method in the specified payment processor
  *
@@ -530,7 +510,6 @@ function civicrm_api3_job_process_batch_merge($params) {
  * Expected @params array keys are:
  * {string  'processor_name' - the name of the payment processor, eg: Sagepay}
  *
- * @access public
  */
 function civicrm_api3_job_run_payment_cron($params) {
 
@@ -561,19 +540,15 @@ function civicrm_api3_job_run_payment_cron($params) {
  * This api cleans up all the old session entries and temp tables. We recommend that sites run this on an hourly basis
  *
  * @param array $params
- *   (reference ) - sends in various config parameters to decide what needs to be cleaned.
- *
- * @return boolean  true if success, else false
- * @static void
- * @access public
+ *   Sends in various config parameters to decide what needs to be cleaned.
  */
 function civicrm_api3_job_cleanup($params) {
-  $session   = CRM_Utils_Array::value('session', $params, true );
-  $tempTable = CRM_Utils_Array::value('tempTables', $params, true );
-  $jobLog    = CRM_Utils_Array::value('jobLog', $params, true );
-  $prevNext  = CRM_Utils_Array::value('prevNext', $params, true );
-  $dbCache   = CRM_Utils_Array::value('dbCache', $params, false);
-  $memCache  = CRM_Utils_Array::value('memCache', $params, false);
+  $session   = CRM_Utils_Array::value('session', $params, TRUE);
+  $tempTable = CRM_Utils_Array::value('tempTables', $params, TRUE);
+  $jobLog    = CRM_Utils_Array::value('jobLog', $params, TRUE);
+  $prevNext  = CRM_Utils_Array::value('prevNext', $params, TRUE);
+  $dbCache   = CRM_Utils_Array::value('dbCache', $params, FALSE);
+  $memCache  = CRM_Utils_Array::value('memCache', $params, FALSE);
 
   if ($session || $tempTable || $prevNext) {
     CRM_Core_BAO_Cache::cleanup($session, $tempTable, $prevNext);
@@ -594,19 +569,17 @@ function civicrm_api3_job_cleanup($params) {
 
 /**
  * Set expired relationships to disabled.
- *
- * @param array $params
- *
+ * @param $params
  * @return array
+ * @throws \API_Exception
  */
 function civicrm_api3_job_disable_expired_relationships($params) {
+  /** @noinspection PhpUnusedParameterInspection */
   $result = CRM_Contact_BAO_Relationship::disableExpiredRelationships();
-  if ($result) {
-    return civicrm_api3_create_success();
-  }
-  else {
-    return civicrm_api3_create_error('Failed to disable all expired relationships.');
+  if (!$result) {
+    throw new API_Exception('Failed to disable all expired relationships.');
   }
+  return civicrm_api3_create_success();
 }
 
 /**
@@ -616,18 +589,18 @@ function civicrm_api3_job_disable_expired_relationships($params) {
  * and use the cache
  *
  * @param array $params
- *
  * @return array
+ * @throws \API_Exception
  */
 function civicrm_api3_job_group_rebuild($params) {
   $lock = new CRM_Core_Lock('civimail.job.groupRebuild');
   if (!$lock->isAcquired()) {
-    return civicrm_api3_create_error('Could not acquire lock, another EmailProcessor process is running');
+    throw new API_Exception('Could not acquire lock, another EmailProcessor process is running');
   }
 
   $limit = CRM_Utils_Array::value('limit', $params, 0);
 
-  CRM_Contact_BAO_GroupContactCache::loadAll(null, $limit);
+  CRM_Contact_BAO_GroupContactCache::loadAll(NULL, $limit);
   $lock->release();
 
   return civicrm_api3_create_success();