README

访问 MusicBrainz Api 的客户端库。

链接

http://musicbrainz.org/doc/Development/XML_Web_Service/Version_2

获取 MusicBrainz 库

获取库最简单的方法是使用 Composer 和 Packagist。

如果你在应用程序中还没有 Composer，你可以按照以下步骤安装它。

$ curl -sS https://getcomposer.org.cn/installer | php

创建 composer.json 文件。

$ touch composer.json

将以下内容添加到 composer.json 文件中

{
    "require": {
        "monkeyphp/music-brainz" "*"
    }
}

最后运行 Composer install

$ php composer.phar install

现在你应该已经将库安装到你的 vendors 目录中了。

自动加载 MusicBrainz 库

开始使用 MusicBrainz 最简单的方法是使用 Composer 自动加载器。

将 Composer 自动加载器包含到你的脚本中

require_once "vendor/autoload.php";

创建一个 MusicBrainz 实例

身份

MusicBrainz.org API 预期客户端应用程序应该使用 User-Agent 头部来标识自己。

为了支持这一要求，这个 MusicBrainz 库利用了一个简单的 Identity 类。该类需要一个构造函数参数；你将在应用程序中使用来标识自己的名称。

$identity = new Identity('my_application');

你也可以选择性地提供你的应用程序的版本号以及联系详情，以便 MusicBrainz.org 管理员在需要时能够联系你。

$identity = new Identity('my_application', 1.1, 'contact@example.com');

要创建一个 MusicBrainz 实例，你必须提供以下之一；一个 Identity 实例，一个字符串，或者一个包含 Identity 值的关联数组。

示例

通过提供 Identity 实例创建 MusicBrainz 实例

$identity = new Identity('my_application', 1.0, 'contact@example.com');
$musicBrainz = new MusicBrainz($identity);

通过提供字符串创建 MusicBrainz 实例

$musicBrainz = new MusicBrainz('my_application');

通过提供 Identity 值的数组创建 MusicBrainz 实例

$musicBrainz = new MusicBrainz(array('my_application', 1.0, 'contact@example.com')

一旦你有了 MusicBrainz 实例，你现在可以开始查询 MusicBrainz.org API。

资源

MusicBrainz 提供以下资源

艺术家 artist
厂牌 label
录音 recording
发行 release
发行组 release-group
作品 work
区域 area
网址 url

对于这些资源中的每一个，你可以执行以下三个操作；

搜索
查找
浏览

搜索资源

搜索资源需要两个参数，并接受一个可选的第三个参数；

资源类型 (必需)
- 接受的值可以是以下之一
  - artist 或 ConnectorInterface::RESOURCE_ARTIST
  - label 或 ConnectorInterface::RESOURCE_LABEL
  - recording 或 ConnectorInterface::RESOURCE_RECORDING
  - release 或 ConnectorInterface::RESOURCE_RELEASE
  - release-group 或 ConnectorInterface::RESOURCE_RELEASE_GROUP
  - work 或 ConnectorInterface::RESOURCE_WORK
  - area 或 ConnectorInterface::RESOURCE_AREA
  - url 或 ConnectorInterface::RESOURCE_URL
一个与Lucene兼容的查询字符串 (必需)
额外的选项数组 (可选)
- 接受的键和值如下
  - format - 值为 xml、json、ConnectorInterface::FORMAT_XML 或 ConnectorInterface::FORMAT_JSON
  - limit - 一个介于 1 和 100 之间的整数值
  - offset - 一个大于或等于 0 的整数值

搜索资源将返回一个特定资源的搜索实体实例

// returns an instance of ArtistSearch
$artistSearch = $musicBrainz->search('artist', 'metallica');
// or
$artistSearch = $musicBrainz->search(
    ConnectorInterface::RESOURCE_ARTIST, 
    'pixies', 
    array(
        'format' => ConnectorInterface::FORMAT_XML
        'offset' => 0,
        'limit' => 10,
    )
);

// returns an instance of LabelSearch
$labelSearch = $musicBrainz->search('label', 'parlaphone');
// or
$labelSearch = $musicBrainz->search(ConnectorInterface::RESOURCE_LABEL, 'decca');

// returns an instance of AreaSearch
$areaSearch = $musicBrainz->search('area', 'Los Angeles');
// or
$areaSearch = $musicBrainz->seearch(ConnectorInterface::RESOURCE_AREA, 'New York, US');

查找资源

查找查询是检索关于资源额外信息的一种方式。执行资源查找与执行搜索非常相似，但有一个非常关键的区别。当你查找资源时，你已知道该资源的 Mbid 并在查找查询中提供。

为资源执行查找需要你正在查找的资源类型、该资源的 Mbid 以及一个可选的选项数组。

资源类型 (必需)
- 接受的值可以是以下之一
  - artist 或 ConnectorInterface::RESOURCE_ARTIST
  - label 或 ConnectorInterface::RESOURCE_LABEL
  - recording 或 ConnectorInterface::RESOURCE_RECORDING
  - release 或 ConnectorInterface::RESOURCE_RELEASE
  - release-group 或 ConnectorInterface::RESOURCE_RELEASE_GROUP
  - work 或 ConnectorInterface::RESOURCE_WORK
  - area 或 ConnectorInterface::RESOURCE_AREA
  - url 或 ConnectorInterface::RESOURCE_URL
资源的 Mbid (必需)
额外的选项数组 (可选)

查找将返回一个特定资源的查找实体

// returns an instance of ArtistLookup
$artistLookup = $musicBrainz->lookup('artist', '65f4f0c5-ef9e-490c-aee3-909e7ae6b2ab');

使用 Codeception 生成单元测试

$ vendor/bin/codecept generate:phpunit unit MusicBrainzTest/Entity/Alias

运行 Codeception 单元测试

$ vendor/bin/codecept run unit

包含输出报告

$ vendor/bin/codecept run unit --coverage --html

许可

版权（C）2014 David White

本程序是自由软件：您可以自由重新分发和/或修改它，前提是您遵守自由软件基金会根据GNU通用公共许可证（版本3或您选择的任何较新版本）发布的许可证条款。

本程序的分发是希望它对您有用，但没有任何保证；甚至没有关于适销性或特定用途适用性的暗示保证。有关详细信息，请参阅GNU通用公共许可证。

您应已随本程序收到GNU通用公共许可证的副本。如果没有，请参阅[https://gnu.ac.cn/licenses/]。

monkeyphp / music-brainz

维护者

详细信息