@@ -6,11 +6,82 @@ The focus here is on keeping it small and simple.
66
77All data is JSON decoded with objects converted into associative arrays.
88
9+ ## License
10+
11+ AGPL-3.0-or-later. See [ LICENSE.md] ( LICENSE.md ) .
12+
13+ This library is an export of the Ampache Discogs plugin and carries Ampache's license. Releases
14+ before 0.3.0 declared ` MIT ` in ` composer.json ` ; that was a mistake in the metadata, not a different
15+ license — the AGPL text and the source headers were there from the initial commit.
16+
917## Requirements
1018
1119* PHP8.2+
1220* rmccue/requests
1321
22+ ## Paging
23+
24+ Discogs paginates the list endpoints. Every method that hits one takes a trailing ` int $page = 1 ` ,
25+ and the ` pagination ` block in the response says how many pages there are:
26+
27+ ``` php
28+ $page = $discogs->get_label_releases(1);
29+ $total = $page['pagination']['pages'];
30+
31+ for ($number = 1; $number <= $total; $number++) {
32+ $releases = $discogs->get_label_releases(1, $number)['releases'];
33+ // ...
34+ }
35+ ```
36+
37+ Paged: ` get_artist_releases ` , ` get_label_releases ` , ` get_master_versions ` ,
38+ ` get_collection_items_by_folder ` , ` get_user_lists ` , ` get_wantlist ` , ` search_album ` ,
39+ ` search_artist ` , ` search_master ` , ` search_release ` . Pass a page to ` search() ` in its parameter
40+ array. Anything returning a single record takes no page.
41+
42+ Each request is paced to about a second, so walking a long list is not instant.
43+
44+ ** ` get_artist_releases() ` repeats a few records across page boundaries** and returns 49 rows for a
45+ ` per_page ` of 50. That is Discogs, not this library: it happens on the raw endpoint under every
46+ ` sort ` option. Key on ` id ` when collecting pages from it:
47+
48+ ``` php
49+ $byId = [];
50+ for ($number = 1; $number <= $total; $number++) {
51+ foreach ($discogs->get_artist_releases($artistId, $number)['releases'] as $release) {
52+ $byId[$release['id']] = $release;
53+ }
54+ }
55+ ```
56+
57+ The other paged endpoints — label releases, master versions, wantlists and search — return
58+ non-overlapping pages.
59+
60+ ## Rate limiting and errors
61+
62+ Discogs allows 60 authenticated requests a minute. The client paces itself to that, widens the gap
63+ as ` X-Discogs-Ratelimit-Remaining ` runs down, and retries a ` 429 ` or a ` 5xx ` up to three times,
64+ honouring ` Retry-After ` . Nothing is required of the caller for that to happen.
65+
66+ Anything that still fails throws ` AmpacheDiscogs\DiscogsException ` , which extends ` Exception ` and
67+ carries the HTTP status so the cases can be told apart:
68+
69+ ``` php
70+ use AmpacheDiscogs\DiscogsException;
71+
72+ try {
73+ $album = $discogs->get_master(1234);
74+ } catch (DiscogsException $error) {
75+ if ($error->getStatusCode() === 404) {
76+ // no such record, nothing to retry
77+ } elseif ($error->isRateLimited()) {
78+ // still limited after three attempts, come back later
79+ }
80+
81+ print_r($error->getMessage());
82+ }
83+ ```
84+
1485## Usage Example
1586
1687``` php
@@ -29,10 +100,10 @@ $media = [
29100
30101echo "Checking: " . print_r($media, true) . PHP_EOL;
31102try {
32- // your own username and password are required to use the Discogs API
33- $username = 'username ';
34- $password = 'password ';
35- $discogs = new Discogs($username , $password );
103+ // your own Discogs api key and secret are required to use the Discogs API
104+ $api_key = 'yourApiKey ';
105+ $secret = 'yourApiSecret ';
106+ $discogs = new Discogs($api_key , $secret );
36107
37108 /**
38109 * https://api.discogs.com/database/search?type=master&release_title=The+Shape&artist=Code+64&per_page=10&key=key@secret=secret
@@ -118,3 +189,24 @@ try {
118189```
119190
120191Look in the [ /examples] ( https://github.com/ampache/php-discogs-api/tree/master/examples ) folder for more.
192+
193+ ## Testing
194+
195+ ``` shell
196+ composer qa # syntax, code style and the offline unit tests
197+ composer stan # static analysis
198+ composer tests:live # really calls Discogs, needs credentials
199+ ```
200+
201+ The unit suite never touches the network. The live suite is opt-in: copy ` .env.dist ` to ` .env ` and
202+ fill in a key and secret from < https://www.discogs.com/settings/developers > . Without them the live
203+ tests skip, so ` composer qa ` and CI stay green on a fresh checkout. ` .env ` is gitignored.
204+
205+ ``` ini
206+ DISCOGS_API_KEY =yourApiKey
207+ DISCOGS_API_SECRET =yourApiSecret
208+ DISCOGS_TEST_USERNAME =someUserWithAPublicCollection
209+ ```
210+
211+ ` DISCOGS_TEST_USERNAME ` is optional and only gates the user endpoint tests. Environment variables
212+ take precedence over the file, so CI can supply the same names as secrets.
0 commit comments