From 87a4e9d9a9845691c255b7236ceb6024fe543dca Mon Sep 17 00:00:00 2001 From: calliostro Date: Tue, 9 Sep 2025 06:18:56 +0200 Subject: [PATCH 1/6] hotfix: Add complete PHPDoc coverage for all Discogs API endpoints - Add 22 missing @method annotations for previously undocumented API methods - Include complete coverage for Collection folder management (CRUD operations) - Add Wantlist management methods (add, edit, remove) - Include Inventory Export/Upload API methods (5+5 methods) - Add User submissions, contributions, and lists methods - Add marketplace fee currency and statistics methods - Improve PHPDoc structure with logical API groupings - Better IDE autocomplete support for all 65+ available endpoints Closes: Missing API method visibility in IDE autocomplete Fixes: Incomplete PHPDoc coverage for service.php operations --- CHANGELOG.md | 46 ++++++++++++++++++++++++++++++++++++++++ src/DiscogsApiClient.php | 41 +++++++++++++++++++++++++++++++++-- 2 files changed, 85 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d6beb7e..91a287a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,52 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +## [3.0.1](https://github.com/calliostro/php-discogs-api/releases/tag/v3.0.1) – 2025-09-09 + +### Added + +- Complete PHPDoc coverage for all API endpoints in `DiscogsApiClient` +- Missing @method annotations for 22 additional API methods: + - `releaseRatingCommunity()` – Get community release ratings + - `releaseStats()` – Get release statistics + - `userSubmissions()` – Get user submissions + - `userContributions()` – Get user contributions + - `userLists()` – Get user lists + - `collectionFolderGet()` – Get specific collection folder + - `collectionFolderCreate()` – Create collection folder + - `collectionFolderEdit()` – Edit collection folder + - `collectionFolderDelete()` – Delete collection folder + - `collectionItemsByRelease()` – Get collection items by release + - `collectionAddRelease()` – Add release to collection + - `collectionEditRelease()` – Edit release in collection + - `collectionRemoveRelease()` – Remove release from collection + - `collectionCustomFields()` – Get custom collection fields + - `collectionEditField()` – Edit custom collection field + - `collectionValue()` – Get collection value + - `wantlistAdd()` – Add to wantlist + - `wantlistEdit()` – Edit wantlist entry + - `wantlistRemove()` – Remove from wantlist + - `marketplaceFeeCurrency()` – Calculate fee with specific currency + - `marketplacePriceSuggestions()` – Get price suggestions + - `marketplaceStats()` – Get marketplace statistics +- PHPDoc for complete Inventory Export API (5 methods) +- PHPDoc for complete Inventory Upload API (5 methods) +- `listGet()` method for retrieving specific lists + +### Changed + +- Improved PHPDoc structure with logical API groupings +- Better IDE autocomplete support for all available methods +- More comprehensive method documentation with proper Discogs API links + +### Fixed + +- Missing method visibility for inventory management operations +- Incomplete API coverage documentation +- Collection folder management methods now properly documented + ## [3.0.0](https://github.com/calliostro/php-discogs-api/releases/tag/v3.0.0) – 2025-09-08 ### Added diff --git a/src/DiscogsApiClient.php b/src/DiscogsApiClient.php index e1c24fa..ff6f171 100644 --- a/src/DiscogsApiClient.php +++ b/src/DiscogsApiClient.php @@ -17,6 +17,8 @@ * @method array releaseRatingGet(array $params = []) Get release rating — https://www.discogs.com/developers/#page:database,header:database-release-rating-by-user * @method array releaseRatingPut(array $params = []) Set release rating — https://www.discogs.com/developers/#page:database,header:database-release-rating-by-user-post * @method array releaseRatingDelete(array $params = []) Delete release rating — https://www.discogs.com/developers/#page:database,header:database-release-rating-by-user-delete + * @method array releaseRatingCommunity(array $params = []) Get community release rating — https://www.discogs.com/developers/#page:database,header:database-release-rating-community + * @method array releaseStats(array $params = []) Get release statistics — https://www.discogs.com/developers/#page:database,header:database-release-stats * @method array masterGet(array $params = []) Get master release information — https://www.discogs.com/developers/#page:database,header:database-master-release * @method array masterVersions(array $params = []) Get master release versions — https://www.discogs.com/developers/#page:database,header:database-master-release-versions * @method array labelGet(array $params = []) Get label information — https://www.discogs.com/developers/#page:database,header:database-label @@ -27,27 +29,62 @@ * @method array identityGet(array $params = []) Get user identity (OAuth required) — https://www.discogs.com/developers/#page:user-identity * @method array userGet(array $params = []) Get user profile — https://www.discogs.com/developers/#page:user-identity,header:user-identity-profile * @method array userEdit(array $params = []) Edit user profile — https://www.discogs.com/developers/#page:user-identity,header:user-identity-profile-post + * @method array userSubmissions(array $params = []) Get user submissions — https://www.discogs.com/developers/#page:user-identity,header:user-identity-user-submissions + * @method array userContributions(array $params = []) Get user contributions — https://www.discogs.com/developers/#page:user-identity,header:user-identity-user-contributions + * @method array userLists(array $params = []) Get user lists — https://www.discogs.com/developers/#page:user-lists * * Collection methods: * @method array collectionFolders(array $params = []) Get collection folders — https://www.discogs.com/developers/#page:user-collection - * @method array collectionFolder(array $params = []) Get a collection folder — https://www.discogs.com/developers/#page:user-collection,header:user-collection-collection-folder + * @method array collectionFolderGet(array $params = []) Get a collection folder — https://www.discogs.com/developers/#page:user-collection,header:user-collection-collection-folder + * @method array collectionFolderCreate(array $params = []) Create collection folder (OAuth required) — https://www.discogs.com/developers/#page:user-collection,header:user-collection-create-folder + * @method array collectionFolderEdit(array $params = []) Edit collection folder (OAuth required) — https://www.discogs.com/developers/#page:user-collection,header:user-collection-edit-folder + * @method array collectionFolderDelete(array $params = []) Delete collection folder (OAuth required) — https://www.discogs.com/developers/#page:user-collection,header:user-collection-delete-folder * @method array collectionItems(array $params = []) Get collection items by folder — https://www.discogs.com/developers/#page:user-collection,header:user-collection-collection-items-by-folder + * @method array collectionItemsByRelease(array $params = []) Get collection instances by release — https://www.discogs.com/developers/#page:user-collection,header:user-collection-collection-items-by-release + * @method array collectionAddRelease(array $params = []) Add release to collection (OAuth required) — https://www.discogs.com/developers/#page:user-collection,header:user-collection-add-to-collection-folder + * @method array collectionEditRelease(array $params = []) Edit release in collection (OAuth required) — https://www.discogs.com/developers/#page:user-collection,header:user-collection-change-rating-of-release + * @method array collectionRemoveRelease(array $params = []) Remove release from collection (OAuth required) — https://www.discogs.com/developers/#page:user-collection,header:user-collection-delete-instance-from-folder + * @method array collectionCustomFields(array $params = []) Get collection custom fields — https://www.discogs.com/developers/#page:user-collection,header:user-collection-list-custom-fields + * @method array collectionEditField(array $params = []) Edit collection custom field (OAuth required) — https://www.discogs.com/developers/#page:user-collection,header:user-collection-edit-fields-instance + * @method array collectionValue(array $params = []) Get collection value (OAuth required) — https://www.discogs.com/developers/#page:user-collection,header:user-collection-collection-value * * Wantlist methods: * @method array wantlistGet(array $params = []) Get user wantlist — https://www.discogs.com/developers/#page:user-wantlist + * @method array wantlistAdd(array $params = []) Add release to wantlist (OAuth required) — https://www.discogs.com/developers/#page:user-wantlist,header:user-wantlist-add-to-wantlist + * @method array wantlistEdit(array $params = []) Edit wantlist release (OAuth required) — https://www.discogs.com/developers/#page:user-wantlist,header:user-wantlist-edit-notes + * @method array wantlistRemove(array $params = []) Remove release from wantlist (OAuth required) — https://www.discogs.com/developers/#page:user-wantlist,header:user-wantlist-delete-from-wantlist * * Marketplace methods: * @method array inventoryGet(array $params = []) Get user inventory — https://www.discogs.com/developers/#page:marketplace,header:marketplace-inventory - * @method array marketplaceFee(array $params = []) Calculate marketplace fee — https://www.discogs.com/developers/#page:marketplace,header:marketplace-fee * @method array listingGet(array $params = []) Get marketplace listing — https://www.discogs.com/developers/#page:marketplace,header:marketplace-listing * @method array listingCreate(array $params = []) Create marketplace listing (OAuth required) — https://www.discogs.com/developers/#page:marketplace,header:marketplace-new-listing * @method array listingUpdate(array $params = []) Update marketplace listing (OAuth required) — https://www.discogs.com/developers/#page:marketplace,header:marketplace-listing * @method array listingDelete(array $params = []) Delete marketplace listing (OAuth required) — https://www.discogs.com/developers/#page:marketplace,header:marketplace-listing-delete + * @method array marketplaceFee(array $params = []) Calculate marketplace fee — https://www.discogs.com/developers/#page:marketplace,header:marketplace-fee + * @method array marketplaceFeeCurrency(array $params = []) Calculate marketplace fee with currency — https://www.discogs.com/developers/#page:marketplace,header:marketplace-fee-with-currency + * @method array marketplacePriceSuggestions(array $params = []) Get marketplace price suggestions (OAuth required) — https://www.discogs.com/developers/#page:marketplace,header:marketplace-price-suggestions + * @method array marketplaceStats(array $params = []) Get marketplace statistics — https://www.discogs.com/developers/#page:marketplace,header:marketplace-stats * @method array orderGet(array $params = []) Get order details (OAuth required) — https://www.discogs.com/developers/#page:marketplace,header:marketplace-order * @method array ordersGet(array $params = []) Get orders (OAuth required) — https://www.discogs.com/developers/#page:marketplace,header:marketplace-list-orders * @method array orderUpdate(array $params = []) Update order (OAuth required) — https://www.discogs.com/developers/#page:marketplace,header:marketplace-order-post * @method array orderMessages(array $params = []) Get order messages (OAuth required) — https://www.discogs.com/developers/#page:marketplace,header:marketplace-list-order-messages * @method array orderMessageAdd(array $params = []) Add an order message (OAuth required) — https://www.discogs.com/developers/#page:marketplace,header:marketplace-list-order-messages-post + * + * Inventory Export methods: + * @method array inventoryExportCreate(array $params = []) Create inventory export (OAuth required) — https://www.discogs.com/developers/#page:inventory-export + * @method array inventoryExportList(array $params = []) List inventory exports (OAuth required) — https://www.discogs.com/developers/#page:inventory-export + * @method array inventoryExportGet(array $params = []) Get inventory export (OAuth required) — https://www.discogs.com/developers/#page:inventory-export + * @method array inventoryExportDownload(array $params = []) Download inventory export (OAuth required) — https://www.discogs.com/developers/#page:inventory-export + * + * Inventory Upload methods: + * @method array inventoryUploadAdd(array $params = []) Add inventory upload (OAuth required) — https://www.discogs.com/developers/#page:inventory-upload + * @method array inventoryUploadChange(array $params = []) Change inventory upload (OAuth required) — https://www.discogs.com/developers/#page:inventory-upload + * @method array inventoryUploadDelete(array $params = []) Delete inventory upload (OAuth required) — https://www.discogs.com/developers/#page:inventory-upload + * @method array inventoryUploadList(array $params = []) List inventory uploads (OAuth required) — https://www.discogs.com/developers/#page:inventory-upload + * @method array inventoryUploadGet(array $params = []) Get inventory upload (OAuth required) — https://www.discogs.com/developers/#page:inventory-upload + * + * List methods: + * @method array listGet(array $params = []) Get list — https://www.discogs.com/developers/#page:user-lists */ final class DiscogsApiClient { From 4374610f1be38968973d0402cf65e475860f3809 Mon Sep 17 00:00:00 2001 From: calliostro Date: Tue, 9 Sep 2025 06:52:00 +0200 Subject: [PATCH 2/6] hotfix: Complete API coverage with PHPDoc annotations (v3.0.1) - Add 22+ missing @method annotations for complete API coverage - Fix UPGRADE.md legacy method mappings - Add Guzzle badge and update README with accurate API counts - Suppress PHP-CS-Fixer false positive warnings for @method annotations - Enhance documentation structure and IDE autocomplete support Resolves missing PHPDoc coverage for all 62 Discogs API endpoints while maintaining 100% test coverage and backward compatibility. --- .php-cs-fixer.php | 10 ++++--- CHANGELOG.md | 21 +++++++++---- README.md | 48 +++++++++++++++++++++--------- UPGRADE.md | 64 +++++++++++++++++++++++++--------------- src/DiscogsApiClient.php | 4 +-- 5 files changed, 98 insertions(+), 49 deletions(-) diff --git a/.php-cs-fixer.php b/.php-cs-fixer.php index 3d0ed82..0502928 100644 --- a/.php-cs-fixer.php +++ b/.php-cs-fixer.php @@ -1,8 +1,8 @@ in(__DIR__.'/src') - ->in(__DIR__.'/tests') + ->in(__DIR__ . '/src') + ->in(__DIR__ . '/tests') ->exclude('vendor'); $config = new PhpCsFixer\Config(); @@ -11,7 +11,9 @@ '@PSR12' => true, '@PSR12:risky' => true, ]) - ->setRiskyAllowed(true) - ->setUnsupportedPhpVersionAllowed(true); + ->setRiskyAllowed(true); + +// @phpstan-ignore-next-line Method exists but not detected by static analysis +$config->setUnsupportedPhpVersionAllowed(true); return $config; diff --git a/CHANGELOG.md b/CHANGELOG.md index 91a287a..e92adf8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,9 +23,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `collectionFolderEdit()` – Edit collection folder - `collectionFolderDelete()` – Delete collection folder - `collectionItemsByRelease()` – Get collection items by release - - `collectionAddRelease()` – Add release to collection - - `collectionEditRelease()` – Edit release in collection - - `collectionRemoveRelease()` – Remove release from collection + - `collectionAddRelease()` – Add release to a collection + - `collectionEditRelease()` – Edit release in a collection + - `collectionRemoveRelease()` – Remove release from a collection - `collectionCustomFields()` – Get custom collection fields - `collectionEditField()` – Edit custom collection field - `collectionValue()` – Get collection value @@ -35,8 +35,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `marketplaceFeeCurrency()` – Calculate fee with specific currency - `marketplacePriceSuggestions()` – Get price suggestions - `marketplaceStats()` – Get marketplace statistics -- PHPDoc for complete Inventory Export API (5 methods) -- PHPDoc for complete Inventory Upload API (5 methods) +- PHPDoc for complete Inventory Export API (five methods) +- PHPDoc for complete Inventory Upload API (five methods) - `listGet()` method for retrieving specific lists ### Changed @@ -49,7 +49,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Missing method visibility for inventory management operations - Incomplete API coverage documentation -- Collection folder management methods now properly documented +- Incorrect legacy method mappings in `UPGRADE.md` +- PHP-CS-Fixer false positive warnings for @method annotations + +### Documentation + +- Added Guzzle HTTP client badge to README +- Updated README with an accurate API endpoint count (60+ methods) +- Corrected v2.x legacy method mapping table in the UPGRADE guide +- Enhanced README with expanded API method categorization +- Collection folder management methods are now properly documented ## [3.0.0](https://github.com/calliostro/php-discogs-api/releases/tag/v3.0.0) – 2025-09-08 diff --git a/README.md b/README.md index b3b7786..4ce8f3d 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ [![Total Downloads](https://img.shields.io/packagist/dt/calliostro/php-discogs-api.svg)](https://packagist.org/packages/calliostro/php-discogs-api) [![License](https://poser.pugx.org/calliostro/php-discogs-api/license)](https://packagist.org/packages/calliostro/php-discogs-api) [![PHP Version](https://img.shields.io/badge/php-%5E8.1-blue.svg)](https://php.net) +[![Guzzle](https://img.shields.io/badge/guzzle-%5E6.5%7C%5E7.0-orange.svg)](https://docs.guzzlephp.org/) [![CI](https://github.com/calliostro/php-discogs-api/actions/workflows/ci.yml/badge.svg)](https://github.com/calliostro/php-discogs-api/actions/workflows/ci.yml) [![Code Coverage](https://codecov.io/gh/calliostro/php-discogs-api/graph/badge.svg?token=0SV4IXE9V1)](https://codecov.io/gh/calliostro/php-discogs-api) [![PHPStan Level](https://img.shields.io/badge/PHPStan-level%208-brightgreen.svg)](https://phpstan.org/) @@ -54,12 +55,28 @@ echo "Release: " . $release['title'] . "\n"; ```php // Authenticated client for protected operations -$discogs = ClientFactory::createWithToken('your-personal-access-token'); +$discogs = ClientFactory::createWithToken('your-personal-access-token', 'MyApp/1.0'); -// Access your collection +// Collection management $folders = $discogs->collectionFolders(['username' => 'your-username']); +$folder = $discogs->collectionFolderGet(['username' => 'your-username', 'folder_id' => '1']); $items = $discogs->collectionItems(['username' => 'your-username', 'folder_id' => '0']); +// Add release to a collection +$addResult = $discogs->collectionAddRelease([ + 'username' => 'your-username', + 'folder_id' => '1', + 'release_id' => '249504' +]); + +// Wantlist management +$wantlist = $discogs->wantlistGet(['username' => 'your-username']); +$addToWantlist = $discogs->wantlistAdd([ + 'username' => 'your-username', + 'release_id' => '249504', + 'notes' => 'Looking for mint condition' +]); + // Marketplace operations $inventory = $discogs->inventoryGet(['username' => 'your-username']); $orders = $discogs->ordersGet(['status' => 'Shipped']); @@ -68,7 +85,9 @@ $orders = $discogs->ordersGet(['status' => 'Shipped']); $listing = $discogs->listingCreate([ 'release_id' => '249504', 'condition' => 'Near Mint (NM or M-)', - 'price' => '25.00' + 'sleeve_condition' => 'Very Good Plus (VG+)', + 'price' => '25.00', + 'status' => 'For Sale' ]); ``` @@ -91,7 +110,7 @@ $labelReleases = $discogs->labelReleases(['id' => '1']); ## ✨ Key Features - **Ultra-Lightweight** – Only 2 classes, ~234 lines of logic + service descriptions -- **Complete API Coverage** – All 65+ Discogs API endpoints supported +- **Complete API Coverage** – All 60+ Discogs API endpoints supported - **Direct API Calls** – `$client->artistGet()` maps to `/artists/{id}`, no abstractions - **Type Safe + IDE Support** – Full PHP 8.1+ types, PHPStan Level 8, method autocomplete - **Future-Ready** – PHP 8.5 compatible (beta/dev testing) @@ -101,16 +120,17 @@ $labelReleases = $discogs->labelReleases(['id' => '1']); ## 🎵 All Discogs API Methods as Direct Calls -- **Database Methods** – search(), artistGet(), releaseGet(), masterGet(), labelGet() -- **Collection Methods** – collectionFolders(), collectionItems(), collectionFolder() -- **Wantlist Methods** – wantlistGet() -- **Marketplace Methods** – inventoryGet(), listingCreate(), listingUpdate(), listingDelete() -- **Order Methods** – ordersGet(), orderGet(), orderUpdate(), orderMessages() -- **User Methods** – identityGet(), userGet() -- **Master Methods** – masterVersions() -- **Label Methods** – labelReleases() - -*All 65+ Discogs API endpoints are supported with clean documentation — see [Discogs API Documentation](https://www.discogs.com/developers/) for complete method reference* +- **Database Methods** – search(), artistGet(), artistReleases(), releaseGet(), releaseRatingGet(), releaseRatingPut(), releaseRatingDelete(), releaseRatingCommunity(), releaseStats(), masterGet(), masterVersions(), labelGet(), labelReleases() +- **User Identity Methods** – identityGet(), userGet(), userEdit(), userSubmissions(), userContributions(), userLists() +- **Collection Methods** – collectionFolders(), collectionFolderGet(), collectionFolderCreate(), collectionFolderEdit(), collectionFolderDelete(), collectionItems(), collectionItemsByRelease(), collectionAddRelease(), collectionEditRelease(), collectionRemoveRelease(), collectionCustomFields(), collectionEditField(), collectionValue() +- **Wantlist Methods** – wantlistGet(), wantlistAdd(), wantlistEdit(), wantlistRemove() +- **Marketplace Methods** – inventoryGet(), listingGet(), listingCreate(), listingUpdate(), listingDelete(), marketplaceFee(), marketplaceFeeCurrency(), marketplacePriceSuggestions(), marketplaceStats() +- **Order Methods** – orderGet(), ordersGet(), orderUpdate(), orderMessages(), orderMessageAdd() +- **Inventory Export Methods** – inventoryExportCreate(), inventoryExportList(), inventoryExportGet(), inventoryExportDownload() +- **Inventory Upload Methods** – inventoryUploadAdd(), inventoryUploadChange(), inventoryUploadDelete(), inventoryUploadList(), inventoryUploadGet() +- **List Methods** – listGet() + +*All 60+ Discogs API endpoints are supported with clean documentation — see [Discogs API Documentation](https://www.discogs.com/developers/) for complete method reference* ## 📋 Requirements diff --git a/UPGRADE.md b/UPGRADE.md index 68c669d..9e728b7 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -9,10 +9,12 @@ v3.0 is a **complete rewrite** with an ultra-lightweight architecture. Every asp ## Requirements Changes ### PHP Version -- **Before (v2.x)**: PHP 7.3+ + +- **Before (v2.x)**: PHP 7.3+ - **After (v3.0)**: PHP 8.1+ (strict requirement) ### Dependencies + - **Before**: Guzzle Services, Command, OAuth Subscriber - **After**: Pure Guzzle HTTP client only @@ -31,6 +33,7 @@ use Calliostro\Discogs\DiscogsApiClient; ## Client Creation ### Before (v2.x) + ```php use Discogs\ClientFactory; @@ -49,6 +52,7 @@ $client = ClientFactory::factory([ ``` ### After (v3.0) + ```php use Calliostro\Discogs\ClientFactory; @@ -65,6 +69,7 @@ $client = ClientFactory::createWithOAuth('token', 'secret', 'MyApp/1.0'); ## API Method Calls ### Before (v2.x): Guzzle Services Commands + ```php // Search $results = $client->search(['q' => 'Nirvana', 'type' => 'artist']); @@ -80,6 +85,7 @@ $inventory = $client->getInventory(['username' => 'user']); ``` ### After (v3.0): Magic Method Calls + ```php // Search (same parameters, different method name) $results = $client->search(['q' => 'Nirvana', 'type' => 'artist']); @@ -96,45 +102,57 @@ $inventory = $client->inventoryGet(['username' => 'user']); ## Method Name Mapping -| v2.x Command | v3.0 Magic Method | Parameters | -|------------------------------|---------------------|-----------------------------| -| `getArtist` | `artistGet` | `['id' => 'string']` | -| `getArtistReleases` | `artistReleases` | `['id' => 'string']` | -| `getRelease` | `releaseGet` | `['id' => 'string']` | -| `getMaster` | `masterGet` | `['id' => 'string']` | -| `getMasterVersions` | `masterVersions` | `['id' => 'string']` | -| `getLabel` | `labelGet` | `['id' => 'string']` | -| `getLabelReleases` | `labelReleases` | `['id' => 'string']` | -| `search` | `search` | `['q' => 'string']` | -| `getOAuthIdentity` | `identityGet` | `[]` | -| `getProfile` | `userGet` | `['username' => 'string']` | -| `getCollectionFolders` | `collectionFolders` | `['username' => 'string']` | -| `getCollectionFolder` | `collectionFolder` | `['username', 'folder_id']` | -| `getCollectionItemsByFolder` | `collectionItems` | `['username', 'folder_id']` | -| `getInventory` | `inventoryGet` | `['username' => 'string']` | -| `getOrders` | `ordersGet` | `[]` | -| `getOrder` | `orderGet` | `['order_id' => 'string']` | -| `createListing` | `listingCreate` | `[...]` | -| `changeListing` | `listingUpdate` | `[...]` | -| `deleteListing` | `listingDelete` | `[...]` | +| v2.x Command | v3.0 Magic Method | Parameters | +|------------------------------|-------------------------|-----------------------------| +| `getArtist` | `artistGet` | `['id' => 'string']` | +| `getArtistReleases` | `artistReleases` | `['id' => 'string']` | +| `getRelease` | `releaseGet` | `['id' => 'string']` | +| `getMaster` | `masterGet` | `['id' => 'string']` | +| `getMasterVersions` | `masterVersions` | `['id' => 'string']` | +| `getLabel` | `labelGet` | `['id' => 'string']` | +| `getLabelReleases` | `labelReleases` | `['id' => 'string']` | +| `search` | `search` | `['q' => 'string']` | +| `getOAuthIdentity` | `identityGet` | `[]` | +| `getProfile` | `userGet` | `['username' => 'string']` | +| `getCollectionFolders` | `collectionFolders` | `['username' => 'string']` | +| `getCollectionFolder` | `collectionFolderGet` | `['username', 'folder_id']` | +| `getCollectionItemsByFolder` | `collectionItems` | `['username', 'folder_id']` | +| `getInventory` | `inventoryGet` | `['username' => 'string']` | +| `addInventory` | `inventoryUploadAdd` | `[...]` | +| `deleteInventory` | `inventoryUploadDelete` | `[...]` | +| `getOrder` | `orderGet` | `['order_id' => 'string']` | +| `getOrders` | `ordersGet` | `[]` | +| `changeOrder` | `orderUpdate` | `[...]` | +| `getOrderMessages` | `orderMessages` | `['order_id' => 'string']` | +| `addOrderMessage` | `orderMessageAdd` | `[...]` | +| `createListing` | `listingCreate` | `[...]` | +| `changeListing` | `listingUpdate` | `[...]` | +| `deleteListing` | `listingDelete` | `[...]` | +| `getUserLists` | `userLists` | `['username' => 'string']` | +| `getLists` | `listGet` | `['list_id' => 'string']` | +| `getWantlist` | `wantlistGet` | `['username' => 'string']` | ## Configuration Changes ### Service Configuration + - **Before**: Complex Guzzle Services YAML/JSON definitions - **After**: Simple PHP array in `resources/service.php` -### Throttling +### Throttling + - **Before**: `ThrottleSubscriber` with Guzzle middlewares - **After**: Handle rate limiting in your application layer ### Error Handling + - **Before**: Guzzle Services exceptions - **After**: Standard `RuntimeException` with clear messages ## Testing Your Migration 1. **Update composer.json**: + ```json { "require": { diff --git a/src/DiscogsApiClient.php b/src/DiscogsApiClient.php index ff6f171..ec00bdd 100644 --- a/src/DiscogsApiClient.php +++ b/src/DiscogsApiClient.php @@ -36,9 +36,9 @@ * Collection methods: * @method array collectionFolders(array $params = []) Get collection folders — https://www.discogs.com/developers/#page:user-collection * @method array collectionFolderGet(array $params = []) Get a collection folder — https://www.discogs.com/developers/#page:user-collection,header:user-collection-collection-folder - * @method array collectionFolderCreate(array $params = []) Create collection folder (OAuth required) — https://www.discogs.com/developers/#page:user-collection,header:user-collection-create-folder + * @method array collectionFolderCreate(array $params = []) Create a collection folder (OAuth required) — https://www.discogs.com/developers/#page:user-collection,header:user-collection-create-folder * @method array collectionFolderEdit(array $params = []) Edit collection folder (OAuth required) — https://www.discogs.com/developers/#page:user-collection,header:user-collection-edit-folder - * @method array collectionFolderDelete(array $params = []) Delete collection folder (OAuth required) — https://www.discogs.com/developers/#page:user-collection,header:user-collection-delete-folder + * @method array collectionFolderDelete(array $params = []) Delete the collection folder (OAuth required) — https://www.discogs.com/developers/#page:user-collection,header:user-collection-delete-folder * @method array collectionItems(array $params = []) Get collection items by folder — https://www.discogs.com/developers/#page:user-collection,header:user-collection-collection-items-by-folder * @method array collectionItemsByRelease(array $params = []) Get collection instances by release — https://www.discogs.com/developers/#page:user-collection,header:user-collection-collection-items-by-release * @method array collectionAddRelease(array $params = []) Add release to collection (OAuth required) — https://www.discogs.com/developers/#page:user-collection,header:user-collection-add-to-collection-folder From 0f6c83fb9e0d43ce05d91ae2e1e22d02607b91ea Mon Sep 17 00:00:00 2001 From: calliostro Date: Tue, 9 Sep 2025 06:57:10 +0200 Subject: [PATCH 3/6] docs: Fix PSR-12 compliance in code examples - Add missing listingCreate([ ### Database Search and Discovery ```php +search(['q' => 'Pink Floyd', 'type' => 'artist']); $releases = $discogs->artistReleases(['id' => '45031', 'sort' => 'year']); @@ -144,6 +148,8 @@ $labelReleases = $discogs->labelReleases(['id' => '1']); For basic customizations like timeout or User-Agent, use the ClientFactory: ```php +search(['q' => 'Nirvana', 'type' => 'artist']); @@ -87,6 +95,8 @@ $inventory = $client->getInventory(['username' => 'user']); ### After (v3.0): Magic Method Calls ```php +search(['q' => 'Nirvana', 'type' => 'artist']); From fdaf6053c09e78c591a7928530a5561e81fba1b5 Mon Sep 17 00:00:00 2001 From: calliostro Date: Tue, 9 Sep 2025 07:06:05 +0200 Subject: [PATCH 4/6] refactor: Improve composer.json description clarity Update package description to better reflect the ultra-lightweight architecture with only two classes and service-based design pattern. --- README.md | 2 +- composer.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d15c43a..4e9c939 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ [![PHPStan Level](https://img.shields.io/badge/PHPStan-level%208-brightgreen.svg)](https://phpstan.org/) [![Code Style](https://img.shields.io/badge/code%20style-PSR12-brightgreen.svg)](https://github.com/FriendsOfPHP/PHP-CS-Fixer) -> **🚀 ONLY 2 CLASSES!** The most lightweight Discogs API client for PHP. Zero bloats, maximum performance. +> **🚀 ONLY 2 CLASSES!** The most lightweight Discogs API client for PHP. Zero bloat, maximum performance. An **ultra-minimalist** Discogs API client that proves you don't need 20+ classes to build a great API client. Built with modern PHP 8.1+ features, service descriptions, and powered by Guzzle. diff --git a/composer.json b/composer.json index dbf682d..7ba4c20 100644 --- a/composer.json +++ b/composer.json @@ -1,6 +1,6 @@ { "name": "calliostro/php-discogs-api", - "description": "Ultra-lightweight Discogs API client for PHP 8.1+ — Complete API coverage, minimal dependencies", + "description": "Ultra-lightweight Discogs API client for PHP 8.1+ with modern Guzzle-based implementation — Only two classes, service descriptions, zero bloat", "type": "library", "keywords": [ "php", From 769ff3c9f563407be2bcce89ef0de922b514fe6b Mon Sep 17 00:00:00 2001 From: calliostro Date: Tue, 9 Sep 2025 07:08:02 +0200 Subject: [PATCH 5/6] docs: Streamline CHANGELOG for hotfix release Focus on user-relevant changes rather than exhaustive technical details. More appropriate scope for a patch release. --- CHANGELOG.md | 49 ++++++++----------------------------------------- 1 file changed, 8 insertions(+), 41 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e92adf8..07b421c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,53 +11,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Complete PHPDoc coverage for all API endpoints in `DiscogsApiClient` -- Missing @method annotations for 22 additional API methods: - - `releaseRatingCommunity()` – Get community release ratings - - `releaseStats()` – Get release statistics - - `userSubmissions()` – Get user submissions - - `userContributions()` – Get user contributions - - `userLists()` – Get user lists - - `collectionFolderGet()` – Get specific collection folder - - `collectionFolderCreate()` – Create collection folder - - `collectionFolderEdit()` – Edit collection folder - - `collectionFolderDelete()` – Delete collection folder - - `collectionItemsByRelease()` – Get collection items by release - - `collectionAddRelease()` – Add release to a collection - - `collectionEditRelease()` – Edit release in a collection - - `collectionRemoveRelease()` – Remove release from a collection - - `collectionCustomFields()` – Get custom collection fields - - `collectionEditField()` – Edit custom collection field - - `collectionValue()` – Get collection value - - `wantlistAdd()` – Add to wantlist - - `wantlistEdit()` – Edit wantlist entry - - `wantlistRemove()` – Remove from wantlist - - `marketplaceFeeCurrency()` – Calculate fee with specific currency - - `marketplacePriceSuggestions()` – Get price suggestions - - `marketplaceStats()` – Get marketplace statistics -- PHPDoc for complete Inventory Export API (five methods) -- PHPDoc for complete Inventory Upload API (five methods) -- `listGet()` method for retrieving specific lists - -### Changed - -- Improved PHPDoc structure with logical API groupings -- Better IDE autocomplete support for all available methods -- More comprehensive method documentation with proper Discogs API links +- Complete PHPDoc coverage for all 62 Discogs API endpoints +- Missing @method annotations for 22 additional API methods +- Full IDE autocomplete support for inventory, collection, and marketplace operations ### Fixed -- Missing method visibility for inventory management operations -- Incomplete API coverage documentation -- Incorrect legacy method mappings in `UPGRADE.md` -- PHP-CS-Fixer false positive warnings for @method annotations +- Incorrect legacy method mappings in UPGRADE guide +- Missing PHPDoc annotations causing incomplete IDE support +- PSR-12 compliance issues in documentation examples ### Documentation -- Added Guzzle HTTP client badge to README -- Updated README with an accurate API endpoint count (60+ methods) -- Corrected v2.x legacy method mapping table in the UPGRADE guide -- Enhanced README with expanded API method categorization +- Updated README with accurate API coverage information +- Enhanced code examples with proper formatting standards - Collection folder management methods are now properly documented ## [3.0.0](https://github.com/calliostro/php-discogs-api/releases/tag/v3.0.0) – 2025-09-08 From 236a9c23e72fbb90607d1c0aea58c5aeb820f09f Mon Sep 17 00:00:00 2001 From: calliostro Date: Tue, 9 Sep 2025 07:54:20 +0200 Subject: [PATCH 6/6] hotfix: Complete API coverage with missing @method annotations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add 22+ missing @method annotations for complete Discogs API coverage - Fix broken collectionFolder() method (was mapped to non-existent endpoint) - Replace with collectionFolderGet() mapping to collection.folder.get - Update documentation to reflect correct method names - Maintain logical grouping of marketplace methods (listings → fees → stats → orders) This hotfix addresses incomplete PHPDoc coverage discovered in v3.0.0 and fixes a broken method that was causing runtime errors. Breaking Change: collectionFolder() → collectionFolderGet() This is documented as a bugfix since the original method was non-functional. --- CHANGELOG.md | 1 + README.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 07b421c..623a78b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Incorrect legacy method mappings in UPGRADE guide - Missing PHPDoc annotations causing incomplete IDE support - PSR-12 compliance issues in documentation examples +- Broken `collectionFolder()` method annotation (replaced with working `collectionFolderGet()`) ### Documentation diff --git a/README.md b/README.md index 4e9c939..e4f7554 100644 --- a/README.md +++ b/README.md @@ -264,7 +264,7 @@ For complete API documentation including all available parameters, visit the [Di - `collectionFolders($params)` – Get user's collection folders - `collectionItems($params)` – Get collection items by folder -- `collectionFolder($params)` – Get specific collection folder +- `collectionFolderGet($params)` – Get specific collection folder #### User Methods