Skip to content
This repository was archived by the owner on Mar 3, 2026. It is now read-only.

Commit 092a1da

Browse files
Morgy93Morgy93
committed
feat: init ddev phpstan
1 parent 41298ff commit 092a1da

22 files changed

Lines changed: 6124 additions & 0 deletions

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
node_modules
2+
.vscode-test/
3+
*.vsix
4+
dist/
5+
.DS_Store
6+
.vscode-test.log

‎.vscode-test.mjs‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
/*
2+
* This file is part of the vscode-ddev-phpstan extension.
3+
*
4+
* © OpenForgeProject
5+
*
6+
* This program is free software: you can redistribute it and/or modify
7+
* it under the terms of the GNU General Public License as published by
8+
* the Free Software Foundation, either version 3 of the License, or
9+
* (at your option) any later version.
10+
*
11+
* This program is distributed in the hope that it will be useful,
12+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
13+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14+
* GNU General Public License for more details.
15+
*
16+
* You should have received a copy of the GNU General Public License
17+
* along with this program. If not, see <https://www.gnu.org/licenses/>.
18+
*/
19+
20+
import { defineConfig } from '@vscode/test-cli';
21+
22+
export default defineConfig({
23+
files: 'dist/test/**/*.test.js',
24+
workspaceFolder: '.',
25+
mocha: {
26+
ui: 'tdd',
27+
timeout: 20000
28+
}
29+
});

‎.vscode/extensions.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"recommendations": [
3+
"ms-vscode.vscode-typescript-next",
4+
"esbenp.prettier-vscode",
5+
"dbaeumer.vscode-eslint"
6+
]
7+
}

‎.vscode/launch.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
"name": "Run Extension",
6+
"type": "extensionHost",
7+
"request": "launch",
8+
"args": [
9+
"--extensionDevelopmentPath=${workspaceFolder}"
10+
],
11+
"outFiles": [
12+
"${workspaceFolder}/dist/**/*.js"
13+
],
14+
"preLaunchTask": "${workspaceFolder}:npm: compile"
15+
},
16+
{
17+
"name": "Extension Tests",
18+
"type": "extensionHost",
19+
"request": "launch",
20+
"args": [
21+
"--extensionDevelopmentPath=${workspaceFolder}",
22+
"--extensionTestsPath=${workspaceFolder}/dist/test"
23+
],
24+
"outFiles": [
25+
"${workspaceFolder}/dist/**/*.js"
26+
],
27+
"preLaunchTask": "${workspaceFolder}:npm: compile-tests"
28+
}
29+
]
30+
}

‎.vscode/tasks.json‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
{
2+
"version": "2.0.0",
3+
"tasks": [
4+
{
5+
"type": "npm",
6+
"script": "compile",
7+
"group": {
8+
"kind": "build",
9+
"isDefault": true
10+
},
11+
"presentation": {
12+
"panel": "shared",
13+
"group": "build"
14+
},
15+
"problemMatcher": {
16+
"base": "$esbuild",
17+
"fileLocation": "absolute"
18+
}
19+
},
20+
{
21+
"type": "npm",
22+
"script": "compile-tests",
23+
"group": "build",
24+
"presentation": {
25+
"panel": "shared",
26+
"group": "build"
27+
},
28+
"problemMatcher": {
29+
"base": "$esbuild",
30+
"fileLocation": "absolute"
31+
}
32+
},
33+
{
34+
"type": "npm",
35+
"script": "watch",
36+
"group": "build",
37+
"presentation": {
38+
"panel": "shared",
39+
"group": "build"
40+
},
41+
"isBackground": true,
42+
"problemMatcher": {
43+
"base": "$esbuild-watch",
44+
"fileLocation": "absolute"
45+
}
46+
},
47+
{
48+
"type": "npm",
49+
"script": "test",
50+
"group": "test",
51+
"presentation": {
52+
"panel": "shared",
53+
"group": "test"
54+
}
55+
}
56+
]
57+
}

