Adding a Installation_Manager to facilitate installation

src/mantle/support/traits/trait-singleton.php

@@ -0,0 +1,35 @@
+<?php
+/**
+ * Singleton trait file
+ *
+ * @package Mantle
+ */
+
+namespace Mantle\Support\Traits;
+
+/**
+ * Make a class into a singleton.
+ */
+trait Singleton {
+	/**
+	 * Existing instances.
+	 *
+	 * @var array
+	 */
+	protected static $instances = [];
+
+	/**
+	 * Get class instance.
+	 *
+	 * @return static
+	 */
+	public static function instance() {
+		$class = get_called_class();
+
+		if ( ! isset( static::$instances[ $class ] ) ) {
+			static::$instances[ $class ] = new static();
+		}
+
+		return self::$instances[ $class ];
+	}
+}

src/mantle/testing/autoload.php

@@ -9,30 +9,32 @@
 
 namespace Mantle\Testing;
 
+use function Mantle\Support\Helpers\tap;
+
 /**
- * Install the Mantle Tests Framework
+ * Retrieve an instance of the Installation Manager
  *
- * @param callable $callback_after_preload Callback to invoke before WordPress is loaded.
- * @return void
+ * The manager can install the Mantle Testing Framework but will not by default.
+ * Call {@see Installation_Manager::install()} to install or use the
+ * {@see install()} helper.
+ *
+ * @return Installation_Manager
  */
