README

轻松使用PHP遵循PSP-1 Podcast RSS标准解析播客源。

要求和安装

Poddle需要PHP 8.1或更高版本。您可以通过运行以下命令使用Composer安装库

composer require phanan/poddle

用法

从URL解析

要从URL解析播客源，请使用带有源URL的fromUrl方法

$poddle = \PhanAn\Poddle::fromUrl('https://example.com/feed.xml');

此方法还接受两个额外的参数

• timeoutInSeconds：尝试连接时等待的秒数。默认为30。请注意，您的PHP配置中的max_execution_time值可能还会限制最大超时值。
• client：一个符合PSR-7规范的客户端来发送请求。如果不提供，Poddle将使用默认客户端。在测试期间或您需要大量自定义请求时，此参数可能很有用。

从XML解析

如果您已经有了XML字符串，您可以使用Poddle::fromXml来解析它

$poddle = \PhanAn\Poddle::fromXml(file_read_contents('feed.xml'));

在成功的情况下，fromUrl和fromXml方法都返回一个Poddle对象，您可以用来访问源频道和剧集。

频道

要访问播客频道，请在Poddle对象上调用getChannel

/** @var \PhanAn\Poddle\Values\Channel $channel */
$channel = $poddle->getChannel();

根据PSP-1标准，所有频道必需元素均作为属性在Channel对象上可用

$channel->title; // string
$channel->link; // string
$channel->description; // string
$channel->language; // string
$channel->image; // string
$channel->categories; // \PhanAn\Poddle\Values\CategoryCollection<\PhanAn\Poddle\Values\Category>
$channel->explicit; // bool

所有频道推荐元素均通过metadata属性可用

$channel->metadata; // \PhanAn\Poddle\Values\ChannelMetadata
$channel->metadata->locked; // bool
$channel->metadata->guid; // ?string
$channel->metadata->author; // ?string
$channel->metadata->copyright; // ?string
$channel->metadata->txts; // \PhanAn\Poddle\Values\TxtCollection<\PhanAn\Poddle\Values\Txt>
$channel->metadata->fundings; // \PhanAn\Poddle\Values\FundingCollection<\PhanAn\Poddle\Values\Funding>
$channel->metadata->type; // ?\PhanAn\Poddle\Values\PodcastType
$channel->metadata->complete; // bool

剧集

要访问播客剧集，请在Poddle对象上调用getEpisodes

$episodes = $poddle->getEpisodes();

默认情况下，如果任何剧集格式不正确，getEpisodes将抛出错误。如果您想有更宽容的行为，请将true传递给调用以静默忽略无效剧集。

此方法返回一个懒加载集合，其中包含\PhanAn\Poddle\Values\Episode对象。您可以遍历集合以访问每个剧集

$episodes->each(function (\PhanAn\Poddle\Values\Episode $episode) {
    // Access episode properties
});

根据PSP-1标准，所有剧集必需元素均作为属性在Episode对象上可用

$episode->title; // string
$episode->enclosure; // \PhanAn\Poddle\Values\Enclosure
$episode->guid; // \PhanAn\Poddle\Values\EpisodeGuid

所有剧集推荐元素均通过metadata属性可用

$episode->metadata; // \PhanAn\Poddle\Values\EpisodeMetadata
$episode->metadata->link; // ?string
$episode->metadata->pubDate; // ?\DateTime
$episode->metadata->description; // ?string
$episode->metadata->duration; // ?int
$episode->metadata->image; // ?string
$episode->metadata->explicit; // ?bool
$episode->metadata->transcripts; // \PhanAn\Poddle\Values\TranscriptCollection<\PhanAn\Poddle\Values\Transcript>
$episode->metadata->episode; // ?int
$episode->metadata->season; // ?int
$episode->metadata->type; // ?\PhanAn\Poddle\Values\EpisodeType
$episode->metadata->block; // ?bool

其他元素和值

