Mago

https://github.com/carthage-software/mago
Admin
Mago is an extremely fast PHP linter, formatter, and static analyzer written in Rust, designed to...
Tokens:953,880
Snippets:6,964
Trust Score:6
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### PHP class with setUp initializer

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/analyzer/configuration-reference.md

Example class that avoids a false positive when the analyzer is configured with class-initializers. The setUp method is treated as an initializer, so the typed property $name is considered definitely initialized.

```php
class MyTest extends TestCase
{
    private string $name;

    protected function setUp(): void
    {
        $this->name = "test";
    }
}
```

--------------------------------

### PHP Hello World Example

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

Example of a good PHP code snippet that prints 'Hello World'.

```php
<?php

echo "Hello World";
```

--------------------------------

### Install Mago with wget

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/installation.md

Alternative to the curl installer for macOS and Linux. Uses wget to fetch and pipe the installer script to bash.

```sh
wget -qO- https://carthage.software/mago.sh | bash
```

--------------------------------

### Install Node tooling for Pagefind

Source: https://github.com/carthage-software/mago/blob/main/docs/README.md

One-time installation of Node tooling required for Pagefind.

```bash
npm install
```

--------------------------------

### Install Mago via shell script

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/_index.md

One-command installer for macOS, Linux, and WSL. Downloads and runs the official install script from carthage.software. No PHP runtime required; installs a single static binary.

```shell
curl --proto '=https' --tlsv1.2 -sSf https://carthage.software/mago.sh | bash
```

--------------------------------

### Install Mago via WinGet and self-update

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/installation.md

Installs Mago via WinGet on Windows and updates the installed binary afterwards, as the WinGet package can lag behind the GitHub release.

```powershell
winget install CarthageSoftware.Mago
mago self-update
```

--------------------------------

### Generate shell completions for fish, zsh, and bash

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/generate-completions.md

Generate completion scripts for fish, zsh, and bash. The fish example pipes directly to source for ad-hoc use; the zsh and bash examples redirect to files for persistent installation.

```sh
mago generate-completions fish
mago generate-completions fish | source              # fish, ad-hoc
mago generate-completions zsh > ~/.zfunc/_mago      # zsh, persisted
mago generate-completions bash > /etc/bash_completion.d/mago
```

--------------------------------

### Verify Mago installation with mago --version

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/installation.md

Run this command in your terminal to verify that Mago is installed correctly. If it prints a version number, the installation is successful and you can proceed to run Mago against your code.

```sh
mago --version
```

--------------------------------

### Example output of mago list-files with different commands

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/list-files.md

Shows the resulting file lists for the example configuration. The default list includes src and tests minus cache; the analyzer list excludes tests; the formatter list excludes AutoGenerated files.

```sh
mago list-files                       # src/** + tests/**, minus cache/**
mago list-files --command analyzer    # src/** only (tests excluded)
mago list-files --command formatter   # src/** + tests/**, minus AutoGenerated files
```

--------------------------------

### ambiguous-constant-access: Good Example

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

Good example for the ambiguous-constant-access rule: uses explicit import or global reference to avoid ambiguity.

```php
<?php

namespace App;

use const PHP_VERSION;

// OK: Explicitly imported
$version1 = PHP_VERSION;

// OK: Explicitly global
$version2 = \PHP_VERSION;
```

--------------------------------

### Install Mago via shell script

Source: https://github.com/carthage-software/mago/blob/main/README.md

Install Mago on macOS and Linux via the official shell script. The first command installs the latest version; the second installs a specific version by passing the --version flag to the installer.

```sh
curl --proto '=https' --tlsv1.2 -sSf https://carthage.software/mago.sh | bash
```

```sh
curl --proto '=https' --tlsv1.2 -sSf https://carthage.software/mago.sh | bash -s -- --version=1.52.0
```

--------------------------------

### Use full `<?php` opening tag

Source: https://github.com/carthage-software/mago/blob/main/docs/content/zh/tools/linter/rules.md

Good example: using the full `<?php` opening tag, which is portable and always interpreted correctly.

```php
<?php

echo "Hello, World!";
```

--------------------------------

### ambiguous-constant-access: Bad Example

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

Bad example for the ambiguous-constant-access rule: unqualified constant reference inside a namespace is ambiguous.

```php
<?php

namespace App;

// Ambiguous: could be App\PHP_VERSION or \PHP_VERSION
$version = PHP_VERSION;
```

--------------------------------

### Quick start: run Mago lint via Docker

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/recipes/docker.md

Mount the current directory and run the lint command. The image is built from scratch and is about 26 MB.

```sh
docker run --rm -v $(pwd):/app -w /app ghcr.io/carthage-software/mago lint
```

--------------------------------

### Install Mago via Cargo and self-update

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/installation.md

Installs Mago via Cargo and runs mago self-update because Crates.io publishing can lag a few hours behind a release.

```sh
cargo install mago
mago self-update
```

--------------------------------

### use-specific-expectations: Use dedicated Pest matchers

Source: https://github.com/carthage-software/mago/blob/main/docs/content/zh/tools/linter/rules.md

The 'avoid' example shows generic Pest comparisons that should be replaced with dedicated matchers, while the 'recommended' example shows the specific matchers. This rule requires the Pest integration to be enabled.

