winzik/docs/ide-plugins.md
David Nurdin 8ceaad03c7 Apps in apps/ beside games/, config/project.yaml beside config/game.yaml (both read)
Apps, CLI apps, graphic apps and IDE plugins are made in apps/<id>; bin/jumphp, the tools, the
workflows, the IDE and the docs find a project in games/ or apps/. New projects get
config/project.yaml (under project:); the engine, bin/jumphp, the tools and the IDE still read
config/game.yaml (under game:). JUMPHP_APP is read before JUMPHP_GAME.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01X3cUrphmz1MoDiCrUbAHuo
2026-11-03 23:30:23 +01:00

16 KiB
Raw Permalink Blame History

Plugins of the JumPHP IDE

The JumPHP IDE (docs/ide.md) can be extended with plugins written in PHP. A plugin runs inside the IDE, on the user's computer. It can add:

  • actions: the Tools menu (or another menu), Find Action and keyboard shortcuts;
  • tool windows, built from simple PHP nodes;
  • run configurations;
  • completion and problems for the files it chooses;
  • tools for Claude, on the IDE's MCP server;
  • listeners and timers.

You develop a plugin like any JumPHP project: one folder, bin/jumphp test to test it, and tests that use the plugin without a window. Example: games/hello-plugin (TODO Finder).

bin/jumphp plugin:new todo-finder "TODO Finder"   # apps/todo-finder from skeleton-plugin/
bin/jumphp install todo-finder
bin/jumphp test todo-finder         # php -l, phpstan, the plugin loads in the IDE's core, its tests
bin/jumphp plugin:pack todo-finder  # apps/todo-finder/dist/todo-finder-0.1.0.zip

Try it in the IDE: Tools > Plugins… (also in File and Find Action). The window lists the installed plugins (enable, disable, remove) and the plugins of this project ("Install in the IDE"). "Install from a Folder…" takes any plugin folder. A plugin installed for the first time works at once; reload the window to see its tool windows. A new version of a plugin that is already loaded takes effect at the next start ("Restart Now"), because PHP cannot unload a class.

The IDE looks for plugins in two places:

  • the user's plugins folder, in the IDE's data folder: plugins/<id>/. Its plugins.json keeps which plugins are disabled and their settings;
  • the project's own plugins: .jumphp/plugins/<id>/, committed with the project.

Plugins run in the desktop IDE only. The web IDE (jumphp.net/ide) does not run them: a plugin is PHP, and there it would run on the server.

A plugin's folder

apps/todo-finder/
  composer.json      what the IDE reads (below)
  config/project.yaml   kind: plugin (so bin/jumphp and the IDE know this folder)
  src/TodoPlugin.php the plugin's class
  tests/             PluginTestCase tests
  phpstan.neon
{
    "name": "jumphp-plugins/todo-finder",
    "type": "jumphp-ide-plugin",
    "description": "Lists the TODO and FIXME comments of the project.",
    "require-dev": { "jumphp/ide": "*" },
    "repositories": [{ "type": "path", "url": "../../ide", "options": { "symlink": true } }],
    "autoload": { "psr-4": { "JumphpPlugins\\TodoFinder\\": "src/" } },
    "extra": {
        "jumphp-ide": { "id": "todo-finder", "name": "TODO Finder", "version": "0.1.0", "class": "JumphpPlugins\\TodoFinder\\TodoPlugin" }
    }
}
  • extra.jumphp-ide:
    • id: lower case letters, digits and dashes;
    • name: what the IDE shows;
    • version;
    • class: the class that implements JumPHP\Ide\Plugin\Plugin.
  • The IDE loads the plugin's classes with its autoload (psr-4, classmap, files). All plugins share one PHP, so give each plugin a namespace of its own (plugin:new uses JumphpPlugins\<Id>\).
  • A plugin has no Composer packages of its own when it runs. It can use PHP and the IDE's own packages (nikic/php-parser, symfony/yaml). jumphp/ide in require-dev is only for its tests.

The API

use JumPHP\Ide\Plugin\{Api, EditorState, Plugin, Ui};

