moai-lang-php

快速参考（30 秒）

PHP 8.3+ 开发专家——Laravel 11、Symfony 7、Eloquent、Doctrine 和现代 PHP 模式。

自动触发：扩展名为 .php 的 PHP 文件、composer.json、artisan 命令、symfony.yaml，以及 Laravel 或 Symfony 相关讨论

核心能力：

• PHP 8.3 特性：只读类、类型化属性、属性、枚举、命名参数
• Laravel 11：控制器、模型、迁移、表单请求、API 资源、Eloquent
• Symfony 7：基于属性的路由、Doctrine ORM、服务、依赖注入
• ORM：Laravel 使用 Eloquent，Symfony 使用 Doctrine
• 测试：PHPUnit、Pest、功能测试和单元测试模式
• 包管理：使用 Composer 进行自动加载
• 编码规范：PSR-12、Laravel Pint、PHP CS Fixer
• Docker：PHP-FPM、nginx、多阶段构建

快速模式

Laravel 控制器模式：

在 App\Http\Controllers\Api 命名空间中，创建一个继承 Controller 的 UserController。导入 StoreUserRequest、UserResource、User 和 JsonResponse。定义一个接受 StoreUserRequest 的 store 方法，使用经过验证的数据创建 User，并返回一个 JsonResponse，其中以 UserResource 包装该用户，状态码为 201。

Laravel 表单请求模式：

在 App\Http\Requests 命名空间中，创建一个继承 FormRequest 的 StoreUserRequest。authorize 方法返回 true。rules 方法返回一个数组，其中 name 要求通过 required、string 和 max 255 验证，email 要求通过 required、email 验证，并在 users 表中满足 unique 验证，password 要求通过 required、min 8 和 confirmed 验证。

Symfony 控制器模式：

在 App\Controller 命名空间中，创建一个继承 AbstractController 的 UserController。导入 User、EntityManagerInterface、JsonResponse 和 Route 属性。在类级别应用 Route 属性，路径设为 api/users。创建一个带有 Route 属性的 create 方法，路径为空，方法为 POST。注入 EntityManagerInterface，创建新的 User，执行 persist 和 flush，然后返回包含该用户且状态码为 201 的 JSON 响应。

---

实现指南（5 分钟）

PHP 8.3 现代特性

只读类：

声明一个只读类 UserDTO，其构造函数通过属性提升声明 public 属性：int 类型的 id、string 类型的 name 和 string 类型的 email。

带方法的枚举：

创建一个由 string 支持的 OrderStatus 枚举。定义 Pending（值为 pending）、Processing（值为 processing）和 Completed（值为 completed）这几个枚举项。添加一个 label 方法，使用针对 $this 的 match 表达式，为每个枚举项返回相应的显示标签。

属性：

创建一个 Validate 属性类，使用 Attribute 属性将其目标设为属性。构造函数接受一个 string 类型的 rule 和一个可选的 string 类型的 message。创建一个 UserRequest 类，其 email 属性使用 Validate 属性装饰，并指定 required 和 email 规则。

Laravel 11 模式

带关联关系的 Eloquent 模型：

在 App\Models 命名空间中，创建一个继承 Model 的 Post 模型。设置受保护的 fillable 数组，包含 title、content、user_id 和 status。设置受保护的 casts 数组，将 status 转换为 PostStatus 枚举，并将 published_at 转换为 datetime。定义 user 方法，返回 BelongsTo 关联关系。定义 comments 方法，返回 HasMany 关联关系。添加 scopePublished 方法，筛选已发布状态的记录。

API 资源模式：

在 App\Http\Resources 命名空间中，创建一个继承 JsonResource 的 PostResource。toArray 方法接收一个 Request 参数。返回一个数组，包含 id、title、使用 UserResource 并通过 whenLoaded 处理 user 关联关系的 author、通过 whenCounted 处理的 comments_count，以及格式化为 ISO 8601 字符串的 created_at。

迁移模式：

创建一个继承 Migration 的匿名迁移类。up 方法调用 Schema，在 posts 表上执行 create。定义 id、带有 constrained 和 cascadeOnDelete 的 user_id 外键、title 字符串、content 文本、默认值为 draft 的 status 字符串、timestamps 和 softDeletes。

服务层模式：

在 App\Services 命名空间中，创建一个 UserService 类。定义一个接收 UserDTO 的 create 方法。使用 DB 事务包装 User 创建操作，数据来自 DTO 属性；创建带有默认 bio 的 profile，并返回已加载 profile 关联关系的 user。捕获 ActiveRecord\RecordInvalid 异常以处理验证失败。

