From 9b9f54af5ab1769321c5e197b00371c470821af0 Mon Sep 17 00:00:00 2001 From: Bailey Herbert Date: Fri, 15 Mar 2024 14:19:32 -0700 Subject: [PATCH] Add type stubs for endpoints --- src/Envato/Stubs/CatalogStub.php | 158 +++++++++++++++++++++++++++++++ src/Envato/Stubs/MarketStub.php | 49 ++++++++++ src/Envato/Stubs/ProfileStub.php | 93 ++++++++++++++++++ src/Envato/Stubs/UserStub.php | 151 +++++++++++++++++++++++++++++ src/EnvatoClient.php | 15 ++- 5 files changed, 462 insertions(+), 4 deletions(-) create mode 100644 src/Envato/Stubs/CatalogStub.php create mode 100644 src/Envato/Stubs/MarketStub.php create mode 100644 src/Envato/Stubs/ProfileStub.php create mode 100644 src/Envato/Stubs/UserStub.php diff --git a/src/Envato/Stubs/CatalogStub.php b/src/Envato/Stubs/CatalogStub.php new file mode 100644 index 0000000..b20ab7d --- /dev/null +++ b/src/Envato/Stubs/CatalogStub.php @@ -0,0 +1,158 @@ +catalog->collection(['id' => 12345]); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_0_getCatalogCollection + */ + public function collection(array $parameters); + + /** + * Returns all details of a particular item on Envato Market. + * + * ```php + * $client->catalog->item(['id' => 12345]); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_0_getCatalogItem + */ + public function item(array $parameters); + + /** + * Returns the latest available version of a theme/plugin. This is the recommended endpoint for Wordpress + * theme/plugin authors building an auto-upgrade system into their item that needs to check if a new version is + * available. + * + * ```php + * $client->catalog->item_version(['id' => 12345]); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_0_getCatalogItemVersion + */ + public function item_version(array $parameters); + + /** + * Search for items. + * + * ```php + * $client->catalog->items(['site' => 'codecanyon.net', 'term' => '']); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#search_getSearchItem + */ + public function items(array $parameters); + + /** + * Search for comments. + * + * ```php + * $client->catalog->comments(['item_id' => 12345]); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#search_getSearchComment + */ + public function comments(array $parameters); + + /** + * Returns the popular files for a particular site. Requires a site parameter, e.g. `themeforest`. + * + * ```php + * $client->catalog->popular(['site' => 'codecanyon']); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_getPopular + */ + public function popular(array $parameters); + + /** + * Lists the categories of a particular site. Requires a site parameter, e.g. `themeforest`. + * + * ```php + * $client->catalog->categories(['site' => 'codecanyon']); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_getCategories + */ + public function categories(array $parameters); + + /** + * Return available licenses and prices for the given item ID. + * + * ```php + * $client->catalog->prices(['item_id' => 12345]); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_getItemPrices + */ + public function prices(array $parameters); + + /** + * New files, recently uploaded to a particular site. Requires `site` and `category` parameters. + * + * ```php + * $client->catalog->newest(['site' => 'codecanyon', 'category' => 'php-scripts']); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_getNewFiles + */ + public function newest(array $parameters); + + /** + * Shows the current site features. + * + * ```php + * $client->catalog->featured(['site' => 'codecanyon']); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_getFeatures + */ + public function featured(array $parameters); + + /** + * Shows a random list of newly uploaded files from a particular site. Requires a site parameter, e.g. + * `themeforest`. + * + * ```php + * $client->catalog->random(['site' => 'codecanyon']); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_getRandomNewFiles + */ + public function random(array $parameters); + +} diff --git a/src/Envato/Stubs/MarketStub.php b/src/Envato/Stubs/MarketStub.php new file mode 100644 index 0000000..80c56ab --- /dev/null +++ b/src/Envato/Stubs/MarketStub.php @@ -0,0 +1,49 @@ +market->users(); + * ``` + * + * @return ResultSet + * @see https://build.envato.com/api/#market_getTotalUsers + */ + public function users(); + + /** + * Returns the total number of items listed on Envato Market. + * + * ```php + * $client->market->items(); + * ``` + * + * @return ResultSet + * @see https://build.envato.com/api/#market_getTotalItems + */ + public function items(); + + /** + * Returns the total number of items listed on Envato Market for a specific site. + * + * ```php + * $client->market->site(['site' => 'codecanyon']); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_getNumberOfFiles + */ + public function site(array $parameters); + +} diff --git a/src/Envato/Stubs/ProfileStub.php b/src/Envato/Stubs/ProfileStub.php new file mode 100644 index 0000000..ed72cf9 --- /dev/null +++ b/src/Envato/Stubs/ProfileStub.php @@ -0,0 +1,93 @@ +profile->collections(); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_0_getUserCollections + */ + public function collections(); + + /** + * Returns details and items for any public collection, or returns details and items for one of the current user's + * private collections, by its ID. + * + * ```php + * $client->profile->collection(['id' => 12345]); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_0_getUserCollection + */ + public function collection(array $parameters); + + /** + * Returns the username, country, number of sales, number of followers, location and image for a user. Requires a + * username, e.g. `collis`. + * + * ```php + * $client->profile->details(['username' => 'collis']); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_getUser + */ + public function details(array $parameters); + + /** + * Returns a list of badges for the given user. + * + * ```php + * $client->profile->badges(['username' => 'baileyherbert']); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_getUserBadges + */ + public function badges(array $parameters); + + /** + * Returns the number of items that the user has for sale on each Market site. Requires a username, e.g. `collis`. + * + * ```php + * $client->profile->portfolio(['username' => 'baileyherbert']); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_getUserItemsBySite + */ + public function portfolio(array $parameters); + + /** + * Returns up to 1,000 of the newest files from a particular user on the target Market site. Requires a username + * and a site parameter, e.g. `collis` and `themeforest`. + * + * ```php + * $client->profile->newest(['username' => 'collis', 'site' => 'themeforest']); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_getNewFilesFromUser + */ + public function newest(array $parameters); + +} diff --git a/src/Envato/Stubs/UserStub.php b/src/Envato/Stubs/UserStub.php new file mode 100644 index 0000000..d5a1622 --- /dev/null +++ b/src/Envato/Stubs/UserStub.php @@ -0,0 +1,151 @@ +user->sales(); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_0_getAuthorSales + */ + public function sales(); + + /** + * Returns the details of an author's sale identified by the purchase code (for authors only). + * + * ```php + * $client->user->sale(['code' => '*****']); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_0_getAuthorSale + */ + public function sale(array $parameters); + + /** + * Lists purchases made by the authenticated user. + * + * ```php + * $client->user->purchases(); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_0_getBuyerListPurchases + */ + public function purchases(); + + /** + * Returns the details of a purchase made by the authenticated user (for buyers only). + * + * ```php + * $client->user->purchase(['code' => '*****']); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_0_getBuyerPurchase + */ + public function purchase(array $parameters); + + /** + * Creates a download link for a Market purchase by either the `item_id` or the `purchase_code`. Each invocation of + * this endpoint will count against the items daily download limit. + * + * ```php + * $client->user->download(['purchase_code' => '*****']); + * $client->user->download(['item_id' => 123456]); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_0_getBuyerDownload + */ + public function download(array $parameters); + + /** + * Returns the first name, surname, earnings available to withdraw, total deposits, balance (deposits + earnings) + * and country for the authenticated user. + * + * ```php + * $client->user->details(); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_getUserAccount + */ + public function details(); + + /** + * Returns the username of the authenticated user. + * + * ```php + * $client->user->username(); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_getUsername + */ + public function username(); + + /** + * Returns the email address of the authenticated user. + * + * ```php + * $client->user->email(); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_getUserEmail + */ + public function email(); + + /** + * Returns the sales/earnings and sales for the authenticated user by month, as displayed on the "earnings" page. + * + * ```php + * $client->user->earnings(); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_getUserEarningsAndSalesByMonth + */ + public function earnings(); + + /** + * Lists transactions from the user's statement page. + * + * ```php + * $client->user->statement([ + * 'page' => 1, + * 'from_date' => '2021-02-01', + * 'to_date' => '2022-06-21', + * 'type' => 'Sale', + * 'site' => 'codecanyon.net' + * ]); + * ``` + * + * @param array $parameters + * @return ResultSet + * @see https://build.envato.com/api/#market_0_getUserStatement + */ + public function statement(array $parameters); + +} diff --git a/src/EnvatoClient.php b/src/EnvatoClient.php index a6f268e..6e36423 100644 --- a/src/EnvatoClient.php +++ b/src/EnvatoClient.php @@ -10,16 +10,20 @@ use Herbert\Envato\Exceptions\NotAuthenticatedException; use Herbert\Envato\RequestWriter; use Herbert\Envato\Schema; + use Herbert\Envato\Stubs\CatalogStub; + use Herbert\Envato\Stubs\MarketStub; + use Herbert\Envato\Stubs\ProfileStub; + use Herbert\Envato\Stubs\UserStub; /** * Represents an authenticated connection to and interface for accessing the Envato API. * * @package Herbert * - * @property Endpoint $market - * @property Endpoint $catalog - * @property Endpoint $profile - * @property Endpoint $user + * @property MarketStub $market + * @property CatalogStub $catalog + * @property ProfileStub $profile + * @property UserStub $user */ class EnvatoClient { @@ -93,6 +97,9 @@ public function __construct(AuthProcedure $auth, $httpOptions = array()) { $this->schema = $o(); } + /** + * Creates an endpoint helper class for the specified schema collection. + */ public function __get($property) { $name = strtolower($property);