跳到主要内容
版本：1.x

Feed 与数据

核心 API 将数据源、Feed 项映射、Feed 级元数据、输出结构和生成结果分开处理。

Feed​

DragonCode\LaravelFeed\Feeds\Feed 是导出的基类。实现 builder()，并且只覆盖 Feed 所需的输出钩子。

abstract public function builder(): Builder
方法默认值契约
builder(): Builder抽象方法返回用作数据源的 Eloquent 查询。
item(Model $model): FeedItem新的基础 FeedItem将一个模型映射为输出项。
transformers(): array[]前置该 Feed 使用的转换器类名。
chunkSize(): int1000数据库查询分块大小。
perFile(): int0每个文件的记录数。零表示不按数量拆分。
maxFiles(): int0输出文件的最大数量。零表示不限制。
header(): stringXML/RSS 使用 XML 声明写入根元素和 Feed 项之前的内容。
footer(): string空字符串写入根元素和 Feed 项之后的内容。
root(): ElementData从类名派生的元素名定义根元素及其属性。
info(): FeedInfo空的 FeedInfo定义 Feed 级信息。
filename(): string从类名派生的文件名返回相对于磁盘的输出文件名。
path($suffix): string适配器解析的路径返回本地路径或适配器解析的路径。
storagePath($suffix): string相对于磁盘的文件名返回存储操作使用的路径。
storage(): FilesystemAdapterpublic 磁盘解析并验证 Laravel 文件系统磁盘。
format(): FeedFormatEnumXml返回配置的输出格式。
converterOptions(): array[]返回此 Feed 继承的 Config 属性值；子 Feed 的键会覆盖父 Feed 的键。

Feed 使用 Laravel 的 Conditionable 和 Macroable。

Feed 目标​

DragonCode\LaravelFeed\Feeds\FeedTarget 标识一个独立生成的输出。其构造函数接受非空字符串键和可选参数数组：

public function __construct(public readonly string $key, public readonly array $parameters = [])

需要目标的 Feed 类应实现 DragonCode\LaravelFeed\Contracts\HasFeedTargets。可选的 DragonCode\LaravelFeed\Concerns\InteractsWithFeedTargets trait 实现 forTarget() 和 target()；Feed 类负责发现目标：

方法契约
targets(): iterable当命令或调度任务生成全部目标时，惰性返回所有可用的 FeedTarget。
findTarget(string $key): ?FeedTarget直接解析一个具有相同键的显式命令目标，找不到时返回 null。
forTarget(FeedTarget $target): static返回配置后的克隆，并重置缓存的文件名。
target(): FeedTarget返回已配置的目标；未设置目标时抛出 LogicException。

构造函数会拒绝空键和仅含空白字符的键，但不会规范化或清理其他值。目标参数对软件包不透明，并会作为队列任务快照进行序列化。目标键用于标识目标，因此必须稳定且在 Feed 类内唯一。请参阅独立输出文件设置和命令目标选择。

FeedItem 与 FeedInfo​

FeedItem 接收当前 Eloquent 模型。其默认行为如下：

  • name() 返回 kebab case 格式的模型类基本名称；
  • attributes() 返回空数组；
  • toArray() 返回模型数组。

FeedInfo::toArray() 返回空数组。这两个类都使用 Conditionable 和 Macroable；输出需要显式结构时，请继承它们。

项目的日期格式​

将 DragonCode\LaravelFeed\Attributes\DateFormat 中的 #[DateFormat('Y-m-d H:i')] 应用于 FeedItem 类，以覆盖其日期格式。

在模型中配置日期类型转换，并从 toArray() 返回原始 DateTimeInterface 值。已格式化的字符串不会重新格式化：

namespace App\Feeds\Items;

use DragonCode\LaravelFeed\Attributes\DateFormat;
use DragonCode\LaravelFeed\Feeds\Items\FeedItem;

#[DateFormat('Y-m-d H:i')]
class ProductFeedItem extends FeedItem
{
    public function toArray(): array
    {
        return [
            'finishedAt' => $this->model->finished_at,
            'createdAt' => $this->model->created_at,
            'updatedAt' => $this->model->updated_at,
        ];
    }
}

该属性适用于所有输出格式，包括嵌套 JSON/XML 结构中的日期，以及 attributes() 为 XML/RSS 项目属性返回的日期。

格式从带有该属性的最近父类继承；子类上的属性会覆盖继承的格式。该属性优先于 Feed 专用和全局日期格式，同时保留 feeds.date.timezone 设置。

FeedInfo、根元素属性以及未使用该属性的其他项目继续使用正常配置的转换流程。

ElementData​

ElementData 是一个只读对象，具有三个构造函数属性：

属性类型默认值
name?stringnull
attributesarray[]
beforeInfobooltrue

将 name 设为 null 或空字符串可隐藏根元素。将 beforeInfo 设为 false 可在根元素之前写入 Feed 信息。

生成结果​

GeneratorService::feed() 返回 GenerationResultData。其只读 paths 属性按输出顺序包含已发布文件。其只读 records 属性将每个路径映射到写入该文件的记录数。

编程式生成和注册方法列在运行时服务与契约中。

FeedFormatEnum​

枚举项值
Xmlxml
Jsonjson
JsonLinesjsonl
Csvcsv
Rssrss

另请参阅​