Mago

https://mago.carthage.software/guide
Admin
Mago is a software project by carthage.software, likely related to high-performance PHP, providing...
Tokens:8,310
Snippets:98
Trust Score:5.5
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install Specific Mago Version via wget

Source: https://mago.carthage.software/guide/installation

Installs a specific version of Mago using wget and the --version flag. This method is an alternative to curl for installing specific Mago versions. Requires wget.

```shell
wget -qO- https://carthage.software/mago.sh | bash -s -- --version=1.12.1
```

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

### Install Mago using wget (macOS & Linux)

Source: https://mago.carthage.software/guide/installation

Installs Mago using the recommended shell script via wget. This method downloads the correct binary and adds it to your system's PATH. It requires wget to be installed.

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

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

### Mago Source Configuration - Basic Example (TOML)

Source: https://mago.carthage.software/guide/configuration

A basic example of the [source] section in a Mago TOML configuration file. It specifies directories for application code, vendor dependencies, and files to exclude, along with file extensions.

```toml
[source]
# Your application code - will be analyzed, linted, and formatted
paths = ["src", "tests"]

# Vendor dependencies - only parsed for type information
includes = ["vendor"]

# Completely ignored by all tools
excludes = ["cache/**", "build/**", "var/**"]

# File extensions to treat as PHP
extensions = ["php"]

```

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

### Verify Mago Installation

Source: https://mago.carthage.software/guide/installation

Checks the installed version of Mago to confirm a successful installation. This command should be run after any installation method.

```shell
mago --version
```

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

### Initialize Mago Project Configuration

Source: https://mago.carthage.software/guide/initialization

The `mago init` command starts an interactive process to generate a `mago.toml` configuration file. It can automatically detect project settings if a `composer.json` file is present, or prompt the user for manual configuration of source paths, dependency paths, exclusion paths, PHP version, and linter/formatter settings.

```shell
mago init
```

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

### Mago Command-Line Interface Init Usage

Source: https://mago.carthage.software/guide/initialization

This shows the basic usage of the `mago init` command, indicating that it accepts options. Global options should be specified before the `init` command.

```shell
Usage: mago init [OPTIONS]
```

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

### Install Mago using curl (macOS & Linux)

Source: https://mago.carthage.software/guide/installation

Installs Mago using the recommended shell script via curl. This method automatically downloads the correct binary and adds it to your system's PATH. It requires curl to be installed.

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

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

### Install Mago using Cargo (Rust)

Source: https://mago.carthage.software/guide/installation

Installs Mago from crates.io using the Cargo package manager for Rust projects. Publishing to crates.io can sometimes be delayed, so running `mago self-update` is recommended.

```shell
cargo install mago
```

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

### Install Specific Mago Version via curl

Source: https://mago.carthage.software/guide/installation

Installs a specific version of Mago using curl and the --version flag. This is useful for testing or maintaining compatibility with older projects. Requires curl.

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

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

### Install Mago using Homebrew (macOS)

Source: https://mago.carthage.software/guide/installation

Installs Mago using the Homebrew package manager on macOS. Note: This formula is community-managed and may lag behind official releases. It is crucial to run `mago self-update` immediately after installation.

```shell
brew install mago
```

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

### Mago Init Command Help Option

Source: https://mago.carthage.software/guide/initialization

The `-h` or `--help` flag can be used with the `mago init` command to print help information regarding its usage and available options.

```shell
-h, --help | Print help information.
```

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

### Mago Initialization with Composer.json Detection

Source: https://mago.carthage.software/guide/initialization

When `mago init` is run in a project with a `composer.json` file, it prompts the user to auto-configure project paths, PHP version, and linter integrations based on the `composer.json` contents. This is the recommended approach for projects using Composer.

```shell
$ mago init

 Mago
 ♥️ Welcome! Let's get you set up.

  ⌒ Step 1: Project Setup
  │
  │   Found `composer.json`. Use it to auto-configure your project? › (Y/n)
  │
  │  Reading composer.json...
  │  Project settings detected!
  └︎
```

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

### Display Specific Mago Configuration Section

Source: https://mago.carthage.software/guide/configuration

