phpactor · dantleech · Jun 25, 2026 · Jun 23, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -137,6 +137,47 @@ jobs:
                   php -dphar.readonly=0 \
                     -dzend.assertions=1 \
                     vendor/bin/phpunit --log-junit phpunit-junit.xml
+    mago:
+        name: "Mago integration (${{ matrix.php-version }})"
+
+        runs-on: "ubuntu-latest"
+
+        permissions:
+            contents: read
+
+        strategy:
+            matrix:
+                php-version:
+                    - '8.2'
+
+        steps:
+            -
+                name: "Checkout code"
+                uses: "actions/checkout@v4"
+            -
+                name: "Install PHP"
+                uses: "shivammathur/setup-php@v2"
+                with:
+                    coverage: "none"
+                    extensions: "${{ env.REQUIRED_PHP_EXTENSIONS }}"
+                    php-version: "${{ matrix.php-version }}"
+                    tools: composer:v2
+
+            -
+                name: "Composer install"
+                uses: "ramsey/composer-install@v2"
+                with:
+                    composer-options: "--no-scripts"
+            -
+                name: "Install Mago"
+                env:
+                    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+                run: |
+                    composer require --dev --no-interaction "carthage-software/mago:^1.30"
+                    vendor/bin/mago --version
+            -
+                name: "Run Mago integration tests"
+                run: 'PATH="$PWD/vendor/bin:$PATH" vendor/bin/phpunit --group language-server-mago'
     phpstan:
         name: "PHPStan (${{ matrix.php-version }})"
 