-function install( callable $callback_after_preload = null ): void {
-	if ( ! file_exists( __DIR__ . '/preload.php' ) ) {
-		echo "ERROR: Failed to locate valid Mantle testing preload file. \n";
-		echo 'Current file: ' . __FILE__ . PHP_EOL;
-		exit( 1 );
-	}
-
+function manager(): Installation_Manager {
 	require_once __DIR__ . '/preload.php';
 
-	if ( $callback_after_preload ) {
-		$callback_after_preload();
-	}
+	return Installation_Manager::instance();
+}
 
-	try {
-		require_once __DIR__ . '/wordpress-bootstrap.php';
-	} catch ( \Throwable $throwable ) {
-		echo "ERROR: Failed to load WordPress!\n";
-		echo "{$throwable}\n";
-		exit( 1 );
-	}
+/**
+ * Install the Mantle Testing Framework
+ *
+ * @param callable $callback_after_preload Callback to invoke before WordPress is loaded.
+ * @return Installation_Manager
+ */
+function install( callable $callback_after_preload = null ): Installation_Manager {
+	return tap(
+		manager(),
+		fn ( Installation_Manager $manager ) => $manager->after( $callback_after_preload ),
+	)->install();
 }

src/mantle/testing/class-installation-manager.php

@@ -0,0 +1,118 @@
+<?php
+/**
+ * Installation_Manager class file
+ *
+ * @package Mantle
+ */
+
+namespace Mantle\Testing;
+
+use Mantle\Support\Traits\Singleton;
+
+/**
+ * Installation Manager
+ */
+class Installation_Manager {
+	use Singleton;
+
+	/**
+	 * Callbacks for before installation.
+	 *
+	 * @var callable[]
+	 */
+	protected array $before_install_callbacks = [];
+
+	/**
+	 * Callbacks for after installation.
+	 *
+	 * @var callable[]
+	 */
+	protected array $after_install_callbacks = [];
+
+	/**
+	 * Callback for after WordPress is loaded.
+	 *
+	 * @var callable[]
+	 */
+	protected array $after_loaded_callbacks = [];
+
+	/**
+	 * Define a callback to be invoked before installation.
+	 *
+	 * @param callable $callback Callback to invoke before installation.
+	 * @return static
+	 */
+	public function before( ?callable $callback ) {
+		if ( is_callable( $callback ) ) {
+			$this->before_install_callbacks[] = $callback;
+		}
+
+		return $this;
+	}
+
+	/**
+	 * Define a callback to be invoked after installation.
+	 *
+	 * @param callable $callback Callback to invoke after installation.
+	 * @return static
+	 */
+	public function after( ?callable $callback ) {
+		if ( is_callable( $callback ) ) {
+			$this->after_install_callbacks[] = $callback;
+		}
+
+		return $this;
+	}
+
+	/**
+	 * Define a callback to be invoked after WordPress is loaded.
+	 *
+	 * @param callable $callback Callback to invoke after WordPress is loaded.
+	 * @return static
+	 */
+	public function loaded( ?callable $callback ) {
+		return $this->on( 'wp_loaded', $callback );
+	}
+
+	/**
+	 * Define a callback for a specific WordPress hook.
+	 *
+	 * @param string   $hook Hook name.
+	 * @param callable $callback Callback to invoke.
+	 * @param int      $priority Priority.
+	 * @param int      $accepted_args Number of accepted arguments.
+	 * @return static
+	 */
+	public function on( string $hook, ?callable $callback, int $priority = 10, int $accepted_args = 1 ) {
+		if ( is_callable( $callback ) ) {
+			tests_add_filter( $hook, $callback, $priority, $accepted_args );
+		}
+
+		return $this;
+	}
+
+	/**
+	 * Install the Mantle Testing Framework.
+	 *
+	 * @return static
+	 */
+	public function install() {
+		foreach ( $this->before_install_callbacks as $callback ) {
+			$callback();
+		}
+
+		try {
+			require_once __DIR__ . '/wordpress-bootstrap.php';
+		} catch ( \Throwable $throwable ) {
+			echo "ERROR: Failed to load WordPress!\n";
+			echo "{$throwable}\n"; // phpcs:ignore
+			exit( 1 );
+		}
+
+		foreach ( $this->after_install_callbacks as $callback ) {
+			$callback();
+		}
+
+		return $this;
+	}
+}

src/mantle/testkit/concerns/trait-installs-wordpress.php

@@ -14,9 +14,10 @@ trait Installs_WordPress {
 	/**
 	 * Manages installing WordPress.
 	 *
-	 * This is useful for installing WordPress in integration tests, while leaving the bootstrap
-	 * free of this overhead during unit tests. To perform actions after WordPress is installed, you
-	 * simply need to define a function `mantle_after_wordpress_install` in your bootstrap file.
+	 * This is useful for installing WordPress in integration tests, while leaving
+	 * the bootstrap free of this overhead during unit tests. To perform actions
+	 * after WordPress is installed,  you can use the Installation Manager to
+	 * define a callback to be invoked before/after installation.
 	 */
 	public static function installs_wordpress_set_up_before_class(): void {
 		static $installed = false;
@@ -25,6 +26,11 @@ public static function installs_wordpress_set_up_before_class(): void {
 			return;
 		}
 
+		/**
+		 * Fire a callback to a named function called 'mantle_after_wordpress_install'.
+		 *
+		 * @deprecated Logic condensed into {@see \Mantle\Testing\Installation_Manager::after()}.
+		 */
 		$callback = function_exists( 'mantle_after_wordpress_install' ) ? 'mantle_after_wordpress_install' : null;
 
 		\Mantle\Testing\install( $callback );

tests/testkit/test-testkit-install-wordpress.php

@@ -1,19 +1,27 @@
 <?php
 namespace Mantle\Tests\Testkit;
 
+use Mantle\Testing\Installation_Manager;
 use Mantle\Testkit\Concerns\Installs_WordPress;
 use Mantle\Testkit\Test_Case;
 
 // Required for callback.
 require_once __DIR__ . '/fixtures/global-functions.php';
 
+Installation_Manager::instance()->after( function() {
+	$_SERVER['__mantle_after_wordpress_install'] ??= 0;
+
+	$_SERVER['__mantle_after_wordpress_install']++;
+} );
+
 class Test_Testkit_Install_WordPress extends Test_Case {
 	use Installs_WordPress;
 
 	public function test_mantle_is_installed_from_trait() {
 		$called = \mantle_after_wordpress_install( false );
 
 		$this->assertEquals( 1, $called );
-	}
 
+		$this->assertEquals( 1, $_SERVER['__mantle_after_wordpress_install'] ?? 0 );
+	}
 }