1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
|
# Spotify Random Song Picker
A PHP CLI utility that selects a random, unplayed track from a specified Spotify playlist. It handles OAuth2 authorization locally, stores access/refresh tokens, and keeps track of played history in a local JSON file so songs aren't repeated.
## Prerequisites
- **PHP 8.5+** with standard extensions (`curl`, `json`)
- **Composer** for dependency autoloading
- **Spotify Developer Account** (to obtain Client Credentials)
---
## Installation & Environment Setup
### Option A: Using Nix (Recommended)
If you use Nix, a `shell.nix` file is provided with PHP 8.5, Composer, and code quality tools pre-configured:
```bash
nix-shell
composer install
```
### Option B: Standard Installation
1. Clone or download the repository.
2. Install Composer dependencies to set up PSR-4 autoloading:
```bash
composer install
```
---
## Configuration
### 1. Register a Spotify Application
1. Go to the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard).
2. Create an app and set the **Redirect URI** to:
```
[http://127.0.0.1:8080/callback](http://127.0.0.1:8080/callback)
```
_(Ensure the IP and port match your `.env.php` config below)_
### 2. Create `.env.php`
Create a `.env.php` file in the root directory returning an array with your credentials and configuration:
A `.env.example.php` is provided.
```php
<?php
declare(strict_types=1);
return [
'clientID' => 'YOUR_SPOTIFY_CLIENT_ID',
'clientSecret' => 'YOUR_SPOTIFY_CLIENT_SECRET',
'redirectURI' => '[http://127.0.0.1:8080/callback](http://127.0.0.1:8080/callback)',
'state' => 'random_secure_string_here',
'serverAddress' => '127.0.0.1',
'serverPort' => 8080,
'serverTimeout' => 60,
'playlistName' => 'My Favorite Playlist',
];
```
---
## Usage
Run the entry point script from your terminal:
```bash
php pick-random-song.php
```
### Initial Authorization Flow
1. On the first run, the script starts a temporary local HTTP server and prints an authorization URL.
2. Open the URL in your browser and authorize access to your Spotify account.
3. Spotify redirects back to `http://127.0.0.1:8080/callback`, capturing the OAuth code and shutting down the local server automatically.
4. Tokens are saved locally to `.token_storage.json`. Subsequent executions refresh tokens automatically without requiring browser authorization.
### Output Example
```text
Picking a random song from the playlist My Favorite Playlist.
Looking up the Spotify playlist ID.
The song picked is Bring Tha Noize by Anthrax,Public Enemy
```
---
## How It Works
- **`HistoryStorage`**: Saves selected song IDs to `.history_storage.json` along with timestamps. Songs already in the history map are excluded from selection.
- **`SpotifyApiClient`**: Resolves the playlist ID by name via `/v1/me/playlists` and fetches track items using `/v1/playlists/{id}/items` with a reduced field response filter.
- **`TokenManager`**: Automatically handles initial authorization code flow, access token retrieval, and background refresh when tokens expire.
|
