Merge pull request #27239 from totten/phpstorm-adaptive-path

phpstorm - Prefer to store generated hints in source-tree

.gitignore

@@ -70,6 +70,7 @@ tools/tests/reports/logfile.tap
 tools/tests/reports/testdox.html
 tools/tests/reports/testdox.txt
 tools/extensions/org.civicrm.contactlayout
+tools/extensions/phpstorm/.phpstorm.meta.php
 l10n
 vendor
 civicrm.settings.php

tools/extensions/phpstorm/Civi/PhpStorm/PhpStormMetadata.php

@@ -68,6 +68,15 @@ public function addExpectedArguments(string $for, int $index, string $argumentSe
     return $this;
   }
 
+  /**
+   * @param string $for
+   * @return $this
+   */
+  public function addExitPoint(string $for) {
+    $this->buffer .= "exitPoint($for);\n";
+    return $this;
+  }
+
   /**
    * @param string $for
    * @param array $map
@@ -89,6 +98,9 @@ public function addOverrideMap(string $for, array $map) {
    */
   public function write(): void {
     $path = phpstorm_metadata_dir();
+    if ($path === NULL) {
+      return;
+    }
 
     if (file_exists($path) && !is_dir($path)) {
       unlink($path);

tools/extensions/phpstorm/Civi/PhpStorm/StaticGenerator.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Civi\PhpStorm;
+
+use Civi\Core\Service\AutoService;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+
+/**
+ * Generate simple/static mappings.
+ *
+ * This could be committed directly, but generating via PhpStormMetadata means that we get the same
+ * install/upgrade/uninstall workflow as the others. (No special carve-outs per-file.)
+ *
+ * @service civi.phpstorm.static
+ */
+class StaticGenerator extends AutoService implements EventSubscriberInterface {
+
+  public static function getSubscribedEvents() {
+    return ['civi.phpstorm.flush' => 'generate'];
+  }
+
+  public function generate() {
+    $builder = new PhpStormMetadata('static', __CLASS__);
+    $builder->addExitPoint('\CRM_Utils_System::civiExit()');
+    $builder->write();
+  }
+
+}

tools/extensions/phpstorm/phpstorm.civix.php

@@ -6,10 +6,10 @@
  * The ExtensionUtil class provides small stubs for accessing resources of this
  * extension.
  */
-class CRM_Phpstorm_ExtensionUtil {
+class CRM_PhpStorm_ExtensionUtil {
   const SHORT_NAME = 'phpstorm';
   const LONG_NAME = 'phpstorm';
-  const CLASS_PREFIX = 'CRM_Phpstorm';
+  const CLASS_PREFIX = 'CRM_PhpStorm';
 
   /**
    * Translate a string using the extension's domain.
@@ -77,7 +77,7 @@ public static function findClass($suffix) {
 
 }
 
-use CRM_Phpstorm_ExtensionUtil as E;
+use CRM_PhpStorm_ExtensionUtil as E;
 
 /**
  * (Delegated) Implements hook_civicrm_config().

tools/extensions/phpstorm/phpstorm.php

@@ -4,7 +4,7 @@
 
 require_once 'phpstorm.civix.php';
 // phpcs:disable
-use CRM_Phpstorm_ExtensionUtil as E;
+use CRM_PhpStorm_ExtensionUtil as E;
 // phpcs:enable
 
 /**
@@ -17,8 +17,28 @@
  *
  * @return string
  */
-function phpstorm_metadata_dir(): string {
-  return \Civi::paths()->getPath('[civicrm.files]/.phpstorm.meta.php');
+function phpstorm_metadata_dir(): ?string {
+  $candidates = _phpstorm_metadata_dirs();
+  foreach ($candidates as $candidate) {
+    if (file_exists($candidate) && is_writable($candidate)) {
+      return $candidate;
+    }
+    if (!file_exists($candidate) && is_writable(dirname($candidate))) {
+      return $candidate;
+    }
+  }
+  \Civi::log()->error("Failed to find writeable folder for PhpStorm metadata. Candidates: " . implode(",", $candidates));
+  return NULL;
+}
+
+function _phpstorm_metadata_dirs(): array {
+  $dirs = [];
+  if (CRM_Utils_Constant::value('CIVICRM_PHPSTORM_METADATA')) {
+    $dirs[] = CRM_Utils_Constant::value('CIVICRM_PHPSTORM_METADATA');
+  }
+  $dirs[] = E::path('.phpstorm.meta.php');
+  $dirs[] = \Civi::paths()->getPath('[civicrm.files]/.phpstorm.meta.php');
+  return $dirs;
 }
 
 /**
@@ -43,9 +63,20 @@ function phpstorm_civicrm_managed(&$entities, $modules) {
   }
 }
 
-function phpstorm_civicrm_uninstall() {
-  $dir = phpstorm_metadata_dir();
-  if (file_exists($dir)) {
-    CRM_Utils_File::cleanDir($dir, TRUE);
+function phpstorm_civicrm_enable(): void {
+  // Remove any stale files from old versions.
+  _phpstorm_cleanup();
+}
+
+function phpstorm_civicrm_uninstall(): void {
+  _phpstorm_cleanup();
+}
+
+function _phpstorm_cleanup(): void {
+  $dirs = _phpstorm_metadata_dirs();
+  foreach ($dirs as $dir) {
+    if (file_exists($dir)) {
+      CRM_Utils_File::cleanDir($dir, TRUE);
+    }
   }
 }