PHP Spotify API Kullanımı

Selamlar, uzun zamandır buraya yazı girmemişim. Bir süredir üzerinde çalıştığım PHP Spotify API'ın nasıl kullanıldığına dair bir Türkçe doküman tarzı bir şey hazırlamak istedim. Önden belirteyim, sorularınızı da yorum bölümünde yanıtlayacağım. Bu sayede hem ben hem de siz öğreneceksiniz. Temel olarak konuştuğumuza göre konuşmaya başlayalım.

PHP Spotify API için gereksinimler:

• PHP 7.4
• Composer
• Spotify üyeliği
• biraz da programlama tutkusu :)

Spotify Developer panelinde uygulama oluşturma:

API'ımızı kullanabilmemiz için Spotify developer panelinde uygulama oluşturmamız gerekiyor. Gelin beraber yapalım.

• https://developer.spotify.com adresine girin ve hesabınızla giriş yapın.
  
  
• Giriş yaptıktan sonra https://developer.spotify.com/dashboard/applications altına ilerleyelim ve yeşil "Create an app" düğmesine tıklayalım.
  
  
• 
  İlk boşluğa uygulama adınızı, ikinci boşluğa da açıklamanızı yazınız ardından tiklerin içeriğini okuyarak işaretleyin ve Create diyin :)
  
  
• 
  Bu iki keyi güvenli bir yere not alın, ileride API bağlantımızı yaparken ihtiyacımız olacak.
  
  

PHP Spotify API nasıl kullanılır?

• Öncelikle temel projemizi açacağız. Bir klasör oluşturun, index.php dosyasını oluşturun.
• Ardından terminal/cmd ekranını açın, klasöre girdikten sonra composer require jwilsson/spotify-web-api-php yazın.
• index.php dosyasının başına

Access token alıp sisteme bağlanmak:

$session = new SpotifyWebAPI\Session('CLIENT_ID', 'CLIENT_SECRET', 'REDIRECT_URI');
$api = new SpotifyWebAPI\SpotifyWebAPI(['auto_refresh' => true, 'auto_retry' => true]);
if (isset($_GET['code'])) {
    $session->requestAccessToken($_GET['code']);
    $api->setAccessToken($session->getAccessToken());
    // $refresh_token = $session->getRefreshToken();
    print_r($api->me());
} else {
    $options = [
        'scope' => [
            // bu kısım hakkında detaylı bilgi için:
            // https://developer.spotify.com/documentation/general/guides/scopes/
            'user-read-email',
        ],
    ];

    header('Location: ' . $session->getAuthorizeUrl($options));
    die();
}

Yukarıdaki kod bloğunu açıklarsak CLIENT_ID kısmına aldığımız id, aynı şekilde secret kısmına da diğer aldığımız kodu gireceğiz. Redirect_uri kısmı ise bu auth işlemini nerede gerçekleştirdiğinize bağlıdır. Ben şahsen bunu ayrı bir sayfada yapıp ardından access tokeni veritabanımda depolamayı tercih ediyorum. Bu kod bloğunu girdiğiniz sayfanın URL'sini yazmanız şimdilik yeterlidir.

Refresh token kullanarak Access token yenilemek:

$session = new SpotifyWebAPI\Session('CLIENT_ID', 'CLIENT_SECRET', 'REDIRECT_URI');
$session->refreshAccessToken(Auth::user()->spotify_refresh_token);
/* bu iki değişkeni bir databasede saklamak cidden iyi fikir. */
$newAccessToken = $session->getAccessToken(); 
$newRefreshToken = $session->getRefreshToken();

Bu iki auth işlemini öğrendikten sonra artık oyuna başlayabiliriz. Aşağıdaki iki kodla API nesnemizi oluşturalım:

$api = new SpotifyWebAPI\SpotifyWebAPI(['auto_refresh' => true, 'auto_retry' => true]);
$api->setAccessToken($session->getAccessToken());

Ardından bu oluşturduğumuz $api değişkeni üzerinden işlemleri yapmaya başlayalım.

addMyTracks - Sevilen Şarkılara Ekleme Yapmak

$api->addMyTracks($tracks)

Access tokeni kullanılan kullanıcının kütüphanesine parça ekler.
https://developer.spotify.com/documentation/web-api/reference/library/save-tracks-user/

Argümanlar

• $tracks string|array - Eklenecek parçaların ID(leri) veya Spotify URI(ları)

Ne döndürüyor?

• boolean Parça kütüphaneye eklendi mi eklenmedi mi?

