Welcome to the Php SDK

About

The Quantone Php SDK makes it simple to query the Quantone API and deal with the results returned.

Calls to the Quantone API are made through query objects, which take care of all the logic involved in running a REST query, including deserializing the results to handy result objects. These can then be used to easily integrate Quantone data into your own application

Download

Please note: The Php SDK is currently in beta release. Content and functionality are likely to change significantly and without warning.

Download

The latest source code for the Quantone Php SDK is avalible from GitHub

Installation

  • Open the downloaded source code files in your chosen IDE and add them to your project if neccessary.
  • If your are using namespaces, all the Quantone SDK classes can be found in the QuantoneSDK namespace.
use QuantoneSDK;
  • Add the following requires or includes to any file that will use the Quantone Php SDK

require_once '../QuantoneSDK/src/Quantone.php';
require_once '../QuantoneSDK/src/QuantoneObjectModel.php';
require_once '../QuantoneSDK/src/QuantoneQuery.php';
require_once '../QuantoneSDK/src/QuantoneException.php';

Querying the API

Before you can query the Quantone API, you first need to create a new Quantone object. This will be used to run all your queries. The Quantone class has a constructor that takes two arguments, your app ID and app Key. These are provided on registration.

$myQuantone = new QuantoneSDK\Quantone("YOUR_APP_ID", "YOUR_APP_KEY");

Each query topic has its own Query class. A full list of topics can be found in our API Reference. Lookup query classes, eg AlbumsByIdQuery, return one result and are used to find items by Quantone ID. Query classes, eg AlbumsQuery, return many results and are used to search the API by parameters such as title, main artists, release date etc.

Querying works the same for all topics. First, a new instance of the class must be created. The parameters should then be filled in with the values you require. The Quantone Php SDK is code completion compatible in most popular IDEs. A full list of parameters can also be found online in our API Reference. Please note: not all parameters are currently supported by the SDK

Single Query

The following code demonstrates how to create a new AlbumsByIdQuery query to find the album with a given Quantone ID.

$qo = new QuantoneSDK\AlbumsByIdQuery();
$qo->setDepth(array(QuantoneSDK\AlbumRetrievalDepth::ARTISTDETAILS));
$qo->setId("156dda6c-358f-e311-be87-ac220b82800d");

Search Query

The following code demonstrates how to create a new AlbumsQuery object, searching for albums with the title 'Rumours' that were released in 1977.

$qo = new QuantoneSDK\AlbumsQuery();
$qo->setTitle("Rumours");
$qo->setDateReleased("1977");

Running The Query

Once the parameters you wish to search on have been set, use the appropraite execute methodmethod to run the query. The result object returned will correspond to the query type

$qr = myQuantone->executeAlbumsQuery($qo);

Dealing With Results

The result of the query is saved to the Result object in your Query object. The structure of this differs slightly for single and search queries.

Checking for Errors

Any errors that occur are thrown as a QuantoneException. It is therefore recommend to implement some form of error handling to catch these exceptions

try{
    $qr = myQuantone->executeAlbumsQuery($qo);
}
catch(QuantoneSDK\QuantoneException ex){
    echo $ex->getMessage();
}

Single Query Result

Lookup query topics return a 'by id' query result object, e.g. a AlbumsByIdQuery would return an AlbumsByIdQueryResult. This query result object contains a single result entity. The type of this entity corresponds to the query topic, so a AlbumsByIdQuery would return an Album. The properties of this entity can then be accessed and used within your own application.

$qr = myQuantone->execute($qo);
$album = $qr->getResult;
// Display the details of the album
echo "Id: " . album->getId();
echo "Title: " . album->getTitle();
echo "ArtistsLiteral: " . album->getArtistsLiteral();
echo "Artists: " . album->getArtists();
echo "OriginalReleaseDate: " . album->getOriginalReleaseDate();
echo "Format: " . album->getFormat();
echo "IsLive: " . album->getIsLive();
echo "IsUnofficial: " . album->getIsUnofficial();
echo "Genres: " . album->getGenres();
echo "ImageId: " . album->getImageId();
echo "Participations: " . album->getParticipations();
echo "Identifiers: " . album->getIdentifiers();
echo "Recordings: " . album->getRecordings();
echo "Releases: " . album->getReleases();

Search Query Result

Search queries return a query result object, e.g. a AlbumsQuery would return an AlbumsQueryResult. This query object contains an array of result entities. The type of this again corresponds to the topic, so a AlbumsQuery would return a Album[].

$qr = myQuantone->execute($qo);
$albums = $qr->getResults;
for(albums as album){ 
    // Display the details of the album
    echo "Id: " . album->getId();
    echo "Title: " . album->getTitle();
    echo "ArtistsLiteral: " . album->getArtistsLiteral();
    echo "Artists: " . album->getArtists();
    echo "OriginalReleaseDate: " . album->getOriginalReleaseDate();
    echo "Format: " . album->getFormat();
    echo "IsLive: " . album->getIsLive();
    echo "IsUnofficial: " . album->getIsUnofficial();
    echo "Genres: " . album->getGenres();
    echo "ImageId: " . album->getImageId();
    echo "Participations: " . album->getParticipations();
    echo "Identifiers: " . album->getIdentifiers();
    echo "Recordings: " . album->getRecordings();
    echo "Releases: " . album->getReleases();
}

Version History

Version 0.1.0

  • Supports query building and result handling for Album, Artist and Recording topics
  • Compatability with Quantone API v3

Planned Changes

Below is a list of planned changes for future releases that will likely effect the way you use the Quantone Php SDK. This list is not comprehensive and is subject to change at any time whilst the SDK is in beta release.

  • The underlying object model is currently being re-written, which may result in changes to some Query and Result objects. Expected v0.2 and upwards

Upcoming Features

Below is a list of features planned for future releases of the SDK. This list is not comprehensive. Features and estimated release versions are subject to change at any time.

  • Error codes will be added to the Error object that will be thrown to make identifying errors easier and more reliable. Estimated v0.2 - v0.3
  • Utilties for dealing with paged results. Will include functions for navigating between pages, to a specific page and returning all pages in a single object. Estimated v0.3
  • Support for Image queries and image handling helpers Estimated v0.4
  • Support for Disc Tag queries Estimated v0.4 - v0.5

Terms of Use

©Quantone Limited, 2015. May be used freely in unaltered form.

Use of the Quantone API is subject to the following end user license agreement & terms and conditions