如果您需要访问PSP-1标准未涵盖的其他元素或值，您可以使用Poddle对象上的$xmlReader属性

$xmlReader = $poddle->xmlReader;

此属性是Saloon\XmlWrangler\XmlReader的一个实例，允许您直接导航XML文档。例如，要访问源的最后构建日期值

$poddle = \PhanAn\Poddle::fromUrl('https://example.com/feed.xml');
$poddle->xmlReader->value('rss.channel.lastBuildDate')?->sole(); // 'Thu, 02 May 2024 06:44:38 +0000'

有关如何使用XmlReader的更多信息，请参阅Saloon\XmlWrangler文档。

原始内容源可通过《Poddle》对象的《xml》属性访问

$xml = $poddle->xml; // string

序列化和反序列化

位于《PhanAn\Poddle\Values》命名空间下的所有类实现了《\Illuminate\Contracts\Support\Arrayable》和《\Illuminate\Contracts\Support\Jsonable》接口，提供了两种方法

/**
  * Get the instance as an array. All nested objects are also converted to arrays.
  */
public function toArray(): array;

/**
  * Convert the object to its JSON representation.
  */
public function toJson($options = 0): string;

此外，例如《Channel》和《Episode》这样的类提供了《fromArray》静态方法，可以从数组中创建实例。这些方法允许您轻松地将对象序列化和反序列化，使得在数据库或JSON文件中存储和检索数据变得简单。例如，您可以通过这种方式在Laravel中创建Eloquent的自定义转换

use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use PhanAn\Poddle\Values\Channel;

class ChannelCast implements CastsAttributes
{
    public function get($model, string $key, $value, array $attributes): Channel
    {
        return Channel::fromArray(json_decode($value, true));
    }

    /** @param Channel $value */
    public function set($model, string $key, $value, array $attributes)
    {
        return $value->toJson();
    }
}

然后，您可以在Eloquent模型中使用此转换

use Illuminate\Database\Eloquent\Model;

class Podcast extends Model
{
    protected $casts = [
        'channel' => ChannelCast::class,
    ];
}

可能的问题

为什么Poddle没有包含来自源中的元素或值X？

Poddle遵循PSP-1标准，该标准指定了播客源所需和推荐元素。如果元素或值不是标准的一部分，则不会包含在Poddle中。然而，您仍然可以使用上面描述的《xmlReader》属性访问任何元素或值。

为什么《pubDate》不是必需元素？

PSP-1标准不要求《pubDate》为必需元素，但它是一个推荐元素。因此，《pubDate》作为可选的《DateTime》对象是作为剧集元数据的一部分提供的。您需要自行确定值是否总是存在，并据此设计您的系统。

为什么剧集的GUID是一个对象而不是字符串？

根据PSP-1标准，项目元素《》确实包含一个全局唯一的字符串值，但它还可以有一个属性《isPermaLink》，表示GUID是否是永久链接。因此，Poddle中的项目GUID以具有两个公共属性的对象形式表示：`value`（字符串）和`isPermaLink`（布尔值）。然而，该对象实现了《__toString》方法，因此您可以将它转换为字符串以便使用。

剧集的媒体URL在哪里？

剧集的媒体URL作为剧集的《enclosure》属性的一部分提供。

为什么剧集以《EpisodeCollection extends LazyCollection》对象返回？什么是延迟集合？

《LazyCollection》类利用PHP的生成器来允许您在保持低内存使用的情况下处理非常大的数据集。《LazyCollection》允许您迭代剧集，而无需一次将它们全部加载到内存中，从而加快处理速度并减少内存消耗。

您能支持功能X/Y/Z吗？

Poddle旨在成为一个轻量级且高效的遵循PSP-1标准的播客源解析器，而不是一个完整的RSS/Atom解析器。尽管如此，如果您有功能请求或建议，请随时创建问题。更好的是，您可以分叉存储库，自行实现该功能，并提交拉取请求。