Download the PHP package suzumaze/bear-phpactor-extension without Composer

suzumaze/bear-phpactor-extension

English | 日本語

BEAR.Sunday conventions for phpactor, the PHP language server. This Composer package plugs BEAR.Sunday's naming and directory conventions into phpactor's LSP: definition jumps and completion that know where app://self/user lives, where SQL files go, and how JSON Schemas are named.

It implements no LSP protocol code itself — it registers a few locators and completors with phpactor's extension container.

Features (v0.1)

All jumps are pure path/namespace mapping — no PHP type inference is involved. Project roots and namespace prefixes come from the project's composer.json autoload.psr-4.

Twig / Qiq template jumps

This is BEAR.Sunday semantics implemented in phpactor's LSP definition chain, not a VS Code DefinitionProvider. Any LSP client can use it when it sends the Twig/Qiq document to phpactor; if the client does not open and send those documents, this package cannot provide jumps from them. In particular, the current Phpactor VS Code client does not select Twig documents by default. Qiq templates use .php files and reach phpactor normally; the VS Code workaround for Twig is documented under Editor setup.

Two kinds of reference are supported: explicit template paths and relations backed by BEAR.Sunday's #[Embed]. The supported standard layouts and cursor positions are deliberately narrow:

For Embed relations, both the parent and embedded Resource and the target template must exist inside the project. Only named string rel: and src: arguments on #[Embed] are used. Absolute app://self/... / page://self/... sources and relative /... sources are supported; a relative source inherits the parent Resource's scheme and resolves against the self host. A repeated rel resolves only when every occurrence names the same normalized URI; otherwise it returns no location. Dynamic template expressions, Twig import and property expressions, Qiq/PHP expressions outside the known helpers, imported-app resources, custom template roots, and ambiguous conventions are intentionally unsupported.

The VS Code extension pack's Twig navigation and idea-php-bearsunday-plugin are not replaced by this feature: those use editor-specific architecture and provide different capabilities. This package is an LSP-side option for clients such as VS Code, Neovim, and Emacs.

Installation

phpactor and this extension must share one Composer autoloader (the extension is loaded by phpactor, not the other way around). The simplest way is your project's own composer.json:

Installing phpactor into the project goes against phpactor's own advice. phpactor's README states plainly: "Phpactor is a general tool, it is not intended that it be installed as a project dependency." The reason this package still supports installing it this way is structural, not a preference: PhpactorDispatcherFactory instantiates every class listed in .phpactor.json while phpactor boots, so each class must already be autoloadable at that point — phpactor and this extension simply need to share one autoloader, and your project's vendor/ is the easiest one to reach for. It does not have to be, though: see Installing outside the project below for a way to keep your project's composer.json untouched entirely.

Notes:

• phpactor depends on dev-master packages, so your project needs "minimum-stability": "dev" (or a repositories override) for the install to resolve.
• phpactor config:trust --trust marks the directory as trusted; phpactor ignores .phpactor.json in untrusted directories.
• The extra.phpactor.extension_class key in this package's composer.json is kept for ecosystem convention only — phpactor no longer reads it. The only working load path is container.extension_classes in .phpactor.json, and it applies to the language server only (not the CLI).
• Pin phpactor/language-server-protocol to 3.17.4 (composer require --dev phpactor/language-server-protocol:3.17.4). With language-server 7.0.1 and protocol 3.17.5, textDocument/didChange never reaches the server: unsaved edits are ignored and every feature answers from the didOpen text until you save — with no error anywhere. bear-phpactor-init detects this combination and warns on stderr (the command still succeeds). The regression is fixed upstream in the pull request that makes the handler read contentChanges as objects (phpactor/language-server#68), but no release has been cut yet. Drop the pin once a fixed language-server is released.

Installing outside the project

phpactor and this extension can instead live together in one directory outside any project, leaving every project's composer.json untouched:

Copy the .phpactor.json this generates into phpactor's global config file — $XDG_CONFIG_HOME/phpactor/phpactor.json, or ~/.config/phpactor/phpactor.json if that variable is unset. phpactor reads this file before any per-project trust check, so config:trust is not required for it to take effect. Point your editor's phpactor path at this external vendor/bin/phpactor instead of a project-local one.

Verified twice, independently: a project with no vendor/ at all, and only php and autoload.psr-4 in its composer.json, gets working definition jumps this way. Tested on one machine only (macOS) — Windows and Linux are unverified.

Why .phpactor.json lists every extension class

phpactor's container.extension_classes parameter replaces the built-in defaults instead of appending to them. There is no "add my extension" option, so a project using this extension must enumerate every built-in extension class plus this one — 69 entries at the time of writing.

The built-in list is a literal array inside Phpactor::boot() with no public API, so vendor/bin/bear-phpactor-init obtains it at runtime: it runs phpactor config:dump --config-only in a clean temporary directory (so no project config can shadow the defaults) and writes the resolved list to .phpactor.json with Suzumaze\BearPhpactor\BearSundayExtension first.

After upgrading phpactor, re-run vendor/bin/bear-phpactor-init. Re-running regenerates the list from the new environment. The command is idempotent: it de-duplicates the extension list, keeps your own extension first, and preserves every other key of an existing .phpactor.json.

Skipping it fails in two different ways, and the second one is worse:

• An extension the upgrade added is missing from your list, so its features are absent. Nothing reports this.
• A class in your list no longer exists — renamed or removed upstream, or by this package. Then the language server does not start at all: PhpactorDispatcherFactory calls new $class() on every enumerated name and a fatal Class "..." not found takes the process down before it answers initialize. You lose every PHP language feature, not just this extension's, and the editor reports it as the server having crashed rather than as a configuration problem.

Verified by putting one non-existent class name in an otherwise valid .phpactor.json: the server died during startup, while the same project with the generated file answered normally.

A trap in config:trust

Run config:trust from inside the project directory, or pass an absolute path:

Passing a relative path to --working-dir records that relative string verbatim in phpactor's trust store (~/.local/share/phpactor/trust.json), and it never matches afterwards. The failure mode is silent: .phpactor.json is not read, so this extension is not loaded and every feature simply does nothing. If jumps and completion do nothing at all, check that file for a relative entry.

Definition jump behavior

Because this extension is listed first, its locators run before phpactor's built-in ones. The chain is first-match-wins, and this ordering is what makes the convention jumps work:

• Cursor on a resource class declaration name (e.g. final class User in src/Resource/App/User.php) → Go to Definition behaves like the built-in: it stays put. F12 is only VS Code's default keyboard shortcut for that editor action; the same action is available from the context menu and command palette. The built-in answer in that situation is "you are already here", and that is what you get.
• The class-name convention jump lives on Go to Type Definition instead. Right-click → Go to Type Definition (no default keybinding) on a resource class declaration name jumps to var/json_schema/user.json. The JSON Schema decides the shape of the resource body, so "where is this resource's type" is the natural question for it to answer.
• Why not Go to Definition? The convention jump used to override that action on class declaration names. In VS Code, the default shortcuts are Shift+F12 for reference search and F12 for definition; missing Shift then landed in a JSON file, which read as "reference search is broken". Moving the jump to a separate editor action removes the collision.
• Everything else is unaffected. Usage sites such as new User() are not class declarations, so the convention jump does not fire and the built-in locator handles them as usual. Normal PHP definition jumps (variables, methods, parameters, non-resource classes) are untouched.

Editor setup

The extension loads inside phpactor's language server, so any editor with an LSP client works. Point the client at your project's vendor/bin/phpactor — the one whose autoloader can see this package — not at a phpactor installed elsewhere.

VS Code

Install the official client, then tell it which binary to run:

.vscode/settings.json in your project:

The client bundles its own phpactor, and that copy cannot autoload this package. Setting phpactor.path is what makes the difference between the extension working and silently doing nothing.

The official client currently selects only php and blade documents. To opt Twig files into phpactor, add this workspace setting alongside phpactor.path:

Twig itself does not require the .html.twig suffix. This glob deliberately matches the default BEAR.Sunday TwigModule convention documented for Resource templates; it is not an attempt to recognize arbitrary Twig projects or custom template-loader configuration.

This makes VS Code send .html.twig documents to phpactor, and the definition locators still recognize them from their file extension. It is a workaround, not native Twig selector support: VS Code treats those files as PHP, which can change syntax highlighting, diagnostics, formatting, and the behavior of other Twig extensions. Keep it workspace-local and remove it if those trade-offs are unacceptable.

Trust the folder. VS Code opens an unfamiliar folder in Restricted Mode, and no language server starts there — verified by opening a project and finding no phpactor process at all. Nothing errors; the features are simply absent. Accept the trust prompt, or use Manage Workspace Trust from the command palette.

Between these two, "I installed it and nothing happens" has two likely causes. Check Restricted Mode first, since it costs one click.

phpactor.config in the same settings file does not work for loading this extension. The server reads container.extension_classes before it merges the client's initialization options, so .phpactor.json remains the only route.

Neovim

What an ambiguous jump looks like

When a URI names more than one class — the context-prefix case above — the server does not return a list of locations. It asks the editor to show a picker and waits for an answer:

Choosing an entry jumps to that class. Candidates are listed by fully qualified name, in directory order.

Reference search (textDocument/references) uses the same resolution and the same rule: a site whose URI names two or more classes is treated as unresolved and does not count as a reference. Keeping the two features on one judgment avoids explaining and implementing them twice.

The reference search finds every site that resolves to the same file as the one under the cursor — not every site with the same URI string. Two mini-apps may both use 'app://self/article'; each string is resolved from its own file's position, so a reference is reported only when it points at the file you asked about.

Measuring how much of a real project this covers

Fixtures prove a feature fires once. They do not say what fraction of a real application it reaches. tools/coverage.php answers that for four of the five features (resource URIs, query names, route paths, resource class declarations — the ALPS profile jump is not yet covered by this tool): it parses every PHP file in a target project, collects every site those features claim to answer, asks a real language server for a definition at each one, and reports the hit rate plus every miss with its file and line.

Measured on BEAR.Kata, BEAR.Sunday's own public tutorial application: 474 sites, 0 mismatches. 388 sites got the expected answer; the remaining 85 are sites where returning nothing is the correct answer (most are resource classes with no matching JSON Schema file under the naming convention — Kata's tutorial-sized codebase does not give every resource one). The expected file for each site is computed independently of this extension's own code, directly from the BEAR.Sunday naming convention, so a mistake shared by both would still surface as a mismatch here.

