This library aims to provide an easy way to access all methods of the Etsy API. The structure is based on the organization of the Etsy API documentation. Methods are organized based upon their "Type" such as Listing, User, etc.
Install via Composer by running:
composer require breakpoint/etsy-php
Usage to access all featured listings:
$esty = new \breakpoint\etsy\EtsyClient('your-keystring', 'your-secret');
$results = $etsy->listing->findAllFeaturedListings();
foreach ($results as $item) {
echo $item->listing_id;
}
All requests originate with the EtsyClient
object and are referenced as properties. These generally correspond to the Etsy API documentation with some variations. Three additional types are included but not documented: application
, baseline
and server
. These are only referenced by results from the getMethodTable method.
$etsy->listing-> // method found in API documentation
Parameters are specified using an array passes directly into the method you are performing.
$etsy->listing->getListing(['listing_id' => '123abc']);
If you wish to specify fields to be returned then specify them first as an array.
$etsy->listing->fields(['listing_id', 'title', 'description', 'url'])->getListing(['listing_id' => '123abc']);
Etsy allows you to request additional Associations be returned with your request. You must specify these first as an array.
$etsy->shop->associations(['Listings' => [
'scope' => 'draft',
'limit' => 10,
'offset' => 0,
'select' => array('listing_id', 'title'),
// you can also specify sub-associations
//'associations' => // scope, limit, select, etc
]])
->getShop(['shop_id' => '123abc']);
All PATCH
, POST
and PUT
requests also accept an array of data.
$etsy->userprofile->updateUserProfile(
// first array is parameters
['user_id', 'user_123'],
// second array is data you are changing
['first_name' => 'john', 'last_name' => 'developer']);
The POST
method will always return an EtsyObject
as the response. The GET
method will return either a EtsyResults
or EtsyObject
based on how many items are expected to be returned. If you are fetching a listing then an EtsyObject
will be returned while if you are fetching active listings then EtsyResults
will be returned.
All other requests (PUT
, PATCH
, DELETE
) will return a true
or false
depending upon their response.
Note: return values have been generated automatically then manually reviewed. Please create an issue or pull request if value is not as expected.
The EtsyResults
object is a simple iterable and array accessible collection. All items within the collection are instances of EtsyObject
. A few basic methods are available:
$results = $etsy->listing->findAllFeaturedListings();
$results[0]; // access the item at that position
$results->count(); // returns number of items
$results->first(); // access the first item
$results->add(object); // useful if you are performing requests with multiple pages
This simple object allows you to access the individual results as properties via magic methods.
$listing = $etsy->listing->getListing(['listing_id' => 'listing_123']);
echo $listing->title;
echo $listing->getType(); // 'Listing'
All methods which require a permission scope will need oauth access via an access and secret token. An easy way to generate these is by using y0lk/oauth1-etsy
. You'll specify these values when creating the EtsyClient
object.
$esty = new \breakpoint\etsy\EtsyClient('your-keystring', 'your-secret', 'access_token', 'token_secret');
By default, only the user who owns the application can authenticate and use it via oauth. To allow other users to use your application you must either request "full access" via the Etsy developers site or by adding them as provisional users. This is made possible by two included method calls:
$etsy->application->addProvisional(['user_id' => 'user_123']);
$etsy->application->removeProvisional(['user_id' => 'user_123']);
// returns all users with access
$etsy->application->getProvisional();
If you prefer to receive the full response then use the raw()
function on your request.
$raw = $etsy->listing->raw()->getTrendingListings();
The generate.php
file is included which creates resources based upon all known types returned from the API. This is meant to serve as a starting point when major changes are made to the API.
php generate.php