diff --git a/doc/integrations/mago.rst b/doc/integrations/mago.rst
@@ -0,0 +1,27 @@
+Mago
+====
+
+`Mago <https://github.com/carthage-software/mago>`_ is a fast PHP linter, formatter and static analysis tool written in Rust.
+
+Phpactor can integrate with Mago and provide diagnostics in your IDE from two of its tools:
+
+- ``mago analyze`` (static analysis, the equivalent of PHPStan or Psalm), reported under the ``mago`` source.
+- ``mago lint`` (style and code smells), reported under the ``mago-lint`` source.
+
+To enable the integration set :ref:`param_language_server_mago.enabled`:
+
+.. code-block:: bash
+
+   $ phpactor config:set language_server_mago.enabled true
+
+Both tools are enabled by default once the extension is on. Toggle them independently with :ref:`param_language_server_mago.analyze.enabled` and :ref:`param_language_server_mago.lint.enabled`.
+
+- Specify the path to Mago if different to ``vendor/bin/mago`` via :ref:`param_language_server_mago.bin`. Mago is commonly installed globally, in which case set this to ``mago``.
+- Override the Mago configuration file with :ref:`param_language_server_mago.config`.
+- Adjust the run timeout (milliseconds) with :ref:`param_language_server_mago.timeout`.
+
+Phpactor sends the current buffer to Mago on standard input, so diagnostics update as you type without saving the file.
+
+.. note::
+
+   Pointing :ref:`param_language_server_mago.config` at a ``mago.toml`` outside the project root may change how Mago resolves the relative paths declared inside that file.
diff --git a/lib/Extension/LanguageServerMago/LanguageServerMagoExtension.php b/lib/Extension/LanguageServerMago/LanguageServerMagoExtension.php
@@ -0,0 +1,114 @@
+<?php
+
+namespace Phpactor\Extension\LanguageServerMago;
+
+use Phpactor\Container\Container;
+use Phpactor\Container\ContainerBuilder;
+use Phpactor\Container\OptionalExtension;
+use Phpactor\Extension\FilePathResolver\FilePathResolverExtension;
+use Phpactor\Extension\LanguageServer\Container\DiagnosticProviderTag;
+use Phpactor\Extension\LanguageServer\LanguageServerExtension;
+use Phpactor\Extension\LanguageServerMago\Model\Linter\MagoLinter;
+use Phpactor\Extension\LanguageServerMago\Model\MagoConfig;
+use Phpactor\Extension\LanguageServerMago\Model\MagoProcess;
+use Phpactor\Extension\LanguageServerMago\Provider\MagoDiagnosticProvider;
+use Phpactor\Extension\Logger\LoggingExtension;
+use Phpactor\FilePathResolver\PathResolver;
+use Phpactor\MapResolver\Resolver;
+
+class LanguageServerMagoExtension implements OptionalExtension
+{
+    public const PARAM_BIN = 'language_server_mago.bin';
+    public const PARAM_CONFIG = 'language_server_mago.config';
+    public const PARAM_TIMEOUT = 'language_server_mago.timeout';
+    public const PARAM_ENABLED = 'language_server_mago.enabled';
+    public const PARAM_ANALYZE_ENABLED = 'language_server_mago.analyze.enabled';
+    public const PARAM_LINT_ENABLED = 'language_server_mago.lint.enabled';
+    private const SERVICE_ANALYZE_PROVIDER = 'language_server_mago.provider.analyze';
+    private const SERVICE_LINT_PROVIDER = 'language_server_mago.provider.lint';
+
+    public function load(ContainerBuilder $container): void
+    {
+        $container->register(MagoProcess::class, function (Container $container) {
+            $pathResolver = $container->expect(
+                FilePathResolverExtension::SERVICE_FILE_PATH_RESOLVER,
+                PathResolver::class
+            );
+
+            $bin = $pathResolver->resolve($container->parameter(self::PARAM_BIN)->string());
+            $root = $pathResolver->resolve('%project_root%');
+
+            $config = null;
+            if ($container->parameter(self::PARAM_CONFIG)->value()) {
+                $config = $pathResolver->resolve($container->parameter(self::PARAM_CONFIG)->string());
+            }
+
+            return new MagoProcess(
+                $root,
+                new MagoConfig($bin, $container->parameter(self::PARAM_TIMEOUT)->int(), $config),
+                LoggingExtension::channelLogger($container, 'mago'),
+            );
+        });
+
+        $this->registerProvider(
+            $container,
+            self::SERVICE_ANALYZE_PROVIDER,
+            'analyze',
+            'mago',
+            self::PARAM_ANALYZE_ENABLED,
+        );
+        $this->registerProvider(
+            $container,
+            self::SERVICE_LINT_PROVIDER,
+            'lint',
+            'mago-lint',
+            self::PARAM_LINT_ENABLED,
+        );
+    }
+
+    public function configure(Resolver $schema): void
+    {
+        $schema->setDefaults([
+            self::PARAM_BIN => '%project_root%/vendor/bin/mago',
+            self::PARAM_CONFIG => null,
+            self::PARAM_TIMEOUT => 10000,
+            self::PARAM_ANALYZE_ENABLED => true,
+            self::PARAM_LINT_ENABLED => true,
+        ]);
+        $schema->setDescriptions([
+            self::PARAM_BIN => 'Path to the Mago executable',
+            self::PARAM_CONFIG => 'Override the Mago configuration file (mago.toml)',
+            self::PARAM_TIMEOUT => 'Maximum time in milliseconds to wait for a Mago run',
+            self::PARAM_ANALYZE_ENABLED => 'Show diagnostics from `mago analyze` (static analysis)',
+            self::PARAM_LINT_ENABLED => 'Show diagnostics from `mago lint` (style and code smells)',
+        ]);
+    }
+
+    public function name(): string
+    {
+        return 'language_server_mago';
+    }
+
+    private function registerProvider(
+        ContainerBuilder $container,
+        string $serviceId,
+        string $subcommand,
+        string $source,
+        string $enabledParam,
+    ): void {
+        $container->register($serviceId, function (Container $container) use ($subcommand, $source, $enabledParam) {
+            $root = $container->expect(
+                FilePathResolverExtension::SERVICE_FILE_PATH_RESOLVER,
+                PathResolver::class
+            )->resolve('%project_root%');
+
+            return new MagoDiagnosticProvider(
+                new MagoLinter($container->get(MagoProcess::class), $root, $subcommand, $source),
+                $source,
+                $container->parameter($enabledParam)->bool(),
+            );
+        }, [
+            LanguageServerExtension::TAG_DIAGNOSTICS_PROVIDER => DiagnosticProviderTag::create($source),
+        ]);
+    }
+}
diff --git a/lib/Extension/LanguageServerMago/LanguageServerMagoSuggestExtension.php b/lib/Extension/LanguageServerMago/LanguageServerMagoSuggestExtension.php
@@ -0,0 +1,50 @@
+<?php
+
+namespace Phpactor\Extension\LanguageServerMago;
+
+use Phpactor\ComposerInspector\ComposerInspector;
+use Phpactor\Configurator\Adapter\Phpactor\PhpactorConfigChange;
+use Phpactor\Configurator\Model\Changes;
+use Phpactor\Configurator\Model\JsonConfig;
+use Phpactor\Container\Container;
+use Phpactor\Container\ContainerBuilder;
+use Phpactor\Container\Extension;
+use Phpactor\Extension\Configuration\ChangeSuggestor\PhpactorComposerSuggestor;
+use Phpactor\Extension\Configuration\ConfigurationExtension;
+use Phpactor\MapResolver\Resolver;
+
+class LanguageServerMagoSuggestExtension implements Extension
+{
+    public function load(ContainerBuilder $container): void
+    {
+        $container->register('language_server_mago.suggest', function (Container $container) {
+            return new PhpactorComposerSuggestor(
+                $container->expect(ConfigurationExtension::SERVICE_PHPACTOR_CONFIG_LOCAL, JsonConfig::class),
+                $container->get(ComposerInspector::class),
+                function (JsonConfig $config, ComposerInspector $inspector) {
+                    if ($config->has(LanguageServerMagoExtension::PARAM_ENABLED)) {
+                        return Changes::none();
+                    }
+
+                    if (!$inspector->package('carthage-software/mago')) {
+                        return Changes::none();
+                    }
+
+                    return Changes::from([
+                        new PhpactorConfigChange('Mago detected, enable Mago extension?', function (bool $enable) {
+                            return [
+                                LanguageServerMagoExtension::PARAM_ENABLED => $enable,
+                            ];
+                        })
+                    ]);
+                }
+            );
+        }, [
+            ConfigurationExtension::TAG_SUGGESTOR => [],
+        ]);
+    }
+
+    public function configure(Resolver $schema): void
+    {
+    }
+}