README

此包不再维护！

Larafy

Larafy 是 Spotify API 的 PHP API 封装器。此封装器更侧重于客户端凭据认证的端点，并提供出色的接口和优雅的方式来搜索曲目、种子流派或简单地提供用户定制的曲目/专辑列表。

安装

安装包

$ composer require rennokki/larafy

如果你的 Laravel 版本不支持包发现，请在你的 config/app.php 文件中的 providers 数组中添加此行

Rennokki\Larafy\LarafyServiceProvider::class,

设置 API

为此，你需要从 Spotify API 控制台获取 APP ID 和 APP SECRET。

为了更简洁的方法，将以下内容添加到你的 config/services.php 文件中

'spotify' => [
    'client_id' => env('SPOTIFY_KEY'),
    'client_secret' => env('SPOTIFY_SECRET'),
    'redirect' => env('SPOTIFY_REDIRECT_URI')
],

要使用 API，你只需将构造函数参数传递给 Rennokki\Larafy\Larafy

$api = new Larafy();

如果你需要动态更改凭据，可以通过声明一个新的 API 实例来执行此操作，其中包含你的 App ID 和 App Secret

use Rennokki\Larafy\Larafy;

$api = new Larafy('your_app_id_here', 'your_app_secret_here');

展示

所有请求都会抛出异常，无论是数据无效，还是请求本身有问题。为此，提供了两种可以捕获的异常

\Rennokki\Larafy\Exceptions\SpotifyAPIException - 当 API 正确认证，但传入的数据无效时抛出。
\Rennokki\Larafy\Exceptions\SpotifyAuthorizationException - 当 API 不能使用提供的凭据进行认证时抛出。

try {
    $api->searchArtists('Lana del Rey');
} catch(\Rennokki\Larafy\Exceptions\SpotifyAuthorizationException $e) {
    // invalid ID & Secret provided
    $e->getAPIResponse(); // Get the JSON API response.
}

try {
    $api->searchArtists('Lana del Rey', -30, -40);
} catch(\Rennokki\Larafy\Exceptions\SpotifyAPIException $e) {
    // invalid data sent
    $e->getAPIResponse(); // Get the JSON API response.
}

由于 Spotify 与音乐相关，因此在市场和地区上有所限制。例如，一些在某个国家可用的专辑可能在其他国家不可用，例如 AC/DC 的 The Razor Edge 专辑，在不同国家如 澳大利亚 或 美国 有不同的版本。

为了帮助更好地搜索市场和地区，可以在 API 实例中使用 setMarket() 和 setLocale() 方法。这些默认设置为 US 和 en_US。这些是可选的。

可以将它们链接起来

$api->setMarket('RO')->setLocale('ro_RO');

或者按需设置它们

$api->setMarket('ES');
...
$api->setLocale('es_ES');

一些请求需要一个 offset 和一个 limit，这些是可选的，默认分别为 0 和 10。限制是请求中可以显示的结果数量，而偏移量指示从第一个结果开始跳过的结果数量。请参见下一个示例，了解如何使用此功能。

$limit = 15;
$offset = 5;

$api->searchAlbums('Master of Puppets', $limit, $offset); // limit 15 with 5 offset.

当检索多个数据时，你可以传递一个数组或一个以逗号分隔值的字符串

$api->getAlbums(['album_id_1', 'album_id_2', ...]);
$api->getAlbums('album_id_1,album_id_2,...');

当对可能返回更多数据的端点发出请求时，通常通过访问 items 属性来完成

$masterOfPuppets = $api->searchAlbums('Master of Puppets');
$masterOfPuppets->items; // this is the array with all results

对于 getArtistAlbums() 方法，有一个选项可以根据专辑是否为单一专辑或艺术家是否出现在专辑上来搜索艺术家的专辑。为此，应用了与逗号分隔值或数组方法相同的规则。

$api->getArtistAlbums('artist_id', $limit, $offset, ['single', 'appears_on']);
$api->getArtistAlbums('artist_id', $limit, $offset, ['single']);
$api->getArtistAlbums('artist_id', $limit, $offset, 'single');
$api->getArtistAlbums('artist_id', $limit, $offset, 'single,appears_on');

API 使用

推荐

推荐允许你查询 Spotify API 以获取个性化内容。通过种子曲目、流派和艺术家以及一系列可调整的属性，如能量、键和节奏感，可以获取为用户定制的曲目。

在深入探讨之前，请确保你熟悉推荐端点。

每个曲目都有其自己的属性，例如键、节奏感、能量或响度。为此，\Rennokki\Larafy\LarafySeed 类可以帮助你更容易地构建种子。让我们从一个示例开始

$seed = (new LarafySeed)
    ->setGenres(['death-metal', 'hard-rock', 'black-metal'])
    ->setTargetValence(90.3)
    ->setSpeechiness(60.0, 90.0)
    ->setLoudness(80.0, 100.0)
    ->setLiveness(80.0, 100.0);

$tracks = $api->getRecommendations($seed, $limit);
foreach ($tracks->items as $track) {
    ...
}