```php
<?php

test('generic comparisons', function () {
    expect($value)->toBe(true);
    expect($value)->toBe(false);
    expect($value)->toBe(null);
    expect($array)->toBe([]);
    expect($value)->not->toBeFalse();
});
```

```php
<?php

test('specific matchers', function () {
    expect($value)->toBeTrue();
    expect($value)->toBeFalse();
    expect($value)->toBeNull();
    expect($array)->toBeEmpty();
});
```

--------------------------------

### disallowed-type-instantiation: bad vs good

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

The first example shows direct instantiation of disallowed types, which is flagged. The second example shows using a factory method instead, which is the recommended approach.

```php
<?php

// Direct instantiation of disallowed type
$client = new HttpService\Client();

// Another disallowed instantiation
$db = new DatabaseConnection('localhost', 'user', 'pass');

```

```php
<?php

// Using factory pattern instead of direct instantiation
$client = ClientProvider::getClient();

```

--------------------------------

### Manually download, verify, and install Mago

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/installation.md

Manual download and verification workflow for any system without bash. Downloads the release archive, verifies its attestation with gh, extracts it, and installs the binary. A successful verification prints 'Verification succeeded!' and the workflow run that produced the archive.

```sh
VERSION=1.52.0
TARGET=x86_64-unknown-linux-gnu  # adjust for your platform
ASSET=mago-${VERSION}-${TARGET}.tar.gz

gh release download "$VERSION" --repo carthage-software/mago --pattern "$ASSET"
gh attestation verify "$ASSET" \
  --repo carthage-software/mago \
  --signer-workflow carthage-software/mago/.github/workflows/cd.yml

tar -xzf "$ASSET"
sudo mv "mago-${VERSION}-${TARGET}/mago" /usr/local/bin/
```

--------------------------------

### Install Mago via Homebrew and self-update

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/installation.md

Installs Mago via Homebrew and immediately runs mago self-update because the community-maintained formula often lags the official release.

```sh
brew install mago
mago self-update
```

--------------------------------

### Pin a specific Mago version

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/installation.md

Installs a specific Mago version by passing the --version flag to the installer script. The same syntax works with wget.

```sh
curl --proto '=https' --tlsv1.2 -sSf https://carthage.software/mago.sh | bash -s -- --version=1.52.0
```

--------------------------------

### stringify rule example

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

Example for the stringify rule, showing a function that converts a mixed value to string if it implements Stringable, otherwise returns an empty string.

```php
<?php

function stringify(mixed $value): string {
    if ($value instanceof Stringable) {
        return (string) $value;
    }

    return '';
}

```

--------------------------------

### string-style: Bad Example (interpolation)

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

Bad example for the string-style rule with default style 'interpolation': flags concatenation and suggests interpolation.

```php
<?php

// With the default `style: interpolation`:
$a = "Hello, " . $name . "!";
$b = "value: " . $obj->name;
```

--------------------------------

### no-inline-html: Good example without inline HTML

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

Good example for the no-inline-html rule: PHP file without inline HTML.

```php
<?php

namespace App;

echo "Hello, world!";
```

--------------------------------

### no-isset bad example

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

Bad example for the no-isset rule: using isset() conflates variable existence and null comparison, leading to ambiguous code.

```php
<?php

if (isset($value)) {
    // ...
}

```

--------------------------------

### no-isset good example

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

Good example for the no-isset rule: using explicit null checks and the null coalescing operator (??) is clearer and more maintainable.

```php
<?php

if ($value !== null) {
    // ...
}

$result = $value ?? 'default';

```

--------------------------------

### Install Mago via Composer

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/installation.md

Installs the Mago Composer package for PHP projects. The first call to vendor/bin/mago downloads and caches the matching pre-built binary; subsequent calls use the cache without network requests.

```sh
composer require --dev "carthage-software/mago:^1.52.0"
```

--------------------------------

### Too many methods: bad vs good example

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

The first example shows a class with too many methods, triggering the too-many-methods rule. The second shows a simpler class with fewer methods, which is preferred.

```php
<?php

class ComplexClass {
    public function a() {}
    public function b() {}
    public function c() {}
    public function d() {}
    public function e() {}
    public function f() {}
    public function g() {}
    public function h() {}
    public function i() {}
    public function j() {}
    public function k() {}
    public function l() {}
    public function m() {}
    public function n() {}
    public function o() {}
    public function p() {}
    public function q() {}
    public function r() {}
    public function s() {}
    public function t() {}
    public function u() {}
}

```

```php
<?php

class SimpleClass {
    public function a() {}
    public function b() {}
}

```

--------------------------------

### Too many properties: bad vs good example

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

The first example shows a class with too many properties, triggering the too-many-properties rule. The second shows a simpler class with fewer properties, which is preferred.

```php
<?php

class ComplexClass {
    public $a; public $b; public $c; public $d; public $e;
    public $f; public $g; public $h; public $i; public $j; public $k;
}

```

```php
<?php

class SimpleClass {
    public $a;
    public $b;
}

```

--------------------------------

### Build documentation site with cargo run

Source: https://github.com/carthage-software/mago/blob/main/docs/README.md

Builds the static documentation site, writing HTML to dist/.

```bash
cargo run -p mago-documentation
```

--------------------------------

### single-class-per-file: Good example - single class in file

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

Shows a PHP file with only one class definition, which satisfies the single-class-per-file rule. This is the recommended approach for better organization.

