From c9380d75f8726aa69f32b1159330fb720a8f1c02 Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Fri, 25 Aug 2023 19:29:20 -0700
Subject: [PATCH] phpstorm - Generate hints about civicrm_api3()

---
 .../phpstorm/Civi/PhpStorm/Api3Generator.php  | 43 +++++++++++++++++++
 1 file changed, 43 insertions(+)
 create mode 100644 tools/extensions/phpstorm/Civi/PhpStorm/Api3Generator.php

diff --git a/tools/extensions/phpstorm/Civi/PhpStorm/Api3Generator.php b/tools/extensions/phpstorm/Civi/PhpStorm/Api3Generator.php
new file mode 100644
index 0000000000..777e3d1989
--- /dev/null
+++ b/tools/extensions/phpstorm/Civi/PhpStorm/Api3Generator.php
@@ -0,0 +1,43 @@
+<?php
+
+namespace Civi\PhpStorm;
+
+use Civi\Core\Service\AutoService;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+
+/**
+ * @service civi.phpstorm.api3
+ */
+class Api3Generator extends AutoService implements EventSubscriberInterface {
+
+  public static function getSubscribedEvents() {
+    return [
+      'civi.phpstorm.flush' => 'generate',
+    ];
+  }
+
+  public function generate() {
+    /*
+     * FIXME: PHPSTORM_META doesn't seem to support compound dynamic arguments
+     * so even if you give it separate lists like
+     * ```
+     * expectedArguments(\civicrm_api4('Contact'), 1, 'a', 'b');
+     * expectedArguments(\civicrm_api4('Case'), 1, 'c', 'd');
+     * ```
+     * It doesn't differentiate them and always offers a,b,c,d for every entity.
+     * If they ever fix that upstream we could fetch a different list of actions per entity,
+     * but for now there's no point.
+     */
+
+    $entities = \civicrm_api3('entity', 'get', []);
+    $actions = ['create', 'delete', 'get', 'getactions', 'getcount', 'getfield', 'getfields', 'getlist', 'getoptions', 'getrefcount', 'getsingle', 'getunique', 'getvalue', 'replace', 'validate'];
+
+    $builder = new PhpStormMetadata('api3', __CLASS__);
+    $builder->registerArgumentsSet('api3Entities', ...$entities['values']);
+    $builder->registerArgumentsSet('api3Actions', ...$actions);
+    $builder->addExpectedArguments('\civicrm_api3()', 0, 'api3Entities');
+    $builder->addExpectedArguments('\civicrm_api3()', 1, 'api3Actions');
+    $builder->write();
+  }
+
+}
-- 
2.25.1