README

This package enables you to comfortably use PhpStorm as a CLI tool for static analysis.

Features

Wrapper for PhpStorm's inspect.sh script with additional functionality
Waits for PhpStorm to finish already running inspections
Clears PhpStorm's cache before every run to prevent stale cache issues
Parses XML output generated by PhpStorm and presents it in a readable form
Supports both text and checkstyle output formats
Modern PHP 8.3 implementation with Symfony Console integration
Tested with PHPStorm 2024.3

Installation

composer require shopsys/phpstorm-inspect

Usage

vendor/bin/phpstorm-inspect inspect \
  --inspect-sh=/path/to/PhpStorm/bin/inspect.sh \
  --system-path=/path/to/.WebIde*/system \
  --project-path=/path/to/project \
  --profile=/path/to/project/.idea/inspectionProfiles/Project_Default.xml \
  --directory=/path/to/inspect \
  --format=text

Arguments

--inspect-sh: Path to inspect.sh script
--system-path: Path to .WebIde*/system directory
--project-path: Path to project directory (that contains .idea directory)
--profile: Path to inspection profile XML file
--directory: Path in which are the inspected sources
--format: Format of output result, accepted values: "text" (default) / "checkstyle"

Environment Configuration

You can configure PhpStorm binary paths using a .env file:

Copy the .env.example file to .env in the project root:
```
cp .env.example .env
```

Edit the .env file with your specific paths:

PHPSTORM_INSPECT_SH=/path/to/PhpStorm/bin/inspect.sh
PHPSTORM_SYSTEM_PATH=/path/to/.WebIde*/system

When environment variables are set, you can omit the corresponding command-line options:

vendor/bin/phpstorm-inspect inspect \
  --project-path=/path/to/project \
  --profile=/path/to/project/.idea/inspectionProfiles/Project_Default.xml \
  --directory=/path/to/inspect \
  --format=text

Example Usage

Creating a Simple Inspection Profile

If you don't have an existing inspection profile, you can create a simple one:

<?xml version="1.0" encoding="UTF-8"?>
<inspections version="1.0">
  <option name="myName" value="Project Default" />
  <inspection_tool class="PhpDocMissingReturnTagInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpDocSignatureInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpMissingDocCommentInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpMissingParentCallCommonInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpMissingParentCallMagicInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpMultipleClassesDeclarationsInOneFile" enabled="true" level="WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpRedundantCatchClauseInspection" enabled="true" level="WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpSingleClassInspection" enabled="true" level="WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpStanGlobal" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
</inspections>

Save this to a file named inspection-profile.xml in your project directory.

Running the Inspection

You can run the inspection on your project's source code:

php bin/phpstorm-inspect --project-path=$(pwd) --profile=$(pwd)/inspection-profile.xml --directory=$(pwd)/src

Self-Inspection Example

A good way to test the tool is to use it to inspect its own code:

# Create a simple inspection profile
cat > inspection-profile.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<inspections version="1.0">
  <option name="myName" value="Project Default" />
  <inspection_tool class="PhpDocMissingReturnTagInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpDocSignatureInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpMissingDocCommentInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpMissingParentCallCommonInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpMissingParentCallMagicInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpMultipleClassesDeclarationsInOneFile" enabled="true" level="WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpRedundantCatchClauseInspection" enabled="true" level="WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpSingleClassInspection" enabled="true" level="WARNING" enabled_by_default="true" />
  <inspection_tool class="PhpStanGlobal" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
</inspections>
EOF

# Run the inspection on the tool's own code
php bin/phpstorm-inspect --project-path=$(pwd) --profile=$(pwd)/inspection-profile.xml --directory=$(pwd)/src

Sample Output (Text Format)

When running the self-inspection example above, you'll get output similar to this:

