README

Spotify for Laravel

Laravel 11 的简单易用的 Spotify Web API 包装器

安装 • 使用示例 • 可选参数 • Spotify API 参考 • 推荐

简介

Spotify for Laravel 使使用 Spotify Web API 变得非常简单。它为每个端点提供直接的方法，并为可选参数提供流畅的接口。

该软件包支持所有可以通过 客户端凭据流程 访问的 Spotify Web API 端点。

安装

使用 Composer 安装软件包。软件包将自动注册自己。

composer require aerni/laravel-spotify

发布软件包配置。

php artisan vendor:publish --provider="Aerni\Spotify\Providers\SpotifyServiceProvider"

以下配置将发布到 config/spotify.php。

return [

    /*
    |--------------------------------------------------------------------------
    | Authentication
    |--------------------------------------------------------------------------
    |
    | The Client ID and Client Secret of your Spotify App.
    |
    */

    'auth' => [
        'client_id' => env('SPOTIFY_CLIENT_ID'),
        'client_secret' => env('SPOTIFY_CLIENT_SECRET'),
    ],

    /*
    |--------------------------------------------------------------------------
    | Default Config
    |--------------------------------------------------------------------------
    |
    | You may define a default country, locale and market that will be used
    | for your Spotify API requests.
    |
    */

    'default_config' => [
        'country' => null,
        'locale' => null,
        'market' => null,
    ],

];

在您的 .env 文件中设置您的 Spotify 应用 的 Client ID 和 Client Secret。

SPOTIFY_CLIENT_ID=********************************
SPOTIFY_CLIENT_SECRET=********************************

使用示例

在文件顶部导入软件包。以下所有示例都使用 外观。

use Spotify;

搜索名为 Closed on Sunday 的曲目。

Spotify::searchTracks('Closed on Sunday')->get();

重要： get() 方法充当流畅接口的最终方法。请确保始终在方法链的最后调用它，以执行对 Spotify Web API 的请求。

可选参数

您可以使用此软件包提供的流畅接口向请求传递可选参数。一个常见的用例是为请求设置 limit 和 offset。

Spotify::searchTracks('Closed on Sunday')->limit(50)->offset(50)->get();

参数方法 API 参考

请参考 Spotify Web API 参考文档，以检查哪些端点可用哪些参数。

// Limit the response to a particular geographical market.
Spotify::artistAlbums('artist_id')->country('US')->get();

// Filter the query using the provided string.
Spotify::playlist('playlist_id')->fields('description, uri')->get();

// Include any relevant content that is hosted externally.
Spotify::searchTracks('query')->includeExternal('audio')->get();

// Filter the response using the provided string.
Spotify::artistAlbums('artist_id')->includeGroups('album, single, appears_on, compilation')->get();

// Set the number of track objects to be returned.
Spotify::searchTracks('query')->limit(10)->get();

// Set the index of the first track to be returned.
Spotify::searchTracks('query')->offset(10)->get();

// Limit the response to a particular geographical market.
Spotify::searchAlbums('query')->market('US')->get();

// Limit the response to a particular language.
Spotify::category('category_id')->locale('en_US')->get();

// Get results based on a specific date and time.
Spotify::featuredPlaylists()->timestamp('2020-03-02T09:00:00')->get();

重置默认值

您可能希望重置特定请求的 country、locale 或 market 的默认设置。您可以调用相应的参数方法并传递空参数来实现这一点。

// This will reset the default market to nothing.
Spotify::searchTracks('query')->market()->get();

响应键

一些 API 响应被包裹在顶级对象中，如 artists 或 tracks。如果您想直接访问给定顶级对象的内容，您可以通过将键作为字符串传递给 get() 方法来实现。

// This will return the content of the tracks object.
Spotify::searchTracks('query')->get('tracks');

Spotify API 参考

注意：任何接受多个值的参数都可以接收以逗号分隔的值的字符串或值数组。

// Pass a string with comma-separated values
Spotify::albums('album_id, album_id_2, album_id_3')->get();

// Or pass an array of values
Spotify::albums(['album_id', 'album_id_2', 'album_id_3'])->get();

专辑

Spotify Web API 关于专辑的参考

// Get an album by ID.
Spotify::album('album_id')->get();

// Get several albums by IDs. Provide a string or array of IDs.
Spotify::albums('album_id, album_id_2, album_id_3')->get();

// Get the tracks of an album by ID.
Spotify::albumTracks('album_id')->get();

艺术家

Spotify Web API 关于艺术家的参考

// Get an artist by ID.
Spotify::artist('artist_id')->get();

// Get several artists by IDs. Provide a string or array of IDs.
Spotify::artists('artist_id, artist_id_2, artist_id_3')->get();

// Get albums of an artist by ID.
Spotify::artistAlbums('artist_id')->get();

// Get the artist's top tracks by ID.
Spotify::artistTopTracks('artist_id')->get();

// Get an artist's related artists by ID.
Spotify::artistRelatedArtists('artist_id')->get();

浏览

Spotify Web API 关于浏览的参考

// Get a category by ID.
Spotify::category('category_id')->get();

// Get a category's playlists by ID.
Spotify::categoryPlaylists('category_id')->get();

// Get a list of categories.
Spotify::categories()->get();

// Get a list of featured playlists.
Spotify::featuredPlaylists()->get();

// Get a list of new releases.
Spotify::newReleases()->get();

// Get available genre seeds.
Spotify::availableGenreSeeds()->get();

// Get recommendations based on a seed.
Spotify::recommendations($seed)->get();

单集

Spotify Web API 关于单集的参考

// Get an episode by ID.
Spotify::episode('episode_id')->get();

// Get several episodes by IDs. Provide a string or array of IDs.
Spotify::episodes('episode_id, episode_id_2, episode_id_3')->get();

