Configuration enhancements for non-standard PHP projects (Drupal, legacy codebases)

[syntlyx]

Summary

PHPantom works great for standard Composer projects, but projects like Drupal use a custom class loader that bypasses Composer's autoloading entirely. Three small configuration additions would make PHPantom usable for a large class of real-world PHP projects.

---

Context: How Drupal loads classes

Drupal does not register module namespaces in composer.json. Instead, it discovers modules at runtime by scanning *.info.yml files and dynamically registering PSR-4 namespaces via its own class loader. This means:

• vendor/autoload_classmap.php and autoload_psr4.php don't know about any module classes
• strategy = "self" works around this, but at the cost of surfacing vendor-internal classes

A more targeted solution would be a combination of the three features below.

---

Requested features

1. includePaths — additional scan directories

Allow specifying extra directories to scan for classes, on top of what Composer knows about. These would be treated like strategy = "self" but scoped to specific paths.

[indexing]
strategy = "composer"
include_paths = ["web/modules", "web/themes", "web/profiles"]

This mirrors intelephense.environment.includePaths and gives precise control without the downsides of global "self" scanning.

---

2. fileExtensions — treat non-.php files as PHP

Drupal uses several file extensions for valid PHP files:

Extension	Purpose
.module	Hook implementations, main module file
.install	hook_schema(), update hooks
.theme	Theme hook implementations
.inc	Shared include files

These are plain PHP files with a <?php header. PHPantom currently won't index them.

[indexing]
file_extensions = ["php", "module", "install", "theme", "inc"]

---

3. LSP initializationOptions — editor-side configuration

Currently the only way to configure PHPantom is via .phpantom.toml committed to the repository. It would be useful to also accept configuration through LSP initializationOptions (passed by the editor in initialize request).

Why this matters:

• Editor config (Zed settings.json, VS Code settings.json, Neovim) is the natural home for developer-specific settings
• .phpantom.toml is project-scoped; some settings are developer-scoped
• Avoids committing editor tooling config into the project repo
• Consistent with how Intelephense, clangd, and other LSP servers handle this

The schema could mirror .phpantom.toml but as JSON:

{
  "phpantom": {
    "php": { "version": "8.3" },
    "indexing": {
      "strategy": "composer",
      "include_paths": ["web/modules", "web/themes"],
      "file_extensions": ["php", "module", "install", "theme", "inc"]
    }
  }
}

.phpantom.toml and initializationOptions could be merged, with the toml file taking precedence for project-level settings.

---

Who this affects

• Drupal projects (one of the largest PHP ecosystems, ~1M+ sites)
• Legacy codebases using .inc includes
• Any project with a custom autoloader alongside Composer

Happy to test any of this on a real Drupal codebase and report back.

[AJenbo]

Good to know about intelephense.environment.includePaths, I was wanting to mostly go for auto discover or nothing, but knowing that others expect projects to configure file context like this means is at least a some what viable solution. Though I still prefer implementing thing in a way where it can discover the type of project by it self an just work out of the box.

[syntlyx]

That makes a lot of sense. For Drupal specifically, auto-discovery is very doable — there are clear signals in composer.json:

• drupal/core, drupal/core-recommended, or drupal/core-dev in require or require-dev
• The web root can be discovered from extra.drupal-scaffold.locations.web-root:

"extra": {
  "drupal-scaffold": {
    "locations": {
      "web-root": "docroot/"
    }
  }
}

If that key is absent, falling back to common conventions (web/, docroot/, public/, html/) would cover most setups.
Once the web root is resolved, PHPantom could automatically scan {web-root}/modules, {web-root}/themes, {web-root}/profiles, and treat .module, .install, .theme, .inc as PHP files.
Happy to help document Drupal project layouts in more detail if useful for implementing detection.

[AJenbo]

Any project you would recommend testing with?

There is a PHPStan like command interface for the LSP's diagnostics that's really helpful for finding our where there are still short comings for a given project:

phpantom_lsp analyze

Even if a project isn't fully typed we should still expect to se zero issues regarding missing classes.

[syntlyx]

For some reason i got No PHP files found.

[AJenbo]

yeah the current version only works for composer projects, you should also either run it from the project root (same folder as composer.json) or specify it with --project-root, there are currently a few things the LSP isn't able to resolve correctly which I'm focusing on before making this more generally usable.

[daronspence]

Not sure if this is possible, but it would also be nice if the LSP could work with a monolith-esque workspace.

We have a monorepo at work that contains about 7 different PHP projects and then a shared Packages/ folder at the root of the repo for shared dependencies.

If the LSP was able to traverse up to the nearest composer.json and then derive the necessary packages from there, that would be neat.

[AJenbo]

It actually does exactly that when no composer.json, but I don't recommend working like that since it's inherently impossible to infer the correct context. Instead what you should be doing is open multiple projects in a single workspace (this works a bit different between IDEs). When opening opening multiple applications you will get completion for things that are not available to the application and class collisions will give false positives for diagnostics.
You can set composer to symlink the shared package so is accessible in each application.

[syntlyx]

@AJenbo, Also if I use "goto reference" the server freezes

Caused by: Get diagnostics via phpantom_lsp failed: Request timed out 2026-03-28T17:53:10+02:00 ERROR [lsp] Cancelled LSP request task for "textDocument/definition" id 144 which took over 120s 2026-03-28T17:53:10+02:00 WARN [project::lsp_store] Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:10+02:00 ERROR [project::lsp_store] Error handling response for request GetDefinitions { position: PointUtf16 { row: 9, column: 40 } }: Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:11+02:00 ERROR [lsp] Cancelled LSP request task for "textDocument/definition" id 150 which took over 120s 2026-03-28T17:53:11+02:00 WARN [project::lsp_store] Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:11+02:00 ERROR [project::lsp_store] Error handling response for request GetDefinitions { position: PointUtf16 { row: 9, column: 41 } }: Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:11+02:00 INFO [editor] Ignoring repeated FindAllReferences invocation with the position of already running task 2026-03-28T17:53:11+02:00 INFO [editor] Ignoring repeated FindAllReferences invocation with the position of already running task 2026-03-28T17:53:13+02:00 ERROR [lsp] Cancelled LSP request task for "textDocument/definition" id 157 which took over 120s 2026-03-28T17:53:13+02:00 WARN [project::lsp_store] Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:13+02:00 ERROR [project::lsp_store] Error handling response for request GetDefinitions { position: PointUtf16 { row: 10, column: 37 } }: Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:13+02:00 INFO [editor] Ignoring repeated FindAllReferences invocation with the position of already running task 2026-03-28T17:53:13+02:00 INFO [editor] Ignoring repeated FindAllReferences invocation with the position of already running task 2026-03-28T17:53:13+02:00 ERROR [lsp] Cancelled LSP request task for "textDocument/definition" id 189 which took over 120s 2026-03-28T17:53:13+02:00 WARN [project::lsp_store] Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:13+02:00 ERROR [project::lsp_store] Error handling response for request GetDefinitions { position: PointUtf16 { row: 12, column: 37 } }: Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:13+02:00 INFO [editor] Ignoring repeated FindAllReferences invocation with the position of already running task 2026-03-28T17:53:13+02:00 INFO [editor] Ignoring repeated FindAllReferences invocation with the position of already running task 2026-03-28T17:53:14+02:00 ERROR [lsp] Cancelled LSP request task for "textDocument/documentHighlight" id 195 which took over 120s 2026-03-28T17:53:14+02:00 WARN [project::lsp_store] Get document highlights via phpantom_lsp failed: Request timed out 2026-03-28T17:53:14+02:00 ERROR [crates/editor/src/editor.rs:7580] Get document highlights via phpantom_lsp failed: Request timed out 2026-03-28T17:53:14+02:00 ERROR [lsp] Cancelled LSP request task for "textDocument/codeAction" id 196 which took over 120s 2026-03-28T17:53:14+02:00 WARN [project::lsp_store] Get code actions via phpantom_lsp failed: Request timed out 2026-03-28T17:53:14+02:00 ERROR [project::lsp_store] Error handling response for request GetCodeActions { range: Anchor { timestamp: Lamport {<local>: 1}, offset: 287, bias: Left, buffer_id: Some(BufferId(21474836661)) }..Anchor { timestamp: Lamport {<local>: 1}, offset: 287, bias: Left, buffer_id: Some(BufferId(21474836661)) }, kinds: None }: Get code actions via phpantom_lsp failed: Request timed out

