Merge pull request #383 from stripe/ob-nested-resource-class-methods

Static methods for accessing nested resources
stripe · Oct 25, 2017 · 63be833 · 63be833
2 parents 97bcb2b + 4006553
commit 63be833
Show file tree

Hide file tree

Showing 9 changed files with 697 additions and 0 deletions.
diff --git a/lib/Account.php b/lib/Account.php
@@ -37,6 +37,9 @@
  */
 class Account extends ApiResource
 {
+    const PATH_EXTERNAL_ACCOUNTS = '/external_accounts';
+    const PATH_LOGIN_LINKS = '/login_links';
+
     public function instanceUrl()
     {
         if ($this['id'] === null) {
@@ -131,6 +134,12 @@ public static function all($params = null, $opts = null)
         return self::_all($params, $opts);
     }
 
+    /**
+     * @param array|null $clientId
+     * @param array|string|null $opts
+     *
+     * @return StripeObject Object containing the response from the API.
+     */
     public function deauthorize($clientId = null, $opts = null)
     {
         $params = array(
@@ -139,4 +148,79 @@ public function deauthorize($clientId = null, $opts = null)
         );
         OAuth::deauthorize($params, $opts);
     }
+
+    /**
+     * @param array|null $id The ID of the account on which to create the external account.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ExternalAccount
+     */
+    public static function createExternalAccount($id, $params = null, $opts = null)
+    {
+        return self::_createNestedResource($id, static::PATH_EXTERNAL_ACCOUNTS, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the account to which the external account belongs.
+     * @param array|null $externalAccountId The ID of the external account to retrieve.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ExternalAccount
+     */
+    public static function retrieveExternalAccount($id, $externalAccountId, $params = null, $opts = null)
+    {
+        return self::_retrieveNestedResource($id, static::PATH_EXTERNAL_ACCOUNTS, $externalAccountId, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the account to which the external account belongs.
+     * @param array|null $externalAccountId The ID of the external account to update.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ExternalAccount
+     */
+    public static function updateExternalAccount($id, $externalAccountId, $params = null, $opts = null)
+    {
+        return self::_updateNestedResource($id, static::PATH_EXTERNAL_ACCOUNTS, $externalAccountId, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the account to which the external account belongs.
+     * @param array|null $externalAccountId The ID of the external account to delete.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ExternalAccount
+     */
+    public static function deleteExternalAccount($id, $externalAccountId, $params = null, $opts = null)
+    {
+        return self::_deleteNestedResource($id, static::PATH_EXTERNAL_ACCOUNTS, $externalAccountId, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the account on which to retrieve the external accounts.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ExternalAccount
+     */
+    public static function allExternalAccounts($id, $params = null, $opts = null)
+    {
+        return self::_allNestedResources($id, static::PATH_EXTERNAL_ACCOUNTS, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the account on which to create the login link.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return LoginLink
+     */
+    public static function createLoginLink($id, $params = null, $opts = null)
+    {
+        return self::_createNestedResource($id, static::PATH_LOGIN_LINKS, $params, $opts);
+    }
 }
diff --git a/lib/ApiResource.php b/lib/ApiResource.php
@@ -199,4 +199,108 @@ protected function _delete($params = null, $options = null)
         $this->refreshFrom($response, $opts);
         return $this;
     }
+
+    /**
+     * @param string $method
+     * @param string $url
+     * @param array|null $params
+     * @param array|string|null $options
+     *
+     * @return StripeObject
+     */
+    protected static function _nestedResourceOperation($method, $url, $params = null, $options = null)
+    {
+        self::_validateParams($params);
+
+        list($response, $opts) = static::_staticRequest($method, $url, $params, $options);
+        $obj = Util\Util::convertToStripeObject($response->json, $opts);
+        $obj->setLastResponse($response);
+        return $obj;
+    }
+
+    /**
+     * @param string $id
+     * @param string $nestedPath
+     * @param string|null $nestedId
+     *
+     * @return string
+     */
+    protected static function _nestedResourceUrl($id, $nestedPath, $nestedId = null)
+    {
+        $url = static::resourceUrl($id) . $nestedPath;
+        if ($nestedId !== null) {
+            $url .= "/$nestedId";
+        }
+        return $url;
+    }
+
+    /**
+     * @param string $id
+     * @param string $nestedPath
+     * @param array|null $params
+     * @param array|string|null $options
+     *
+     * @return StripeObject
+     */
+    protected static function _createNestedResource($id, $nestedPath, $params = null, $options = null)
+    {
+        $url = static::_nestedResourceUrl($id, $nestedPath);
+        return self::_nestedResourceOperation('post', $url, $params, $options);
+    }
+
+    /**
+     * @param string $id
+     * @param string $nestedPath
+     * @param array|null $params
+     * @param array|string|null $options
+     *
+     * @return StripeObject
+     */
+    protected static function _retrieveNestedResource($id, $nestedPath, $nestedId, $params = null, $options = null)
+    {
+        $url = static::_nestedResourceUrl($id, $nestedPath, $nestedId);
+        return self::_nestedResourceOperation('get', $url, $params, $options);
+    }
+
+    /**
+     * @param string $id
+     * @param string $nestedPath
+     * @param array|null $params
+     * @param array|string|null $options
+     *
+     * @return StripeObject
+     */
+    protected static function _updateNestedResource($id, $nestedPath, $nestedId, $params = null, $options = null)
+    {
+        $url = static::_nestedResourceUrl($id, $nestedPath, $nestedId);
+        return self::_nestedResourceOperation('post', $url, $params, $options);
+    }
+
+    /**
+     * @param string $id
+     * @param string $nestedPath
+     * @param array|null $params
+     * @param array|string|null $options
+     *
+     * @return StripeObject
+     */
+    protected static function _deleteNestedResource($id, $nestedPath, $nestedId, $params = null, $options = null)
+    {
+        $url = static::_nestedResourceUrl($id, $nestedPath, $nestedId);
+        return self::_nestedResourceOperation('delete', $url, $params, $options);
+    }
+
+    /**
+     * @param string $id
+     * @param string $nestedPath
+     * @param array|null $params
+     * @param array|string|null $options
+     *
+     * @return StripeObject
+     */
+    protected static function _allNestedResources($id, $nestedPath, $params = null, $options = null)
+    {
+        $url = static::_nestedResourceUrl($id, $nestedPath);
+        return self::_nestedResourceOperation('get', $url, $params, $options);
+    }
 }
diff --git a/lib/ApplicationFee.php b/lib/ApplicationFee.php
@@ -9,6 +9,8 @@
  */
 class ApplicationFee extends ApiResource
 {
+    const PATH_REFUNDS = '/refunds';
+
     /**
      * This is a special case because the application fee endpoint has an
      *    underscore in it. The parent `className` function strips underscores.
@@ -67,4 +69,54 @@ public function refund($params = null, $opts = null)
         $this->refresh();
         return $this;
     }
+
+    /**
+     * @param array|null $id The ID of the application fee on which to create the refund.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ApplicationFeeRefund
+     */
+    public static function createRefund($id, $params = null, $opts = null)
+    {
+        return self::_createNestedResource($id, static::PATH_REFUNDS, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the application fee to which the refund belongs.
+     * @param array|null $refundId The ID of the refund to retrieve.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ApplicationFeeRefund
+     */
+    public static function retrieveRefund($id, $refundId, $params = null, $opts = null)
+    {
+        return self::_retrieveNestedResource($id, static::PATH_REFUNDS, $refundId, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the application fee to which the refund belongs.
+     * @param array|null $refundId The ID of the refund to update.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ApplicationFeeRefund
+     */
+    public static function updateRefund($id, $refundId, $params = null, $opts = null)
+    {
+        return self::_updateNestedResource($id, static::PATH_REFUNDS, $refundId, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the application fee on which to retrieve the refunds.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ApplicationFeeRefund
+     */
+    public static function allRefunds($id, $params = null, $opts = null)
+    {
+        return self::_allNestedResources($id, static::PATH_REFUNDS, $params, $opts);
+    }
 }
diff --git a/lib/Customer.php b/lib/Customer.php
@@ -26,6 +26,8 @@
  */
 class Customer extends ApiResource
 {
+    const PATH_SOURCES = '/sources';
+
     /**
      * @param array|string $id The ID of the customer to retrieve, or an
      *     options array containing an `id` key.
@@ -188,4 +190,67 @@ public function deleteDiscount()
         list($response, $opts) = $this->_request('delete', $url);
         $this->refreshFrom(array('discount' => null), $opts, true);
     }
+
+    /**
+     * @param array|null $id The ID of the customer on which to create the source.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ExternalAccount
+     */
+    public static function createSource($id, $params = null, $opts = null)
+    {
+        return self::_createNestedResource($id, static::PATH_SOURCES, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the customer to which the source belongs.
+     * @param array|null $sourceId The ID of the source to retrieve.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ExternalAccount
+     */
+    public static function retrieveSource($id, $sourceId, $params = null, $opts = null)
+    {
+        return self::_retrieveNestedResource($id, static::PATH_SOURCES, $sourceId, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the customer to which the source belongs.
+     * @param array|null $sourceId The ID of the source to update.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ExternalAccount
+     */
+    public static function updateSource($id, $sourceId, $params = null, $opts = null)
+    {
+        return self::_updateNestedResource($id, static::PATH_SOURCES, $sourceId, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the customer to which the source belongs.
+     * @param array|null $sourceId The ID of the source to delete.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ExternalAccount
+     */
+    public static function deleteSource($id, $sourceId, $params = null, $opts = null)
+    {
+        return self::_deleteNestedResource($id, static::PATH_SOURCES, $sourceId, $params, $opts);
+    }
+
+    /**
+     * @param array|null $id The ID of the customer on which to retrieve the sources.
+     * @param array|null $params
+     * @param array|string|null $opts
+     *
+     * @return ExternalAccount
+     */
+    public static function allSources($id, $params = null, $opts = null)
+    {
+        return self::_allNestedResources($id, static::PATH_SOURCES, $params, $opts);
+    }
 }