PHPCS Integration Composer Package (#91)

Created a new Composer package `obliviousharmony/vscode-phpcs-integration` that will be used instead of the integrated report files when `phpCodeSniffer.autoloadPHPCSIntegration` is enabled. This allows us to easily support environments where we can't know the path to the report files but can use Composer's autoloader.

.gitignore

@@ -8,6 +8,7 @@
 
 # Build Artifacts
 *.vsix
+obliviousharmony-vscode-phpcs-integration-*
 extension.js
 extension.js.map
 

.vscodeignore

@@ -11,3 +11,4 @@ composer.json
 composer.lock
 .gitignore
 *.vsix
+obliviousharmony-vscode-phpcs-integration-*

CHANGELOG.md

@@ -5,6 +5,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- Support using an `obliviousharmony/vscode-phpcs-integration` Composer package to provide
+the integration files when a new `phpCodeSniffer.autoloadPHPCSIntegration` option
+is enabled.
+
+### Removed
+- **BREAKING:** The `phpCodeSniffer.specialOptions.phpcsIntegrationPathOverride` option
+has been removed in favor of using `phpCodeSniffer.autoloadPHPCSIntegration`.
+There is no reason to set a manual asset path since the Composer package accomplishes
+the same thing with an easier-to-use configuration path.
 
 ## [2.3.0] - 2024-01-26
 ### Added
@@ -42,7 +52,8 @@ for platform-specific executables.
 - Support for execution on Windows without the use of WSL.
 
 ### Changed
-- **BREAKING:** Even if `phpCodeSniffer.autoExecutable` is enabled, the working directory given to PHPCS should always be the workspace root.
+- **BREAKING:** Even if `phpCodeSniffer.autoExecutable` is enabled, the working directory given to
+PHPCS should always be the workspace root.
 
 ### Deprecated
 - `phpCodeSniffer.executable` has been deprecated in favor of platform-specific executable options.

README.md

@@ -60,3 +60,7 @@ any file rules in your coding standard, this option allows you to define additio
      }
  }
  ```
+
+## Using in Containerized Development Environments (`phpCodeSniffer.autoloadPHPCSIntegration`)
+
+If you are using a container for your development environment we would _strongly_ recommend using one of [VS Code's remote development extensions](https://code.visualstudio.com/docs/remote/remote-overview). However, if this is not possible, [we have provided a Composer package with the files required to integrate with PHPCS](./assets/phpcs-integration). You _must_ install these files alongside PHPCS (globally or per-project) in order for the extension to work properly. Once you have installed the package it will be used instead of the build-in integration when `phpCodeSniffer.autoloadPHPCSIntegration` is enabled.

assets/phpcs-integration/Extension/File.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace VSCode\PHP_CodeSniffer\Extension;
+namespace ObliviousHarmony\VSCodePHPCSIntegration\Extension;
 
 use PHP_CodeSniffer\Files\File as BaseFile;
 use PHP_CodeSniffer\Sniffs\Sniff;
@@ -9,7 +9,7 @@
  * A class that supports targeting specific tokens for fixes to allow for
  * tracking the edits that should be created by a single
  *
- * @property \VSCode\PHP_CodeSniffer\Extension\Fixer $fixer
+ * @property \ObliviousHarmony\VSCodePHPCSIntegration\Extension\Fixer $fixer
  */
 class File extends BaseFile
 {

assets/phpcs-integration/Extension/Fixer.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace VSCode\PHP_CodeSniffer\Extension;
+namespace ObliviousHarmony\VSCodePHPCSIntegration\Extension;
 
 use PHP_CodeSniffer\Fixer as BaseFixer;
 

assets/phpcs-integration/Handlers/CodeAction.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace VSCode\PHP_CodeSniffer\Handlers;
+namespace ObliviousHarmony\VSCodePHPCSIntegration\Handlers;
 
-use VSCode\PHP_CodeSniffer\Extension\File;
+use ObliviousHarmony\VSCodePHPCSIntegration\Extension\File;
 
 /**
  * A handler for returning information about edits from PHPCS in a way

assets/phpcs-integration/Handlers/Diagnostic.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace VSCode\PHP_CodeSniffer\Handlers;
+namespace ObliviousHarmony\VSCodePHPCSIntegration\Handlers;
 
-use VSCode\PHP_CodeSniffer\Extension\File;
+use ObliviousHarmony\VSCodePHPCSIntegration\Extension\File;
 
 /**
  * A handler for returning information from PHPCS in a way that the

assets/phpcs-integration/Handlers/Format.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace VSCode\PHP_CodeSniffer\Handlers;
+namespace ObliviousHarmony\VSCodePHPCSIntegration\Handlers;
 
-use VSCode\PHP_CodeSniffer\Extension\File;
+use ObliviousHarmony\VSCodePHPCSIntegration\Extension\File;
 
 /**
  * A handler for formatting a document or range within a document.

assets/phpcs-integration/Handlers/Handler.php

@@ -1,8 +1,8 @@
 <?php
 
-namespace VSCode\PHP_CodeSniffer\Handlers;
+namespace ObliviousHarmony\VSCodePHPCSIntegration\Handlers;
 
-use VSCode\PHP_CodeSniffer\Extension\File;
+use ObliviousHarmony\VSCodePHPCSIntegration\Extension\File;
 
 /**
  * The interface for all PHPCS handlers.

assets/phpcs-integration/README.md

@@ -0,0 +1,10 @@
+# VS Code PHP_CodeSniffer Integration Files
+
+This package contains the PHP files required to integrate [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) into [the PHP_CodeSniffer VS Code extension](https://marketplace.visualstudio.com/items?itemName=obliviousharmony.vscode-php-codesniffer).
+
+**Note: This package requires version 3.0 or newer of the VS Code extension.**
+
+## Usage
+
+The use of this package is _optional_ and is only required in cases where the `phpcs` command is not ran from the same environment as
+VS Code. For example, when running PHP in a Docker container but not using one of VS Code's remote extensions. Simply install this package alongside PHPCS (globally or per-project) and enable the `phpCodeSniffer.autoloadPHPCSIntegration` option to use it.

assets/phpcs-integration/VSCode.php → assets/phpcs-integration/VSCodeIntegration.php

@@ -1,16 +1,21 @@
 <?php
 
-namespace VSCode\PHP_CodeSniffer;
+namespace ObliviousHarmony\VSCodePHPCSIntegration;
 
 use PHP_CodeSniffer\Files\File as BaseFile;
 use PHP_CodeSniffer\Reports\Report;
-use VSCode\PHP_CodeSniffer\Extension\File;
-use VSCode\PHP_CodeSniffer\Handlers\Handler;
+use ObliviousHarmony\VSCodePHPCSIntegration\Extension\File;
+use ObliviousHarmony\VSCodePHPCSIntegration\Handlers\Handler;
+
+// This should match the version in the `configuration.ts` file so that
+// we can provide error messaging that tells them to update the
+// Composer package containing these files.
+define('PHPCS_INTEGRATION_VERSION', '1.0.0');
 
 /**
  * The custom report for our PHPCS integration.
  */
-class VSCode implements Report
+class VSCodeIntegration implements Report
 {
     /**
      * Constructor.
@@ -45,6 +50,15 @@ public function generateFileReport($report, BaseFile $phpcsFile, $showSources =
         // We use an environment variable to pass input to the reports.
         $input = $this->getVSCodeInput();
 
+        // Make sure that we are running the correct version of the integration package.
+        if ($input->version !== PHPCS_INTEGRATION_VERSION) {
+            $errorMessage = 'The extension expected version '
+            . PHPCS_INTEGRATION_VERSION
+            . ' of the integration files. Current Version: '
+            . $input->version . PHP_EOL;
+            throw new \InvalidArgumentException($errorMessage);
+        }
+
         // Use the handler to process the report.
         $handler = $this->getHandler($input->type);
         return $handler->execute($report, $phpcsFile, $input->data);
@@ -90,7 +104,7 @@ public function generate(
     protected function getHandler($reportType)
     {
         // Find the handler class file that should power this report.
-        $report = '\\VSCode\\PHP_CodeSniffer\\Handlers\\' . $reportType;
+        $report = '\\ObliviousHarmony\\VSCodePHPCSIntegration\\Handlers\\' . $reportType;
         if (!\class_exists($report)) {
             throw new \InvalidArgumentException('Handler "' . $report . '" could be found');
         }

composer.json

@@ -1,7 +1,42 @@
 {
+    "name": "obliviousharmony/vscode-phpcs-integration",
+    "description": "The custom PHPCS integration for the obliviousharmony.vscode-php-codesniffer VS Code extension.",
+	"version": "1.0.0",
+    "homepage": "https://github.com/ObliviousHarmony/vscode-php-codesniffer",
+    "license": "GPL-2.0-or-later",
+    "authors": [
+        {
+            "name": "Christopher Allford",
+            "homepage": "https://github.com/ObliviousHarmony"
+        }
+    ],
+    "keywords": [
+        "phpcs",
+        "phpcbf",
+        "vscode",
+        "vscode-extension",
+        "vscode-phpcs",
+        "vscode-phpcbf"
+    ],
+    "readme": "assets/phpcs-integration/README.md",
+    "archive": {
+        "exclude": [
+            "*",
+            "!/composer.json",
+            "!/LICENSE.txt",
+            "!/assets/phpcs-integration"
+        ]
+    },
+	"prefer-stable": true,
+	"minimum-stability": "dev",
     "require-dev": {
         "squizlabs/php_codesniffer": "^3.1"
     },
+    "autoload": {
+        "psr-4": {
+            "ObliviousHarmony\\VSCodePHPCSIntegration\\": "assets/phpcs-integration"
+        }
+    },
     "scripts": {
         "lint": "phpcs --standard=psr12 -sp assets",
         "lint:fix": "phpcbf --standard=psr12 -sp assets"

package.json

@@ -4,7 +4,7 @@
   "description": "Brings PHPCS support to VS Code.",
   "version": "2.3.0",
   "license": "GPL-2.0-or-later",
-  "author": "Christopher Allford",
+  "author": "Christopher Allford (https://github.com/ObliviousHarmony)",
   "repository": {
     "type": "git",
     "url": "https://github.com/ObliviousHarmony/vscode-php-codesniffer.git"
@@ -46,6 +46,12 @@
           "default": false,
           "scope": "resource"
         },
+        "phpCodeSniffer.autoloadPHPCSIntegration": {
+          "type": "boolean",
+          "default": false,
+          "markdownDescription": "Whether or not the PHPCS integration files are available through the autoloader. This should only be enabled when the integration files are provided via Composer.",
+          "scope": "resource"
+        },
         "phpCodeSniffer.exec.linux": {
           "type": "string",
           "markdownDescription": "The path to the PHPCS executable we want to use on Linux when `#phpCodeSniffer.autoExecutable#` is disabled or unable to find one.",