```php
<?php

namespace App;

class Foo
{
}
```

--------------------------------

### Check granular capability with current_user_can

Source: https://github.com/carthage-software/mago/blob/main/docs/content/zh/tools/linter/rules.md

Good example: checking a granular capability instead of a role.

```php
<?php

if ( current_user_can( 'edit_posts' ) ) { /* ... */ }
```

--------------------------------

### Install Mago with mandatory verification

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/installation.md

Makes attestation verification mandatory. The installer aborts before touching the PATH if gh is unavailable, too old, or the attestation does not match. Mutually exclusive with --no-verify.

```sh
curl --proto '=https' --tlsv1.2 -sSf https://carthage.software/mago.sh | bash -s -- --always-verify
```

--------------------------------

### Run mago init

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/initialization.md

Run in the project root to start the interactive initialization. If a composer.json is present, Mago offers to pre-fill source paths, PHP version, and framework integrations; otherwise it falls back to a manual walkthrough.

```sh
mago init
```

--------------------------------

### no-missing-format-argument: sprintf with missing vs correct arguments

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

The first example shows a sprintf call with a missing argument, which will trigger a runtime error. The second example provides the correct number of arguments.

```php
<?php

// Missing second value; will trigger a runtime error.
$result = sprintf('Hello %s, you have %d messages', $name);
```

```php
<?php

$result = sprintf('Hello %s, you have %d messages', $name, $count);
```

--------------------------------

### Avoid: direct instantiation of disallowed types

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/linter/rules.md

Example of disallowed direct instantiation that triggers a warning.

```php
<?php

// Direct instantiation of disallowed type
$client = new HttpService\Client();

// Another disallowed instantiation
$db = new DatabaseConnection('localhost', 'user', 'pass');

```

--------------------------------

### PHPVersion

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/extensions/sdk/extensions-and-workers.md

Documentation for the PHPVersion class, including its methods and usage example.

```APIDOC
## PHPVersion

### Description
Represents the configured target PHP version. Provides methods to compare versions and extract components.

### Methods
- `fromParts(int $major, int $minor, int $patch): PHPVersion` - Creates a PHPVersion instance from major, minor, and patch components.
- `major(): int` - Returns the major version component.
- `minor(): int` - Returns the minor version component.
- `patch(): int` - Returns the patch version component.
- `isAtLeast(PHPVersion $other): bool` - Returns true if this version is at least the given version.

### Example
```php
if ($context->phpVersion->isAtLeast(PHPVersion::fromParts(8, 4))) {
    // Apply PHP 8.4-specific behavior.
}
```
```

--------------------------------

### Typical Mago workflow commands

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/getting-started.md

Shows the typical Mago workflow: initialize a configuration file, lint, format, and analyze. Each command is a separate step in the pipeline.

```sh
mago init           # write a starter mago.toml
mago lint           # surface stylistic and correctness issues
mago format         # rewrite files to match the formatter
mago analyze        # type-check and find logic bugs
```

--------------------------------

### Prefer: factory pattern for object creation

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/linter/rules.md

Example of using a factory pattern to avoid direct instantiation of disallowed types.

```php
<?php

// Using factory pattern instead of direct instantiation
$client = ClientProvider::getClient();

```

--------------------------------

### mago init usage

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/initialization.md

Shows the command usage. The only flag is -h/--help to print help and exit. Global flags must come before the subcommand.

```sh
Usage: mago init
```

--------------------------------

### Apply formatting

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/recipes/docker.md

Run the formatter to apply formatting to the project files.

```sh
docker run --rm -v $(pwd):/app -w /app ghcr.io/carthage-software/mago fmt
```

--------------------------------

### Create project-owned extension entrypoint .mago/extensions.php

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/extensions/development/packaging-and-compatibility.md

Creates a PHP entrypoint that instantiates the extension and runs the Worker. Requires the project's autoloader and the AcmeExtension class.

```php
<?php

declare(strict_types=1);

use Acme\Mago\AcmeExtension;
use Mago\Sdk\Worker;

require dirname(__DIR__) . '/vendor/autoload.php';

(new Worker(
    AcmeExtension::create(),
))->run();
```

--------------------------------

### no-trailing-space: Good Example

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

Good example for the no-trailing-space rule: a comment without trailing whitespace.

```php
<?php

// This is a good comment.
```

--------------------------------

### Sync binary to project version with mago self-update --to-project-version

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/configuration.md

Syncs the installed binary to the version pinned in mago.toml. For exact pins it resolves directly to that release tag; for major or minor pins it scans recent GitHub releases and installs the highest satisfying release.

```sh
mago self-update --to-project-version
```

--------------------------------

### no-trailing-space: Bad Example

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

Bad example for the no-trailing-space rule: a comment with trailing whitespace at the end.

```php
<?php

// This is a comment with trailing whitespace.
```

--------------------------------

### Examples of suppressing issues with @mago-expect and @mago-ignore

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/fundamentals/suppressing-issues.md

A collection of examples showing how to suppress specific issues with @mago-expect and @mago-ignore. It covers guard, lint, and analysis codes, including multiple codes on one line, counting occurrences with (3), and suppressing all issues for a function.

