README

本项目包含一个易于使用的 PHP API 客户端，用于访问 MusicBrainz JSON Web 服务。

内容

• 安装
  • 使用 Git 安装
  • 使用 Composer 安装
• 设置
  • HTTP 适配器
  • 日志记录器
  • MusicBrainz 凭证
• 用法
  • 搜索请求
  • 查找请求
  • 浏览请求

安装

使用 Git 安装

git clone https://github.com/XenosEleatikos/MusicBrainz.git

使用 Composer 安装

该项目可在 Packagist 上找到：https://packagist.org.cn/packages/xenos/musicbrainz。

您可以使用以下命令在项目中使用它

composer require xenos/musicbrainz

设置

HTTP 适配器

由于 MusicBrainz API 客户端需要一个 HTTP 客户端，您必须将其作为构造函数参数提供。您可以通过实例化 MusicBrainz\AbstractHttpAdapter 使用任何 HTTP 客户端。该项目提供了一个用于 Guzzle 6 的适配器，但您可以为您的首选 HTTP 客户端编写自己的适配器。

使用 Guzzle

<?php
use MusicBrainz\MusicBrainz;
use MusicBrainz\HttpAdapter\GuzzleHttpAdapter;
use GuzzleHttp\Client;

$guzzleHttpAdapter = new GuzzleHttpAdapter(new Client);
$musicBrainz       = new MusicBrainz($guzzleHttpAdapter);

如果尚未要求，请记住将 Guzzle 添加到您的 composer 项目中。

composer require guzzlehttp/guzzle

日志记录器

可选地，您可以设置任何实现 Psr\Log\LoggerInterface 的 PSR-3 日志记录器，通过将其作为第二个构造函数参数注入。

使用 Guzzle 和 Monolog

<?php
use Monolog\Logger;
use MusicBrainz\MusicBrainz;
use MusicBrainz\HttpAdapter\GuzzleHttpAdapter;
use GuzzleHttp\Client;

$guzzleHttpAdapter = new GuzzleHttpAdapter(new Client);
$logger            = new Logger('MusicBrainz API Client Logger');
$musicBrainz       = new MusicBrainz($guzzleHttpAdapter, $logger);

如果尚未要求，请记住将 Monolog 添加到您的 composer 项目中。

composer require monolog/monolog

MusicBrainz 凭证

所有针对 user-tags 或 user-ratings 的请求都需要进行身份验证。

<?php
/** @var \MusicBrainz\MusicBrainz $musicBrainz*/
$musicBrainz->config()
    ->setUsername('myUsername')
    ->setPassword('myPassword');

自定义 API 路径

默认情况下，所有请求都是针对位于 https://musicbrainz.org/ws/2 的 MusicBrainz API 执行。您可以设置另一个基本路径（例如，用于您自己的 MusicBrainz 安装），如下所示

<?php
/** @var \MusicBrainz\MusicBrainz $musicBrainz*/
$musicBrainz->config()
    ->setApiUrl('https://example.com/ws/2');

用法

搜索请求

搜索 API 提供了搜索 MusicBrainz 核心实体 的方法。对于这些实体中的每一个，都有一个搜索方法，该方法接受一个特定的过滤器对象和一个分页过滤器。返回值将是一个特定的列表对象，其中包含匹配实体的基本信息。有关更多信息，您必须执行一个带有实体 MusicBrainz 标识符（MBID）的 查找请求。

以下示例搜索名为 "Tom Waits" 的艺术家，并将结果列表限制为最佳匹配。

<?php
use MusicBrainz\Filter\PageFilter;
use MusicBrainz\Filter\Search\ArtistFilter;
use MusicBrainz\Value\Name;

$artistFilter = new ArtistFilter;
$artistFilter->addArtistNameWithoutAccents(new Name('Tom Waits'));
$pageFilter = new PageFilter(0, 1);

$artistList = $this->musicBrainz->api()->search()->artist($artistFilter, $pageFilter);

查找请求

如果您有一个实体的 MusicBrainz 标识符（MBID）（通过 搜索请求），您可以通过执行查找请求来获取更多关于它的信息。对于每个核心实体，都有一个特定的查找方法。作为第一个参数，您必须传递 MBID。第二个参数是响应对象应包含的附加字段列表。

以下示例查找 MBID 为 c3aeb863-7b26-4388-94e8-5a240f2be21b 的艺术家（即 Tom Waits），并请求将他的录音和工作信息附加到响应中。

<?php
use MusicBrainz\Supplement\Lookup\ArtistFields;
use MusicBrainz\Value\MBID;

$fields = (new ArtistFields)
    ->includeRecordings()
    ->includeWorks();

self::$artist = $this->musicBrainz->api()->lookup()->artist(
    new MBID('c3aeb863-7b26-4388-94e8-5a240f2be21b'),
    $fields
);

浏览请求

浏览请求是直接查找与给定 MusicBrainz 标识符（MBID）直接链接到另一个实体的所有实体。

以下示例查找与MBID为c3aeb863-7b26-4388-94e8-5a240f2be21b（代表Tom Waits）直接相关的所有事件。类似于正常的查找请求，响应中可以指定额外的字段，并添加页面过滤器以实现分页。

<?php
use MusicBrainz\Filter\Browse\Relation\Entity\EventRelation;
use MusicBrainz\Supplement\Browse\EventFields;

$eventRelation = (new EventRelation)
    ->artist(new MBID('4aae17a7-9f0c-487b-b60e-f8eafb410b1d'));
$eventFields = (new EventFields)
    ->includeTags();
$pageFilter = new PageFilter(0, 5);

$eventList = $musicBrainz->api()->browse()->event($eventRelation, $eventFields, $pageFilter);