@@ -134,12 +140,7 @@
           "type": "object",
           "description": "An object of special options for the extension that serve more narrow use-cases.",
           "default": {},
-          "properties": {
-            "phpcsIntegrationPathOverride": {
-              "type": "string",
-              "description": "Overrides the path to the directory that contains the extension's PHPCS integration."
-            }
-          },
+          "properties": {},
           "additionalProperties": false,
           "scope": "resource"
         },

src/phpcs-report/__tests__/worker-integration.test.ts

@@ -8,18 +8,18 @@ import { MockCancellationToken } from '../../__mocks__/vscode';
 
 // We need to mock the report files because Webpack is being used to bundle them.
 describe('Worker/WorkerPool Integration', () => {
-	let phpcsIntegrationPath: string;
 	let phpcsPath: string;
 
 	beforeAll(() => {
-		phpcsIntegrationPath = resolvePath(
+		// Make sure the test knows where the real assets are located.
+		process.env.ASSETS_PATH = resolvePath(
 			__dirname,
 			'..',
 			'..',
 			'..',
-			'assets',
-			'phpcs-integration'
+			'assets'
 		);
+
 		phpcsPath = resolvePath(
 			__dirname,
 			'..',
@@ -53,7 +53,7 @@ describe('Worker/WorkerPool Integration', () => {
 				options: {
 					executable: phpcsPath,
 					standard: 'PSR12',
-					phpcsIntegrationPath: phpcsIntegrationPath,
+					autoloadPHPCSIntegration: false,
 				},
 				data: null,
 			};
@@ -82,7 +82,7 @@ describe('Worker/WorkerPool Integration', () => {
 				options: {
 					executable: phpcsPath,
 					standard: 'PSR12',
-					phpcsIntegrationPath: phpcsIntegrationPath,
+					autoloadPHPCSIntegration: false,
 				},
 				data: null,
 			};

src/phpcs-report/__tests__/worker.spec.ts

@@ -8,18 +8,18 @@ import { Worker } from '../worker';
 
 // We need to mock the report files because Webpack is being used to bundle them.
 describe('Worker', () => {
-	let phpcsIntegrationPath: string;
 	let phpcsPath: string;
 
 	beforeAll(() => {
-		phpcsIntegrationPath = resolvePath(
+		// Make sure the test knows where the real assets are located.
+		process.env.ASSETS_PATH = resolvePath(
 			__dirname,
 			'..',
 			'..',
 			'..',
-			'assets',
-			'phpcs-integration'
+			'assets'
 		);
+
 		phpcsPath = resolvePath(
 			__dirname,
 			'..',
@@ -52,7 +52,7 @@ describe('Worker', () => {
 			options: {
 				executable: phpcsPath,
 				standard: 'PSR12',
-				phpcsIntegrationPath: phpcsIntegrationPath,
+				autoloadPHPCSIntegration: false,
 			},
 			data: null,
 		};
@@ -75,7 +75,7 @@ describe('Worker', () => {
 			options: {
 				executable: phpcsPath,
 				standard: 'PSR12',
-				phpcsIntegrationPath: phpcsIntegrationPath,
+				autoloadPHPCSIntegration: false,
 			},
 			data: null,
 		};
@@ -100,7 +100,7 @@ describe('Worker', () => {
 			options: {
 				executable: phpcsPath,
 				standard: 'PSR12',
-				phpcsIntegrationPath: phpcsIntegrationPath,
+				autoloadPHPCSIntegration: false,
 			},
 			data: {
 				code: 'PSR12.Files.OpenTag.NotAlone',
@@ -141,7 +141,7 @@ describe('Worker', () => {
 			options: {
 				executable: phpcsPath,
 				standard: 'PSR12',
-				phpcsIntegrationPath: phpcsIntegrationPath,
+				autoloadPHPCSIntegration: false,
 			},
 			data: {},
 		};
@@ -164,7 +164,7 @@ describe('Worker', () => {
 			options: {
 				executable: phpcsPath,
 				standard: 'PSR12',
-				phpcsIntegrationPath: phpcsIntegrationPath,
+				autoloadPHPCSIntegration: false,
 			},
 			data: null,
 		};
@@ -191,7 +191,7 @@ describe('Worker', () => {
 			options: {
 				executable: phpcsPath,
 				standard: 'PSR12',
-				phpcsIntegrationPath: phpcsIntegrationPath,
+				autoloadPHPCSIntegration: false,
 			},
 			data: null,
 		};
@@ -214,7 +214,7 @@ describe('Worker', () => {
 				// Since we use custom reports, adding `-s` for sources won't break anything.
 				executable: phpcsPath + ' -s',
 				standard: 'PSR12',
-				phpcsIntegrationPath: phpcsIntegrationPath,
+				autoloadPHPCSIntegration: false,
 			},
 			data: null,
 		};

src/phpcs-report/request.ts

@@ -6,7 +6,7 @@ import { ReportType } from './response';
 export interface RequestOptions {
 	executable: string;
 	standard: string | null;
-	phpcsIntegrationPath: string;
+	autoloadPHPCSIntegration: boolean;
 }
 
 /**