PHP 工具链 Mago 1.0.0 发布！

Mago 1.0.0

经过超过 1,000 次提交、13 个发布候选版、34 个测试版和 12 个 Alpha 版后，我们很高兴地宣布 Mago 1.0.0 —— Mago PHP 工具链的第一个稳定版。

Mago 是一个用 Rust 编写的全面 PHP 工具链，它将 linter（代码检查器）、formatter（代码格式化器）和 static analyzer（静态分析器）结合成一个单一的、闪电般快速的二进制文件。无论您是在处理小型项目还是拥有数百万行代码的庞大代码库，Mago 都能在几秒钟内提供一致、可靠的反馈。

自 0.26.1 版本以来的新功能？

如果您上次使用 Mago 是 0.26.1 版本，那么这个工具已经发生了翻天覆地的变化：

• 分析器的完整重写，支持深度类型推断、泛型和控制流分析
• 插件系统，用于可扩展的类型提供器
• 135 条 linter 规则，分布在 9 个类别中，支持自动修复
• 50+ 格式化设置，符合 PER-CS 标准
• Guard，用于强制执行架构边界和结构规则
• 属性初始化检查
• 异常跟踪，带有 @throws 验证
• Baseline 支持，用于在现有代码库中逐步采用
• Web playground：mago.carthage.software/playground

功能

Linter（代码检查器）

linter 包含 135 条规则，组织成 9 个类别：

许多规则包含 自动修复，可以使用 mago lint --fix 应用。

Formatter（格式化器）

格式化器会生成干净、一致的代码，遵循 https://www.php-fig.org/per/coding-style/，并提供超过 50 个自定义选项：

• 打印宽度、缩进风格和行尾
• 大括号放置和间距规则
• 方法链和参数列表断行
• 闭包和箭头函数格式化
• 以及更多

在 CI 中运行 mago format --check 以确保团队中一致的格式化。

Analyzer（分析器）

分析器执行 深度静态分析，包括：

• 类型推断，支持泛型、交集、联合和键控数组
• 控制流分析，在条件语句中进行类型缩小
• 292+ 种问题类型，涵盖类型错误、未使用代码等
• 异常跟踪（check-throws），确保异常被捕获或记录
• 属性初始化检查，捕获未初始化的类型化属性
• 缺失类型提示检测，针对参数、返回类型和属性

插件系统

分析器支持插件，用于库特定的类型推断：

在您的 mago.toml 中启用插件：

[analyzer]
plugins = [
    "psl",
    "flow-php"
]

即将推出的插件包括 Symfony、Laravel、Doctrine 和 PHPUnit。

Guard（架构边界）

Guard 强制执行代码库中的 架构规则 和 依赖边界：

[guard.perimeter]
# 定义从核心到基础设施的架构层。
layering = [
    "CarthageSoftware\\Domain",
    "CarthageSoftware\\Application",
    "CarthageSoftware\\UI",
    "CarthageSoftware\\Infrastructure"
]
# 为命名空间组创建可重用的别名。
[guard.perimeter.layers]
core = [
    "@native",
    "Psl\\**"
]
psr = [
    "Psr\\**"
]
framework = [
    "Symfony\\**",
    "Doctrine\\**"
]
# 为特定命名空间定义依赖规则。
[[guard.perimeter.rules]]
namespace = "CarthageSoftware\\Domain"
permit = [
    "@layer:core"
]

[[guard.perimeter.rules]]
namespace = "CarthageSoftware\\Application"
permit = [
    "@layer:core",
    "@layer:psr"
]

[[guard.perimeter.rules]]
namespace = "CarthageSoftware\\Infrastructure"
permit = [
    "@layer:core",
    "@layer:psr",
    "@layer:framework"
]

[[guard.perimeter.rules]]
namespace = "CarthageSoftware\\Tests"
permit = [
    "@all"
]

运行 mago guard 来检查架构违规。这有助于通过以下方式维护干净的架构：

• Perimeter 规则：控制哪些命名空间可以依赖其他命名空间
• 结构规则：强制执行类修饰符、继承和命名约定
• 层强制执行：防止较低层依赖较高层

生产就绪

Mago 1.0.0 已 生产就绪，并被公司每天分析 数百万行 PHP 代码。该工具链已在各种代码库中经过实战测试，从遗留单体到现代框架。

使用 Baseline 逐步采用

将静态分析引入现有代码库可能令人不知所措。Mago 支持 baseline，让您可以：

1. 生成当前问题的 baseline：mago analyze --generate-baseline
2. 忽略现有问题，同时捕获新问题：mago analyze --baseline baseline.toml
3. 以自己的节奏逐步修复问题

快速 bug 修复

我们致力于快速修复报告的问题。大多数 bug 报告在 1-2 天 内解决。虽然偶尔会出现假阳性，但我们将其视为高优先级 bug。

自 RC.13 以来的变化

此版本自最后一个发布候选版以来的变化包括：

Analyzer（分析器）

• properties-of<T> 现在正确扩展为 array<non-empty-string, mixed>，用于泛型对象约束
• 带有自动生成钩子的后备属性现在被正确识别
• 改进了键控数组中 null 键强制转换的可能 null 数组索引警告
• 数组和 iterable 类型之间的比较现在正确处理

Linter（代码检查器）

• 为 explicit-octal 规则添加了自动修复器

性能

Mago 比传统的 PHP 工具快得多。在 wordpress-develop 代码库上：

Mago 在不到 4 秒内分析整个 WordPress 代码库——比 Psalm 快 12 倍，比 PHPStan 快 31 倍。

有关 linter 和 formatter 的完整基准测试，请参阅 mago.carthage.software/benchmarks](https://mago.carthage.software/benchmarks

安装

Shell 脚本（macOS/Linux）

curl --proto '=https' --tlsv1.2 -sSfO https://carthage.software/mago.sh && bash mago.sh

Homebrew

brew install carthage-software/tap/mago

Composer

composer require --dev carthage-software/mago

Cargo

cargo install mago

有关更多安装选项，请参阅 安装指南。

入门

1. 在您的项目中初始化 Mago：

mago init

1. 运行 linter：

mago lint

1. 运行分析器：

mago analyze

1. 格式化您的代码：

mago format

有关全面文档，请访问 mago.carthage.software。

展望未来

1.0.0 版本只是开始。我们的路线图包括：

• PHP 版本管理器：无缝管理多个 PHP 版本
• 扩展安装：安装和管理 PHP 扩展
• 迁移助手：帮助在 PHP 版本之间迁移
• 框架插件：Symfony、Laravel、Doctrine、PHPUnit