v0.2

Finalise basics of all methods as per Etsy's API reference.

* Add ListingFile
* Add ListingImage
* Add ListingInventory
* Add ListingOffering
* Add ListingProduct
* Add ListingTranslation
* Add ListingVariationImage

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v0.2
+Finalise basics of all methods as per Etsy's API reference.
+
+* Add ListingFile
+* Add ListingImage
+* Add ListingInventory
+* Add ListingOffering
+* Add ListingProduct
+* Add ListingTranslation
+* Add ListingVariationImage
+
 ## v0.1.2
 * Add Shop Listing methods
 * Update Request Utility getParamaters method

composer.json

@@ -1,6 +1,6 @@
 {
   "name": "rhysnhall/etsy-php-sdk",
-  "version": "0.1.2",
+  "version": "0.2",
   "description": "PHP SDK for Etsy API v3.",
   "type": "library",
   "keywords": [

src/Etsy.php

@@ -199,7 +199,7 @@ public function getShippingCarriers($iso_code) {
    */
   public function getListing(
     $listing_id,
-    array $include = []
+    array $includes = []
   ) {
     $response = static::$client->get(
       "/application/listings/{$listing_id}",
@@ -237,11 +237,9 @@ public function getListings(
     array $listing_ids,
     array $includes = []
   ) {
-    if(!count($listing_ids)) {
-      throw new ApiException("At least one listing ID is required.");
-    }
-    else if(count($listing_ids) > 100) {
-      throw new ApiException("Request exceeds the 100 listing ID maximum.");
+    if(!count($listing_ids)
+      || count($listing_ids) > 100) {
+      throw new ApiException("Query requires at least one listing ID and cannot exceed a maximum of 100 listing IDs.");
     }
     $response = static::$client->get(
       "/application/listings/batch",

src/Resources/Listing.php

@@ -56,7 +56,7 @@ public function delete() {
   public function getListingProperties() {
     return $this->request(
       "GET",
-      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}",
+      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/properties",
       "ListingProperty"
     )
       ->append([
@@ -86,4 +86,258 @@ public function getListingProperty($property_id) {
     return $listing_property;
   }
 
+  /**
+   * Get the listing files associated with the listing.
+   *
+   * @link https://developers.etsy.com/documentation/reference#operation/getAllListingFiles
+   * @return Etsy\Collection[Etsy\Resources\ListingFile]
+   */
+  public function getFiles() {
+    return $this->request(
+      "GET",
+      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/files",
+      "ListingFile"
+    )
+      ->append(["shop_id" => $this->shop_id]);
+  }
+
+  /**
+   * Get a specific listing file.
+   *
+   * @link https://developers.etsy.com/documentation/reference#operation/getListingFile
+   * @param integer|string $listing_file_id
+   * @return Etsy\Resources\ListingFile
+   */
+  public function getFile($listing_file_id) {
+    $listing_file = $this->request(
+      "GET",
+      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/files/{$listing_file_id}",
+      "ListingFile"
+    );
+    if($listing_file) {
+      $listing_file->shop_id = $this->shop_id;
+    }
+    return $listing_file;
+  }
+
+  /**
+   * Uploads a listing file.
+   *
+   * @link https://developers.etsy.com/documentation/reference#operation/uploadListingFile
+   * @param array $data
+   * @return Etsy\Resources\ListingFile
+   */
+  public function uploadFile(array $data) {
+    if(!isset($data['image']) && !isset($data['listing_image_id'])) {
+      throw new ApiException("Request requires either 'listing_file_id' or 'file' paramater.");
+    }
+    $listing_file = $this->request(
+      "POST",
+      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/files",
+      "ListingFile",
+      $data
+    );
+    if($listing_file) {
+      $listing_file->shop_id = $this->shop_id;
+    }
+    return $listing_file;
+  }
+
+  /**
+   * Get the Listing Images for the listing.
+   *
+   * @link https://developers.etsy.com/documentation/reference#operation/getListingImages
+   * @return Etsy\Collection[Etsy\Resources\ListingImage]
+   */
+  public function getImages() {
+    return $this->request(
+      "GET",
+      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/images",
+      "ListingImage"
+    )
+      ->append(["shop_id" => $this->shop_id]);
+  }
+
+  /**
+   * Get a specific listing image.
+   *
+   * @link https://developers.etsy.com/documentation/reference#operation/getListingImage
+   * @param integer|string $listing_image_id
+   * @return Etsy\Resources\ListingImage
+   */
+  public function getImage($listing_image_id) {
+    $listing_image = $this->request(
+      "GET",
+      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/images/{$listing_image_id}",
+      "ListingImage"
+    );
+    if($listing_image) {
+      $listing_image->shop_id = $this->shop_id;
+    }
+    return $listing_image;
+  }
+
+  /**
+   * Upload a listing image.
+   *
+   * @link https://developers.etsy.com/documentation/reference#operation/uploadListingImage
+   * @param array $data
+   * @return Etsy\Resources\ListingImage
+   */
+  public function uploadImage(array $data) {
+    if(!isset($data['image']) && !isset($data['listing_image_id'])) {
+      throw new ApiException("Request requires either 'listing_image_id' or 'image' paramater.");
+    }
+    $listing_image = $this->request(
+      "POST",
+      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/images",
+      "ListingImage",
+      $data
+    );
+    if($listing_image) {
+      $listing_image->shop_id = $this->shop_id;
+    }
+    return $listing_image;
+  }
+
+  /**
+   * Get the inventory for the listing.
+   *
+   * @link https://developers.etsy.com/documentation/reference#operation/getListingInventory
+   * @return Etsy\Resources\ListingInventory
+   */
+  public function getInventory() {
+    $inventory = $this->request(
+      "GET",
+      "/application/listings/{$this->listing_id}/inventory",
+      "ListingInventory"
+    );
+    // Assign the listing ID to associated inventory products.
+    array_map(
+      (function($product){
+        $product->listing_id = $this->listing_id;
+      }),
+      ($inventory->products ?? [])
+    );
+    return $inventory;
+  }
+
+  /**
+   * Update the inventory for the listing.
+   *
+   * @link https://developers.etsy.com/documentation/reference#operation/updateListingInventory
+   * @param array $data
+   * @return Etsy\Resources\ListingInventory
+   */
+  public function updateInventory(array $data) {
+    $inventory = $this->request(
+      "PUT",
+      "/application/listings/{$this->listing_id}/inventory",
+      "ListingInventory",
+      $data
+    );
+    // Assign the listing ID to associated inventory products.
+    array_map(
+      (function($product){
+        $product->listing_id = $this->listing_id;
+      }),
+      ($inventory->products ?? [])
+    );
+    return $inventory;
+  }
+
+  /**
+   * Get a specific product for a listing. Use this method to bypass going through the ListingInventory resource.
+   *
+   * @link https://developers.etsy.com/documentation/reference#tag/ShopListing-Product
+   * @param integer|string $product_id
+   * @return Etsy\Resources\ListingProduct
+   */
+  public function getProduct($product_id) {
+    $product = $this->request(
+      "GET",
+      "/application/listings/{$this->listing_id}/inventory/products/{$product_id}",
+      "ListingProduct"
+    );
+    if($product) {
+      $product->listing_id = $this->listing_id;
+    }
+    return $product;
+  }
+
+  /**
+   * Get a translation for the listing in a specific language.
+   *
+   * @link https://developers.etsy.com/documentation/reference#operation/getListingTranslation
+   * @param string $language
+   * @return Etsy\Resources\ListingTranslation
+   */
+  public function getTranslation(
+    string $language
+  ) {
+    $translation = $this->request(
+      "GET",
+      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/translations/{$language}",
+      "ListingTranslation"
+    );
+    if($translation) {
+      $translation->shop_id = $this->shop_id;
+    }
+    return $translation;
+  }
+
+  /**
+   * Creates a listing translation.
+   *
+   * @link https://developers.etsy.com/documentation/reference#operation/createListingTranslation
+   * @param string $language
+   * @param array $data
+   * @return Etsy\Resources\ListingTranslation
+   */
+  public function createTranslation(
+    string $language,
+    array $data
+  ) {
+    $translation = $this->request(
+      "POST",
+      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/translations/{$language}",
+      "ListingTranslation",
+      $data
+    );
+    if($translation) {
+      $translation->shop_id = $this->shop_id;
+    }
+    return $translation;
+  }
+
+  /**
+   * Gets variation images for the listing.
+   *
+   * @link https://developers.etsy.com/documentation/reference#operation/getListingVariationImages
+   * @return Etsy\Collection[Etsy\Resources\ListingVariationImage]
+   */
+  public function getVariationImages() {
+    return $this->request(
+      "GET",
+      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/variation-images",
+      "ListingVariationImage"
+    );
+  }
+
+  /**
+   * Updates variation images for the listing. You MUST pass data for ALL variation images, including the ones you are not updating, as this method will override all existing variation images.
+   *
+   * @link https://developers.etsy.com/documentation/reference#operation/updateVariationImages
+   * @param array $data
+   * @return Etsy\Collection[Etsy\Resources\ListingVariationImage]
+   */
+  public function updateVariationImages(array $data) {
+    return $this->request(
+      "PUT",
+      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/variation-images",
+      "ListingVariationImage",
+      $data
+    );
+  }
+
 }

src/Resources/ListingFile.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Etsy\Resources;
+
+use Etsy\Resource;
+
+/**
+ * Listing File class.
+ *
+ * @link https://developers.etsy.com/documentation/reference#tag/ShopListing-File
+ * @author Rhys Hall hello@rhyshall.com
+ */
+class ListingFile extends Resource {
+
+  /**
+   * Delete the listing file.
+   *
+   * @link https://developers.etsy.com/documentation/reference#operation/deleteListingFile
+   * @return boolean
+   */
+  public function delete() {
+    return $this->deleteRequest(
+      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/files/{$this->listing_file_id}"
+    );
+  }
+}

src/Resources/ListingImage.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Etsy\Resources;
+
+use Etsy\Resource;
+
+/**
+ * Listing Image class.
+ *
+ * @link https://developers.etsy.com/documentation/reference#tag/ShopListing-Image
+ * @author Rhys Hall hello@rhyshall.com
+ */
+class ListingImage extends Resource {
+
+  /**
+   * Delete the listing image.
+   *
+   * @link https://developers.etsy.com/documentation/reference#operation/deleteListingImage
+   * @return boolean
+   */
+  public function delete() {
+    return $this->deleteRequest(
+      "/application/shops/{$this->shop_id}/listings/{$this->listing_id}/images/{$this->listing_image_id}"
+    );
+  }
+}

src/Resources/ListingInventory.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Etsy\Resources;
+
+use Etsy\Resource;
+
+/**
+ * Listing Inventory class.
+ *
+ * @link https://developers.etsy.com/documentation/reference#tag/ShopListing-Inventory
+ * @author Rhys Hall hello@rhyshall.com
+ */
+class ListingInventory extends Resource {
+
+  /**
+   * @var array
+   */
+  protected $_associations = [
+    "products" => "ListingProduct"
+  ];
+
+}