From 797ef33882d284b6ae3789651883e135a714509f Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Mon, 7 Aug 2023 16:33:53 -0700
Subject: [PATCH] Define `Top` helper to load classes regardless of namespace
 prefixing

Currently, `cv` has a list of php-scoper rules to exclude certain classes from prefixing.
The same list has to be adapted to use in `civix` - so, presumbly, they'll have to be
sync'd over time.

The main reason for this is to allow the PHAR to call-out to the UF during bootstrap -- and
each UF has a different list of rules.

In theory, we could drop these rules -- and replace any lines like
`drupal_bootstrap()` with `Top::call('drupal_bootstrap')`. Then there would be no
need to keep the rules in sync.

Additionally, it would allow `cv.phar` to take advantage of libraries (like `symfony/event`)
that might be dual-purpose. (Ex: cv.phar and UF both have `EventDispatcher`s; and you want
to add listeners to both of them.)
---
 lib/src/Top.php | 93 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 lib/src/Top.php

diff --git a/lib/src/Top.php b/lib/src/Top.php
new file mode 100644
index 0000000..5c55118
--- /dev/null
+++ b/lib/src/Top.php
@@ -0,0 +1,93 @@
+<?php
+
+namespace Civi\Cv;
+
+class Top {
+
+  /**
+   * @var string|null
+   */
+  private static $prefixRegex;
+
+  /**
+   * Call a top-level function or method
+   *
+   * @param string|string[] $callable
+   *   Ex: 'drupal_bootstrap'
+   *   Ex: '\drupal_bootstrap'
+   *   Ex: ['Drupal', 'service']
+   *   Note: All symbols are implicitly relative to top-level namespace.
+   * @param mixed[] $args
+   * @return mixed
+   */
+  public static function call($callable, ...$args) {
+    $callable = static::symbol($callable);
+    return call_user_func_array($callable, $args);
+  }
+
+  /**
+   * Instantiate an object (based on the top-level classname).
+   *
+   * @param string $class
+   *   Ex: 'Symfony\Contracts\EventDispatcher\EventDispatcher'
+   *   Ex: '\Symfony\Contracts\EventDispatcher\EventDispatcher'
+   *   Note: All symbols are implicitly relative to top-level namespace.
+   * @param mixed[] $args
+   * @return object
+   */
+  public static function create($class, ...$args) {
+    $class = static::symbol($class);
+    return new $class(...$args);
+  }
+
+  /**
+   * Evaluate a symbol, returning the top-level version of that symbol.
+   *
+   * @param string|string[] $symbol
+   *   Ex: 'Drupal', '\Symfony', ['\Drupal', 'service'], 'Drupal::service'
+   * @return string|string[]
+   *   The same symbol, ut without any php-scoper prefixes.
+   */
+  public static function symbol($symbol) {
+    if (is_string($symbol)) {
+      // Translate function or class
+      if (static::$prefixRegex === NULL) {
+        static::$prefixRegex = static::createPrefixRegex();
+      }
+      $result = preg_replace(static::$prefixRegex, '\\', $symbol);
+      if ($result[0] !== '\\') {
+        $result = '\\' . $result;
+      }
+      return $result;
+    }
+    elseif (is_array($symbol)) {
+      // Translate class
+      $symbol[0] = static::symbol($symbol[0]);
+      return $symbol;
+    }
+    else {
+      return $symbol;
+    }
+  }
+
+  /**
+   * Build a string to match the php-scoper prefix.
+   *
+   * @return string
+   */
+  protected static function createPrefixRegex(): string {
+    $parts = explode('\\', static::class);
+    $topNS = $parts[0];
+
+    // Are we running in a scoped PHAR?
+    if ($topNS[0] === '_' || substr($topNS, -4) === 'Phar') {
+      // In `box`+`php-scoper`, default prefix is dynamic value like '_HumbugXYZ'.
+      // Most of my projects use an explicit prefix like 'MyAppPhar'
+      return ';^\\\?' . preg_quote($parts[0], ';') . '\\\;';
+    }
+    else {
+      return ';^\\\;';
+    }
+  }
+
+}