getMyDevices - Kullanıcının Cihazlarını Almak

$api->getMyDevices()

Kullanıcının cihazları hakkında bilgileri almak.
https://developer.spotify.com/documentation/web-api/reference/player/get-a-users-available-devices/

Ne dönüyor?

• array|object Kullanıcının cihazları. Dönen veri tipini return_assoc ile değiştirebilirsiniz.

changeMyDevice - Çalan Cihazı Değiştirmek

$api->changeMyDevice($options)

Kullanıcının müzik çaldığı cihazı değiştirir.
https://developer.spotify.com/documentation/web-api/reference/player/transfer-a-users-playback/

Argümanlar

• $options array|object - Gereken ayarların listesi.
  • string|array device_ids Zorunludur. Değiştirmek istediğiniz cihazın ID değerini girmelisiniz.
  • bool play Opsiyonel olarak diğer cihazda oynatmanın başlama durumunu belirlersiniz.

Ne döndürüyor?

• boolean İşlem başarılı mı?

changeVolume - Sesi Değiştirmek

$api->changeVolume($options)

Kullanıcının ses düzeyini değiştirir.
https://developer.spotify.com/documentation/web-api/reference/player/set-volume-for-users-playback/

Argümanlar

• $options array|object - Ses ayarları
  • int volume_percent Zorunlu, ayarlanacak sesin düzeyi.
  • string device_id Opsiyonel, sesi değiştirilecek cihazın ID'si.

Ne dönüyor?

• boolean İşlem başarılı mı?

createPlaylist - Playlist Oluşturmak

$api->createPlaylist($options)

Yeni bir çalma listesi oluşturun.
https://developer.spotify.com/documentation/web-api/reference/playlists/create-playlist/

Argümanlar

• $options array|object - Playlist için ayarlar listesi.
  • string name Zorunlu, çalma listesinin ismi.
  • bool public Opsiyonel, çalma listesi herkese açık mı?

Ne dönüyor?

• array|object Yeni çalma listesinin kendisi, tipini return_assoc ile değiştirebilirsiniz.

me - Kullanıcının Bilgilerini Getirmek

$api->me()

O anda giriş yapmış olan kullanıcının bilgilerini alabilirsiniz.
https://developer.spotify.com/documentation/web-api/reference/users-profile/get-current-users-profile/

Ne dönüyor?

• array|object O an giriş yapmış olan kullanıcının bilgileri döner. Tipini return_assoc ile değiştirebilirsiniz.

play - Çalmayı Başlatmak

$api->play($deviceId, $options)

Çalma işlemini başlatır.
https://developer.spotify.com/documentation/web-api/reference/player/start-a-users-playback/

Argümanlar

• $deviceId string - Opsiyonel, çalmak istediğiniz cihazın ID'si.
• $options array|object - Opsiyonel, ayarlar.
  • string context_uri Opsiyonel, çalınacak şeyin Spotify URI'ı (farkı parça değil albüm, podcast çalabiliyor)
  • array uris Opsiyonel, çalınacak parçaların Spotify URI'ı.
  • object offset Opsiyonel, çalma işleminin hangi kısımdan başlaması gerektiği.

Ne dönüyor?

• boolean İşlem başarılı mı?

queue - Çalma Sırasına Şarkı Eklemek

$api->queue($trackUri, $deviceId)

Çalma sırasına şarkı ekler.
https://developer.spotify.com/documentation/web-api/reference/player/add-to-queue/

Argümanlar

• $trackUri string - Zorunlu, çalacak parçanın Spotify URI'ı.
• $deviceId string - Opsiyonel, cihaz ID'si.

Ne dönüyor?

• boolean İşlem başarılı mı?

search - Arama Yapmak

$api->search($query, $type, $options)

Spotify kütüphanesinde arama yapmak için kullanıyoruz.
https://developer.spotify.com/documentation/web-api/reference/search/search/

Argümanlar

• $query string - Aranacak terim.
• $type string|array - Aranacak terimin türü. album, artist, playlist, track, show, episode kelimelerinden birini veya birden fazlasını seçebilirsiniz.
• $options array|object - Arama ayarları
  • string market Opsiyonel, hangi pazarlarda aransın. Ülke kodu ile seçilir.
  • int limit Opsiyonel, kaç sorgu dönsün?
  • int offset Opsiyonel, kaç item geçilsin?

Ne dönüyor?

• array|object Arama sonuçları, tipini return_assoc ile değiştirebilirsiniz.

next - Sıradaki Parçayı Çal