```php
// Suppress a guard issue
// @mago-expect guard:disallowed-use
use App\Infrastructure\SomeForbiddenClass;

// Suppress one lint issue
// @mago-expect lint:no-shorthand-ternary
$result = $condition ?: 'default';

// Suppress issues for an entire function
// @mago-expect analysis:missing-return-statement,impossible-condition
function complexFunction(): string {
    if (false) {
        return 'never reached';
    }
}

// Three occurrences of one code on the next line
// @mago-expect analysis:mixed-operand(3)
return $a . $b . $c;

// All lint issues on one line
// @mago-ignore lint:all
$result = $value ?: ($x == true ? 'yes' : 'no');

// Everything, for a legacy function
// @mago-ignore all
function legacyFunction(): string {
    // Everything suppressed here.
}
```

--------------------------------

### Run tests and linter

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/contributing.md

Run the test suite and the linter using Just. Run these before committing.

```bash
just test
just check
```

--------------------------------

### no-redundant-variable: Unused variable example

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

This example shows a variable $unused that is assigned but never read, which is flagged by the no-redundant-variable rule.

```php
<?php

function greet(string $name): string
{
    $unused = compute_something();

    return "Hello, $name!";
}

```

--------------------------------

### no-inline-html: Bad example with inline HTML

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

Bad example for the no-inline-html rule: inline content before and after PHP tags is flagged.

```php
<?php

echo "Hello, world!";

?>
Goodbye
```

--------------------------------

### no-unused-global: used global (good)

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

An example of a global declaration that is used, which is the correct pattern for the no-unused-global rule. This is the 'good' example to follow.

```php
<?php

function bump(): void {
    global $counter;
    $counter++;
}

```

--------------------------------

### Configure class-initializers for property initialization

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/analyzer/configuration-reference.md

Enables the property initialization check and lists method names treated as class initializers. Bare names like "boot" apply to any class defining that method; qualified entries like "PHPUnit\Framework\TestCase::setUp" only apply to classes that extend or implement the named class.

```toml
[analyzer]
check-property-initialization = true
class-initializers = [
    "boot",
    "PHPUnit\Framework\TestCase::setUp",
    "PHPUnit\Framework\TestCase::setUpBeforeClass",
    "Symfony\Component\Console\Command\Command::configure",
]
```

--------------------------------

### no-unused-global: unused global (bad)

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

An example of a global declaration that is never used, which is flagged by the no-unused-global rule. This is the 'bad' example to avoid.

```php
<?php

function f(): void {
    global $forgotten;
}

```

--------------------------------

### Run a worker with FrameworkExtension

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/extensions/sdk/extensions-and-workers.md

Creates a worker with a single framework extension and runs it. The run() method owns the process protocol loop, reading from the SDK-selected input transport and writing frames to standard output. Production entrypoints should use the default input/output resources.

```php
use Vendor\Framework\Mago\FrameworkExtension;
use Mago\Sdk\Worker;

(new Worker(
    FrameworkExtension::create(strict: true),
))->run();
```

--------------------------------

### require-namespace: Good example - class with namespace

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

Shows a PHP file with a namespace declaration, which satisfies the require-namespace rule. This is the recommended approach to avoid naming conflicts.

```php
<?php

namespace App;

class Foo {}
```

--------------------------------

### no-unused-closure-capture: unused capture (bad)

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

An example of a closure that captures a variable but does not use it, which is flagged by the no-unused-closure-capture rule. This is the 'bad' example to avoid.

```php
<?php

$base = 10;
$add = function (int $x) use ($base): int {
    return $x;
};

```

--------------------------------

### Configuration with global and tool-specific excludes

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/list-files.md

Example configuration showing global excludes under [source] and tool-specific excludes under [analyzer] and [formatter]. The comments indicate which files are excluded from every tool or additionally from analysis/formatting.

```toml
[source]
paths    = ["src", "tests"]
excludes = ["cache/**"]                        # excluded from every tool

[analyzer]
excludes = ["tests/**/*.php"]                   # additionally excluded from analysis

[formatter]
excludes = ["src/**/AutoGenerated/**"]         # additionally excluded from formatting
```

--------------------------------

### Run Mago via Nixpkgs

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/installation.md

Enters a Nix shell with Mago and prints its version. Uses the pre-built Mago derivation from Nixpkgs.

```sh
nix-shell -p mago
mago --version
```

--------------------------------

### no-unused-static: used static (good)

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

An example of a static variable declaration that is used, which is the correct pattern for the no-unused-static rule. This is the 'good' example to follow.

```php
<?php

function next_id(): int {
    static $counter = 0;
    return ++$counter;
}

```

--------------------------------

### Create the worker entrypoint (acme-worker.php)

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/extensions/getting-started.md

Creates the worker entrypoint in .mago/acme-worker.php. It instantiates the Worker with the extension and runs it. The entrypoint must reserve standard output for the SDK protocol; write diagnostics to standard error instead.

```php
<?php

declare(strict_types=1);

use Acme\Mago\AcmeExtension;
use Mago\Sdk\Worker;

require dirname(__DIR__) . '/vendor/autoload.php';

(new Worker(
    AcmeExtension::create(),
))->run();

```

--------------------------------

### no-unused-static: unused static (bad)

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

An example of a static variable declaration that is never used, which is flagged by the no-unused-static rule. This is the 'bad' example to avoid.

```php
<?php

function f(): void {
    static $forgotten = 0;
}

```

--------------------------------

### Use default plugins (stdlib only)

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/analyzer/configuration-reference.md

