Skip to content

Commit e28eae2

Browse files
AJenboAJenbo
committed
Clean up setup page
1 parent dbe5df0 commit e28eae2

1 file changed

Lines changed: 79 additions & 80 deletions

File tree

‎docs/SETUP.md‎

Lines changed: 79 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -21,79 +21,12 @@ cargo build --release
2121
# Binary is at target/release/phpantom_lsp
2222
```
2323

24-
## Project Requirements
25-
26-
PHPantom works best with Composer projects. It reads `composer.json` to discover autoload directories and vendor packages, so completions and go-to-definition only surface classes that your autoloader can actually load. Projects without `composer.json` fall back to scanning every PHP file in the workspace.
27-
28-
## Configuration
29-
30-
PHPantom supports an optional per-project configuration file for settings like PHP version overrides and diagnostic toggles.
31-
32-
To generate a default config file with all options documented and commented out:
33-
34-
```bash
35-
phpantom_lsp --init
36-
```
37-
38-
This creates a `.phpantom.toml` in the current directory. Currently supported settings:
39-
40-
```toml
41-
[php]
42-
# Override the detected PHP version (default: inferred from composer.json, or 8.5).
43-
# version = "8.5"
44-
45-
[diagnostics]
46-
# Report member access on subjects whose type could not be resolved.
47-
# Useful for discovering gaps in type coverage. Off by default.
48-
# unresolved-member-access = true
49-
50-
[indexing]
51-
# How PHPantom discovers classes across the workspace.
52-
# "composer" (default) - use Composer classmap, self-scan on fallback
53-
# "self" - always self-scan, ignore Composer classmap
54-
# "none" - no proactive scanning, Composer classmap only
55-
# strategy = "composer"
56-
```
57-
58-
The file is optional. When absent, all settings use their defaults. New settings will be added as features land. Unknown keys are silently ignored, so the file is forward-compatible.
59-
60-
### Indexing Strategy
61-
62-
By default, PHPantom trusts Composer's autoloader to determine which classes exist in your project. This is intentional: it means completions, diagnostics, and go-to-definition reflect what your code will actually see at runtime. Classes that aren't autoloadable don't appear, because using them would be an error.
63-
64-
The `strategy` setting controls this behaviour:
65-
66-
| Strategy | Behaviour |
67-
| --- | --- |
68-
| `"composer"` (default) | Use Composer's classmap when available, self-scan to fill gaps. Results match what `composer dump-autoload` knows about. |
69-
| `"self"` | Ignore Composer's classmap entirely and scan every PHP file in the workspace. Discovers all classes regardless of autoloading. |
70-
| `"none"` | Use only Composer's classmap with no fallback scanning. The most conservative option. |
71-
72-
Most projects should leave this at the default. Change it to `"self"` if your project loads classes outside of Composer (custom autoloaders, `require_once`, legacy inclusion patterns). Be aware that `"self"` will also surface vendor-internal classes and potential duplicates that Composer's autoloader would never load.
73-
74-
## Troubleshooting
75-
76-
### Classes from other files are not found
77-
78-
PHPantom resolves cross-file classes through Composer's autoloading rules (PSR-4 mappings and the generated classmap). If a class exists in your project but PHPantom reports it as unknown, the most common causes are:
79-
80-
1. **The class isn't Composer-autoloadable.** If your project loads classes via `require_once`, `include`, or a custom autoloader alongside Composer, those classes won't be discovered by default. Set `strategy = "self"` in `.phpantom.toml` to scan all files.
81-
82-
2. **Composer's classmap is stale.** Run `composer dump-autoload` to regenerate it. PHPantom reads the classmap at startup.
83-
84-
3. **The class is in a directory not covered by `autoload` or `autoload-dev`.** Check that your `composer.json` PSR-4 mappings cover the directory where the class lives.
85-
86-
### Too many classes in completion lists
87-
88-
If you're seeing vendor-internal classes, duplicate framework classes (common in monorepos), or other noise, your indexing strategy may be too broad. The default `"composer"` strategy only surfaces classes that Composer's autoloader can load, which filters out this noise. If you previously set `strategy = "self"`, consider switching back to `"composer"`.
89-
9024
## Editor Setup
9125

9226
PHPantom communicates over stdin/stdout using the standard [Language Server Protocol](https://microsoft.github.io/language-server-protocol/). Any editor with LSP support can use it. Point the client at the `phpantom_lsp` binary with `php` as the file type. No special initialization options are required.
9327

94-
---
95-
96-
### Zed
28+
<details>
29+
<summary><b>Zed</b></summary>
9730

9831
A Zed extension is included in the `zed-extension/` directory:
9932

@@ -116,9 +49,10 @@ To make PHPantom the default PHP language server, add to your Zed `settings.json
11649
}
11750
```
11851

119-
---
52+
</details>
12053

121-
### Neovim
54+
<details>
55+
<summary><b>Neovim</b></summary>
12256

12357
```lua
12458
vim.lsp.config['phpantom'] = {
@@ -129,9 +63,10 @@ vim.lsp.config['phpantom'] = {
12963
vim.lsp.enable('phpantom')
13064
```
13165

132-
---
66+
</details>
13367

134-
### VS Code
68+
<details>
69+
<summary><b>VS Code</b></summary>
13570

13671
1. **Install a generic LSP client extension**
13772

@@ -154,9 +89,10 @@ vim.lsp.enable('phpantom')
15489
* Add the Language ID: `php`
15590
* Restart VS Code
15691
157-
---
92+
</details>
15893
159-
### PHPStorm
94+
<details>
95+
<summary><b>PHPStorm</b></summary>
16096
16197
1. **Download PHPantom LSP binary**
16298
@@ -172,15 +108,16 @@ vim.lsp.enable('phpantom')
172108
173109
* Name: `PHPantom`
174110
* Command: path to your PHPantom binary
175-
* Mapping: add a new Language and set it to `PHP`
111+
* Mapping: set `PHP` on both the **Language** tab and the **File Type** tab (the dialogs are identical). Setting both ensures PHPStorm activates the server reliably.
176112
177-
<img width="779" height="645" alt="Screenshot From 2026-02-21 00-28-37" src="https://github.com/user-attachments/assets/2da88e68-d012-476e-82e7-977dbfcd9653" />
113+
<img width="779" height="645" alt="PHPStorm new language server dialog" src="https://github.com/user-attachments/assets/2da88e68-d012-476e-82e7-977dbfcd9653" />
178114
179-
<img width="779" height="645" alt="Screenshot From 2026-02-21 00-32-24" src="https://github.com/user-attachments/assets/62358f9e-973c-487d-ac17-098d7dab007e" />
115+
<img width="779" height="645" alt="PHPStorm language server mapping dialog" src="https://github.com/user-attachments/assets/62358f9e-973c-487d-ac17-098d7dab007e" />
180116
181-
---
117+
</details>
182118
183-
### Sublime Text
119+
<details>
120+
<summary><b>Sublime Text</b></summary>
184121
185122
> [!NOTE]
186123
> This configuration is untested. If you get it working (or run into issues), please [open an issue](../../issues).
@@ -198,3 +135,65 @@ With [LSP for Sublime Text](https://github.com/sublimelsp/LSP):
198135
}
199136
}
200137
```
138+
139+
</details>
140+
141+
## Project Configuration
142+
143+
PHPantom works best with Composer projects. It reads `composer.json` to discover autoload directories and vendor packages, so completions and go-to-definition only surface classes that your autoloader can actually load. Projects without `composer.json` fall back to scanning every PHP file in the workspace.
144+
145+
### `.phpantom.toml`
146+
147+
PHPantom supports an optional per-project configuration file for settings like PHP version overrides and diagnostic toggles.
148+
149+
To generate a default config file with all options documented and commented out:
150+
151+
```bash
152+
phpantom_lsp --init
153+
```
154+
155+
This creates a `.phpantom.toml` in the current directory. Currently supported settings:
156+
157+
```toml
158+
[php]
159+
# Override the detected PHP version (default: inferred from composer.json, or 8.5).
160+
# version = "8.5"
161+
162+
[diagnostics]
163+
# Report member access on subjects whose type could not be resolved.
164+
# Useful for discovering gaps in type coverage. Off by default.
165+
# unresolved-member-access = true
166+
167+
[indexing]
168+
# How PHPantom discovers classes across the workspace.
169+
# "composer" (default) - use Composer classmap, self-scan on fallback
170+
# "self" - always self-scan, ignore Composer classmap
171+
# "none" - no proactive scanning, Composer classmap only
172+
# strategy = "composer"
173+
```
174+
175+
The file is optional. When absent, all settings use their defaults. New settings will be added as features land. Unknown keys are silently ignored, so the file is forward-compatible.
176+
177+
### Indexing Strategy
178+
179+
By default, PHPantom trusts Composer's autoloader to determine which classes exist in your project. This is intentional: it means completions, diagnostics, and go-to-definition reflect what your code will actually see at runtime. Classes that aren't autoloadable don't appear, because using them would be an error.
180+
181+
The `strategy` setting controls this behaviour:
182+
183+
| Strategy | Behaviour |
184+
| --- | --- |
185+
| `"composer"` (default) | Use Composer's classmap when available, self-scan to fill gaps. Results match what `composer dump-autoload` knows about. |
186+
| `"self"` | Ignore Composer's classmap entirely and scan every PHP file in the workspace. Discovers all classes regardless of autoloading. |
187+
| `"none"` | Use only Composer's classmap with no fallback scanning. The most conservative option. |
188+
189+
Most projects should leave this at the default. Change it to `"self"` if your project loads classes outside of Composer (custom autoloaders, `require_once`, legacy inclusion patterns). Be aware that `"self"` will also surface vendor-internal classes and potential duplicates that Composer's autoloader would never load.
190+
191+
### Classes from other files are not found
192+
193+
PHPantom resolves cross-file classes through Composer's autoloading rules (PSR-4 mappings and the generated classmap). If a class exists in your project but PHPantom reports it as unknown, the most common causes are:
194+
195+
1. **The class isn't Composer-autoloadable.** If your project loads classes via `require_once`, `include`, or a custom autoloader alongside Composer, those classes won't be discovered by default. Set `strategy = "self"` in `.phpantom.toml` to scan all files.
196+
197+
2. **Composer's classmap is stale.** Run `composer dump-autoload` to regenerate it. PHPantom reads the classmap at startup.
198+
199+
3. **The class is in a directory not covered by `autoload` or `autoload-dev`.** Check that your `composer.json` PSR-4 mappings cover the directory where the class lives.

0 commit comments

Comments
 (0)