Permit single-file mu-plugins

HM/Sniffs/Files/FunctionFileNameSniff.php

@@ -8,6 +8,8 @@
  * Sniff to check for namespaced functions are in `namespace.php`.
  */
 class FunctionFileNameSniff implements Sniff {
+	use MuPluginFileTrait;
+
 	public function register() {
 		return array( T_FUNCTION );
 	}
@@ -25,6 +27,11 @@ public function process( File $phpcsFile, $stackPtr ) {
 			return;
 		}
 
+		if ( $this->is_single_file_mu_plugin( $phpcsFile->getFileName() ) ) {
+			// Single-file plugins cannot be split into a namespace.php file.
+			return;
+		}
+
 		$filename = basename( $phpcsFile->getFileName() );
 
 		if ( $filename === 'namespace.php' ) {

HM/Sniffs/Files/MuPluginFileTrait.php

@@ -0,0 +1,27 @@
+<?php
+namespace HM\Sniffs\Files;
+
+/**
+ * Shared helper for detecting single-file must-use plugins.
+ *
+ * Single-file mu-plugins live as direct children of a `mu-plugins/` directory
+ * (or `client-mu-plugins/`, on VIP). This is a useful pattern to support, but
+ * by definition can't be split into an inc/ directory or named namespace.php
+ * (multiple plugins would collide), and should allow side effects.
+ */
+trait MuPluginFileTrait {
+	/**
+	 * Is the given file a single-file mu-plugin?
+	 *
+	 * @param string $path Full path to the file being checked.
+	 * @return bool True if the file is a direct child of mu-plugins/ or client-mu-plugins/.
+	 */
+	protected function is_single_file_mu_plugin( $path ) {
+		// Normalize the directory separator across operating systems.
+		if ( DIRECTORY_SEPARATOR !== '/' ) {
+			$path = str_replace( DIRECTORY_SEPARATOR, '/', $path );
+		}
+
+		return (bool) preg_match( '#/(?:client-)?mu-plugins/[^/]+\.php$#', $path );
+	}
+}

HM/Sniffs/Files/NamespaceDirectoryNameSniff.php

@@ -8,6 +8,8 @@
  * Namespaced things must be in directories matching the namespace.
  */
 class NamespaceDirectoryNameSniff implements Sniff {
+	use MuPluginFileTrait;
+
 	/**
 	 * Returns an array of tokens this test wants to listen for.
 	 *
@@ -50,6 +52,11 @@ public function process( File $phpcsFile, $stackPtr ) {
 			$directory = str_replace( DIRECTORY_SEPARATOR, '/', $directory );
 		}
 
+		if ( $this->is_single_file_mu_plugin( $full ) ) {
+			// Single-file mu-plugins will naturally never have an inc/ directory.
+			return;
+		}
+
 		if ( $filename === 'plugin.php' || $filename === 'functions.php' || $filename === 'load.php' ) {
 			// Ignore the main file.
 			return;

HM/Tests/Files/FunctionFileNameUnitTest.php

@@ -2,7 +2,8 @@
 
 namespace HM\Tests\Files;
 
-use DirectoryIterator;
+use RecursiveDirectoryIterator;
+use RecursiveIteratorIterator;
 use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
 
 /**
@@ -20,10 +21,12 @@ protected function getTestFiles( $test_base_dir ) {
 		$test_base_dir = rtrim( $test_base_dir, '.' );
 		$test_files = [];
 
-		$di = new DirectoryIterator( $test_base_dir );
+		$di = new RecursiveIteratorIterator(
+			new RecursiveDirectoryIterator( $test_base_dir )
+		);
 
 		foreach ( $di as $file ) {
-			if ( $file->isDot() ) {
+			if ( ! $file->isFile() ) {
 				continue;
 			}
 
@@ -46,6 +49,9 @@ public function getErrorList() {
 		$pass = [
 			'namespace.php',
 			'matching-namespace.php',
+			// Single-file mu-plugins can't all be named namespace.php.
+			'my-plugin.php',
+			'my-client-plugin.php',
 		];
 		if ( in_array( $file, $pass, true ) ) {
 			return [];

HM/Tests/Files/FunctionFileNameUnitTest/client-mu-plugins/my-client-plugin.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace HM\Coding\Standards\Tests;
+
+function foo() {}

HM/Tests/Files/FunctionFileNameUnitTest/mu-plugins/my-plugin.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace HM\Coding\Standards\Tests;
+
+function foo() {}

HM/Tests/Files/FunctionFileNameUnitTest/mu-plugins/nested/nested-plugin.php

@@ -0,0 +1,5 @@
+<?php
+
+namespace HM\Coding\Standards\Tests;
+
+function foo() {}

HM/Tests/Files/NamespaceDirectoryNameUnitTest.php

@@ -52,6 +52,9 @@ public function getErrorList() {
 			'camelcased-namespace.php',
 			'underscored-namespace.php',
 			'strict-types-namespace.php',
+			// Single-file mu-plugins are exempt from the directory structure rules.
+			'mu-plugin.php',
+			'client-mu-plugin.php',
 		];
 		if ( in_array( $file, $pass, true ) ) {
 			return [];

HM/Tests/Files/NamespaceDirectoryNameUnitTest/client-mu-plugins/client-mu-plugin.php

@@ -0,0 +1,3 @@
+<?php
+
+namespace HM\Coding\Standards\Client_Mu_Plugin;

HM/Tests/Files/NamespaceDirectoryNameUnitTest/mu-plugins/mu-plugin.php

@@ -0,0 +1,3 @@
+<?php
+
+namespace HM\Coding\Standards\Mu_Plugin;

HM/Tests/Files/NamespaceDirectoryNameUnitTest/mu-plugins/nested/nested-mu-plugin.php

@@ -0,0 +1,3 @@
+<?php
+
+namespace HM\Coding\Standards\Nested;

HM/ruleset.xml

@@ -143,7 +143,11 @@
 	<rule ref="PSR1.Classes.ClassDeclaration" />
 
 	<!-- Declare symbols or run code, but not both. -->
-	<rule ref="PSR1.Files.SideEffects" />
+	<rule ref="PSR1.Files.SideEffects">
+		<!-- Permit single-file mu-plugins, which can be pragmatically useful. -->
+		<exclude-pattern>*/mu-plugins/[^/]+\.php$</exclude-pattern>
+		<exclude-pattern>*/client-mu-plugins/[^/]+\.php$</exclude-pattern>
+	</rule>
 
 	<!-- Namespacing required for functions. -->
 	<rule ref="PSR2.Namespaces.NamespaceDeclaration" />

phpunit.xml.dist

@@ -11,6 +11,7 @@
 		<testsuite name="all">
 			<file>tests/AllSniffs.php</file>
 			<file>tests/FixtureTests.php</file>
+			<file>tests/MuPluginSideEffectsTest.php</file>
 		</testsuite>
 	</testsuites>
 </phpunit>

tests/MuPluginSideEffectsTest.php

@@ -0,0 +1,77 @@
+<?php
+/**
+ * Test that PSR1.Files.SideEffects is excluded for single-file mu-plugins.
+ *
+ * The two HM file-structure sniffs handle their own mu-plugin exemption in
+ * code (covered by their sniff unit tests). PSR1.Files.SideEffects is a
+ * third-party sniff, so its exemption lives as an <exclude-pattern> in
+ * HM/ruleset.xml.
+ *
+ * We exercise it by running the phpcs binary in a subprocess rather than
+ * building the ruleset in-process: loading the full HM standard alongside the
+ * other test suites triggers sniff class redeclaration errors, and restricting
+ * the sniffs in-process makes PHPCS skip the ruleset processing that loads the
+ * exclude-patterns in the first place.
+ */
+
+namespace HM\CodingStandards\Tests;
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Class MuPluginSideEffectsTest
+ *
+ * @group fixtures
+ */
+class MuPluginSideEffectsTest extends TestCase {
+	const PSR1_SIDE_EFFECTS = 'PSR1.Files.SideEffects.FoundWithSymbols';
+
+	/**
+	 * Run PSR1.Files.SideEffects over a fixture and return the message sources.
+	 *
+	 * @param string $relative_file Fixture path relative to the tests directory.
+	 * @return string[] List of reported message sources.
+	 */
+	protected function get_sources( string $relative_file ) {
+		$root  = dirname( __DIR__ );
+		$phpcs = $root . '/vendor/bin/phpcs';
+		$file  = __DIR__ . '/' . $relative_file;
+
+		$command = sprintf(
+			'%s %s --standard=HM --sniffs=PSR1.Files.SideEffects --report=json %s',
+			escapeshellarg( PHP_BINARY ),
+			escapeshellarg( $phpcs ),
+			escapeshellarg( $file )
+		);
+
+		$output = shell_exec( $command );
+		$report = json_decode( $output, true );
+
+		$this->assertSame( JSON_ERROR_NONE, json_last_error(), 'phpcs should return valid JSON' );
+
+		$sources = [];
+		foreach ( $report['files'] as $details ) {
+			foreach ( $details['messages'] as $message ) {
+				$sources[] = $message['source'];
+			}
+		}
+
+		return $sources;
+	}
+
+	/**
+	 * Single-file mu-plugins should be exempt from the side-effects rule.
+	 */
+	public function test_mu_plugin_is_exempt() {
+		$sources = $this->get_sources( 'fixtures/sideeffects/mu-plugins/example-plugin.php' );
+		$this->assertNotContains( static::PSR1_SIDE_EFFECTS, $sources );
+	}
+
+	/**
+	 * The same code outside mu-plugins/ should still get flagged, to prove correct scoping.
+	 */
+	public function test_regular_file_is_flagged() {
+		$sources = $this->get_sources( 'fixtures/sideeffects/regular/example-plugin.php' );
+		$this->assertContains( static::PSR1_SIDE_EFFECTS, $sources );
+	}
+}

tests/fixtures/sideeffects/mu-plugins/example-plugin.php

@@ -0,0 +1,18 @@
+<?php
+/**
+ * Plugin Name: Example single-file mu-plugin.
+ *
+ * Single-file mu-plugins routinely declare symbols and add hooks in the same
+ * file, so PSR1.Files.SideEffects should not flag them.
+ */
+
+namespace HM\Coding\Standards\Example;
+
+add_action( 'init', __NAMESPACE__ . '\\bootstrap' );
+
+/**
+ * Bootstrap the plugin.
+ */
+function bootstrap() {
+	// ...
+}

tests/fixtures/sideeffects/regular/example-plugin.php

@@ -0,0 +1,18 @@
+<?php
+/**
+ * Plugin Name: Example regular plugin file.
+ *
+ * Identical to the mu-plugin fixture, but not a direct child of mu-plugins/,
+ * so PSR1.Files.SideEffects should still flag it.
+ */
+
+namespace HM\Coding\Standards\Example;
+
+add_action( 'init', __NAMESPACE__ . '\\bootstrap' );
+
+/**
+ * Bootstrap the plugin.
+ */
+function bootstrap() {
+	// ...
+}