Shows the minimal [analyzer] TOML section that uses the default stdlib plugin. No extra configuration is needed.

```toml
[analyzer]

```

--------------------------------

### Good: simplified return patterns

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

Good example for the no-redundant-literal-return rule: shows simplified code without redundant literal returns, and a case where a guard is necessary.

```php
<?php

function getValue($x) {
    return $x;
}

function getValueOrDefault($x, $default) {
    if ($x === null) {
        return $default;
    }
    return $x;
}

```

--------------------------------

### Basic [source] configuration with paths, patches, includes, excludes, and extensions

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/configuration.md

Defines the four path categories and the extensions option. The more specific pattern wins when a file matches both paths and includes; equally specific patterns favor includes.

```toml
[source]
paths     = ["src", "tests"]
patches   = ["patches"]
includes  = ["vendor"]
excludes  = ["cache/**", "build/**", "var/**"]
extensions = ["php"]
```

--------------------------------

### no-unused-closure-capture: used capture (good)

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

An example of a closure that captures and uses a variable, which is the correct pattern for the no-unused-closure-capture rule. This is the 'good' example to follow.

```php
<?php

$base = 10;
$add = function (int $x) use ($base): int {
    return $x + $base;
};

```

--------------------------------

### Configure worker with extension factory

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/extensions/linter/overview.md

PHP example showing how to pass extension options via the worker entrypoint or extension factory. Here, AcmeExtension::create(requireFinalServices: true) is passed to the Worker constructor.

```php
(new Worker(
    AcmeExtension::create(requireFinalServices: true),
))->run();
```

--------------------------------

### class-name: Recommended class definition

Source: https://github.com/carthage-software/mago/blob/main/docs/content/zh/tools/linter/rules.md

Recommended example for the class-name rule. Uses a PSR-4 compliant class name with braces and a namespace.

```php
<?php
// File: test.php

namespace App;

class test
{
}

```

--------------------------------

### Format the project with mago format

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/formatter/usage.md

Formats every source file declared in mago.toml in place. Run it after pulling, before committing, or as a step in CI.

```sh
mago format
```

--------------------------------

### Avoid ini_set() for runtime configuration

Source: https://github.com/carthage-software/mago/blob/main/docs/content/zh/tools/linter/rules.md

Bad example for the no-ini-set rule: calling ini_set() to change runtime configuration, which can override server settings unpredictably.

```php
<?php

// This can override server settings in an unpredictable way.
ini_set( 'display_errors', 1 );
ini_set( 'memory_limit', '256M' );

```

--------------------------------

### Avoid vs Prefer: Use getenv for passwords

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/linter/rules.md

Avoid hardcoding passwords; use environment variables instead.

```php
<?php

$password = "supersecret";

```

```php
<?php

$password = getenv('DB_PASSWORD');

```

--------------------------------

### Make pre-commit hook executable

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/recipes/pre-commit-hooks.md

Make the pre-commit hook executable. Run this after creating the hook file.

```bash
chmod +x .git/hooks/pre-commit
```

--------------------------------

### Example output of mago inspect-baseline

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/fundamentals/baseline.md

Example output from mago inspect-baseline showing the ranked bar chart of issue codes. The ellipsis indicates truncated output.

```plaintext
359670 issues across 221 codes

  49543  ██████████████████████████████  mixed-return-statement
  32167  ███████████████████             mixed-argument
  31707  ███████████████████             non-existent-property
  …

```

--------------------------------

### Run static analysis

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/recipes/docker.md

Run the static analyzer on the project.

```sh
docker run --rm -v $(pwd):/app -w /app ghcr.io/carthage-software/mago analyze
```

--------------------------------

### Ignore a region with @mago-format-ignore-start/end

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/formatter/format-ignore.md

Preserves everything between the start and end markers. If the region is opened but never closed, formatting is preserved from the start marker to the end of the file.

```php
<?php

$formatted = 'normal';

// @mago-format-ignore-start
$a=1;
$b=2;
$c=3;
// @mago-format-ignore-end

$alsoFormatted = 'normal';
```

```php
<?php

class Example
{
    public const FORMATTED = 1;

    // @mago-format-ignore-start
    public const A = 1;
    public const B = 2;
    public $prop = 123;
    public function foo() { return 1; }
    // @mago-format-ignore-end

    public const ALSO_FORMATTED = 3;
}
```

--------------------------------

### getResolvedName(Node $node)

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/extensions/sdk/syntax-and-source.md

Looks up the semantic name whose span starts at the selection's start offset. Returns null if no resolved name is found.

```APIDOC
## getResolvedName(Node $node)

### Description
Looks up the semantic name whose span starts at the selection's start offset. Returns null if no resolved name is found.

### Method
SDK Method

### Endpoint
`getResolvedName(Node $node)`

### Parameters
#### Path Parameters
- **$node** (Node) - Required - The node whose resolved name is to be retrieved.

### Returns
- **ResolvedName|null** - The resolved name object with properties `name`, `span`, and `imported`, or null if not found.

### Example
```php
$resolved = $source->getResolvedName($callNode);
if ($resolved !== null) {
    $resolved->name;     // e.g. Psl\Iter\any
    $resolved->span;     // range of the name in source
    $resolved->imported; // whether an import participated
}
```
```

--------------------------------

