PHPantom LSP

PHPantom is a fast, lightweight PHP language server written in Rust. It is designed to be responsive and memory-efficient, avoiding long indexing phases or heavy disk caching. It is suitable for large codebases, capable of becoming ready in seconds with minimal RAM usage.

Key Capabilities:

• Deep Type Intelligence: Supports generics, conditional return types, closure parameter inference, array shapes, and PHPStan types.
• Laravel Support: Provides intelligence for Eloquent relationships, scopes, accessors, casts, Builder chains, macros, and Blade templates without requiring ide-helper or direct database access.
• Tool Integration: Integrates with PHPStan, PHPCS, and Mago to surface diagnostics from these tools directly in your editor on save.
• Refactoring: Supports renaming, extracting methods/functions/variables/constants/interfaces, implementing interface methods, promoting constructor parameters, and modernizing syntax.
• CLI Tools: Includes analyze for batch diagnostics and fix for automated fixes, useful for CI/CD and bulk cleanup.

This demo project showcases how PHPantom provides context-aware intelligence for the Laravel framework across several domains:

Eloquent Models

Supports virtual properties from $fillable, $casts, $attributes, relationships, scopes, accessors, custom collections, and query builder forwarding.

Model Factories

Provides convention-based factories with:

• create() and make() methods returning the model.
• Synthesized dynamic relationship methods like has{Relationship}() and for{Relationship}() (e.g., BlogAuthor::factory()->hasPosts(3)->create()).
• trashed() support for models using SoftDeletes.

Navigation and Discovery

• Config & Env: Resolves config('key.name') to its file (e.g., config/app.php) and env('VAR') to .env.
• Views: Resolves view('name') and View::make('path.to.view') to Blade templates in resources/views/.
• Routes: Resolves route('name') to the corresponding route definition.
• Controllers: Supports go-to-definition, hover, rename, and completion for route action strings in [Controller::class, 'method'] and Route::controller(...) groups.
• Translations: Resolves __('key'), trans('key'), and trans_choice(...) to files in the lang/ directory.

Artisan Commands

Provides completion, go-to-definition, and diagnostics for command names used in:

• Artisan::call('command', [...])
• Artisan::queue(...)
• Schedule::command(...)
• $this->call(...)

Inside a command class, $this->argument(...) and $this->option(...) provide completion and validation against the command's signature/#[AsCommand] attribute.

Currently, the type engine records property assignments (e.g., $obj->prop = expr) as overrides to the declared class property hints. This is correct for real properties but incorrect for magic properties handled by __set. Because __set can transform or reroute values, the recorded write type should not override the type resolved via __get.

Example of the issue:

/** @template TData of array */
class DataBag {
    /** @param TData $data */
    public function __construct(private array $data) {}
    /** @return TData[K] */
    public function __get(string $property) { return $this->data[$property]; }
    /** @param TData[K] $value */
    public function __set(string $property, $value) { /* may store anything */ }
}

/** @extends DataBag<array{a: int, b: string}> */
class FooBag extends DataBag {}

$foo = new FooBag(["a" => 5, "b" => "hello"]);
$foo->a = 9;
$a = $foo->a;   // PHPantom: 9 (Incorrect) | Psalm: int (Correct via __get)

Resolution Strategy: Do not record a property write if the property is undeclared on the subject's class AND the class declares __set. This allows reads to continue resolving through __get.

PHPantom uses a prioritized resolution chain to determine the types of variables within a Blade template. This chain aligns with the Bladestan model to ensure consistency between the editor and CI type-checking.

Priority Order (Highest to Lowest):

1. Backed component class: Public properties and constructor parameters, merged with the blade-side signature.
2. @bladestan-signature docblock: The canonical contract defined via a specific marker tag. @var tags within this docblock define the template's variables.
3. Implicit docblock: The first docblock found before the template code is treated as a signature if no @bladestan-signature is present.
4. @props: Used for default-value type inference in anonymous components.
5. mixed: The fallback type if no other source is found.
6. Call-site inference: (Lowest priority) Types inferred from view() calls (e.g., compact(), ->with()) that reference the template. This is used as a fallback for unannotated projects.

PHPantom uses a high-performance, hash-consed type system centered around the PhpType handle.

Key Concepts

• PhpType: A pointer-sized handle to an interned TypeKind node. This allows structural equality to be checked via simple pointer comparison (PartialEq) rather than expensive structural walks.
• Interning: All types are routed through an interner in php_type/intern.rs. This ensures that structurally identical types share the same memory allocation, reducing memory overhead.
• Memory Efficiency: Because types are interned, a type occurrence costs only 8 bytes. The system uses weak references in the interner table so that unused type forms are reclaimed, preventing memory leaks in long-running servers.
• Usage: To inspect a type, use PhpType::kind(). To create new types, use constructors like PhpType::named, PhpType::nullable, or PhpType::union instead of constructing TypeKind directly. This ensures the pointer and structural notions of equality remain synchronized.

Data Model Integration

PhpType is used for all type-carrying fields, including:

• type_hint and native_type_hint
• return_type and native_return_type
• asserted_type
• template_param_bounds
• Generics type arguments
• ResolvedType::type_string