播放列表

Spotify Web API 关于播放列表的参考

// Get a playlist by ID.
Spotify::playlist('playlist_id')->get();

// Get a playlist's tracks by ID.
Spotify::playlistTracks('playlist_id')->get();

// Get a playlist's cover image by ID.
Spotify::playlistCoverImage('playlist_id')->get();

搜索

Spotify Web API 关于搜索的参考

// Search items by query. Provide a string or array to the second parameter.
Spotify::searchItems('query', 'album, artist, playlist, track')->get();

// Search albums by query.
Spotify::searchAlbums('query')->get();

// Search artists by query.
Spotify::searchArtists('query')->get();

// Search episodes by query.
Spotify::searchEpisodes('query')->get();

// Search playlists by query.
Spotify::searchPlaylists('query')->get();

// Search shows by query.
Spotify::searchShows('query')->get();

// Search tracks by query.
Spotify::searchTracks('query')->get();

节目

Spotify Web API 关于节目的参考

// Get a show by ID.
Spotify::show('show_id')->get();

// Get several shows by IDs. Provide a string or array of IDs.
Spotify::shows('show_id, show_id_2, show_id_3')->get();

// Get the episodes of a show by ID.
Spotify::showEpisodes('show_id')->get();

曲目

Spotify Web API 轨道参考

// Get a track by ID.
Spotify::track('track_id')->get();

// Get several tracks by IDs. Provide a string or array of IDs.
Spotify::tracks('track_id, track_id_2, track_id_3')->get();

// Get audio analysis for a track by ID.
Spotify::audioAnalysisForTrack('track_id')->get();

// Get audio features for a track by ID.
Spotify::audioFeaturesForTrack('track_id')->get();

// Get audio features for several tracks by ID. Provide a string or array of IDs.
Spotify::audioFeaturesForTracks('track_id, track_id_2, track_id_3')->get();

用户资料

Spotify Web API 用户资料参考

// Get a user's profile
Spotify::user('user_id')->get();

// Get a list of a user's playlists
Spotify::userPlaylists('user_id')->get();

推荐内容

您可以使用种子艺术家、流派和轨道以及一系列可调整的属性（如能量、音调和舞曲性）来通过推荐端点获取个性化曲目。

使用示例

导入SpotifySeed类。以下所有示例都使用外观。

use SpotifySeed;

构建您的个性化$seed。您可以链式调用任意多个方法。

$seed = SpotifySeed::setGenres(['gospel', 'pop', 'funk'])
    ->setTargetValence(1.00)
    ->setSpeechiness(0.3, 0.9)
    ->setLiveness(0.3, 1.0);

通过将$seed传递给recommendations()方法来获取个性化曲目。

Spotify::recommendations($seed)->get();

SpotifySeed API 参考

注意：任何接受多个值的参数都可以接收以逗号分隔的值的字符串或值数组。

将艺术家、流派和轨道添加到您的种子中

// Add an artist by ID.
SpotifySeed::addArtist('artist_id');

// Add several artists by IDs. Provide a string or array of IDs.
SpotifySeed::addArtists('artist_id_1, artist_id_2, artist_id_3');

// Set artists by IDs. Provide a string or array of IDs. This overwrites previously added artists.
SpotifySeed::setArtists('artist_id_1, artist_id_2, artist_id_3');

// Add a genre by ID.
SpotifySeed::addGerne('gerne_id');

// Add several genres by IDs. Provide a string or array of IDs.
SpotifySeed::addGenres('gerne_id_1, gerne_id_2, gerne_id_3');

// Set gernes by IDs. Provide a string or array of IDs. This overwrites previously added genres.
SpotifySeed::setGenres('genre_id_1, genre_id_2, genre_id_3');

// Add a track by ID.
SpotifySeed::addTrack('track_id');

// Add several tracks by IDs. Provide a string or array of IDs.
SpotifySeed::addTracks('track_id_1, track_id_2, track_id_3');

// Set tracks by IDs. Provide a string or array of IDs. This overwrites previously added tracks.
SpotifySeed::setTracks('track_id_1, track_id_2, track_id_3');

将可调整的属性添加到您的种子中

SpotifySeed::setAcousticness(float $min, float $max);
SpotifySeed::setTargetAcousticness(float $target);

SpotifySeed::setDanceability(float $min, float $max);
SpotifySeed::setTargetDanceability(float $target);

SpotifySeed::setDuration(int $min, int $max);
SpotifySeed::setTargetDuration(int $target);

SpotifySeed::setEnergy(float $min, float $max);
SpotifySeed::setTargetEnergy(float $target);

SpotifySeed::setInstrumentalness(float $min, float $max);
SpotifySeed::setTargetInstrumentalness(float $target);

SpotifySeed::setKey(int $min, int $max);
SpotifySeed::setTargetKey(int $target);

SpotifySeed::setLiveness(float $min, float $max);
SpotifySeed::setTargetLiveness(float $target);

SpotifySeed::setLoudness(float $min, float $max);
SpotifySeed::setTargetLoudness(float $target);

SpotifySeed::setMode(int $min, int $max);
SpotifySeed::setTargetMode(int $target);

SpotifySeed::setPopularity(float $min, float $max);
SpotifySeed::setTargetPopularity(float $target);

SpotifySeed::setSpeechiness(float $min, float $max);
SpotifySeed::setTargetSpeechiness(float $target);

SpotifySeed::setTempo(int $min, int $max);
SpotifySeed::setTargetTempo(int $target);

SpotifySeed::setTimeSignature(int $min, int $max);
SpotifySeed::setTargetTimeSignature(int $target);

SpotifySeed::setValence(float $min, float $max);
SpotifySeed::setTargetValence(float $target);

测试

按照以下方式运行测试

vendor/bin/phpunit