Use the `--show` flag with `mago config` to inspect a particular section of the configuration, such as the linter or formatter settings. This helps in isolating and understanding specific configuration parts.

```sh
# Show only the [linter] configuration
mago config --show linter

# Show only the [formatter] configuration
mago config --show formatter
```

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

### Configure Linter Rule Exclusions (TOML)

Source: https://mago.carthage.software/guide/configuration

Allows excluding specific linter rules for certain files or directories, enabling granular control over linting behavior.

```toml
[linter.rules]
# Don't enforce static closures in test files
prefer-static-closure = { exclude = ["tests/"] }
```

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

### Mago Config Command

Source: https://mago.carthage.software/guide/configuration

The `mago config` command displays the final, merged configuration Mago is using for the current project. This is useful for debugging your setup by showing the result of combining your `mago.toml` file, environment variables, and built-in defaults.

```APIDOC
## GET /config

### Description
Displays the final, merged configuration Mago is using for the current project. This is invaluable for debugging your setup, as it shows you the result of combining your `mago.toml` file, any environment variables, and the built-in defaults.

### Method
GET

### Endpoint
/config

### Parameters
#### Query Parameters
- **--show** (string) - Optional - Display only a specific section of the configuration. Values: `source`, `parser`, `linter`, `formatter`, `analyzer`
- **--default** (boolean) - Optional - Show the default configuration values instead of the current merged configuration.
- **--schema** (boolean) - Optional - Output JSON schema instead of configuration values. Useful for documentation and IDE integration.
- **-h, --help** (boolean) - Optional - Print help information.

### Request Example
```sh
mago config

# Show only the [linter] configuration
mago config --show linter

# Output the JSON schema for the entire configuration
mago config --schema
```

### Response
#### Success Response (200)
- **configuration** (object) - The merged configuration object or its JSON schema.

#### Response Example
```json
{
  "linter": {
    "enabled": true,
    "rules": [
      "recommended"
    ]
  },
  "formatter": {
    "enabled": true,
    "format": "pretty"
  }
}
```
```

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

### Update Mago to Latest Version

Source: https://mago.carthage.software/guide/installation

Updates Mago to the latest official version. This command is essential after installing via package managers like Homebrew or Cargo, or as a general maintenance step.

```shell
mago self-update
```

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

### Mago Source Configuration - Glob Patterns (TOML)

Source: https://mago.carthage.software/guide/configuration

Demonstrates the use of glob patterns within the [source] section of a Mago TOML configuration. This allows for more granular control over which files are included, excluded, or processed.

```toml
[source]
# Use glob patterns to target specific files
paths = ["src/**/*.php"]
includes = ["vendor/symfony/**/*.php"]  # Only Symfony from vendor
excludes = [
    "**/*_generated.php",      # Any generated file
    "**/tests/**",             # All test directories
    "src/Legacy/**",           # Specific legacy code
]

```

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

### Add Mago to PHP Project via Composer

Source: https://mago.carthage.software/guide/installation

Adds Mago as a development dependency to a PHP project using Composer. This integrates Mago into your project's workflow and manages its versioning.

```shell
composer require --dev "carthage-software/mago:^1.12.1"
```

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

### Configure PHP Parser Settings (TOML)

Source: https://mago.carthage.software/guide/configuration

Configures how Mago parses PHP code, specifically controlling the recognition of PHP short open tags (`<?`).

```toml
[parser]
enable-short-tags = false
```

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

### List Files Processed by Mago Commands (Shell)

Source: https://mago.carthage.software/guide/configuration

Utility command to view files that Mago will process based on the current configuration. Useful for verifying `paths`, `includes`, and `excludes` settings.

```sh
# See all files in your project
mago list-files

# See which files the formatter will process
mago list-files --command formatter

# See which files the analyzer will process
mago list-files --command analyzer
```

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

### Configure Editor URL for Clickable Diagnostics (TOML)

Source: https://mago.carthage.software/guide/configuration

Sets a URL template to make file paths in diagnostic output clickable, opening files directly in the editor at the specified line and column.

```toml
editor-url = "phpstorm://open?file=%file%&line=%line%&column=%column%"
```

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

### Configure Source Code Paths and Exclusions (TOML)

Source: https://mago.carthage.software/guide/configuration

