WIP: WordPress aware Container conrtact and Adapter

README.md

@@ -7,6 +7,7 @@ Foundation is a StellarWP Composer monorepo for reusable PHP packages intended f
 
 ## Repositories
 - [stellarwp/foundation-container](https://github.com/stellarwp/foundation-container)
+- [stellarwp/foundation-container-wordpress](https://github.com/stellarwp/foundation-container-wordpress)
 - [stellarwp/foundation-pipeline](https://github.com/stellarwp/foundation-pipeline)
 - [stellarwp/foundation-log](https://github.com/stellarwp/foundation-log)
 - [stellarwp/foundation-wpcli](https://github.com/stellarwp/foundation-wpcli)

composer.json

@@ -13,7 +13,7 @@
         "ext-curl": "*",
         "ext-exif": "*",
         "adbario/php-dot-notation": ">=2.5",
-        "lucatume/di52": ">=3.0",
+        "lucatume/di52": ">=4.1",
         "monolog/monolog": "^2.11",
         "psr/log": ">=1.0",
         "stellarwp/container-contract": "^1.1",
@@ -25,6 +25,7 @@
         "monorepo-php/monorepo": "^12.7",
         "nunomaduro/collision": "^8.9",
         "php-mock/php-mock-mockery": "^1.5",
+        "php-stubs/wordpress-stubs": ">=6.0",
         "phpstan/extension-installer": "^1.4",
         "phpstan/phpstan": "^2.2",
         "phpunit/phpunit": "^11.5",
@@ -34,6 +35,7 @@
     "replace": {
         "stellarwp/foundation-cli": "self.version",
         "stellarwp/foundation-container": "self.version",
+        "stellarwp/foundation-container-wordpress": "self.version",
         "stellarwp/foundation-log": "self.version",
         "stellarwp/foundation-pipeline": "self.version",
         "stellarwp/foundation-wpcli": "self.version"
@@ -43,6 +45,7 @@
     "autoload": {
         "psr-4": {
             "StellarWP\\Foundation\\Cli\\": "src/Cli/",
+            "StellarWP\\Foundation\\ContainerWordPress\\": "src/ContainerWordPress/",
             "StellarWP\\Foundation\\Container\\": "src/Container/",
             "StellarWP\\Foundation\\Log\\": "src/Log/",
             "StellarWP\\Foundation\\Pipeline\\": "src/Pipeline/",

phpstan.neon.dist

@@ -3,7 +3,13 @@ parameters:
     paths:
         - src
         - tests
+    scanFiles:
+        - vendor/php-stubs/wordpress-stubs/wordpress-stubs.php
     excludePaths:
         analyse:
             - src/*/vendor/*
             - tests/CodeceptionSupport/*
+    ignoreErrors:
+        -
+            identifier: catch.neverThrown
+            path: tests/*

src/Container/ContainerAdapter.php

@@ -39,7 +39,7 @@ public function get(string $id): mixed {
 	/**
 	 * @codeCoverageIgnore
 	 */
-	public function get_container(): DI52Container {
+	public function getContainer(): DI52Container {
 		return $this->container;
 	}
 
@@ -95,6 +95,15 @@ public function instance(mixed $id, array $buildArgs = [], ?array $afterBuildMet
 		return $this->container->instance($id, $buildArgs, $afterBuildMethods);
 	}
 
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @throws ContainerException
+	 */
+	public function mergeArrayVar(string $id, mixed $implementation): void {
+		$this->container->mergeArrayVar($id, $implementation);
+	}
+
 	/**
 	 * @param class-string|string|object $id
 	 *

src/Container/Contracts/Container.php

@@ -37,6 +37,15 @@ public function needs(string $id): Container;
 
 	public function give(mixed $implementation): void;
 
+	/**
+	 * Add array values to an existing or future binding without replacing previous values.
+	 *
+	 * @param class-string|string $id
+	 *
+	 * @throws \lucatume\DI52\ContainerException
+	 */
+	public function mergeArrayVar(string $id, mixed $implementation): void;
+
 	/**
 	 * Returns a callable object (Closure) that will build an instance of the specified
 	 * class using the specified arguments when called.

src/Container/composer.json

@@ -10,7 +10,7 @@
     "require": {
         "php": ">=8.3",
         "adbario/php-dot-notation": ">=2.5",
-        "lucatume/di52": ">=3.0",
+        "lucatume/di52": ">=4.1",
         "stellarwp/container-contract": "^1.1",
         "vlucas/phpdotenv": ">=4.3"
     },

src/ContainerWordPress/.gitattributes

@@ -0,0 +1,7 @@
+# Path-based git attributes
+# https://www.kernel.org/pub/software/scm/git/docs/gitattributes.html
+
+# Ignore paths when git creates an archive of this package
+.gitattributes         export-ignore
+.gitignore             export-ignore
+.github                export-ignore

src/ContainerWordPress/.github/workflows/close-pull-request.yml

@@ -0,0 +1,13 @@
+name: Close Pull Request
+
+on:
+  pull_request_target:
+    types: [opened]
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: superbrothers/close-pull-request@v3
+        with:
+          comment: "This is a read-only repository. Please submit your PR on the https://github.com/stellarwp/foundation repository.<br><br>Thanks!"

src/ContainerWordPress/.gitignore

@@ -0,0 +1,2 @@
+vendor/
+composer.lock

src/ContainerWordPress/ContainerAdapter.php

@@ -0,0 +1,258 @@
+<?php declare(strict_types=1);
+
+namespace StellarWP\Foundation\ContainerWordPress;
+
+use Closure;
+use InvalidArgumentException;
+use lucatume\DI52\Container as DI52Container;
+use lucatume\DI52\ContainerException;
+use StellarWP\Foundation\Container\ContainerAdapter as FoundationContainerAdapter;
+use StellarWP\Foundation\Container\Contracts\Providable;
+use StellarWP\Foundation\ContainerWordPress\Contracts\Container;
+
+/**
+ * WordPress-aware container adapter.
+ *
+ * Wraps the Foundation container so WordPress projects keep the full base
+ * container API and gain WordPress-specific helpers. Add WordPress-specific
+ * methods here alongside the matching signatures on {@see Container}.
+ *
+ * @method mixed make(string $id)
+ * @method mixed getVar(string $key, mixed|null $default = null)
+ * @method void  singletonDecorators($id, array<string> $decorators, ?array<string> $afterBuildMethods = null)
+ * @method void  bindDecorators($id, array<string> $decorators, ?array<string> $afterBuildMethods = null)
+ */
+final readonly class ContainerAdapter implements Container
+{
+	private FoundationContainerAdapter $container;
+
+	private string $prefix;
+
+	public function __construct(
+		FoundationContainerAdapter $container,
+		string $prefix = 'nexcess/foundation/container/wp/',
+	) {
+		$this->container = $container;
+		$this->prefix    = $prefix === '' ? '' : rtrim($prefix, '/') . '/';
+	}
+
+	/**
+	 * Build the "registered" WordPress action name for a service provider or alias.
+	 *
+	 * @param string $identifier The service provider class or alias slug.
+	 *
+	 * @throws InvalidArgumentException When the provided $identifier is empty.
+	 *
+	 * @return non-empty-string
+	 */
+	private function registeredAction(string $identifier): string {
+		if ($identifier === '') {
+			throw new InvalidArgumentException('You need to provide an identifier!');
+		}
+
+		return $this->prefix . $identifier . '/registered';
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	public function register(string $serviceProviderClass, ...$alias): void {
+		$this->registeredAction($serviceProviderClass);
+
+		foreach ($alias as $slug) {
+			$this->registeredAction($slug);
+		}
+
+		$this->container->register($serviceProviderClass, ...$alias);
+
+		/**
+		 * Fires after a service provider has been registered in the container.
+		 *
+		 * The dynamic portion of the hook name, `$serviceProviderClass`, refers to the
+		 * fully-qualified class name of the registered service provider.
+		 *
+		 * @param class-string<Providable> $serviceProviderClass The registered service provider class.
+		 * @param string[]                 $alias                The aliases the provider was registered under.
+		 */
+		do_action($this->registeredAction($serviceProviderClass), $serviceProviderClass, $alias);
+
+		foreach ($alias as $slug) {
+			/**
+			 * Fires after a service provider has been registered, once per alias.
+			 *
+			 * The dynamic portion of the hook name, `$slug`, refers to an alias the
+			 * service provider was registered under.
+			 *
+			 * @param class-string<Providable> $serviceProviderClass The registered service provider class.
+			 * @param string[]                 $alias                The aliases the provider was registered under.
+			 */
+			do_action($this->registeredAction($slug), $serviceProviderClass, $alias);
+		}
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	public function registerAfterAllActions(array $actions, string $serviceProviderClass, ...$alias): void {
+		$pending = array_values(array_filter($actions, static fn (string $action): bool => ! did_action($action)));
+
+		if ($pending === []) {
+			// All the actions have already fired, register the provider immediately.
+			$this->register($serviceProviderClass, ...$alias);
+
+			return;
+		}
+
+		// A single closure is hooked onto every pending action. Whichever action fires
+		// last finds all actions done, registers once, and detaches from the rest.
+		$register_when_ready = function () use ($actions, $pending, $serviceProviderClass, $alias, &$register_when_ready): void {
+			foreach ($actions as $action) {
+				if (! did_action($action)) {
+					return;
+				}
+			}
+
+			// Detach from every pending action so the provider is only registered once.
+			foreach ($pending as $action) {
+				remove_action($action, $register_when_ready);
+			}
+
+			$this->register($serviceProviderClass, ...$alias);
+		};
+
+		foreach ($pending as $action) {
+			add_action($action, $register_when_ready);
+		}
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	public function registerOnAction(string $action, string $serviceProviderClass, ...$alias): void {
+		if (did_action($action)) {
+			// If the action has already fired, register the provider immediately.
+			$this->register($serviceProviderClass, ...$alias);
+
+			return;
+		}
+
+		// If the action has not fired yet, register the provider when/if it does.
+		$registration_closure = function () use ($action, $serviceProviderClass, $alias, &$registration_closure) {
+			// Remove the closure from the action to avoid calling it again.
+			remove_action($action, $registration_closure);
+			$this->register($serviceProviderClass, ...$alias);
+		};
+
+		add_action($action, $registration_closure);
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	public function registerOnProvider(
+		string $baseProviderClass,
+		string $dependentProviderClass,
+		...$alias
+	): void {
+		$this->registerOnAction($this->registeredAction($baseProviderClass), $dependentProviderClass, ...$alias);
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	public function when(string $class): Container {
+		$this->container->when($class);
+
+		return $this;
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	public function needs(string $id): Container {
+		$this->container->needs($id);
+
+		return $this;
+	}
+
+	/**
+	 * @param string[]|null $afterBuildMethods
+	 *
+	 * @throws \lucatume\DI52\ContainerException
+	 */
+	public function bind(string $id, mixed $implementation = null, ?array $afterBuildMethods = null): void {
+		$this->container->bind($id, $implementation, $afterBuildMethods);
+	}
+
+	/**
+	 * {@inheritDoc}
+	 */
+	public function get(string $id): mixed {
+		return $this->container->get($id);
+	}
+
+	/**
+	 * @codeCoverageIgnore
+	 */
+	public function getContainer(): DI52Container {
+		return $this->container->getContainer();
+	}
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @codeCoverageIgnore
+	 */
+	public function has(string $id): bool {
+		return $this->container->has($id);
+	}
+
+	/**
+	 * @param string[]|null $afterBuildMethods
+	 *
+	 * @throws \lucatume\DI52\ContainerException
+	 */
+	public function singleton(string $id, mixed $implementation = null, ?array $afterBuildMethods = null): void {
+		$this->container->singleton($id, $implementation, $afterBuildMethods);
+	}
+
+	public function give(mixed $implementation): void {
+		$this->container->give($implementation);
+	}
+
+	/**
+	 * {@inheritDoc}
+	 *
+	 * @throws ContainerException
+	 */
+	public function mergeArrayVar(string $id, mixed $implementation): void {
+		$this->container->mergeArrayVar($id, $implementation);
+	}
+
+	/**
+	 * @param array<mixed>  $buildArgs
+	 * @param string[]|null $afterBuildMethods
+	 */
+	public function instance(mixed $id, array $buildArgs = [], ?array $afterBuildMethods = null): Closure {
+		return $this->container->instance($id, $buildArgs, $afterBuildMethods);
+	}
+
+	/**
+	 * @param class-string|string|object $id
+	 *
+	 * @throws ContainerException
+	 */
+	public function callback(object|string $id, string $method): callable {
+		return $this->container->callback($id, $method);
+	}
+
+	/**
+	 * Defer all other calls to the wrapped Foundation container adapter.
+	 *
+	 * @param string  $name The method name.
+	 * @param mixed[] $args Method arguments.
+	 */
+	public function __call(string $name, array $args): mixed {
+		return $this->container->{$name}(...$args);
+	}
+}