### no-redundant-use: Avoid and prefer examples

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/linter/rules.md

Avoid use statements that import unused items or import from the same namespace. Prefer removing unused imports to keep the code clean.

```php
<?php
namespace App;

use App\Helpers\ArrayHelper;
use App\Helpers\StringHelper; // StringHelper is not used.

$result = ArrayHelper::combine([]);

```

```php
<?php
namespace App;

use App\Helpers\ArrayHelper;

$result = ArrayHelper::combine([]);

```

--------------------------------

### string-style: Good Example (interpolation)

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

Good example for the string-style rule with default style 'interpolation': uses interpolation for simple expressions and keeps concatenation for complex ones.

```php
<?php

// With the default `style: interpolation`:
$a = "Hello, {$name}!";
$b = "value: {$obj->name}";

// Complex expressions stay as concatenation (never flagged):
$c = "result: " . strtolower($input);
$d = "class: " . Foo::class;
```

--------------------------------

### Run tests with just test

Source: https://github.com/carthage-software/mago/blob/main/CONTRIBUTING.md

Run the tests to verify your changes are correct.

```bash
just test
```

--------------------------------

### Print the version

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/recipes/docker.md

Print the Mago version from the Docker image.

```sh
docker run --rm ghcr.io/carthage-software/mago --version
```

--------------------------------

### disallowed-functions: flagged vs allowed calls

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

The first example shows a call to curl_init() which is flagged because it belongs to a disallowed extension. The second example shows a custom function that is not flagged.

```php
<?php

curl_init(); // Error: part of a disallowed extension

```

```php
<?php

function allowed_function(): void {
    // ...
}

allowed_function(); // Not flagged

```

--------------------------------

### Run the acme/no-eval rule with mago lint --only

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/extensions/getting-started.md

Runs only the acme/no-eval rule. Because the example rule is enabled by default, a normal mago lint run also executes it.

```sh
mago lint --only acme/no-eval
```

--------------------------------

### Usage: mago lint [OPTIONS] [PATH]...

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/linter/command-reference.md

Shows the basic command syntax for mago lint. Global flags must come before 'lint'.

```sh
Usage: mago lint [OPTIONS] [PATH]...
```

--------------------------------

### Preview changes with --dry-run

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/formatter/usage.md

Shows a unified diff of the proposed changes without writing anything to disk.

```sh
mago format --dry-run
```

--------------------------------

### Psl array functions: array_filter vs Psl\Vec\filter

Source: https://github.com/carthage-software/mago/blob/main/docs/content/zh/tools/linter/rules.md

Shows the bad and good usage of Psl array functions. The bad example uses array_filter, while the good example uses Psl\Vec\filter.

```php
<?php

$filtered = array_filter($xs, fn($x) => $x > 2);

```

```php
<?php

$filtered = Psl\Vec\filter($xs, fn($x) => $x > 2);

```

--------------------------------

### Rebuild baseline from scratch with mago lint --generate-baseline

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/fundamentals/baseline.md

Rebuilds the baseline file from scratch, capturing every current issue. Use --backup-baseline with this or the prune command to keep the previous file as lint-baseline.toml.bkp.

```sh
mago lint --generate-baseline --baseline lint-baseline.toml
```

--------------------------------

### Excessive nesting: bad vs good example

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

The first example shows deeply nested code that triggers the excessive-nesting rule. The second shows a shallower nesting level, which is preferred.

```php
<?php

if ($a) {
    if ($b) {
        if ($c) {
            if ($d) {
                if ($e) {
                    if ($f) {
                        if ($g) {
                            if ($h) {
                                echo "Too deeply nested!";
                            }
                        }
                    }
                }
            }
        }
    }
}

```

```php
<?php

if ($condition) {
    while ($otherCondition) {
        echo "Hello"; // nesting depth = 2
    }
}

```

--------------------------------

### Pin install script to a specific commit

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/installation.md

Pins the installer to a reviewed commit to avoid automatic updates. Replace the COMMIT value with a commit you have read. Uses `--always-verify` to enforce verification.

```sh
COMMIT=cd4cf4dfdbc72bd028ad26d11bcc815a49e27e9a  # replace with a commit you have read
curl --proto '=https' --tlsv1.2 -sSf \
  "https://raw.githubusercontent.com/carthage-software/mago/${COMMIT}/scripts/install.sh" \
  | bash -s -- --always-verify
```

--------------------------------

### Configure linter and rules in mago.toml

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/linter/configuration-reference.md

Shows the full [linter] and [linter.rules] configuration in mago.toml, including integrations, excludes, baseline, and per-rule settings like disabling a rule, changing severity, setting options, and excluding paths.

```toml
[linter]
integrations = ["symfony", "phpunit"]
excludes = ["src/Generated/"]
baseline = "linter-baseline.toml"

[linter.rules]
# Disable a rule completely
ambiguous-function-call = { enabled = false }

# Change a rule's severity level
no-else-clause = { level = "warning" }

# Configure a rule's specific options
cyclomatic-complexity = { threshold = 20 }

# Exclude specific paths from one rule
prefer-static-closure = { exclude = ["tests/"] }

```

--------------------------------

### Configure extension host command in TOML

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/extensions/development/packaging-and-compatibility.md

Configures the extension host command to run the project-owned entrypoint. The command array invokes PHP with the entrypoint path.