Defines source code directories, dependency paths, and files to exclude from analysis, linting, or formatting. Tool-specific excludes are additive to global excludes.

```toml
[source]
paths = ["src", "tests"]
excludes = ["cache/**"]  # Excluded from ALL tools

[analyzer]
# Additionally exclude test files from analysis only
# (they'll still be linted and formatted)
excludes = ["tests/**/*.php", "src/**/tests/**"]

[formatter]
# Additionally exclude auto-generated code from formatting only
# (it will still be analyzed and linted)
excludes = ["src/**/AutoGenerated/**/*.php"]

[linter]
# Additionally exclude database migrations from linting only
excludes = ["database/migrations/**"]
```

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

### Editor URL Templates for Opening Files

Source: https://mago.carthage.software/guide/configuration

These templates allow Mago to generate clickable links that open specific files at given lines and columns in various code editors. The placeholders like `%file%`, `%line%`, and `%column%` are dynamically replaced by Mago.

```plaintext
VS Code: vscode://file/%file%:%line%:%column%
VS Code Insiders: vscode-insiders://file/%file%:%line%:%column%
Cursor: cursor://file/%file%:%line%:%column%
Windsurf: windsurf://file/%file%:%line%:%column%
PhpStorm / IntelliJ: phpstorm://open?file=%file%&line=%line%&column=%column%
Zed: zed://file/%file%:%line%:%column%
Sublime Text: subl://open?url=file://%file%&line=%line%&column=%column%
Emacs: emacs://open?url=file://%file%&line=%line%&column=%column%
Atom: atom://core/open/file?filename=%file%&line=%line%&column=%column%
```

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

### List Mago Reserved Environment Variables

Source: https://mago.carthage.software/guide/environment-variables

Lists all environment variables that start with the MAGO_ prefix. Mago reserves this prefix for its configuration and will error if an unrecognized MAGO_ variable is set.

```bash
env | grep ^MAGO_
```

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

### Mago Global Configuration Options (TOML)

Source: https://mago.carthage.software/guide/configuration

Defines the global configuration settings for Mago in a TOML file. These options control aspects like the PHP version, number of threads, stack size, and editor URL integration.

```toml
php-version = "8.2"
threads = 8
stack-size = 8388608 # 8 MB
editor-url = "phpstorm://open?file=%file%&line=%line%&column=%column%"

```

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

### Configure Editor URL via Environment Variable (Shell)

Source: https://mago.carthage.software/guide/configuration

Sets the `MAGO_EDITOR_URL` environment variable to define a URL template for making diagnostic file paths clickable in the editor.

```sh
export MAGO_EDITOR_URL="vscode://file/%file%:%line%:%column%"
```

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

### Update Mago to Specific Version (Shell)

Source: https://mago.carthage.software/guide/upgrading

Updates Mago to a specific version specified by a version tag. This allows for precise control over the Mago version installed, which can be useful for testing or compatibility.

```shell
mago self-update --tag 1.0.0-rc.1
```

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

### Display Mago Configuration using `mago config`

Source: https://mago.carthage.software/guide/configuration

The `mago config` command displays the final, merged configuration Mago is using. This is useful for debugging configuration issues by showing the combined result of configuration files, environment variables, and defaults. The output is a pretty-printed JSON object.

```sh
mago config
```

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

### Output Mago Configuration JSON Schema

Source: https://mago.carthage.software/guide/configuration

The `--schema` flag with `mago config` outputs the JSON schema for the configuration. This is valuable for generating documentation, integrating with IDEs, or building validation tools.

```sh
# Output the JSON schema for the entire configuration
mago config --schema

# Output the JSON schema for a specific section
mago config --schema --show linter
```

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

### Mago Generate Completions Command Reference (Shell)

Source: https://mago.carthage.software/guide/generate-completions

Provides the command reference for generating Mago shell completions. It shows the basic usage and available options.

```shell
Usage: mago generate-completions <SHELL>
```

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

### List Files for Specific Mago Commands

Source: https://mago.carthage.software/guide/list-files

Generate file lists tailored to specific Mago commands like 'linter', 'formatter', 'analyzer', or 'guard'. This accounts for both global and command-specific `excludes` configurations, showing precisely which files each tool will operate on.