[daronspence]

It actually does exactly that when no composer.json, but I don't recommend working like that since it's inherently impossible to infer the correct context. Instead what you should be doing is open multiple projects in a single workspace (this works a bit different between IDEs). When opening opening multiple applications you will get completion for things that are not available to the application and class collisions will give false positives for diagnostics. You can set composer to symlink the shared package so is accessible in each application.

Ah, good to know. I tried opening that project and was seeing some weird squiggles and didn't put a ton of effort into debugging further.

I agree that separate projects would be better. I've tried that in VSCode and the results were not great, but I'll give it a shot in Zed and see if it fares better. This project also doesn't have any real test coverage (another problem...) so often it's necessary to do sanity checks of the entire codebase with a global search/find/replace when doing refactors on the shared library code. Having everything available in the same project makes that possible with few surprises.

Of course in a better world, there would be tests to catch any regression but alas ;(

Edit: it appears Zed does not support multi-root workspaces.

[syntlyx]

It would also be a good idea to add an exclude_paths setting (/tests/).
Currently, paths from gitignore are excluded from the index; in Drupal, modules/contrib should also be indexed.

[AJenbo]

@AJenbo, Also if I use "goto reference" the server freezes

`Caused by: Get diagnostics via phpantom_lsp failed: Request timed out 2026-03-28T17:53:10+02:00 ERROR [lsp] Cancelled LSP request task for "textDocument/definition" id 144 which took over 120s 2026-03-28T17:53:10+02:00 WARN [project::lsp_store] Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:10+02:00 ERROR [project::lsp_store] Error handling response for request GetDefinitions { position: PointUtf16 { row: 9, column: 40 } }: Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:11+02:00 ERROR [lsp] Cancelled LSP request task for "textDocument/definition" id 150 which took over 120s 2026-03-28T17:53:11+02:00 WARN [project::lsp_store] Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:11+02:00 ERROR [project::lsp_store] Error handling response for request GetDefinitions { position: PointUtf16 { row: 9, column: 41 } }: Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:11+02:00 INFO [editor] Ignoring repeated FindAllReferences invocation with the position of already running task 2026-03-28T17:53:11+02:00 INFO [editor] Ignoring repeated FindAllReferences invocation with the position of already running task 2026-03-28T17:53:13+02:00 ERROR [lsp] Cancelled LSP request task for "textDocument/definition" id 157 which took over 120s 2026-03-28T17:53:13+02:00 WARN [project::lsp_store] Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:13+02:00 ERROR [project::lsp_store] Error handling response for request GetDefinitions { position: PointUtf16 { row: 10, column: 37 } }: Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:13+02:00 INFO [editor] Ignoring repeated FindAllReferences invocation with the position of already running task 2026-03-28T17:53:13+02:00 INFO [editor] Ignoring repeated FindAllReferences invocation with the position of already running task 2026-03-28T17:53:13+02:00 ERROR [lsp] Cancelled LSP request task for "textDocument/definition" id 189 which took over 120s 2026-03-28T17:53:13+02:00 WARN [project::lsp_store] Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:13+02:00 ERROR [project::lsp_store] Error handling response for request GetDefinitions { position: PointUtf16 { row: 12, column: 37 } }: Get definition via phpantom_lsp failed: Request timed out 2026-03-28T17:53:13+02:00 INFO [editor] Ignoring repeated FindAllReferences invocation with the position of already running task 2026-03-28T17:53:13+02:00 INFO [editor] Ignoring repeated FindAllReferences invocation with the position of already running task 2026-03-28T17:53:14+02:00 ERROR [lsp] Cancelled LSP request task for "textDocument/documentHighlight" id 195 which took over 120s 2026-03-28T17:53:14+02:00 WARN [project::lsp_store] Get document highlights via phpantom_lsp failed: Request timed out 2026-03-28T17:53:14+02:00 ERROR [crates/editor/src/editor.rs:7580] Get document highlights via phpantom_lsp failed: Request timed out 2026-03-28T17:53:14+02:00 ERROR [lsp] Cancelled LSP request task for "textDocument/codeAction" id 196 which took over 120s 2026-03-28T17:53:14+02:00 WARN [project::lsp_store] Get code actions via phpantom_lsp failed: Request timed out 2026-03-28T17:53:14+02:00 ERROR [project::lsp_store] Error handling response for request GetCodeActions { range: Anchor { timestamp: Lamport {: 1}, offset: 287, bias: Left, buffer_id: Some(BufferId(21474836661)) }..Anchor { timestamp: Lamport {: 1}, offset: 287, bias: Left, buffer_id: Some(BufferId(21474836661)) }, kinds: None }: Get code actions via phpantom_lsp failed: Request timed out`

I think we are starting to mix different issues into one. The LSP currently works by lazy loading, that means that scanning for all references is a mostly operation as it traverses all files thats considered to belong to your project, if it's not setup in a way where it can tell vendor files from the project's own files this becomes costly, this is especially true on Windows where file access is slow. Once pre indexing is implemented you can trade it up front for memory usage, but ideally it would be able to map out your project in an efficient way.

A sample project where you have this issue and maybe a bit about the system your using and IDE.

[AJenbo]

It actually does exactly that when no composer.json, but I don't recommend working like that since it's inherently impossible to infer the correct context. Instead what you should be doing is open multiple projects in a single workspace (this works a bit different between IDEs). When opening opening multiple applications you will get completion for things that are not available to the application and class collisions will give false positives for diagnostics. You can set composer to symlink the shared package so is accessible in each application.

Ah, good to know. I tried opening that project and was seeing some weird squiggles and didn't put a ton of effort into debugging further.

I agree that separate projects would be better. I've tried that in VSCode and the results were not great, but I'll give it a shot in Zed and see if it fares better. This project also doesn't have any real test coverage (another problem...) so often it's necessary to do sanity checks of the entire codebase with a global search/find/replace when doing refactors on the shared library code. Having everything available in the same project makes that possible with few surprises.

Of course in a better world, there would be tests to catch any regression but alas ;(

Edit: it appears Zed does not support multi-root workspaces.

You can open multiple windows with little cost. It's one of the reasons I started this project other LSPs are very resources hungry preventing me from working on multiple projects simultaneously.

[AJenbo]

It would also be a good idea to add an exclude_paths setting (/tests/). Currently, paths from gitignore are excluded from the index; in Drupal, modules/contrib should also be indexed.

Maybe it would be good to start an issue specifically for adding Drupal support so it can be handled intelligently rather then like a legacy system with various workaround and manual conditions

[AJenbo]

This project also doesn't have any real test coverage (another problem...) so often it's necessary to do sanity checks of the entire codebase with a global search/find/replace when doing refactors on the shared library code.

Using Phpstan would probably be the right solution here, test coverage is more for catching login issues where Phpstan let's you know if you project is semantically correct, even level 0 would go a long way here.

phpantom actually had a cli mode that gives you a lightweight check to make sure everything is correctly struktured, but it's currently only available for composer based projects.