final class TodoPlugin implements Plugin
{
    public function activate(Api $ide): void
    {
        $ide->action('count', 'Count the TODOs', fn (EditorState $at) => $ide->notify(substr_count($at->text, 'TODO') . ' TODO'),
            ['kbd' => 'Ctrl+Alt+T', 'icon' => 'check', 'menu' => 'Tools']);

        $window = $ide->toolWindow('todos', 'TODOs', fn () => Ui::column(
            Ui::input('Filter', fn (string $q) => $this->filter = $q, $this->filter),
            Ui::list(array_map(fn ($t) => Ui::item($t['text'], fn () => $ide->openFile($t['path'], $t['line']), $t['path']), $this->todos())),
        ), ['side' => 'right', 'icon' => 'check']);

        $ide->on('file.saved', fn (string $path) => $window->refresh());
        $ide->diagnostics('*.php', fn (string $path, string $text) => [['line' => 3, 'message' => '...', 'severity' => 'warning']]);
        $ide->completion('config/*.yaml', fn (EditorState $at) => [['label' => 'speed', 'insert' => 'speed: ', 'detail' => 'pixels per second']]);
        $ide->mcpTool('list_todos', 'The TODO comments of the project: path, line, text.', fn (array $args) => $this->todos($args['path'] ?? ''),
            ['path' => ['type' => 'string', 'description' => 'only under this folder']]);
        $ide->runConfiguration('assets', 'Rebuild the assets', ['bin/jumphp', 'php', 'games/x', 'tools/assets.php'], ['kind' => 'build']);
    }
}
Api method What it does
action($id, $label, fn (EditorState $at), [kbd, icon, menu]) Adds an action: Find Action, the main menu (menu: Tools by default; also File, Edit, View, Navigate, Code, Refactor, Run, Git) and a shortcut. If the action returns a string, the IDE shows it as a notification.
toolWindow($id, $label, fn () => Ui node, [side, icon]) Adds a tool window: a button on the stripe of side (left, right or bottom). The IDE calls the render function each time the window shows and after each of its callbacks. ->refresh() draws the window again.
runConfiguration($id, $label, $command, [kind, icon, group]) Adds a run configuration to the Run widget: the command runs in the project's folder, with its output in the Run window.
completion($glob, fn (EditorState) => items) Completion in the files that match: label, insert, detail, kind (text, keyword, value, property, method, function, class, snippet).
diagnostics($glob, fn ($path, $text) => problems) Problems in the files that match, checked as the user types: line, column, endLine, endColumn, message, severity (warning or error).
mcpTool($name, $description, fn (array $args), $properties, $required) Adds a tool for Claude, on the IDE's MCP server (see below). Returns its MCP name.
on('file.saved' | 'files.changed' | 'setting.changed', fn) A listener. file.saved gets the path; files.changed means files changed outside the editor (git, a run); setting.changed gets the name and the value saved on the plugin's settings page.
every($seconds, fn) A timer, called on the IDE's frame.
notify($message, $kind), openFile($path, $line), showToolWindow($id), run($command, $label) Asks the interface to show a notification, open a file at a line, show a tool window, or run a command in the Run window.
workspace() The project's files: files(), read(), write(), exists()… Paths are relative to the project.
root() The project's folder on this computer.
core() The IDE's core: ->index (the PHP index), ->php (code intelligence: completion, definitions, usages), ->search, ->git.
settings([$name => field, ...]) The plugin's settings page: Tools › Plugins… › Settings… next to it. A field: label, type (text, number, bool, choice), default, description, choices (choice: value => label), min / max (number). The IDE draws the form and checks the values (a number is kept between min and max).
setting($name, $default), setSetting($name, $value) The plugin's settings, kept on this computer for all projects. Without a value of the user's, setting() gives $default, else the field's default. on('setting.changed', fn (string $name, mixed $value) => ...) follows the settings page.