```shell
# Files the linter will check
mago list-files --command linter

# Files the formatter will format
mago list-files --command formatter

# Files the analyzer will analyze
mago list-files --command analyzer

# Files the guard will check
mago list-files --command guard
```

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

### List All Files with `mago list-files`

Source: https://mago.carthage.software/guide/list-files

This command lists all files Mago will process based on your `paths` configuration. It does not include files specified in `includes`. This is useful for a general overview of your project's source files.

```shell
mago list-files
```

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

### Generate Shell Completions for Mago (Shell)

Source: https://mago.carthage.software/guide/generate-completions

Generates shell completions for Mago. Accepts the desired shell name as an argument (e.g., 'fish'). The output can be piped to 'source' to apply completions directly or saved to a file.

```shell
mago generate-completions fish
```

```shell
mago generate-completions fish | source
```

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

### Zero-Terminate Filenames for Piping

Source: https://mago.carthage.software/guide/list-files

Use the `-0` or `--zero-terminate` flag to output filenames separated by NUL bytes instead of newlines. This is crucial for safely passing file lists to other command-line tools like `xargs`, especially when filenames might contain spaces or newlines.

```shell
mago list-files -0 | xargs -0r ls -l
```

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

### Allow Unsupported PHP Versions in Mago

Source: https://mago.carthage.software/guide/environment-variables

Overrides the allow_unsupported_php_version setting. Setting this to true allows Mago to run on PHP versions not officially supported, though this is not recommended.

```bash
MAGO_ALLOW_UNSUPPORTED_PHP_VERSION=true mago lint
```

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

### Mago Self-Update Command Reference (Shell)

Source: https://mago.carthage.software/guide/upgrading

Displays the usage and available options for the `mago self-update` command. This includes flags for checking updates, skipping confirmation, and specifying a version tag.

```shell
Usage: mago self-update [OPTIONS]
```

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

### Set Mago Configuration Directory

Source: https://mago.carthage.software/guide/environment-variables

Overrides the default directory for Mago's configuration file. Mago follows the XDG Base Directory Specification, searching in $XDG_CONFIG_HOME/mago.toml, $HOME/.config/mago.toml, and $HOME/mago.toml.

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

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

### Update Mago to Latest Version Without Confirmation (Shell)

Source: https://mago.carthage.software/guide/upgrading

Updates Mago to the latest version and skips the interactive confirmation prompt. This is useful for automated update processes where user interaction is not possible.

```shell
mago self-update --no-confirm
```

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

### Check for Mago Updates (Shell)

Source: https://mago.carthage.software/guide/upgrading

Checks if a new version of Mago is available without performing the update. If a newer version exists, it prints the version number and exits with a non-zero status code, suitable for scripting.

```shell
mago self-update --check
```

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

### Force Mago Colored Output

Source: https://mago.carthage.software/guide/environment-variables

Forces Mago to produce colored output, even when not connected to a terminal. This is useful for preserving color when redirecting output. This setting takes precedence over NO_COLOR.

```bash
FORCE_COLOR=1 mago lint | less -R
```

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

### Set Mago Logging Level

Source: https://mago.carthage.software/guide/environment-variables

Configures the logging verbosity for Mago. This is useful for debugging and observing Mago's internal processes. Accepted values include trace, debug, info, warn, and error.

```bash
MAGO_LOG=trace mago lint
```

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

### Override Mago PHP Version

Source: https://mago.carthage.software/guide/environment-variables

Overrides the php_version setting in mago.toml. This allows testing code against different PHP versions without altering the configuration file.

```bash
MAGO_PHP_VERSION=8.2 mago lint
```

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

### Disable Mago Colored Output

Source: https://mago.carthage.software/guide/environment-variables

Disables all colored output from Mago, making the output plain text. This is useful when piping Mago's output to files or other tools that do not support ANSI color codes.

```bash
NO_COLOR=1 mago lint
```

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

### Override Mago Thread Count

Source: https://mago.carthage.software/guide/environment-variables

Overrides the threads setting in mago.toml, controlling the number of parallel threads Mago uses for tasks like linting and formatting.

```bash
MAGO_THREADS=4 mago lint
```
Tokens:
Raw