From 61cb60ca1b19ca1780380a44334f35e16ffa0777 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Wed, 23 Nov 2022 14:18:56 -0800
Subject: [PATCH] Add example+test for 'entity-types-php@1'

To some extent, there's implicit coverage because `search_kit` uses
`entity-types-php@1`.  But this goes a bit further, ensuring that the
entity-type metadata is maintained consistently across different stages of
lifecycle (enable/disable/uninstall) and styles of interaction (eg local-only
phpunit and multi-process cv CLI).
---
 .../example/CRM/Shimmy/DAO/ShimThing.php      | 189 ++++++++++++++++++
 mixin/entity-types-php@1/example/make-dao.php |  67 +++++++
 .../example/tests/mixin/EntityTypesTest.php   |  50 +++++
 .../CRM/Shimmy/ShimThing.entityType.php       |  10 +
 .../xml/schema/CRM/Shimmy/ShimThing.xml       |  38 ++++
 5 files changed, 354 insertions(+)
 create mode 100644 mixin/entity-types-php@1/example/CRM/Shimmy/DAO/ShimThing.php
 create mode 100644 mixin/entity-types-php@1/example/make-dao.php
 create mode 100644 mixin/entity-types-php@1/example/tests/mixin/EntityTypesTest.php
 create mode 100644 mixin/entity-types-php@1/example/xml/schema/CRM/Shimmy/ShimThing.entityType.php
 create mode 100644 mixin/entity-types-php@1/example/xml/schema/CRM/Shimmy/ShimThing.xml

