PHP Ninja
PHP tooling for VS Code:
- Global JSDoc-style
@typedef for PHPDoc, with completion, hover and go to definition.
- Hover docs for built-in PHP symbols and for the symbols in your workspace.
Coming from "PHP Typedef"? This extension replaces it. Uninstall the old one, and rename your settings from phpTypedef.* to phpNinja.* and the command from PHP Typedef: Reindex Workspace to PHP Ninja: Reindex Workspace.
@typedef
No holder class, no per-file imports.
<?php
namespace App\Types;
/**
* @typedef UserAddress array{street: string, city: string, zip?: string}
*
* @typedef User array{
* id: int,
* name: string,
* address: UserAddress
* }
* @typedef Collection<T> array<int, T>
* @typedef Id int|string
*/
Use it anywhere in the workspace:
/** @param User $user */
function show(array $user) {
echo $user['address']['ci // completes: street, city, zip
}
- Workspace-wide index of
@typedef in all *.php files (any docblock, class or not). Updates on edit/save.
- Multi-line definitions, generics (
Collection<T>), unions, nullable, optional keys, T[], array<K,V>, list<T>.
- Name resolution: absolute
\Ns\Name, use imports (with as), current namespace, then a short-name match anywhere in the workspace (phpNinja.globalFallback).
- Completion of array keys after
$var[, $var[', nested to any depth, through aliases, generics and [0] element access.
- Completion of typedef names after
@param, @var, @return, @property.
- Hover and Go to Definition on typedef names inside docblocks.
A variable's type is taken from the closest preceding @param Type $x, @var Type $x, or /** @var Type */ $x = .... Inferring types from arbitrary expressions or function calls is not implemented.
Symbol hover
Hover on a PHP symbol shows its signature, description, @param/@returns/@throws/@deprecated tags and a link. It covers:
- Built-ins: functions, constants, classes and their methods, properties and constants. Text comes from the PHP manual: the one-line summary, description, parameters, return values, errors, changelog and notes, with the manual's cross references turned into links. Every hover ends with a link to the exact manual page (
[PHP Manual](https://gitlab.com/GCSBOSS/vscode-php-ninja/-/blob/HEAD/...) · extension · PHP versions). Signatures and anything the manual lacks come from JetBrains phpstorm-stubs (Apache-2.0) for PHP 8.4, limited to extensions bundled with PHP. Long sections are shortened; the manual link has the rest.
- Your workspace: functions, classes, interfaces, traits, enums, constants (
const and define()) and their methods, properties, constants and enum cases, with a link to where they are declared. Docblock types win over native ones, so @param User $user on an array $user shows User $user (@phpstan-param and @psalm-param win over @param).
- Where it works: calls,
new, type hints, catch, use imports, Foo::bar(), Foo::BAR, Foo::$bar, self::, static::, parent::, $this->member, declarations themselves (class, method, property, promoted constructor property, constant, enum case) and class names inside docblock types (@param, @return, @var, @throws, ...).
- Name resolution follows PHP: leading
\, use / use function / use const (including grouped imports and as), the current namespace, and the global fallback for functions and constants. An unimported class inside a namespace resolves to Namespace\Name, never to a built-in.
- Not covered yet: members of other objects (
$user->name) need type inference. Strings, comments, inline HTML and variables get no hover (except property declarations).
Indexing: every *.php file not matched by phpNinja.exclude is parsed in the background (about 7 MB/s) and kept up to date as you type, save, create or delete files. vendor/ is excluded by default.
Settings
phpNinja.exclude: glob excluded from indexing (default **/{node_modules,vendor,.git}/**).
phpNinja.globalFallback: resolve unqualified typedef names by unique short name workspace-wide (default true).
phpNinja.builtinHover.enabled: hover for built-in PHP symbols (default true).
phpNinja.builtinHover.sections: which manual sections the built-in hover shows. Choose from description, parameters, returns, errors, changelog, notes, examples, seeAlso. Default: all but examples and seeAlso. The signature, summary and manual link are always shown.
phpNinja.workspaceHover.enabled: index the workspace and hover its symbols (default true).
Turn the two hover settings off while Intelephense is on if you do not want duplicate hovers.
Intelephense
This extension runs next to Intelephense and cannot feed types into its engine. Completions are merged, and hovers, go to definition and diagnostics from both are shown.
Known limitation: Intelephense does not know @typedef. It reads a typedef name in @param/@var/@return as a class and reports PHPDoc undefined type 'Ns\User'. When the typedef is the only type (@param User $u), it also reports Expected type 'array|string|ArrayAccess'. Found 'Ns\User' on $u['id']. An extension cannot suppress another extension's diagnostics. Docblocks that declare @typedef produce no errors.
Not yet implemented: PHPStan/Psalm stub generation, diagnostics, $obj->prop chains, @return inference.
Third-party code
Develop
npm install
npm run compile
Press F5 to launch the Extension Development Host.
Regenerate the built-in data with npm run build:builtins. It compiles, clones the stubs and downloads the PHP manual (13 MB) into .cache/, then writes data/builtins.json.gz and data/manual/<extension>.json.gz (about 1.7 MB together). Add -- --no-manual to skip the manual. The generated files are committed.
Tests
npm run test:unit: mocha tests for parsing, name resolution, extraction and hover rendering (no VS Code needed).
npm run test:integration: runs inside a real VS Code Extension Host via @vscode/test-cli against test-fixtures/workspace (downloads VS Code on first run). Its intelephense entry also installs Intelephense (bmewburn.vscode-intelephense-client) and checks that both extensions work side by side.
npm test: unit and integration.
| |