Configuration Reference¶

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.

.phpantom.toml¶

PHPantom supports an optional per-project configuration file. To generate a starter config file:

phpantom_lsp init

This creates a minimal .phpantom.toml with a JSON schema directive. Editors with TOML schema support (Zed, VS Code + Even Better TOML, Neovim) provide autocomplete and hover documentation for every option via the schema. Only add settings you want to override -- when absent, all settings use their defaults.

Global config¶

Settings you want in every project belong in the global config rather than in a .phpantom.toml per repository:

phpantom_lsp init --global

It lives at $XDG_CONFIG_HOME/phpantom_lsp/.phpantom.toml (typically ~/.config/phpantom_lsp/.phpantom.toml on Linux and macOS alike, and %APPDATA%\phpantom_lsp\.phpantom.toml on Windows), takes exactly the same keys as a project config, and is read first. macOS follows the XDG path rather than ~/Library/Application Support, which is where a command-line tool's config is expected to be, and keeps the path the same across a machine you use both platforms on. A project config is then merged over it key by key, not wholesale, so a project only has to spell out the settings where it differs from your defaults: with workspace = true and extra-arguments = true set globally, a project that sets only workspace = false still gets extra-arguments.

Both the global config and a project's own .phpantom.toml are watched, and most settings take effect within a couple of seconds of saving either file. The exceptions are settings that shape the initial workspace scan, such as the PHP version and indexing strategy below -- those still need a restart to fully apply.

The full schema is at config-schema.json.

[php]¶

[diagnostics]¶

[[diagnostics.ignore]]¶

Rules that suppress matching diagnostics, similar to PHPStan's ignoreErrors. Each rule may constrain by message (regex), path (glob relative to workspace root), and/or identifier (diagnostic code). A diagnostic is suppressed when it matches every constraint present on a rule; omitted constraints match anything.

[[diagnostics.ignore]]
path = "tests/**"

[[diagnostics.ignore]]
identifier = "deprecated_usage"
message = "^Call to deprecated function some_legacy_helper\\(\\)"

[indexing]¶

[semantic_tokens]¶

PHPantom defaults to contextual semantic tokens so editor syntax highlighting remains in charge of ordinary PHP syntax.

[formatting]¶

[phpstan]¶

[phpcs]¶

[mago]¶

Mago is only activated when mago.toml exists at the workspace root.

Which of Mago's two diagnostic commands run follows the workspace mago.toml, since a project that uses Mago for one thing rarely wants the others. A mago.toml holding a [formatter] table and nothing else belongs to a project that formats with Mago and checks its code with something else, so neither mago lint nor mago analyze is proxied for it.

On a Laravel project, mago analyze additionally needs the mago.toml to wire up an extension, either an enabled [extension-hosts.*] entry or a namespaced plugin such as plugins = ["acme/laravel"]. Mago's analyser has no built-in Laravel support, so without one it cannot see through Eloquent or the facades and reports correct code in bulk. Mago's own plugins (stdlib, psl, flow-php, psr-container) do not count, since none of them supplies that knowledge. mago lint is unaffected, as its linter does have a Laravel integration.

Set lint or analyze explicitly to override all of this in either direction.

[laravel]¶

[laravel.schema]¶

[laravel.migrations]¶

The file is optional. Unknown keys are silently ignored, so the file is forward-compatible.

Code Formatting¶

PHPantom ships a built-in PHP formatter (mago-formatter) that works out of the box, so textDocument/formatting requests are answered without any setup. The formatter is chosen per project in this order:

1. Explicit config wins. A tool path set under [formatting] in .phpantom.toml (pint, php-cs-fixer, or phpcbf) is always used. Setting a tool to "" disables it.
2. Composer require-dev wins over the built-in formatter. If composer.json lists laravel/pint, friendsofphp/php-cs-fixer, or squizlabs/php_codesniffer in require-dev, PHPantom resolves the binary through Composer's bin-dir and runs it as a subprocess. A phpcs.xml, .phpcs.xml, phpcs.xml.dist, or .phpcs.xml.dist file at the workspace root certifies phpcbf the same way, so a project that only pulls squizlabs/php_codesniffer in transitively (e.g. through slevomat/coding-standard) is still detected. These tools discover their own project config (pint.json, .php-cs-fixer.php, .phpcs.xml, etc.) as they normally would.
3. Otherwise, the built-in formatter is used.

The built-in formatter defaults to the PER-CS 2.0 style. If a mago.toml is present at the workspace root, its [formatter] table is honoured instead, so PHPantom formats with the same preset and settings your project already uses with the Mago CLI:

# mago.toml
[formatter]
preset = "psr-12"
print-width = 100
use-tabs = false

For the full list of [formatter] options (presets, brace placement, blank-line handling, casing, and the rest), refer to the upstream Mago documentation: Formatter configuration reference.

Indexing Strategy¶

By default, PHPantom builds a full workspace index: it discovers PHP files, then background-parses user files to populate symbol maps and the reference candidate index. This gives complete cross-file references, implementation lookup, and workspace-wide navigation without per-feature scanning.

The strategy setting controls this behaviour:

Most projects should leave this at the default. Change it to "composer" or "none" only if you want a lighter or more Composer-constrained index.

Troubleshooting¶

Classes from other files are not found¶

PHPantom resolves cross-file classes through the full workspace index by default. If a class exists in your project but PHPantom reports it as unknown, the most common causes are:

1. The file is excluded from the workspace walk. Check ignored directories and .gitignore rules. If you explicitly set strategy = "composer" or "none", classes outside Composer's autoload rules may be skipped.

2. Composer's classmap is stale. Run composer dump-autoload to regenerate it. PHPantom reads the classmap at startup.

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.