Skip to content

SETUP.md

Latest commit

 

History

History
274 lines (190 loc) · 8.86 KB

SETUP.md

File metadata and controls

274 lines (190 loc) · 8.86 KB

Installation & Editor Setup

Installation

Pre-built Binaries

Download the latest binary for your platform from GitHub Releases. Available for:

  • x86_64-unknown-linux-gnu
  • aarch64-unknown-linux-gnu
  • x86_64-apple-darwin
  • aarch64-apple-darwin
  • x86_64-pc-windows-msvc

Build from Source

See BUILDING.md for full instructions. Quick version:

cargo build --release
# Binary is at target/release/phpantom_lsp

Editor Setup

PHPantom communicates over stdin/stdout using the standard 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.

Zed

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

  1. Ensure you have rustc available in your $PATH. This is part of the Rust toolchain
  2. Open Zed
  3. Open the Extensions panel
  4. Click Install Dev Extension
  5. Select the zed-extension/ directory

The extension automatically downloads the correct pre-built binary from GitHub releases for your platform. If you'd prefer to use a locally built binary, ensure phpantom_lsp is on your PATH and the extension will use it instead.

To make PHPantom the default PHP language server, add to your Zed settings.json:

{
  "languages": {
    "PHP": {
      "language_servers": ["phpantom_lsp", "!intelephense", "!phpactor", "!phptools", "..."]
    }
  }
}
Neovim 
vim.lsp.config['phpantom'] = {
  cmd = { '/path/to/phpantom_lsp' },
  filetypes = { 'php' },
  root_markers = { 'composer.json', '.git' },
}
vim.lsp.enable('phpantom')
VS Code

  1. Install a generic LSP client extension

  2. Download PHPantom LSP binary

    • Get it from GitHub Releases
    • Extract the binary and place it in a preferred location

  3. Configure the extension

    • Open VS Code settings for Generic LSP Client (v2)
    • Set the path to your PHPantom binary
    • Add the Language ID: php
    • Restart VS Code
PHPStorm

  1. Download PHPantom LSP binary

  2. Install and configure LSP plugin

    • Go to Editor → Plugins and install LSP4IJ

    • Restart PHPStorm

    • Navigate to Languages & Frameworks → Language Servers

    • Click + to add a new server

      • Name: PHPantom
      • Command: path to your PHPantom binary
      • 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.
PHPStorm new language server dialog PHPStorm language server mapping dialog
Sublime Text

With LSP for Sublime Text:

{
  "clients": {
    "phpantom": {
      "enabled": true,
      "command": ["/path/to/phpantom_lsp"],
      "selector": "embedding.php",
      "priority_selector": "source.php"
    }
  }
}
Helix

Helix has built-in LSP support. Add PHPantom to your languages.toml (typically ~/.config/helix/languages.toml):

[language-server.phpantom]
command = "phpantom_lsp"

[[language]]
name = "php"
language-servers = ["phpantom"]
Emacs (eglot)

[!NOTE] This configuration is untested. If you get it working (or run into issues), please open an issue.

Eglot is built into Emacs 29+. Add to your init.el:

(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               '(php-mode . ("phpantom_lsp"))))

Then open a PHP file and run M-x eglot.

Emacs (lsp-mode)

[!NOTE] This configuration is untested. If you get it working (or run into issues), please open an issue.

Add to your init.el:

(with-eval-after-load 'lsp-mode
  (lsp-register-client
   (make-lsp-client
    :new-connection (lsp-stdio-connection '("phpantom_lsp"))
    :activation-fn (lsp-activate-on "php")
    :server-id 'phpantom)))

Then open a PHP file and run M-x lsp.

Kate

[!NOTE] This configuration is untested. If you get it working (or run into issues), please open an issue.

Kate (KDE) has built-in LSP support. Open Settings → Configure Kate → LSP Client → User Server Settings and add:

{
  "servers": {
    "php": {
      "command": ["/path/to/phpantom_lsp"],
      "url": "https://github.com/AJenbo/phpantom_lsp"
    }
  }
}

Project Configuration

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 for settings like PHP version overrides and diagnostic toggles.

To generate a default config file with all options documented and commented out:

phpantom_lsp init

This creates a .phpantom.toml in the current directory. Currently supported settings:

[php]
# Override the detected PHP version (default: inferred from composer.json, or 8.5).
# version = "8.5"

[diagnostics]
# Report member access on subjects whose type could not be resolved.
# Useful for discovering gaps in type coverage. Off by default.
# unresolved-member-access = true

[indexing]
# How PHPantom discovers classes across the workspace.
#   "composer" (default) - use Composer classmap, self-scan on fallback
#   "self"    - always self-scan, ignore Composer classmap
#   "none"    - no proactive scanning, Composer classmap only
# strategy = "composer"

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.

Indexing Strategy

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.

The strategy setting controls this behaviour:

Strategy Behaviour
"composer" (default) Use Composer's classmap when available, self-scan to fill gaps. Results match what composer dump-autoload knows about.
"self" Ignore Composer's classmap entirely and scan every PHP file in the workspace. Discovers all classes regardless of autoloading.
"none" Use only Composer's classmap with no fallback scanning. The most conservative option.

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.

Classes from other files are not found

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:

  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.

  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.