diff --git a/mixin/entity-types-php@1/example/CRM/Shimmy/DAO/ShimThing.php b/mixin/entity-types-php@1/example/CRM/Shimmy/DAO/ShimThing.php
new file mode 100644
index 0000000000..895876eec7
--- /dev/null
+++ b/mixin/entity-types-php@1/example/CRM/Shimmy/DAO/ShimThing.php
@@ -0,0 +1,189 @@
+<?php
+
+/**
+ * @package CRM
+ * @copyright CiviCRM LLC https://civicrm.org/licensing
+ *
+ * Generated from /xml/schema/CRM/Shimmy/ShimThing.xml
+ * DO NOT EDIT.  Generated by CRM_Core_CodeGen
+ * (GenCodeChecksum:1043dfe0f6d600e56520a94c3fb6f89d)
+ */
+
+/**
+ * Database access object for the ShimThing entity.
+ */
+class CRM_Shimmy_DAO_ShimThing extends CRM_Core_DAO {
+  const EXT = 'civicrm';
+  const TABLE_ADDED = '';
+
+  /**
+   * Static instance to hold the table name.
+   *
+   * @var string
+   */
+  public static $_tableName = 'civicrm_shim_thing';
+
+  /**
+   * Icon associated with this entity.
+   *
+   * @var string
+   */
+  public static $_icon = 'fa-clone';
+
+  /**
+   * Should CiviCRM log any modifications to this table in the civicrm_log table.
+   *
+   * @var bool
+   */
+  public static $_log = TRUE;
+
+  /**
+   * Unique ShimThing ID
+   *
+   * @var int|string|null
+   *   (SQL type: int unsigned)
+   *   Note that values will be retrieved from the database as a string.
+   */
+  public $id;
+
+  /**
+   * Unique name for the shim thing
+   *
+   * @var string
+   *   (SQL type: varchar(255))
+   *   Note that values will be retrieved from the database as a string.
+   */
+  public $name;
+
+  /**
+   * Class constructor.
+   */
+  public function __construct() {
+    $this->__table = 'civicrm_shim_thing';
+    parent::__construct();
+  }
+
+  /**
+   * Returns localized title of this entity.
+   *
+   * @param bool $plural
+   *   Whether to return the plural version of the title.
+   */
+  public static function getEntityTitle($plural = FALSE) {
+    return $plural ? ts('Shim Things') : ts('Shim Thing');
+  }
+
+  /**
+   * Returns all the column names of this table
+   *
+   * @return array
+   */
+  public static function &fields() {
+    if (!isset(Civi::$statics[__CLASS__]['fields'])) {
+      Civi::$statics[__CLASS__]['fields'] = [
+        'id' => [
+          'name' => 'id',
+          'type' => CRM_Utils_Type::T_INT,
+          'title' => ts('ShimThing ID'),
+          'description' => ts('Unique ShimThing ID'),
+          'required' => TRUE,
+          'where' => 'civicrm_shim_thing.id',
+          'table_name' => 'civicrm_shim_thing',
+          'entity' => 'ShimThing',
+          'bao' => 'CRM_Shimmy_DAO_ShimThing',
+          'localizable' => 0,
+          'readonly' => TRUE,
+          'add' => '1.0',
+        ],
+        'name' => [
+          'name' => 'name',
+          'type' => CRM_Utils_Type::T_STRING,
+          'title' => ts('ShimThing Name'),
+          'description' => ts('Unique name for the shim thing'),
+          'required' => TRUE,
+          'maxlength' => 255,
+          'size' => CRM_Utils_Type::HUGE,
+          'where' => 'civicrm_shim_thing.name',
+          'table_name' => 'civicrm_shim_thing',
+          'entity' => 'ShimThing',
+          'bao' => 'CRM_Shimmy_DAO_ShimThing',
+          'localizable' => 0,
+          'html' => [
+            'type' => 'Text',
+          ],
+          'add' => '1.0',
+        ],
+      ];
+      CRM_Core_DAO_AllCoreTables::invoke(__CLASS__, 'fields_callback', Civi::$statics[__CLASS__]['fields']);
+    }
+    return Civi::$statics[__CLASS__]['fields'];
+  }
+
+  /**
+   * Return a mapping from field-name to the corresponding key (as used in fields()).
+   *
+   * @return array
+   *   Array(string $name => string $uniqueName).
+   */
+  public static function &fieldKeys() {
+    if (!isset(Civi::$statics[__CLASS__]['fieldKeys'])) {
+      Civi::$statics[__CLASS__]['fieldKeys'] = array_flip(CRM_Utils_Array::collect('name', self::fields()));
+    }
+    return Civi::$statics[__CLASS__]['fieldKeys'];
+  }
+
+  /**
+   * Returns the names of this table
+   *
+   * @return string
+   */
+  public static function getTableName() {
+    return self::$_tableName;
+  }
+
+  /**
+   * Returns if this table needs to be logged
+   *
+   * @return bool
+   */
+  public function getLog() {
+    return self::$_log;
+  }
+
+  /**
+   * Returns the list of fields that can be imported
+   *
+   * @param bool $prefix
+   *
+   * @return array
+   */
+  public static function &import($prefix = FALSE) {
+    $r = CRM_Core_DAO_AllCoreTables::getImports(__CLASS__, 'shim_thing', $prefix, []);
+    return $r;
+  }
+
+  /**
+   * Returns the list of fields that can be exported
+   *
+   * @param bool $prefix
+   *
+   * @return array
+   */
+  public static function &export($prefix = FALSE) {
+    $r = CRM_Core_DAO_AllCoreTables::getExports(__CLASS__, 'shim_thing', $prefix, []);
+    return $r;
+  }
+
+  /**
+   * Returns the list of indices
+   *
+   * @param bool $localize
+   *
+   * @return array
+   */
+  public static function indices($localize = TRUE) {
+    $indices = [];
+    return ($localize && !empty($indices)) ? CRM_Core_DAO_AllCoreTables::multilingualize(__CLASS__, $indices) : $indices;
+  }
+
+}
diff --git a/mixin/entity-types-php@1/example/make-dao.php b/mixin/entity-types-php@1/example/make-dao.php
new file mode 100644
index 0000000000..ef6293321c
--- /dev/null
+++ b/mixin/entity-types-php@1/example/make-dao.php
@@ -0,0 +1,67 @@
+<?php
+
+// Generate the example DAO for use with mixin testing.
+//
+// Doesn't use GenCode.php because it's not really core.
+// Doesn't use generate:entity-boilerplate because it's not a full extension.
+// Roll a hard dice.
+
+if (PHP_SAPI !== 'cli') {
+  die("This script can only be run from command line.");
+}
+
+$includes = [dirname(__DIR__, 3), dirname(__DIR__, 3) . '/packages'];
+ini_set('include_path', implode(PATH_SEPARATOR, $includes));
+date_default_timezone_set('UTC');
+define('CIVICRM_UF', 'Drupal');
+define('CIVICRM_UF_BASEURL', '/');
+define('CIVICRM_L10N_BASEDIR', getenv('CIVICRM_L10N_BASEDIR') ? getenv('CIVICRM_L10N_BASEDIR') : __DIR__ . '/../l10n');
+$GLOBALS['civicrm_paths']['cms.root']['url'] = 'http://gencode.example.com/do-not-use';
+
+require_once 'CRM/Core/ClassLoader.php';
+CRM_Core_ClassLoader::singleton()->register();
+
+makeDAOs(__DIR__, __DIR__ . "/xml/schema/CRM/Shimmy/*.xml");
+
+/**
+ * @param string $basedir
+ *   Where to find XML's and put DAO's.
+ * @param string $xmlSchemasGlob
+ *   Expression to find XML's.
+ */
+function makeDAOs(string $basedir, string $xmlSchemasGlob): void {
+  $specification = new \CRM_Core_CodeGen_Specification();
+  $specification->buildVersion = \CRM_Utils_System::majorVersion();
+  $config = new \stdClass();
+  $config->phpCodePath = $basedir . '/';
+  $config->sqlCodePath = $basedir . '/sql/';
+  $config->database = [
+    'name' => '',
+    'attributes' => '',
+    'tableAttributes_modern' => 'ENGINE=InnoDB',
+    'tableAttributes_simple' => 'ENGINE=InnoDB',
+    'comment' => '',
+  ];
+  $config->tables = [];
+
+  foreach (glob($xmlSchemasGlob) as $xmlSchema) {
+    $dom = new \DomDocument();
+    $dom->loadXML(file_get_contents($xmlSchema));
+    $xml = simplexml_import_dom($dom);
+    if (!$xml) {
+      throw new \RuntimeException("There is an error in the XML for $xmlSchema");
+    }
+    $specification->getTable($xml, $config->database, $config->tables);
+    $name = (string) $xml->name;
+    $config->tables[$name]['name'] = $name;
+    $config->tables[$name]['sourceFile'] = \CRM_Utils_File::relativize($xmlSchema, $basedir);
+  }
+
+  foreach ($config->tables as $table) {
+    $dao = new \CRM_Core_CodeGen_DAO($config, (string) $table['name'], 'ts');
+    ob_start();
+    $dao->run();
+    ob_end_clean();
+    echo "Write " . $dao->getAbsFileName() . "\n";
+  }
+}
diff --git a/mixin/entity-types-php@1/example/tests/mixin/EntityTypesTest.php b/mixin/entity-types-php@1/example/tests/mixin/EntityTypesTest.php
new file mode 100644
index 0000000000..b8e3cc3595
--- /dev/null
+++ b/mixin/entity-types-php@1/example/tests/mixin/EntityTypesTest.php
@@ -0,0 +1,50 @@
+<?php
+
+namespace Civi\Shimmy\Mixins;
+
+/**
+ * Assert that the `settings/*.setting.php` mixin is working properly.
+ *
+ * This class defines the assertions to run when installing or uninstalling the extension.
+ * It use called as part of E2E_Shimmy_LifecycleTest.
+ *
+ * @see E2E_Shimmy_LifecycleTest
+ */
+class EntityTypesTest extends \PHPUnit\Framework\Assert {
+
+  const EXAMPLE_DAO = 'CRM_Shimmy_DAO_ShimThing';
+
+  const EXAMPLE_TABLE = 'civicrm_shim_thing';
+
+  const EXAMPLE_NAME = 'ShimThing';
+
+  public function testPreConditions($cv) {
+    $this->assertFileExists(static::getPath('/xml/schema/CRM/Shimmy/ShimThing.xml'), 'The shimmy extension must have *.xml.');
+    $this->assertFileExists(static::getPath('/xml/schema/CRM/Shimmy/ShimThing.entityType.php'), 'The shimmy extension must have *.entityTYpe.php.');
+    $this->assertFileExists(static::getPath('/CRM/Shimmy/DAO/ShimThing.php'), 'The shimmy extension must have DAO.');
+  }
+
+  public function testInstalled($cv) {
+    $this->assertEquals(self::EXAMPLE_NAME, $cv->phpCall('CRM_Core_DAO_AllCoreTables::getBriefName', [self::EXAMPLE_DAO]));
+    $this->assertEquals(self::EXAMPLE_TABLE, $cv->phpCall('CRM_Core_DAO_AllCoreTables::getTableForClass', [self::EXAMPLE_DAO]));
+    $this->assertEquals(self::EXAMPLE_NAME, $cv->phpCall('CRM_Core_DAO_AllCoreTables::getEntityNameForTable', [self::EXAMPLE_TABLE]));
+    $this->assertEquals('ShimThing ID', $cv->phpEval('return \CRM_Shimmy_DAO_ShimThing::fields()["id"]["title"];'));
+  }
+
+  public function testDisabled($cv) {
+    $this->assertEquals(NULL, $cv->phpCall('CRM_Core_DAO_AllCoreTables::getBriefName', [self::EXAMPLE_DAO]));
+    $this->assertEquals(NULL, $cv->phpCall('CRM_Core_DAO_AllCoreTables::getTableForClass', [self::EXAMPLE_DAO]));
+    $this->assertEquals(NULL, $cv->phpCall('CRM_Core_DAO_AllCoreTables::getEntityNameForTable', [self::EXAMPLE_TABLE]));
+  }
+
+  public function testUninstalled($cv) {
+    $this->assertEquals(NULL, $cv->phpCall('CRM_Core_DAO_AllCoreTables::getBriefName', [self::EXAMPLE_DAO]));
+    $this->assertEquals(NULL, $cv->phpCall('CRM_Core_DAO_AllCoreTables::getTableForClass', [self::EXAMPLE_DAO]));
+    $this->assertEquals(NULL, $cv->phpCall('CRM_Core_DAO_AllCoreTables::getEntityNameForTable', [self::EXAMPLE_TABLE]));
+  }
+
+  protected static function getPath($suffix = ''): string {
+    return dirname(__DIR__, 2) . $suffix;
+  }
+
+}
diff --git a/mixin/entity-types-php@1/example/xml/schema/CRM/Shimmy/ShimThing.entityType.php b/mixin/entity-types-php@1/example/xml/schema/CRM/Shimmy/ShimThing.entityType.php
new file mode 100644
index 0000000000..defea0e5f8
--- /dev/null
+++ b/mixin/entity-types-php@1/example/xml/schema/CRM/Shimmy/ShimThing.entityType.php
@@ -0,0 +1,10 @@
+<?php
+// This file declares a new entity type. For more details, see "hook_civicrm_entityTypes" at:
+// https://docs.civicrm.org/dev/en/latest/hooks/hook_civicrm_entityTypes
+return [
+  [
+    'name' => 'ShimThing',
+    'class' => 'CRM_Shimmy_DAO_ShimThing',
+    'table' => 'civicrm_shim_thing',
+  ],
+];
diff --git a/mixin/entity-types-php@1/example/xml/schema/CRM/Shimmy/ShimThing.xml b/mixin/entity-types-php@1/example/xml/schema/CRM/Shimmy/ShimThing.xml
new file mode 100644
index 0000000000..efe2f4551d
--- /dev/null
+++ b/mixin/entity-types-php@1/example/xml/schema/CRM/Shimmy/ShimThing.xml
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="iso-8859-1" ?>
+
+<table>
+  <base>CRM/Shimmy</base>
+  <class>ShimThing</class>
+  <name>civicrm_shim_thing</name>
+  <comment>ShimThing Example Entity</comment>
+  <log>true</log>
+  <icon>fa-clone</icon>
+
+  <field>
+    <name>id</name>
+    <title>ShimThing ID</title>
+    <type>int unsigned</type>
+    <required>true</required>
+    <comment>Unique ShimThing ID</comment>
+    <add>1.0</add>
+  </field>
+  <primaryKey>
+    <name>id</name>
+    <autoincrement>true</autoincrement>
+    <add>1.0</add>
+  </primaryKey>
+
+  <field>
+    <name>name</name>
+    <title>ShimThing Name</title>
+    <comment>Unique name for the shim thing</comment>
+    <required>true</required>
+    <type>varchar</type>
+    <length>255</length>
+    <html>
+      <type>Text</type>
+    </html>
+    <add>1.0</add>
+  </field>
+
+</table>
-- 
2.25.1