Fractal 不能直接通过 composer require 使用，需手动处理HTTP响应、序列化等；常见报错原因包括自动加载未生效、误用抽象类、PHP版本不兼容；最小示例需正确实现Transformer与Resource并调用toArray()后json_encode()。
Fractal 不能靠 composer require league/fractal 就直接用起来，它只提供数据转换能力，不处理 HTTP 响应、序列化格式（如 JSON）、请求上下文或资源嵌套的自动解析——这些得你手动搭或选配套包。
为什么 composer require league/fractal 装完就报错？
装完后一跑就提示 Class 'League\Fractal\Manager' not found 或 Cannot instantiate abstract class League\Fractal\TransformerAbstract，常见原因有三个：
- 没 autoload 到类（Composer 自动加载未生效）：确认运行过
composer dump-autoload，且项目根目录有vendor/autoload.php并已引入 - 用了抽象类当具体类用：比如直接 new
TransformerAbstract—— 它必须被继承，不能实例化 - PHP 版本不兼容：
league/fractal ^0.19要求 PHP >=7.4；若用 PHP 8.2+，别装老版本（如 0.18.x），否则ArrayIterator兼容性会出问题
怎么写一个能跑通的最小 Transformer + Resource 示例？
Fractal 的核心是「资源（Resource）」+「转换器（Transformer）」两层结构，漏掉任何一层都会返回空数组或抛异常。以下是最简可用组合：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
// UserTransformer.php
use League\Fractal\TransformerAbstract;
class UserTransformer extends TransformerAbstract
{
public function transform(array $user)
{
return [
'id' => (int) $user['id'],
'name' => $user['name'],
'email' => $user['email'],
];
}
}
// 使用处 use League\Fractal\Manager; use League\Fractal\Resource\Collection; $fractal = new Manager(); $resource = new Collection($users, new UserTransformer()); $data = $fractal->createData($resource)->toArray(); // 注意：这里不会自动 JSON encode
-
$users必须是数组（非对象或 PDOStatement），否则Collection构造失败 -
transform()方法参数必须是array，不能传stdClass或 Eloquent 模型（除非你在 transformer 里手动转成数组） -
createData()->toArray()返回的是 PHP 数组，不是 JSON 字符串；要输出 API 响应，得自己json_encode()并设 header
如何让 Fractal 支持嵌套资源（比如用户 + 文章列表）？
嵌套不是自动发生的，得在 Transformer 里显式调用 item() 或 collection()，并确保子资源的 transformer 已注册到 manager：
class UserTransformer extends TransformerAbstract
{
protected $availableIncludes = ['posts'];
public function includePosts($user)
{
// $user['posts'] 必须是数组，且每个元素满足 PostTransformer::transform() 的输入要求
return $this->collection($user['posts'], new PostTransformer());
}
}
- 必须提前调用
$fractal->parseIncludes(['posts'])，否则includePosts根本不会执行 -
$user['posts']若是 Laravel 的Collection对象，需先调用->toArray()，否则collection()会静默失败 - 嵌套层级深时，性能损耗明显：每层 include 都会触发一次 transformer 实例化和循环，别在高并发接口里无节制 include
Fractal 的真正门槛不在安装，而在“资源边界”——你得自己决定哪些字段进、哪些关系展开、哪些分页信息塞进 meta。它不帮你猜上下文，也不管你用的是 Laravel 还是 Slim，所有衔接逻辑都得手写。漏掉 parseIncludes、传错数据类型、忘了 toArray()，这三个点占了调试时间的八成。