```toml
[extension-hosts.php]
command = ["php", ".mago/extensions.php"]
```

--------------------------------

### Implement ClassInitializerProvider for component mount method

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/extensions/analyzer/properties-and-initialization.md

Implements ClassInitializerProvider to return the 'mount' lifecycle method when it exists on the target class. Mago analyzes each returned method and its transitive calls with the same definite-initialization rules used for constructors. Every returned name must be a valid PHP method identifier; return only lifecycle methods the framework guarantees to run during instance setup.

```php
<?php

declare(strict_types=1);

namespace Acme\Mago\Analyzer\Providers;

use Acme\Framework\Component\Component;
use Mago\Sdk\Analyzer\ClassInitializerProvider;
use Mago\Sdk\Analyzer\ClassInitializerProviderContext;
use Mago\Sdk\Analyzer\ClassTarget;

final class ComponentInitializers implements ClassInitializerProvider
{
    public function getTargets(): array
    {
        return [ClassTarget::exact(Component::class)];
    }

    public function getClassInitializers(ClassInitializerProviderContext $context): array
    {
        return $context->codebase->methodExists($context->class->name, 'mount')
            ? ['mount']
            : [];
    }
}
```

--------------------------------

### mago guard --substitute example

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/guard/command-reference.md

Replaces one host file with another for a single run without writing to disk. Both ORIG and TEMP must be absolute paths and both files must exist. ORIG must be a host file under one of the configured paths; vendored or excluded files cannot be substituted. The flag can be repeated and conflicts with '--stdin-input'.

```sh
mago guard --substitute /abs/path/to/src/Foo.php=/tmp/mutation-42.php
```

--------------------------------

### Serve dist/ with PHP built-in server

Source: https://github.com/carthage-software/mago/blob/main/docs/README.md

Serves the built site locally using PHP's built-in server. The output uses absolute asset paths, so file:// URLs do not work.

```bash
cd dist && php -S 127.0.0.1:3031
```

--------------------------------

### Avoid alternative syntax for control structures

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/linter/rules.md

The rule detects alternative syntax for control structures like 'endif'. The first example shows the alternative syntax, which is discouraged. The second example uses the preferred brace-style syntax.

```php
<?php

if ($condition):
    echo 'yes';
endif;

```

```php
<?php

if ($condition) {
    echo 'yes';
}

```

--------------------------------

### single-class-per-file: avoid vs recommended

Source: https://github.com/carthage-software/mago/blob/main/docs/content/zh/tools/linter/rules.md

Avoid: multiple class-like definitions in one file. Recommended: one class per file to ensure each file contains at most one class-like definition.

```php
<?php

namespace App;

class Foo
{
}

class Bar
{
}
```

```php
<?php

namespace App;

class Foo
{
}
```

--------------------------------

### Reference the local Composer schema in TOML

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/configuration.md

References the version-matched schema written to vendor/carthage-software/mago/schema.json when Mago is installed via Composer. Use a relative path so the schema always tracks the installed version without manual URL updates.

```toml
#:schema vendor/carthage-software/mago/schema.json
version = "1"
php-version = "8.3"
```

--------------------------------

### Configure baseline paths in mago.toml

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/fundamentals/baseline.md

Sets baseline paths in mago.toml so you don't have to pass --baseline every time.

```toml
[linter]
baseline = "lint-baseline.toml"

[analyzer]
baseline = "analysis-baseline.toml"
```

--------------------------------

### Enforce block statements for control structures

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/linter/rules.md

The rule enforces that control structures always use block statements. The first example shows single-statement bodies without braces, which is discouraged. The second example uses braces, which is preferred.

```php
<?php

if (true)
    echo "Hello";

for ($i = 0; $i < 10; $i++)
    echo $i;

```

```php
<?php

if (true) {
    echo "Hello";
}

for ($i = 0; $i < 10; $i++) {
    echo $i;
}

```

--------------------------------

### mago guard --stdin-input example

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/guard/command-reference.md

Pipes file content from stdin for editor integrations. Exactly one path argument is required and is used as the workspace-relative file name for baseline matching and diagnostics. The path is normalized, so './src/Example.php' is treated the same as 'src/Example.php'. Conflicts with '--substitute'.

```sh
cat src/Example.php | mago guard --stdin-input src/Example.php
```

--------------------------------

### Use double slash comments instead of shell-style comments

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/linter/rules.md

The rule detects shell-style comments ('#') in PHP code. The first example shows a shell-style comment, which is discouraged. The second example uses the preferred double slash comment.

```php
<?php

# This is a shell-style comment.

```

```php
<?php

// This is a good comment.

```

--------------------------------

### WordPress input handling: unsafe vs safe

Source: https://github.com/carthage-software/mago/blob/main/docs/content/fr/tools/linter/rules.md

The first example shows unsafe direct use of $_POST without validation. The second example demonstrates the recommended approach using isset(), wp_unslash(), and sanitize_text_field() to safely handle input.

```php
<?php

function handle_input() {
    $name = $_POST['name'];
}

```

```php
<?php

function handle_input() {
    if (isset($_POST['name'])) {
        $name = sanitize_text_field(wp_unslash($_POST['name']));
    }
}

```

--------------------------------

### no-fully-qualified-global-class-like: Avoid fully-qualified references, prefer imports

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/linter/rules.md

