orin

Discogs PHP Client

Project maintained by xyrotech Hosted on GitHub Pages — Theme by mattgraham

Orin

API

API CLIENT

Endpoint Todo List


Getting Started

Install via Composer

composer require xyrotech/orin

Copy test config file.

cp vendor/xyrotech/orin/config/orin.php myconfig.php

If using laravel use the publish command to import the config file

php artisan vendor:publish --provider="Xyrotech\OrinServiceProvider" --tag="orin-config"

Note: While technically this isn’t require, there’s no guarentee your API call will work at all


Start using the library! See example below

use Xyrotech\Orin;

$config = include('myconfig.php');
$discog = new Orin($config);

$artist = $discogs->artist(45);
echo $artist->name; // 'Aphex Twin'


Tips

Rate Limits

Attached along to each response are your rate limits according to Discogs rolling 60 second rate limit. To access these limits use the following

use Xyrotech\Orin;

$config = include('myconfig.php');
$discog = new Orin($config);

$artist = $discogs->artist(45);

$artist->rates['used']; // 1
$artist->rates['remaining']; // 59
$artist->rates['limit']; // 60


Configuration

DISCOGS_USER_AGENT

Your application must provide a User-Agent string that identifies itself – preferably something that follows RFC 1945. Some good examples below

AwesomeDiscogsBrowser/0.1 +http://adb.example.com
LibraryMetadataEnhancer/0.3 +http://example.com/lime
MyDiscogsClient/1.0 +http://mydiscogsclient.org

Note: Please don’t just copy one of those! Make it unique so discogs can let you know if your application starts to misbehave – the alternative is that discogs just silently blocks it.


DISCOGS_TOKEN

You’ll need a token otherwise you’ll be rate limited to 25 request per minute. Find your token here: https://www.discogs.com/settings/developers after you’ve create an app.


DISCOGS_CONSUMER_KEY

After you have created an application navigate to this link: https://www.discogs.com/settings/developers and click on the settings button next to you app to reveal the key and secret


DISCOGS_CONSUMER_SECRET

After you have created an application navigate to this link: https://www.discogs.com/settings/developers and click on the settings button next to you app to reveal the key and secret


DISCOGS_VERSION

Default: v2

Currently, Discogs API only supports one version: v2. However, you can specify a version in your requests to future-proof your application. By adding an Accept header with the version and media type, you can guarantee your requests will receive data from the correct version you develop your app on.


DISCOGS_MEDIA_TYPE

Default: discogs

If you are requesting information from an endpoint that may have text formatting in it, you can choose which kind of formatting you want to be returned by changing that section of the Accept header. Discogs currently support 3 types: html, plaintext, discogs.


RATE_THRESHOLD

Default: 2, Testing: 6

Mostly used for testing purposes. This threshold leaves X amount of buffer on your used rate limit.


OAUTH_CALLBACK

After the user verifies their account via OAuth they will be sent to this webpage so that your application can store OAuth credentials.


Supported API Endpoints


Database

Release

:mag: More Info

Get a Release

$discog->release(int $release_id, string $curr_abbr = null);


Release Rating by User

:mag: More Info

Retrieves the release’s rating for a given user.

$discog->release_rating_by_user(int $release_id, string $username);

Edit the release’s rating for a given user. :closed_lock_with_key: Auth Required

$discog->update_release_rating_by_user(int $release_id, string $username, int $rating);

Delete the release’s rating for a given user. :closed_lock_with_key: Auth Required

$discog->delete_release_rating_by_user(int $release_id, string $username);


Community Release Rating

:mag: More Info

Retrieves the community release rating average and count.

$discog->community_release_rating(int $release_id);


Release Stats

:mag: More Info

Retrieves the release’s “have” and “want” counts.

$discog->release_stats(int $release_id);


Master Release

:mag: More Info

Get a master release

$discog->master_release(int $master_id);


Master Release Versions

:mag: More Info

Retrieves a list of all Releases that are versions of this master.

$master = $discog->master_release_versions(int $master_id, array $parameters = null);

foreach($master->releases as $release)
{
    echo $release->name;
}


Artist

:mag: More Info

Get an artist

$discog->artist(int $artist_id);


Artist Releases

:mag: More Info

Get an artist’s releases

$artist = $discog->artist_releases(int $artist_id, array $parameters = null);

foreach($artist->releases as $release)
{
    echo $release->name;
}


Label

:mag: More Info

Get a label

$discog->label(int $label_id);


All Label Releases

:mag: More Info

Returns a list of Releases associated with the label.

$discog->all_label_releases(int $label_id, array $parameters = null);


Search

:mag: More Info

Issue a search query to discog’s database. :closed_lock_with_key: Auth Required

$search = $discog->search(string $query, array $parameters = null);

foreach($search->results as $result)
{
    var_dump($result);
}


Marketplace

Inventory

:mag: More Info

Get a seller’s inventory

$user = $discog->inventory(int $username, array $parameters = null);

foreach($user->listings as $listing)
{
    var_dump($listing);
}


Listing

:mag: More Info

The Listing resource allows you to view Marketplace listings.

$listing = $discog->listing(int $listing_id, string $curr_abbr = null);

Edit the data associated with a listing. :closed_lock_with_key: Auth Required

$parameters = [
    'release_id' => 16457562,
    'condition' => 'Poor (P)',
    'price' => 89.00,
    'status' => 'For Sale'
];
        
$discog->edit_listing(int $listing_id, array $parameters);

Permanently remove a listing from the Marketplace. :closed_lock_with_key: Auth Required

$discog->delete_listing(int $listing_id);


New Listing

:mag: More Info

Create a Marketplace listing. :closed_lock_with_key: Auth Required

