From 4783c62630c14a477db963b647a70cd0a3598522 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Thu, 15 Jul 2021 23:16:01 -0700
Subject: [PATCH] (REF) APIv4 FieldSpec - Extract SqlSpecTrait (tableName,
 columnName, operators, sqlRenderer, sqlFilters)

---
 Civi/Api4/Service/Spec/FieldSpec.php | 107 +--------------------
 Civi/Schema/Traits/SqlSpecTrait.php  | 133 +++++++++++++++++++++++++++
 2 files changed, 137 insertions(+), 103 deletions(-)
 create mode 100644 Civi/Schema/Traits/SqlSpecTrait.php

diff --git a/Civi/Api4/Service/Spec/FieldSpec.php b/Civi/Api4/Service/Spec/FieldSpec.php
index 3fb247e15c..4f5006d931 100644
--- a/Civi/Api4/Service/Spec/FieldSpec.php
+++ b/Civi/Api4/Service/Spec/FieldSpec.php
@@ -14,6 +14,7 @@ namespace Civi\Api4\Service\Spec;
 
 use Civi\Schema\Traits\BasicSpecTrait;
 use Civi\Schema\Traits\GuiSpecTrait;
+use Civi\Schema\Traits\SqlSpecTrait;
 
 class FieldSpec {
 
@@ -23,6 +24,9 @@ class FieldSpec {
   // GuiSpecTrait: label, inputType, inputAttrs, helpPre, helpPost
   use GuiSpecTrait;
 
+  // SqlSpecTrait tableName, columnName, operators, sqlFilters
+  use SqlSpecTrait;
+
   /**
    * @var mixed
    */
@@ -53,11 +57,6 @@ class FieldSpec {
    */
   public $options;
 
-  /**
-   * @var string
-   */
-  public $tableName;
-
   /**
    * @var callable
    */
@@ -68,11 +67,6 @@ class FieldSpec {
    */
   public $dataType;
 
-  /**
-   * @var string[]
-   */
-  public $operators;
-
   /**
    * @var string
    */
@@ -88,11 +82,6 @@ class FieldSpec {
    */
   public $permission;
 
-  /**
-   * @var string
-   */
-  public $columnName;
-
   /**
    * @var bool
    */
@@ -103,17 +92,6 @@ class FieldSpec {
    */
   public $outputFormatters;
 
-  /**
-   * @var callable
-   */
-  public $sqlRenderer;
-
-  /**
-   * @var callable[]
-   */
-  public $sqlFilters;
-
-
   /**
    * Aliases for the valid data types
    *
@@ -268,16 +246,6 @@ class FieldSpec {
     return $this->permission;
   }
 
-  /**
-   * @param string[] $operators
-   * @return $this
-   */
-  public function setOperators($operators) {
-    $this->operators = $operators;
-
-    return $this;
-  }
-
   /**
    * @param callable[] $outputFormatters
    * @return $this
@@ -301,39 +269,6 @@ class FieldSpec {
     return $this;
   }
 
-  /**
-   * @param callable $sqlRenderer
-   * @return $this
-   */
-  public function setSqlRenderer($sqlRenderer) {
-    $this->sqlRenderer = $sqlRenderer;
-
-    return $this;
-  }
-
-  /**
-   * @param callable[] $sqlFilters
-   * @return $this
-   */
-  public function setSqlFilters($sqlFilters) {
-    $this->sqlFilters = $sqlFilters;
-
-    return $this;
-  }
-
-  /**
-   * @param callable $sqlFilter
-   * @return $this
-   */
-  public function addSqlFilter($sqlFilter) {
-    if (!$this->sqlFilters) {
-      $this->sqlFilters = [];
-    }
-    $this->sqlFilters[] = $sqlFilter;
-
-    return $this;
-  }
-
   /**
    * @param string $type
    * @return $this
@@ -354,23 +289,6 @@ class FieldSpec {
     return $this;
   }
 
-  /**
-   * @param string $tableName
-   * @return $this
-   */
-  public function setTableName($tableName) {
-    $this->tableName = $tableName;
-
-    return $this;
-  }
-
-  /**
-   * @return string
-   */
-  public function getTableName() {
-    return $this->tableName;
-  }
-
   /**
    * Add valid types that are not not part of \CRM_Utils_Type::dataTypes
    *
@@ -439,23 +357,6 @@ class FieldSpec {
     return $this;
   }
 
-  /**
-   * @return string|NULL
-   */
-  public function getColumnName(): ?string {
-    return $this->columnName;
-  }
-
-  /**
-   * @param string|null $columnName
-   *
-   * @return $this
-   */
-  public function setColumnName(?string $columnName) {
-    $this->columnName = $columnName;
-    return $this;
-  }
-
   /**
    * Gets all public variables, converted to snake_case
    *
diff --git a/Civi/Schema/Traits/SqlSpecTrait.php b/Civi/Schema/Traits/SqlSpecTrait.php
new file mode 100644
index 0000000000..f8e740ac5f
--- /dev/null
+++ b/Civi/Schema/Traits/SqlSpecTrait.php
@@ -0,0 +1,133 @@
+<?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\Schema\Traits;
+
+/**
+ * If a field is specifically stored in the database, then use SqlSpecTrait
+ * to describe how to read/write the field.
+ *
+ * @package Civi\Schema\Traits
+ */
+trait SqlSpecTrait {
+
+  /**
+   * SQL table which stores this field.
+   *
+   * @var string
+   */
+  public $tableName;
+
+  /**
+   * SQL column which stores this field.
+   *
+   * @var string
+   */
+  public $columnName;
+
+  /**
+   * If set, limits the operators that can be used on this field for "get"
+   * actions.
+   *
+   * @var string[]
+   */
+  public $operators;
+
+  /**
+   * @var callable
+   */
+  public $sqlRenderer;
+
+  /**
+   * Some fields use a callback to generate their SQL (for reading/searching).
+   *
+   * @var callable[]
+   */
+  public $sqlFilters;
+
+  /**
+   * @param string $tableName
+   *
+   * @return $this
+   */
+  public function setTableName($tableName) {
+    $this->tableName = $tableName;
+    return $this;
+  }
+
+  /**
+   * @return string
+   */
+  public function getTableName() {
+    return $this->tableName;
+  }
+
+  /**
+   * @return string|NULL
+   */
+  public function getColumnName(): ?string {
+    return $this->columnName;
+  }
+
+  /**
+   * @param string|null $columnName
+   *
+   * @return $this
+   */
+  public function setColumnName(?string $columnName) {
+    $this->columnName = $columnName;
+    return $this;
+  }
+
+  /**
+   * @param string[] $operators
+   *
+   * @return $this
+   */
+  public function setOperators($operators) {
+    $this->operators = $operators;
+    return $this;
+  }
+
+  /**
+   * @param callable $sqlRenderer
+   * @return $this
+   */
+  public function setSqlRenderer($sqlRenderer) {
+    $this->sqlRenderer = $sqlRenderer;
+    return $this;
+  }
+
+  /**
+   * @param callable[] $sqlFilters
+   *
+   * @return $this
+   */
+  public function setSqlFilters($sqlFilters) {
+    $this->sqlFilters = $sqlFilters;
+    return $this;
+  }
+
+  /**
+   * @param callable $sqlFilter
+   *
+   * @return $this
+   */
+  public function addSqlFilter($sqlFilter) {
+    if (!$this->sqlFilters) {
+      $this->sqlFilters = [];
+    }
+    $this->sqlFilters[] = $sqlFilter;
+
+    return $this;
+  }
+
+}
-- 
2.25.1