‎CHANGELOG.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Changelog
2+
3+
All notable changes to the "DDEV PHPStan" extension will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
## [0.1.0] - 2025-09-30
11+
12+
### Added
13+
14+
- Initial release of DDEV PHPStan extension
15+
- PHPStan integration with DDEV containers for seamless static analysis
16+
- Real-time error highlighting in VS Code editor
17+
- Status bar integration showing analysis state and results
18+
- Configurable PHPStan analysis levels (0-9) with best practice defaults (level 6)
19+
- Support for custom PHPStan configuration files with auto-detection
20+
- Comprehensive exclude patterns for common directories (vendor/, var/, cache/, etc.)
21+
- Validation timing options (on save or on type)
22+
- Minimum severity filtering (error, warning, info)
23+
- Debug command for troubleshooting analysis issues
24+
- Problems panel integration with clickable error navigation
25+
- Commands for manual analysis and extension management
26+
27+
### Features
28+
29+
- **DDEV Integration**: Runs PHPStan analysis directly in DDEV containers
30+
- **Smart Configuration**: Auto-detects common PHPStan config files (phpstan.neon, etc.)
31+
- **Best Practice Defaults**: Ships with production-ready settings (level 6, smart excludes)
32+
- **Real-time Feedback**: Instant error highlighting and VS Code diagnostics integration
33+
- **Flexible Settings**: Comprehensive configuration options for different project needs
34+
- **Developer Experience**: Clear status indicators and helpful debug tools
35+
36+
### Configuration Options
37+
38+
- `ddev-phpstan.enable`: Enable/disable the extension (default: true)
39+
- `ddev-phpstan.validateOn`: When to validate - "save" or "type" (default: "save")
40+
- `ddev-phpstan.level`: PHPStan analysis level 0-9 (default: 6)
41+
- `ddev-phpstan.minSeverity`: Minimum severity level (default: "warning")
42+
- `ddev-phpstan.configPath`: Path to custom PHPStan configuration file
43+
- `ddev-phpstan.excludePaths`: Paths to exclude from analysis (includes smart defaults)
44+
45+
### Commands
46+
47+
- `DDEV PHPStan: Analyze Current File` - Run analysis on the current file
48+
- `DDEV PHPStan: Debug Analysis (Show Raw Output)` - Show raw PHPStan output for debugging
49+
- `DDEV PHPStan: Enable` - Enable the extension
50+
- `DDEV PHPStan: Disable` - Disable the extension
51+
- `DDEV PHPStan: Toggle Enable/Disable` - Toggle extension state
52+
53+
### Technical Details
54+
55+
- Built with TypeScript and VS Code Extension API
56+
- Uses esbuild for efficient bundling and fast compilation
57+
- ESLint integration for code quality assurance
58+
- Comprehensive test suite with Mocha framework
59+
- Modular service-based architecture for maintainability
60+
- Proper error handling and user feedback

