Api4 - Prevent developer error mixing up the `addValue` and `addWhere` functions

diff --git a/Civi/Api4/Action/Setting/Set.php b/Civi/Api4/Action/Setting/Set.php
index cd8413331f7341b059ac3332c27b0c1b3400bb8d..753a51876e3af362df72d1990c14a09e744c42d3 100644 (file)
--- a/Civi/Api4/Action/Setting/Set.php
+++ b/Civi/Api4/Action/Setting/Set.php
@@ -22,6 +22,8 @@ use Civi\Api4\Generic\Result;
  */
 class Set extends AbstractSettingAction {
 
+  use \Civi\Api4\Generic\Traits\GetSetValueTrait;
+
   /**
    * Setting names/values to set.
    *
@@ -51,15 +53,4 @@ class Set extends AbstractSettingAction {
     }
   }
 
-  /**
-   * Add an item to the values array
-   * @param string $settingName
-   * @param mixed $value
-   * @return $this
-   */
-  public function addValue($settingName, $value) {
-    $this->values[$settingName] = $value;
-    return $this;
-  }
-
 }

diff --git a/Civi/Api4/Generic/AbstractCreateAction.php b/Civi/Api4/Generic/AbstractCreateAction.php
index c1f88ad9ac622f4bbed05280dd8aa2056dc5a94f..b807f38a316152dd27aa558d0e70409d1bc40912 100644 (file)
--- a/Civi/Api4/Generic/AbstractCreateAction.php
+++ b/Civi/Api4/Generic/AbstractCreateAction.php
@@ -26,6 +26,8 @@ use Civi\Api4\Utils\CoreUtil;
  */
 abstract class AbstractCreateAction extends AbstractAction {
 
+  use Traits\GetSetValueTrait;
+
   /**
    * Field values to set for the new $ENTITY.
    *
@@ -33,25 +35,6 @@ abstract class AbstractCreateAction extends AbstractAction {
    */
   protected $values = [];
 
-  /**
-   * @param string $fieldName
-   * @return mixed|null
-   */
-  public function getValue(string $fieldName) {
-    return $this->values[$fieldName] ?? NULL;
-  }
-
-  /**
-   * Add a field value.
-   * @param string $fieldName
-   * @param mixed $value
-   * @return $this
-   */
-  public function addValue(string $fieldName, $value) {
-    $this->values[$fieldName] = $value;
-    return $this;
-  }
-
   /**
    * @throws \CRM_Core_Exception
    * @throws \Civi\API\Exception\UnauthorizedException

diff --git a/Civi/Api4/Generic/AbstractUpdateAction.php b/Civi/Api4/Generic/AbstractUpdateAction.php
index d4b78a13eb0b1307c2163c512a97cb8d85de8498..4c5942fe371262fa38601203c50976e0a8de2e53 100644 (file)
--- a/Civi/Api4/Generic/AbstractUpdateAction.php
+++ b/Civi/Api4/Generic/AbstractUpdateAction.php
@@ -28,6 +28,8 @@ use Civi\Api4\Utils\CoreUtil;
  */
 abstract class AbstractUpdateAction extends AbstractBatchAction {
 
+  use Traits\GetSetValueTrait;
+
   /**
    * Field values to update.
    *
@@ -107,27 +109,6 @@ abstract class AbstractUpdateAction extends AbstractBatchAction {
     $result->exchangeArray($this->updateRecords($items));
   }
 
-  /**
-   * @param string $fieldName
-   *
-   * @return mixed|null
-   */
-  public function getValue(string $fieldName) {
-    return $this->values[$fieldName] ?? NULL;
-  }
-
-  /**
-   * Add an item to the values array.
-   *
-   * @param string $fieldName
-   * @param mixed $value
-   * @return $this
-   */
-  public function addValue(string $fieldName, $value) {
-    $this->values[$fieldName] = $value;
-    return $this;
-  }
-
   /**
    * @throws \CRM_Core_Exception
    */

diff --git a/Civi/Api4/Generic/BasicGetFieldsAction.php b/Civi/Api4/Generic/BasicGetFieldsAction.php
index 0b10f4f6a163e2c700818f91dd799435a3255636..82dd6e0e5f57419a6141703dd75d9f0731ddbb6e 100644 (file)
--- a/Civi/Api4/Generic/BasicGetFieldsAction.php
+++ b/Civi/Api4/Generic/BasicGetFieldsAction.php
@@ -32,6 +32,8 @@ use Civi\Api4\Utils\CoreUtil;
  */
 class BasicGetFieldsAction extends BasicGetAction {
 
+  use Traits\GetSetValueTrait;
+
   /**
    * Fetch option lists for fields?
    *
@@ -206,17 +208,6 @@ class BasicGetFieldsAction extends BasicGetAction {
     return $sub[$this->action] ?? $this->action;
   }
 
-  /**
-   * Add an item to the values array
-   * @param string $fieldName
-   * @param mixed $value
-   * @return $this
-   */
-  public function addValue(string $fieldName, $value) {
-    $this->values[$fieldName] = $value;
-    return $this;
-  }
-
   /**
    * Helper function to retrieve options from an option group (for non-DAO entities).
    *

diff --git a/Civi/Api4/Generic/CheckAccessAction.php b/Civi/Api4/Generic/CheckAccessAction.php
index a3cd5dc0a3924bc61c293701df14dd0e491555be..21094e15ccf4dfeca293db06978a0c68ddbf3dd8 100644 (file)
--- a/Civi/Api4/Generic/CheckAccessAction.php
+++ b/Civi/Api4/Generic/CheckAccessAction.php
@@ -24,6 +24,8 @@ use Civi\Api4\Utils\CoreUtil;
  */
 class CheckAccessAction extends AbstractAction {
 
+  use Traits\GetSetValueTrait;
+
   /**
    * @var string
    * @required
@@ -59,15 +61,4 @@ class CheckAccessAction extends AbstractAction {
     return TRUE;
   }
 
-  /**
-   * Add an item to the values array
-   * @param string $fieldName
-   * @param mixed $value
-   * @return $this
-   */
-  public function addValue(string $fieldName, $value) {
-    $this->values[$fieldName] = $value;
-    return $this;
-  }
-
 }

diff --git a/Civi/Api4/Generic/Traits/GetSetValueTrait.php b/Civi/Api4/Generic/Traits/GetSetValueTrait.php
new file mode 100644 (file)
index 0000000..fb9649e
--- /dev/null
+++ b/Civi/Api4/Generic/Traits/GetSetValueTrait.php
@@ -0,0 +1,64 @@
+<?php
+
+/*
+ +--------------------------------------------------------------------+
+ | Copyright CiviCRM LLC. All rights reserved.                        |
+ |                                                                    |
+ | This work is published under the GNU AGPLv3 license with some      |
+ | permitted exceptions and without any warranty. For full license    |
+ | and copyright information, see https://civicrm.org/licensing       |
+ +--------------------------------------------------------------------+
+ */
+
+namespace Civi\Api4\Generic\Traits;
+
+/**
+ * Trait for actions with a `$values` array
+ */
+trait GetSetValueTrait {
+
+  /**
+   * Add an item to the values array.
+   *
+   * @param string $fieldName
+   * @param mixed $value
+   * @return $this
+   */
+  public function addValue(string $fieldName, $value) {
+    // Prevent accidentally using this function like `addWhere` which takes 3 args.
+    if ($value === '=' && func_num_args() > 2) {
+      throw new \CRM_Core_Exception('APIv4 function `addValue` incorrectly called with 3 arguments.');
+    }
+    $this->values[$fieldName] = $value;
+    return $this;
+  }
+
+  /**
+   * Overwrite all values
+   *
+   * @param array $values
+   * @return $this
+   */
+  public function setValues(array $values) {
+    $this->values = $values;
+    return $this;
+  }
+
+  /**
+   * Retrieve a single value
+   *
+   * @param string $fieldName
+   * @return mixed|null
+   */
+  public function getValue(string $fieldName) {
+    return $this->values[$fieldName] ?? NULL;
+  }
+
+  /**
+   * @return array
+   */
+  public function getValues() {
+    return $this->values;
+  }
+
+}