$parameters = [
    'release_id' => 16457562,
    'condition' => 'Fair (F)',
    'price' => 99.00,
];
        
$discog->new_listing(array $parameters);


Order

:mag: More Info

View the data associated with an order. :closed_lock_with_key: Auth Required

$discog->order(int $order_id);

Edit the data associated with an order. :closed_lock_with_key: Auth Required

$discog->edit_order(int $order_id, array $parameters = null);


List Orders

:mag: More Info

Returns a list of the authenticated user’s orders. :closed_lock_with_key: Auth Required

$user = $discog->list_orders();

foreach($user->orders as $order)
{
    var_dump($order);
}


List Order Messages

:mag: More Info

Returns a list of the order’s messages with the most recent first. :closed_lock_with_key: Auth Required

$order = $discog->list_order_messages();

foreach($order->messages as $message)
{
    var_dump($message);
}

Adds a new message to the order’s message log. :closed_lock_with_key: Auth Required

$discog->new_order_message(int $order_id, string $message = null, string $status = null);


Fee

:mag: More Info

The Fee resource allows you to quickly calculate the fee for selling an item on the Marketplace.

$discog->fee(float $price);


Fee with Currency

:mag: More Info

The Fee resource allows you to quickly calculate the fee for selling an item on the Marketplace given a particular currency.

$discog->fee_with_currency(float $price, string $currency = null);


Price Suggestion

:mag: More Info

Retrieve price suggestions for the provided Release ID. :closed_lock_with_key: Auth Required

$discog->price_suggestions(int $release_id);


Release Statistics

:mag: More Info

Retrieve marketplace statistics for the provided Release ID.

$discog->release_statistics(int $release_id, string $curr_abbr = null);


User Identity

Identity

:mag: More Info

Retrieve basic information about the authenticated user. :closed_lock_with_key: Auth Required

$discog->identity();


Profile

:mag: More Info

Retrieve a user by username.

$discog->profile(string $username);

Edit a user’s profile data. :closed_lock_with_key: Auth Required

$discog->edit_profile(string $username, array $parameters => null);


User Submissions

:mag: More Info

Retrieve a user’s submissions by username.

$user = $discog->user_submissions(string $username);

foreach($user->submissions as $submission)
{
    var_dump($submission);
}


User Collection

Collection

:mag: More Info

Retrieve a list of folders in a user’s collection.

$user = $discog->collection_folders(string $username);

foreach($user->folders as $folder)
{
    var_dump($folder);
}

Create a new folder in a user’s collection. :closed_lock_with_key: Auth Required

$discog->new_collection_folder(string $username, string $name);


Collection Folder

:mag: More Info

Retrieve a list of folders in a user’s collection.

$discog->collection_folders(string $username);

Create a new folder in a user’s collection.

$discog->new_collection_folder(string $username, string $name);

Retrieve metadata about a folder in a user’s collection.

$discog->collection_folder(string $username, int $folder_id);

Edit the metadata about a folder in a user’s collection. :closed_lock_with_key: Auth Required

$discog->edit_collection_folder(string $username, int $folder_id, string $name);

Delete a folder from a user’s collection. :closed_lock_with_key: Auth Required

$discog->delete_collection_folder(string $username, int $folder_id);


Collection Items by Release

:mag: More Info

View the user’s collection folders which contain a specified release.

$discog->collection_items_by_release(string $username, int $release_id);


Collection Items by Folder

:mag: More Info

Returns the list of item in a folder in a user’s collection.

$discog->collection_items_by_release(string $username, int $release_id);


Add to Collection Folder

:mag: More Info

Add a release to a folder in a user’s collection. :closed_lock_with_key: Auth Required

$discog->add_to_collection_folder(string $username, int $folder_id, int $release_id);


Change Rating of Release

:mag: More Info

Change the rating on a release and/or move the instance to another folder. :closed_lock_with_key: Auth Required

$discog->change_rating_of_release(string $username, int $folder_id, int $release_id, int $instance_id, array $parameters = null);


Delete Instance from Folder

:mag: More Info

Remove an instance of a release from a user’s collection folder. :closed_lock_with_key: Auth Required

$discog->delete_instance_from_folder(string $username, int $folder_id, int $release_id, int $instance_id);


List Custom Fields

:mag: More Info

Retrieve a list of user-defined collection notes fields.

$discog->list_custom_fields(string $username);

Change the value of a notes field on a particular instance.

$discog->edit_fields_instance(string $username, string $value, int $folder_id, int $release_id, int $instance_id, int $field_id);


Collection Value

:mag: More Info

Returns the minimum, median, and maximum value of a user’s collection. :closed_lock_with_key: Auth Required

$discog->collection_value(string $username);


User Wantlist

Wantlist

:mag: More Info

Returns the list of releases in a user’s wantlist.

$discog->wantlist(string $username);

Add a release to a user’s wantlist. :closed_lock_with_key: Auth Required

$discog->add_to_wantlist(string $username, int $relase_id, string $notes = null, int $rating = null);

Edit a release from a user’s wantlist. :closed_lock_with_key: Auth Required

$discog->edit_from_wantlist(string $username, int $relase_id, string $notes = null, int $rating = null);

Delete a release from a user’s wantlist. :closed_lock_with_key: Auth Required

$discog->delete_from_wantlist(string $username, int $relase_id, string $notes = null, int $rating = null);


User Lists

User Lists

:mag: More Info

Returns a User’s Lists.

$discog->user_lists(string $username);


List

:mag: More Info

Returns items from a specified List.

$discog->user_lists(int $list_id);


Authentication

Request Token

:mag: More Info

Generate the request token

$discog->request_token();


List

:mag: More Info

Generate the access token.

$discog->access_token(string $oauth_token, string $oauth_token_secret, string $verifier);