File: /path/to/project/src/PhpStormInspect/Command/InspectCommand.php
--------------------------------------------------------------------------------
Found 15 problems
--------------------------------------------------------------------------------
Line 25: Missing PHPDoc comment: Missing PHPDoc comment for class
Line 27: Class constant type is missing: Class constant type is missing
Line 28: Class constant type is missing: Class constant type is missing
Line 30: Missing parent call for method: Missing parent method call
Line 30: unused declaration: Method is never used.
Line 72: Missing parent call for method: Missing parent method call
Line 72: unused declaration: Method is never used.
Line 83: Fully qualified name usage: Qualifier can be replaced with an import
Line 89: Fully qualified name usage: Qualifier can be replaced with an import
Line 110: Fully qualified name usage: Qualifier can be replaced with an import
Line 120: Fully qualified name usage: Qualifier can be replaced with an import
Line 125: Fully qualified name usage: Qualifier can be replaced with an import
Line 142: Fully qualified name usage: Qualifier can be replaced with an import
Line 152: Fully qualified name usage: Qualifier can be replaced with an import
Line 165: Fully qualified name usage: Qualifier can be replaced with an import
--------------------------------------------------------------------------------

File: /path/to/project/src/PhpStormInspect/Inspection/InspectionRunner.php
--------------------------------------------------------------------------------
Found 5 problems
--------------------------------------------------------------------------------
Line 10: Missing PHPDoc comment: Missing PHPDoc comment for class
Line 12: Class constant type is missing: Class constant type is missing
Line 13: Class constant type is missing: Class constant type is missing
Line 69: Fully qualified name usage: Qualifier can be replaced with an import
Line 73: Fully qualified name usage: Qualifier can be replaced with an import
--------------------------------------------------------------------------------

... (more files and issues) ...

This output shows various code quality issues that PhpStorm's inspection has found, such as:

Missing PHPDoc comments
Missing class constant types
Missing parent method calls
Fully qualified name usage that could be replaced with imports
Unused declarations
And more

Sample Output (Checkstyle Format)

You can also get the output in checkstyle format, which is useful for integration with CI tools:

php bin/phpstorm-inspect --project-path=$(pwd) --profile=$(pwd)/inspection-profile.xml --directory=$(pwd)/src --format=checkstyle

Output:

<?xml version="1.0"?>
<checkstyle version="1.0.0">
  <file name="/path/to/project/src/PhpStormInspect/Command/InspectCommand.php">
    <error line="25" column="0" severity="weak warning" message="Missing PHPDoc comment for class"/>
    <error line="27" column="0" severity="weak warning" message="Class constant type is missing"/>
    <error line="28" column="0" severity="weak warning" message="Class constant type is missing"/>
    <error line="30" column="0" severity="weak warning" message="Missing parent method call"/>
    <error line="30" column="0" severity="weak warning" message="Method is never used."/>
    <!-- More errors... -->
  </file>
  <file name="/path/to/project/src/PhpStormInspect/Inspection/InspectionRunner.php">
    <error line="10" column="0" severity="weak warning" message="Missing PHPDoc comment for class"/>
    <error line="12" column="0" severity="weak warning" message="Class constant type is missing"/>
    <error line="13" column="0" severity="weak warning" message="Class constant type is missing"/>
    <error line="69" column="0" severity="weak warning" message="Qualifier can be replaced with an import"/>
    <error line="73" column="0" severity="weak warning" message="Qualifier can be replaced with an import"/>
  </file>
  <!-- More files... -->
</checkstyle>

The checkstyle format is particularly useful for integrating with CI/CD pipelines and other tools that can process this standard format.

Tips for Effective Usage

Customizing Inspection Profiles

For more comprehensive code quality checks, you can create a custom inspection profile in PhpStorm:

Open your project in PhpStorm
Go to Settings/Preferences → Editor → Inspections
Configure the inspections you want to enable/disable
Click the gear icon and select "Export" to save your profile as an XML file
Use this exported file with the --profile option

Integrating with CI/CD

To integrate with CI/CD pipelines:

Use the checkstyle output format (--format=checkstyle)
Save the output to a file: php bin/phpstorm-inspect ... --format=checkstyle > phpstorm-inspection.xml
Use a tool like checkstyle-formatter to convert the output to HTML or other formats
Configure your CI system to fail the build if certain types or numbers of issues are found

Performance Considerations

The first run may take longer as PhpStorm builds its indexes
For large projects, consider inspecting specific directories rather than the entire project
Clearing the cache (which this tool does automatically) helps prevent stale cache issues but may increase inspection time

License

MIT License (see LICENSE file)

This is a modernized version of shopsys/phpstorm-inspect updated for PHP 8.3.

uzulla / phpstorm-inspect-code-cli-runner

Maintainers

Details