Globs: * (every file), *.php (a file name), config/*.yaml (a path).

EditorState describes the editor:

  • path and text: the active file and its text as typed;
  • line and column: the caret's position, both counted from 1;
  • selection: the selected text;
  • helpers: lineText(), before() (the line up to the caret), word() (the word being typed), extension().

Ui nodes (JumPHP\Ide\Plugin\Ui):

  • column(...), row(...);
  • heading(), text($t, $muted), code(), separator();
  • button($label, fn, $icon, $primary), link($label, fn);
  • list($items, $empty) and item($label, fn, $hint, $icon);
  • input($placeholder, fn (string), $value), called on Enter;
  • checkbox($label, $checked, fn (bool));
  • html(): trusted HTML of the plugin's own.

The IDE draws them in its own style, in both themes. A string among the children is a text, and a null is skipped. The callbacks run in PHP, and the window is drawn again after each one.

Icons use the IDE's names:

  • play, test, debug, refresh, check, warning;
  • file, folder, search, find, settings;
  • plus, minus, close, star, globe;
  • package, terminal, history, code, game, app, plugin.

Tools for Claude (MCP)

The IDE runs an MCP server, jumphp-ide, for the Claude Code it starts. That covers:

  • the Claude tool window;
  • jumphp.net's web IDE, through bin/jumphp claude:connect.

Claude uses it to drive the IDE: open files, point at lines, run configurations, debug. A plugin adds its own tools to that server with mcpTool():

$ide->mcpTool('list_todos', 'The TODO and FIXME comments of the project: path, line, tag, text. Use it to find what is left to do.',
    function (array $args) use ($ide): array {
        return array_values(array_filter($this->scan($ide), fn ($t) => empty($args['fixme_only']) || $t['tag'] === 'FIXME'));
    },
    ['fixme_only' => ['type' => 'boolean', 'description' => 'only the FIXME ones'],
        'path' => ['type' => 'string', 'description' => 'only under this folder of the project']],
    [],      // the required arguments
);
  • Name: $name is lower case letters, digits and _. The server offers the tool as plugin_<id>_<name>, with the - of the id written _: plugin_todo_finder_list_todos. Claude Code sees it as mcp__jumphp-ide__plugin_todo_finder_list_todos.

  • Description: the server puts the plugin's name in front of it, as [TODO Finder] …. Claude chooses its tools from their descriptions: say what the tool returns and when to use it.

  • Arguments: the JSON Schema of each argument, and which ones are required.

  • What the handler returns is what Claude reads:

    • a string;
    • an array, sent as JSON;
    • a whole MCP result, ['content' => [['type' => 'text', 'text' => '…']]] (images too);
    • a JumPHP\Ide\Async\Deferred of one of these, for work that ends later.

    An exception is the tool's error: Claude reads its message.

  • Where it runs: in PHP, in the IDE, on its frame, not in the interface. Never block. For long work, return a Deferred and settle it from every().

  • Permissions: the IDE lets its Claude use every tool of jumphp-ide without asking (--allowedTools mcp__jumphp-ide), so a plugin's tools run without a question. A tool that changes files or runs commands should say so in its description, and the plugin should ask the user itself when needed (a notification or a tool window).

  • When the list changes: Claude Code reads the tool list when it starts. A plugin installed or enabled later gives its tools to the next conversation.

  • Where to see them: the Plugins window lists each plugin's tools ("Tools for Claude"). bin/jumphp test counts them.

In tests:

  • $this->mcp('list_todos', ['fixme_only' => true]) calls the tool as the server does. It waits for a Deferred that settles at once.
  • $this->mcpTools() lists the MCP names.

The rules

  • Never block. The plugin runs on the IDE's frame: no sleep(), no long loops, no network calls that wait. For work that takes time, do a slice at a time with every(), or run a command (runConfiguration(), run()).
  • If the plugin throws an exception (when it activates, in an action, a window, a provider or a timer), the IDE shows it as a notification, and the Plugins window shows "failed" with the message. The IDE never stops because of it. A plugin that fails to activate loses everything it had added.
  • Only install plugins you trust. A plugin is PHP that runs with the user's rights. The project's own plugins (.jumphp/plugins/) load when the project opens, so only open projects you trust.

Tests

JumPHP\Ide\Testing\PluginTestCase runs the IDE's core, with no window and no Docker, on a project made of a few files. The plugin is loaded in it, and the test does what a user does:

final class TodoPluginTest extends PluginTestCase
{
    public function testAClickOpensTheLine(): void
    {
        $this->project(['src/Hero.php' => "<?php\n\n// TODO: jump higher\n"]);
        self::assertStringContainsString('jump higher', $this->toolText('todos'));
        $this->click('todos', 'jump higher');
        self::assertSame(['path' => 'src/Hero.php', 'line' => 3], $this->opened());
    }
}
Helper What it does
project([$path => $content]) A fresh project made of these files, with the plugin loaded in it.
action($id, $path, $line) Runs an action.
tool($id) The window's Ui nodes.
toolText($id) The window's texts, one per line.
click($tool, $label) Clicks a button, link, list item or check box with this label.
submit($tool, $placeholder, $text) Types text into an input and presses Enter.
`complete($path, "text with at the caret")`
problems($path, $text) The problems the plugin finds.
save($path, $content) Saves a file as the editor does, so the plugin hears file.saved.
wait($seconds) Lets time pass for the timers.
mcp($name, $args) Calls one of the plugin's tools for Claude.
mcpTools() The MCP names of the plugin's tools.
settingsPage() The settings page as the IDE shows it: name => value (the defaults until changed).
changeSetting($name, $value) The user saves a field of the settings page (setting.changed listeners run); returns the value kept.
notifications(), opened(), ui($do), errors() What the plugin asked the interface, and the errors it reported.

Sharing a plugin: jumphp.net

jumphp.net/ide-plugins is the plugins' marketplace.

  • Install: Tools › Plugins…, section "On jumphp.net". Search, then Install. When a newer version is out, the button says "Update to x.y.z".
  • Updates: the IDE checks jumphp.net for the plugins you installed, a little after it starts and then every 6 hours.
    • When a newer version is out, a notification offers Update, Plugins… and Update Automatically.
    • With Update plugins automatically (in the Plugins window), the IDE installs the new versions by itself and tells you.
    • Tools › Check for Plugin Updates checks now.
    • An update takes effect at the next start ("Restart Now"), because PHP keeps the classes it loaded.
    • Only the plugins installed in the IDE are updated. A project's own plugins (.jumphp/plugins/) change with the project.
  • Publish: Tools › Plugins…, "Plugins of this project", then "Publish on jumphp.net". Sign in with jumphp.net first. The IDE packs the folder as plugin:pack does and sends that version.
    • The first account to publish an id owns it.
    • Each version is kept. To publish again, raise extra.jumphp-ide.version.
    • homepage (or extra.jumphp-ide.repository), an https address, shows as the plugin's source code.
  • bin/jumphp plugin:pack <id> makes the same zip: dist/<id>-<version>.zip. It holds the folder without vendor/, tests/, var/ and dist/.
  • The API:
    • public: GET https://jumphp.net/api/plugins?q=, /api/plugins/<id>, /api/plugins/<id>/download?version=;
    • the IDE's (its sign-in token): POST /api/ide/plugins (the zip as the body), GET /api/ide/plugins/mine, DELETE /api/ide/plugins/<id>?version=.
  • Marks: anyone can give a plugin 1 to 5 stars, on its page (no account needed, as for the games) or in the IDE (Plugins window › Rate…, signed in). The average and the number of marks show on the page, in the list and in the IDE.
  • Statistics:
    • public: the total downloads, those of the last 30 days, the mark;
    • private, for the plugin's author only: each of the last 30 days (page views, installs and updates from the IDE, .zip downloads from the site), the downloads per version, how many marks of each. They show on the plugin's page when the author is signed in, and in the IDE (Plugins window › Statistics, next to a plugin of the project);
    • GET /api/ide/plugins/<id>/stats (the author's token), POST /api/ide/plugins/<id>/rating {"score": 4}.
  • jumphp.net never runs a plugin: it only reads its composer.json.