Avoid fully-qualified class-like references with backslash prefix. Prefer explicit use imports for readability and centralized imports.

```php
<?php

namespace App;

$dt = new \DateTime();

function foo(\DateTime $dt): \Exception {}

```

```php
<?php

namespace App;

use DateTime;
use Exception;

$dt = new DateTime();

function foo(DateTime $dt): Exception {}

```

--------------------------------

### Use preset version suffix

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/formatter/configuration-reference.md

Shows how to specify a preset version suffix. Only 'latest' is supported today; 'psr-12' is equivalent to 'psr-12@latest'.

```toml
preset = "psr-12@latest"
preset = "psr-12"          # same as @latest
```

--------------------------------

### CancellationTokenInterface

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/extensions/sdk/extensions-and-workers.md

Documentation for the CancellationTokenInterface, including its methods and usage example.

```APIDOC
## CancellationTokenInterface

### Description
Provides cancellation support for long-running operations. Allows checking for cancellation, subscribing to cancellation events, and unsubscribing.

### Methods
- `throwIfCancelled(): void` - Throws an exception if cancellation has been requested.
- `isCancelled(): bool` - Returns true if cancellation has been requested, without throwing.
- `subscribe(callable $callback): int` - Installs a callback to be invoked on cancellation. Returns a subscription identifier.
- `unsubscribe(int $subscriptionId): void` - Removes a previously installed subscription.

### Example
```php
foreach ($largeCollection as $item) {
    $context->cancellation->throwIfCancelled();
    process($item);
}
```
```

--------------------------------

### Configure an extension host in TOML

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/extensions/configuration.md

Defines a single extension host named 'framework' under the [extension-hosts] table. It starts a PHP worker process with adaptive worker count, inherits the environment, sets APP_ENV to 'analysis', and applies payload, request, shutdown, and stderr limits.

```toml
[extension-hosts.framework]
enabled = true
command = ["php", ".mago/framework-worker.php"]
workers = 0
working-directory = "."
inherit-environment = true
environment = { APP_ENV = "analysis" }
maximum-payload-size = 67108864
request-timeout-ms = 30000
shutdown-timeout-ms = 250
stderr-tail-size = 65536

```

--------------------------------

### Implement CodebaseScanHook with getTargets() and scan()

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/extensions/analyzer/lifecycle-hooks.md

Implements CodebaseScanHook to receive selected host source snapshots without re-parsing. getTargets() returns non-empty path/glob patterns; scan() receives batches with firstBatch/lastBatch markers and SourceFile snapshots. Narrow targets are a key performance control.

```php
<?php

declare(strict_types=1);

namespace Acme\Mago\Analyzer\Hooks;

use Mago\Sdk\Analyzer\CodebaseScanContext;
use Mago\Sdk\Analyzer\CodebaseScanHook;

final class RouteScanner implements CodebaseScanHook
{
    public function getTargets(): array
    {
        return ['src/**/*.php', 'routes/*.php'];
    }

    public function scan(CodebaseScanContext $context): void
    {
        if ($context->firstBatch) {
            // Clear data derived during a previous analysis generation.
        }

        foreach ($context->files as $file) {
            // Inspect Mago's SourceFile snapshot.
        }

        if ($context->lastBatch) {
            // Finalize indexes before provider requests begin.
        }
    }
}
```

--------------------------------

### Class name must match file name

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/tools/linter/rules.md

The rule enforces that class names match the file name. The first example shows a class name 'Foo' in a file named 'test.php', which is incorrect. The second example uses 'test' to match the file name.

```php
<?php
// File: test.php

namespace App;

class Foo
{
}

```

```php
<?php
// File: test.php

namespace App;

class test
{
}

```

--------------------------------

### Set XDG_CONFIG_HOME for config lookup

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/guide/environment-variables.md

Changes the first directory Mago looks in for a global config file when no project-level file exists. The fallback chain is $XDG_CONFIG_HOME/mago.toml, then $HOME/.config/mago.toml, then $HOME/mago.toml.

```sh
XDG_CONFIG_HOME=/path/to/config mago lint
```

--------------------------------

### Initialization hook: add in-memory stubs

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/extensions/analyzer/lifecycle-hooks.md

Runs before Mago parses project source. Use to add stub declarations that Mago should understand before building metadata. Context contains only phpVersion, cancellation, addStub(), and addMultipleStubs(). Stubs exist only in Mago's in-memory source database and are never analyzed, linted, formatted, or fixed as project files.

```php
<?php

declare(strict_types=1);

namespace Acme\Mago\Analyzer\Hooks;

use Mago\Sdk\Analyzer\InitializationContext;
use Mago\Sdk\Analyzer\InitializationHook;

final class FrameworkStubs implements InitializationHook
{
    public function initialize(InitializationContext $context): void
    {
        $context->addStub(
            'acme-extension/container.php',
            '<?php interface AcmeContainer { public function get(string $id): object; }',
        );
    }
}
```

--------------------------------

### Validate extension registration with CLI commands

Source: https://github.com/carthage-software/mago/blob/main/docs/content/en/extensions/development/testing-and-debugging.md

Run these commands to verify the host can start and advertise a stable registration. `extension validate` exercises host startup and linter registration; `extension list` reports hosts, logical extensions, and linter rules (not analyzer plugins).

```sh
mago extension validate
mago extension list
mago extension list --json
```
Tokens:
Raw