A separate probe for false positives — jumping from a site that should not jump — found 0 misfires across 948 checks (tools/misfire.php). Completion candidates are not covered by either tool; verifying those needs inspecting each suggestion list, which is a different kind of check.

Known limitations

• Template jumps follow the BEAR modules' default loader configuration only. Twig searches src/Resource and then var/templates, matching Madapaja.TwigModule's default AppPathProvider. Qiq searches var/qiq/template with the .php extension, matching BEAR.QiqModule. Custom Twig paths/namespaces and custom Qiq paths/extensions/collections cannot be inferred from DI bindings and are not resolved. Explicit template paths must be static string literals.
• The official VS Code phpactor client does not select Twig documents by default. Its document selector currently includes only php and blade. The files.associations workaround in Editor setup sends .html.twig files as PHP, with the corresponding language-mode trade-offs. Clients that support configuring their LSP document selector directly should attach phpactor to Twig instead. Qiq files under the BEAR default layout use .php and reach phpactor normally.
• SQL jumps land at file start (0,0). The Router and Resource URI locators land on the class-declaration name, both JSON Schema locators (attribute and convention) land on the title key inside the schema file, and the ALPS profile locator lands on the matching descriptor's id key. Only the SQL locator returns the .sql file's first line. Cosmetic, but visible in the editor.
• The resource-class scan regex can false-positive. Project::resourcePhpFiles() matches files whose text contains extends ... ResourceObject; a docblock sentence or a class extending MyResourceObject can match, which bloats URI completion candidates.
• Reference search only reads files from disk, and only inside psr-4 directories. A #[Link] you have typed but not saved does not appear in the results, and neither do sites in files outside the autoload/autoload-dev psr-4 roots — bin/*.php, public/index.php, and the like. Measured on BEAR.Kata: 16 of the sites a plain text search finds live in bin/. The definition jump is unaffected; it works from the buffer the editor sends.
• Windows absolute-path detection is incomplete in psr-4 resolution. Paths starting with / are treated as absolute; drive-letter paths (C:/src) are handled by PathGuard but not by the psr-4 directory resolution side.
• "Find all references" with includeDeclaration: true lists the class itself as the declaration. On a resource class declaration name, the definition chain no longer resolves to var/json_schema/<name>.json (the convention jump moved to Go to Type Definition), so the built-in locator answers and VS Code's "Find All References" shows the class itself in the declaration slot before the actual reference sites.

Support

This is a personal side project, maintained on a best-effort basis. Bug reports and pull requests are welcome, but there is no support commitment.

If you use PhpStorm, idea-php-bearsunday-plugin is a more complete, actively maintained option — it reads BEAR.Sunday's structure directly through JetBrains' PSI and includes features (such as MCP tool integration) this package does not attempt. This package exists for editors that speak LSP and have no BEAR.Sunday-aware plugin of their own.

Development