Symfony 7 模式

带 Doctrine 属性的实体：

在 App\Entity 命名空间中，创建一个 User 类。应用 ORM\Entity 属性，并将 repositoryClass 指向 UserRepository。应用 ORM\Table 属性，name 设置为 users。添加 private nullable int id，并应用 ORM\Id、ORM\GeneratedValue 和 ORM\Column 属性。添加 private nullable string name，并应用 length 为 255 的 ORM\Column 属性和 Assert\NotBlank。添加 private nullable string email，并应用 length 为 180、unique 的 ORM\Column 属性和 Assert\Email。

依赖注入服务：

在 App\Service 命名空间中，创建一个 UserService 类。构造函数通过属性提升接收 readonly EntityManagerInterface 和 readonly UserPasswordHasherInterface。定义一个接收 email 和 password 字符串的 createUser 方法。创建新的 User，设置 email，使用密码哈希器对密码进行哈希，通过实体管理器持久化，执行 flush，并返回 user。

测试模式

Laravel 的 PHPUnit 功能测试：

在 Tests\Feature 命名空间中，创建一个带有 RefreshDatabase trait 并继承 TestCase 的 UserApiTest。test_can_create_user 方法向 api/users 发送 JSON 请求，包含 name、email、password 和 password_confirmation。断言状态码为 201，且 JSON 结构包含带有 id、name 和 email 的 data。断言 users 表中存在具有该 email 的记录。

Laravel 的 Pest 测试：

使用 App\Models\User 和 Post。使用 it 函数创建一个测试，测试能否创建帖子。使用工厂创建 user。调用 actingAs 并传入 user，然后向 api/posts 发送包含 title 和 content 的 JSON 请求。断言状态码为 201，并断言 Post 数量为 1。再创建一个测试，验证需要身份验证：在未进行身份验证的情况下发送请求，并断言状态码为 401。

---

高级实现（10 分钟以上）

全面涵盖以下内容：

• Docker 和 Kubernetes 的生产部署模式
• 包含观察者、访问器和修改器的高级 Eloquent 模式
• 使用可嵌入对象和继承的 Doctrine 高级映射
• 队列和作业处理
• 事件驱动架构
• 使用 Redis 和 Memcached 的缓存策略
• 遵循 OWASP 模式的安全最佳实践
• CI/CD 集成模式

参见：

• modules/advanced-patterns.md，查看完整的高级模式指南

Context7 库映射

• laravel/framework：用于 Laravel Web 框架
• symfony/symfony：用于 Symfony 组件和框架
• doctrine/orm：用于 PHP 的 Doctrine ORM
• phpunit/phpunit：用于 PHP 测试框架
• pestphp/pest：用于优雅的 PHP 测试框架
• laravel/sanctum：用于 Laravel API 身份验证
• laravel/horizon：用于 Laravel 队列仪表板

---

配合良好

• moai-domain-backend：用于 REST API 和微服务架构
• moai-domain-database：用于 SQL 模式和 ORM 优化
• moai-workflow-testing：用于 DDD 和测试策略
• moai-platform-deploy：用于 Docker 和部署模式
• moai-essentials-debug：用于 AI 驱动的调试
• moai-foundation-quality：用于 TRUST 5 质量原则

---

故障排除

常见问题：

PHP 版本检查：

运行 php 并使用版本标志，验证版本为 8.3 或更高。运行 php 并使用 -m 标志，再通过管道传递给 grep，以检查 pdo、mbstring 和 openssl 扩展。

Composer 自动加载问题：

运行 composer dump-autoload 并使用 -o 标志，以优化自动加载器。运行 composer clear-cache 以清除软件包缓存。

Laravel 缓存问题：

运行 php artisan config:clear 以清除配置缓存。运行 php artisan cache:clear 以清除应用程序缓存。运行 php artisan route:clear 以清除路由缓存。运行 php artisan view:clear 以清除已编译视图。

Symfony 缓存问题：

运行 php bin/console cache:clear 以清除缓存。运行 php bin/console cache:warmup 以预热缓存。

数据库连接：

在 DB::connection()->getPdo() 调用外使用 try-catch 代码块。连接成功时输出成功消息，连接失败时输出异常消息。

迁移回滚：

使用 php artisan migrate:rollback 并将 step 设为 1，以回滚上一次迁移。仅在开发环境重置时使用带有 seed 标志的 php artisan migrate:fresh。对于 Symfony，使用 php bin/console doctrine:migrations:migrate prev 进行回滚。

---

版本：1.1.0 | 更新日期：2026-01-11 | 状态：Active