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专辑，在不同的国家（如Austrialia或US）有不同的版本。

为了帮助更好地搜索市场和相应地区，可以在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{property}($min, $max) 与 setTarget{property}($value) 之间有一个区别

set{property}($min, $max)
setTarget{property}($value).

当设置范围时，它可能在两个值之间变化。当设置目标值时，它会尽可能地围绕它。

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

$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);

rennokki / larafy

维护者

详细信息