README

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

内容

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

安装

使用Git安装

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

使用Composer安装

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

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

composer require papposilene/musicbrainz

设置

HTTP适配器

由于HTTP客户端对于MusicBrainz API客户端是必需的，您必须将其作为构造函数参数提供。您可以使用任何HTTP客户端，通过实例化MusicBrainz\AbstractHttpAdapter来使用适配器。本项目提供了一个用于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日志记录器注入为第二个构造函数参数来设置任何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);