在前一个示例中，我们只搜索了来自死亡金属、硬摇滚和黑金属的曲目，这些曲目的情绪值（积极程度；值越高，越积极）约为90.3，然后我们为语音性（值越高，音乐性越低：播客）、响度和现场感（值越高，越可能是现场表演）设置了范围。

要获取可用种子，您可以使用$api->getGenreSeeds()来获取setGenres()方法的可能值列表。

以下两种用法存在区别：

set{属性}($最小值, $最大值)
setTarget{属性}($值).

在设置范围时，它可能在两个值之间变化。在设置目标值时，它尽可能接近该值。在此处了解更多关于每个种子信息

要添加艺术家、曲目或流派，您可以使用

$seed->addArtist('artist_id');
$seed->addArtists(['artist_id_1', 'artist_id_2', ...']);
$seed->addArtists('artist_id_1,artist_id_2,...');
$seed->setArtists(['artist_id_1', 'artist_id_2', ...']); // overwrites
$seed->setArtists('artist_id_1,artist_id_2,...'); // overwrites

$seed->addTrack('track_id');
$seed->addTracks(['track_id_1', 'track_id_2', ...']);
$seed->addTracks('track_id_1,track_id_2,...');
$seed->setTracks(['track_id_1', 'track_id_2', ...']); // overwrites
$seed->setTracks('track_id_1,track_id_2,...'); // overwrites

$seed->addGenre('genre');
$seed->addGenres(['genre1', 'genre2', ...']);
$seed->addGenres('genre1,genre2,...');
$seed->setGenres(['genre1', 'genre2', ...']); // overwrites
$seed->setGenres('genre1,genre2,...'); // overwrites

对于歌曲的可调属性，您可以使用以下方法

$seed->setAcousticness($min, $max); // float
$seed->setTargetAcousticness($target); // float

$seed->setDanceability($min, $max); // float
$seed->setTargetDanceability($target); // float

$seed->setEnergy($min, $max); // float
$seed->setTargetEnergy($target); // float

$seed->setInstrumentalness($min, $max); // float
$seed->setTargetInstrumentalness($target); // float

$seed->setKeys($min, $max); // int
$seed->setTargetKey($target); // int

$seed->setLiveness($min, $max); // float
$seed->setTargetLiveness($target); // float

$seed->setLoudness($min, $max); // float
$seed->setTargetLoudness($target); // float

$seed->setMode($min, $max); // int
$seed->setTargetMode($target); // int

$seed->setPopularity($min, $max); // float
$seed->setTargetPopularity($target); // float

$seed->setSpeechiness($min, $max); // float
$seed->setTargetSpeechiness($target); // float

$seed->setTempo($min, $max); // int
$seed->setTargetTempo($target); // int

$seed->setTimeSignature($min, $max); // int
$seed->setTargetTimeSignature($target); // int

$seed->setValence($min, $max); // float
$seed->setTargetValence($target); // float

$seed->setDuration($min, $max); // int, in seconds
$seed->setTargetDuration($target); // int, in seconds

注意：在构建种子时，您可以链式调用所需属性的数量。

专辑

专辑API参考

// Search for albums.
$api->searchAlbums('Master of Puppets', $limit, $offset);

// Get an album using ID.
$api->getAlbum('album_id');

// Get more albums at once based on IDs.
$api->getAlbums(['id1', 'id2', ...]);
$api->getAlbums('id1,id2,...');

// Get album's tracks.
$api->getAlbumTracks('album_id', $limit, $offset);

曲目

曲目API参考

// Search for tracks.
$api->searchTracks('Fade to Black', $limit, $offset);

// Get a track using ID.
$api->getTrack('track_id');

// Get more tracks at once based on IDs.
$api->getTracks(['id1', 'id2', ...]);
$api->getTracks('id1,id2,...');

艺术家

艺术家API参考

// Search for artists.
$api->searchArtists('Metallica', $limit, $offset);

// Get an artist using ID.
$api->getArtist('artist_id');

// Get more artists at once based on IDs.
$api->getArtists(['id1', 'id2', ...]);
$api->getArtists('id1,id2,...');

// Get artist's albums.
$api->getArtistAlbums('artist_id', $limit, $offset, ['single', 'appears_on']);

// Get artist's top tracks.
$api->getArtistTopTracks('artist_id');

// Get artist's related artists.
$api->getArtistRelatedArtists('artist_id');

播放列表

播放列表API参考

// Search for playlists.
$api->searchPlaylists('This Is Metallica', $limit, $offset);

// Get a playlist using ID.
$api->getPlaylist('playlist_id');

// Get playlist's albums.
$api->getPlaylistTracks('playlist_id', $limit, $offset);

// Get featured playlists from a specific time.
$api->getFeaturedPlaylists(Carbon::now(), $limit, $offset);
$api->getFeaturedPlaylists('2018-05-19 00:00:00', $limit, $offset);

浏览

浏览API参考

// Get genre seeds.
$api->getGenreSeeds();

// Get all the Browse categories.
$api->getBrowseCategories($limit, $offset);

// Get details about one of the Browse's category.
$api->getBrowseCategory('mood');

// Get playlists from a Browse category.
$api->getCategoryPlaylists('mood', $limit, $offset);

// Get new albums releases.
$api->getNewReleases($limit, $offset);

mezuky04 / larafy

维护者

详细信息