‎README.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# DDEV PHPStan Extension for VS Code
2+
3+
This extension integrates [PHPStan](https://phpstan.org/) with Visual Studio Code using [DDEV](https://ddev.com/) as the runtime environment. It provides real-time static analysis for PHP projects running in DDEV containers.
4+
5+
## Features
6+
7+
- Real-time PHP static analysis using PHPStan through DDEV
8+
- **Easy enable/disable functionality per project**
9+
- Configurable validation triggers (on save or on type)
10+
- Customizable PHPStan levels and severity filtering
11+
- Automatic DDEV project detection
12+
- Problems panel integration with clickable issue links
13+
- Status bar indicator showing extension state
14+
15+
## Requirements
16+
17+
- [VS Code](https://code.visualstudio.com/) 1.100.0 or higher
18+
- [DDEV](https://github.com/ddev/ddev) project with running container
19+
- PHPStan installed in your DDEV container
20+
21+
## Installation
22+
23+
Install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=OpenForgeProject.vscode-ddev-phpstan) or search for "DDEV PHPStan" in VS Code's extension panel.
24+
25+
Install [PHPStan](https://github.com/phpstan/phpstan) in your DDEV container:
26+
```bash
27+
ddev composer require --dev phpstan/phpstan
28+
```
29+
30+
## Usage
31+
32+
1. Open a DDEV project in VS Code
33+
2. The extension automatically analyzes PHP files when you save them
34+
3. Issues appear in the Problems panel and are highlighted in the editor
35+
4. Click on issues to view detailed information and external documentation
36+
37+
### Enable/Disable Extension
38+
39+
Use the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`):
40+
- `DDEV PHPStan: Enable` - Enable the extension
41+
- `DDEV PHPStan: Disable` - Disable the extension
42+
- `DDEV PHPStan: Toggle Enable/Disable` - Toggle the extension state
43+
44+
Or click the status bar item to access commands quickly.
45+
46+
## Configuration
47+
48+
Key settings in VS Code preferences:
49+
50+
- `ddev-phpstan.enable`: Enable/disable the extension (default: `true`)
51+
- `ddev-phpstan.validateOn`: When to validate (`"save"` or `"type"`)
52+
- `ddev-phpstan.level`: PHPStan analysis level 0-9 (default: `6` - recommended for most projects)
53+
- `ddev-phpstan.minSeverity`: Minimum severity level (`"error"`, `"warning"`, `"info"`)
54+
- `ddev-phpstan.configPath`: Path to custom PHPStan configuration file
55+
- `ddev-phpstan.excludePaths`: Array of paths to exclude from analysis (includes common exclusions by default)
56+
57+
**Important:** When `configPath` is specified, the extension will only use the configuration file and ignore the `level` and `excludePaths` settings, as these should be defined in the PHPStan configuration file itself.
58+
59+
### Example Configuration
60+
61+
```json
62+
{
63+
"ddev-phpstan.enable": true,
64+
"ddev-phpstan.validateOn": "save",
65+
"ddev-phpstan.level": 6,
66+
"ddev-phpstan.minSeverity": "warning",
67+
"ddev-phpstan.configPath": "",
68+
"ddev-phpstan.excludePaths": [
69+
"vendor/",
70+
"var/",
71+
"cache/",
72+
"public/bundles/",
73+
"node_modules/",
74+
"tests/fixtures/",
75+
"migrations/"
76+
]
77+
}
78+
```
79+
80+
**Best Practice Defaults:** The extension comes pre-configured with sensible defaults:
81+
- **Analysis Level 6**: Provides strong type checking without being overly strict
82+
- **Common Exclusions**: Automatically excludes vendor code, cache directories, and other common paths that shouldn't be analyzed
83+
- **Save-based Validation**: Runs analysis when files are saved for optimal performance
84+
85+
**Note:** When `configPath` is set to a specific PHPStan configuration file, the `level` and `excludePaths` settings will be ignored, and these values should instead be configured in your PHPStan configuration file.
86+
87+
## Status Bar
88+
89+
The extension shows its status in the VS Code status bar:
90+
91+
- **$(check) PHPStan** - Extension active, no issues in current file
92+
- **$(error) PHPStan** - Extension active, issues found in current file
93+
- **$(warning) PHPStan** - DDEV/PHPStan not available (click for options)
94+
- **$(circle-slash) PHPStan** - Extension disabled (click to enable)
95+
96+
## Commands
97+
98+
Available commands in the Command Palette:
99+
100+
- `DDEV PHPStan: Analyze Current File` - Run PHPStan analysis on the current file
101+
- `DDEV PHPStan: Debug Analysis (Show Raw Output)` - Show raw PHPStan JSON output for debugging
102+
- `DDEV PHPStan: Enable` - Enable the extension
103+
- `DDEV PHPStan: Disable` - Disable the extension
104+
- `DDEV PHPStan: Toggle Enable/Disable` - Toggle extension state
105+
106+
## Troubleshooting
107+
108+
### PHPStan not found
109+
110+
If you see "PHPStan service is not available":
111+
112+
1. Ensure DDEV is running: `ddev start`
113+
2. Install PHPStan: `ddev composer require --dev phpstan/phpstan`
114+
3. Restart VS Code or click "Retry"
115+
116+
### DDEV not running
117+
118+
If you see "DDEV appears to be stopped":
119+
120+
1. Start DDEV: `ddev start`
121+
2. Click "Start DDEV" in the error message
122+
3. Or disable the extension for this project
123+
124+
### Configuration file errors
125+
126+
If you see "PHPStan configuration error":
127+
128+
1. Check that your `ddev-phpstan.configPath` setting points to a valid file
129+
2. Ensure the configuration file syntax is correct
130+
3. Try running PHPStan manually: `ddev exec phpstan analyse --help`
131+
132+
### PHPStan exit codes
133+
134+
PHPStan uses different exit codes to indicate different states:
135+
- **Exit code 0**: No errors found
136+
- **Exit code 1**: Errors found (this is normal and expected)
137+
- **Exit code 2**: Configuration error or fatal error
138+
139+
The extension handles exit codes 0 and 1 as successful execution, only treating exit code 2 and higher as actual failures.
140+
141+
### No issues detected
142+
143+
PHPStan might not find issues if:
144+
145+
- The analysis level is too low (try increasing `ddev-phpstan.level`)
146+
- Files are excluded by your PHPStan configuration
147+
- The minimum severity level filters out issues
148+
- PHPStan configuration is missing or incorrect
149+
150+
**Debug Steps:**
151+
1. Use `DDEV PHPStan: Debug Analysis (Show Raw Output)` to see the actual PHPStan JSON output
152+
2. Check the VS Code Developer Console (Help → Toggle Developer Tools → Console) for detailed logs
153+
3. Verify PHPStan works manually: `ddev exec phpstan analyse src/your-file.php --error-format=json`
154+
155+
## Development
156+
157+
This extension is built using:
158+
159+
- TypeScript
160+
- VS Code Extension API
161+
- esbuild for bundling
162+
- Mocha for testing
163+
164+
### Contributing
165+
166+
1. Fork the repository
167+
2. Create your feature branch
168+
3. Run tests: `npm test`
169+
4. Submit a pull request
170+
171+
## License
172+
173+
GPL-3.0 License. See [LICENSE](LICENSE) for details.
174+
175+
## About
176+
177+
Developed by [OpenForgeProject](https://github.com/OpenForgeProject) as part of a suite of DDEV-based VS Code extensions for PHP development.
178+
179+
## Related Extensions
180+
181+
- [DDEV PHPMD Extension](https://marketplace.visualstudio.com/items?itemName=OpenForgeProject.vscode-ddev-phpmd) - PHP Mess Detector integration

0 commit comments

Comments
 (0)