Complete API coverage with PHPDoc annotations (v3.0.1) (#2)

calliostro · web-flow · commit 87b0d9b39fa7 · 2025-09-09T07:56:58.000+02:00
Add missing @method annotations for 22 API endpoints providing complete IDE autocomplete support. Fix documentation inconsistencies and ensure PSR-12 compliance in code examples. Maintains backward compatibility and 100% test coverage while improving developer experience.
diff --git a/.php-cs-fixer.php b/.php-cs-fixer.php
@@ -1,8 +1,8 @@
 <?php
 
 $finder = PhpCsFixer\Finder::create()
-    ->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
@@ -5,6 +5,29 @@ 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 62 Discogs API endpoints
+- Missing @method annotations for 22 additional API methods
+- Full IDE autocomplete support for inventory, collection, and marketplace operations
+
+### Fixed
+
+- 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
+
+- 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
 
 ### Added
diff --git a/README.md b/README.md
@@ -4,12 +4,13 @@
 [![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/)
 [![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.
 
@@ -53,13 +54,31 @@ echo "Release: " . $release['title'] . "\n";
 ### Collection and Marketplace
 
 ```php
+<?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,13 +87,17 @@ $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'
 ]);
 ```
 
 ### Database Search and Discovery
 
 ```php
+<?php
+
 // Search the Discogs database
 $results = $discogs->search(['q' => 'Pink Floyd', 'type' => 'artist']);
 $releases = $discogs->artistReleases(['id' => '45031', 'sort' => 'year']);
@@ -91,7 +114,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 +124,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()
+- **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 65+ Discogs API endpoints are supported with clean documentation — see [Discogs API Documentation](https://www.discogs.com/developers/) for complete method reference*
+*All 60+ Discogs API endpoints are supported with clean documentation — see [Discogs API Documentation](https://www.discogs.com/developers/) for complete method reference*
 
 ## 📋 Requirements
 
@@ -124,6 +148,8 @@ $labelReleases = $discogs->labelReleases(['id' => '1']);
 For basic customizations like timeout or User-Agent, use the ClientFactory:
 
 ```php
+<?php
+
 use Calliostro\Discogs\ClientFactory;
 
 $discogs = ClientFactory::create('MyApp/1.0 (+https://myapp.com)', [
@@ -139,6 +165,8 @@ $discogs = ClientFactory::create('MyApp/1.0 (+https://myapp.com)', [
 For advanced HTTP client features (middleware, interceptors, etc.), create your own Guzzle client:
 
 ```php
+<?php
+
 use GuzzleHttp\Client;
 use Calliostro\Discogs\DiscogsApiClient;
 
@@ -236,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
 
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -9,16 +9,20 @@ 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
 
 ## Namespace Changes
 
 ```php
+<?php
+
 // OLD (v2.x)
 use Discogs\ClientFactory;
 use Discogs\DiscogsClient;
@@ -31,7 +35,10 @@ use Calliostro\Discogs\DiscogsApiClient;
 ## Client Creation
 
 ### Before (v2.x)
+
 ```php
+<?php
+
 use Discogs\ClientFactory;
 
 // Basic client
@@ -49,7 +56,10 @@ $client = ClientFactory::factory([
 ```
 
 ### After (v3.0)
+
 ```php
+<?php
+
 use Calliostro\Discogs\ClientFactory;
 
 // Anonymous client
@@ -65,7 +75,10 @@ $client = ClientFactory::createWithOAuth('token', 'secret', 'MyApp/1.0');
 ## API Method Calls
 
 ### Before (v2.x): Guzzle Services Commands
+
 ```php
+<?php
+
 // Search
 $results = $client->search(['q' => 'Nirvana', 'type' => 'artist']);
 
@@ -80,7 +93,10 @@ $inventory = $client->getInventory(['username' => 'user']);
 ```
 
 ### After (v3.0): Magic Method Calls
+
 ```php
+<?php
+
 // Search (same parameters, different method name)
 $results = $client->search(['q' => 'Nirvana', 'type' => 'artist']);
 
@@ -96,45 +112,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/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",
diff --git a/src/DiscogsApiClient.php b/src/DiscogsApiClient.php

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "calliostro/php-discogs-api",`
`3`		`- "description": "Ultra-lightweight Discogs API client for PHP 8.1+ — Complete API coverage, minimal dependencies",`
	`3`	`+ "description": "Ultra-lightweight Discogs API client for PHP 8.1+ with modern Guzzle-based implementation — Only two classes, service descriptions, zero bloat",`
`4`	`4`	`"type": "library",`
`5`	`5`	`"keywords": [`
`6`	`6`	`"php",`