$api->next($deviceId)

Kullanıcının kuyruğundaki sıradaki parçayı çalar.
https://developer.spotify.com/documentation/web-api/reference/player/skip-users-playback-to-next-track/

Argümanlar

• $deviceId string - Opsiyonel, çalacak cihaz ID'si

Ne dönüyor?

• boolean İşlem başarılı mı?

pause - Şarkıyı Durdurmak

$api->pause($deviceId)

Çalma işlemini durdurur.
https://developer.spotify.com/documentation/web-api/reference/player/pause-a-users-playback/

Argümanlar

• $deviceId string - Opsiyonel, çalacak cihaz ID'si

Ne dönüyor?

• boolean İşlem başarılı mı?

getTrack - Şarkının Bilgilerini Çekmek

$api->getTrack($trackId)

ID'sine sahip olduğunuz şarkının bilgilerini almak.
https://developer.spotify.com/documentation/web-api/reference/tracks/get-track/

Argümanlar

• $trackId string - ID veya Spotify URI girebilirsiniz, zorunludur.

Ne dönüyor?

• array|object Şarkı bilgileri, türü return_assoc ile değiştirebilirsiniz.

getMyCurrentPlaybackInfo - Çalan Şarkıyı Hakkında Bilgi Almak

$api->getMyCurrentPlaybackInfo()

Kullanıcının o andaki oynatma bilgilerini almak.
https://developer.spotify.com/documentation/web-api/reference/player/get-information-about-the-users-current-playback/

Ne dönüyor?

• array|object Kullanıcının oynatma bilgisi, dönen veri tipini return_assoc ile değiştirebilirsiniz.

getMyPlaylists - Kullanıcının Çalma Listelerini Almak

$api->getMyPlaylists($options)

Kullanıcının çalma listelerini getirir.
https://developer.spotify.com/documentation/web-api/reference/playlists/get-a-list-of-current-users-playlists/

Argümanlar

• $options array|object - Opsiyonel, ayarlar.
  • int limit Opsiyonel, kaç tane getirilsin?
  • int offset Opsiyonel, kaç tanesi geçilsin?

Ne dönüyor?

• array|object Kullanıcının playlistleri, dönen veri tipini return_assoc ile değiştirebilirsiniz.

getMySavedTracks - Kullanıcının Beğendiği Şarkılar

$api->getMySavedTracks($options)

Kullanıcının beğendiği şarkıların listesi.
https://developer.spotify.com/documentation/web-api/reference/library/get-users-saved-tracks/

Argümanlar

• $options array|object - Opsiyonel, ayarlar.
  • int limit Opsiyonel, kaç tane getirilsin?
  • int offset Opsiyonel, kaç tanesi geçilsin?

Ne dönüyor?

• array|object Kullanıcının beğendiği şarkılar, dönen veri tipini return_assoc ile değiştirebilirsiniz.

getPlaylist - Playlist Hakkında Bilgi Getirmek

$api->getPlaylist($playlistId)

IDsi belirli olan 
https://developer.spotify.com/documentation/web-api/reference/playlists/get-playlist/

Argümanlar

• $playlistId string - Playlistin Spotify URI'ı.

Ne dönüyor?

• array|object Playlist hakkında bilgiler, dönen veri tipini return_assoc ile değiştirebilirsiniz.

getPlaylistTracks - Playlistten Şarkıları Çekmek

$api->getPlaylistTracks($playlistId, $options)

Playlistten şarkıları getirir.
https://developer.spotify.com/documentation/web-api/reference/playlists/get-playlists-tracks/

Argümanlar

• $playlistId string - Playlistin Spotify URI'ı.
• $options array|object - Opsiyonel, ayarlar.
  • int limit Opsiyonel, kaç tane getirilsin?
  • int offset Opsiyonel, kaç tanesi geçilsin?

Ne dönüyor?

• array|object Playlist hakkında bilgiler, dönen veri tipini return_assoc ile değiştirebilirsiniz.

Önemli olan tüm fonksiyonları çevirdiğimi düşünüyorum. Eksik kaldığını düşündüğünüz kısımlar varsa yorum kısmında belirtirseniz sevinirim. Anlamadığınız kısımlarda da sorularınıza yanıt vermeye çalışacağım. Okuduğunuz için teşekkür ederim. Umarım faydalı olmuştur.

Faydalı kaynaklar:
https://github.com/jwilsson/spotify-web-api-php/tree/master/docs/method-reference
https://github.com/jwilsson/spotify-web-api-php/tree/master/docs/examples