bgultekin / cashier-fastspring

src/Fastspring/ApiClient.php

<?php

namespace Bgultekin\CashierFastspring\Fastspring;

use GuzzleHttp\Client;

/**
 * ApiClient is a simple class for sending requests to FastSpring API.
 *
 * This class aims to handle some APIs of Fastspring if you think to develop
 * and add some other features please consider not doing it with one class.
 *
 * Note: This class does not cover whole FastSpring API, it covers just a couple of things
 * in FastSpring API like accounts and sessions.
 *
 * Example usage:
 * ```php
 * $fastspring = new ApiClient();
 * $accounts = $fastspring->getAccounts();
 * ```
 *
 * @author   Bilal Gultekin <bilal@gultekin.me>
 *
 * @version  0.1
 *
 * @see      https://docs.fastspring.com/integrating-with-fastspring/fastspring-api
 */
class ApiClient
{
    /**
     * The Fastspring API Username.
     *
     * @var string
     */
    public $username;

    /**
     * The Fastspring API password.
     *
     * @var string
     */
    public $password;

    /**
     * The Fastspring API Base Url.
     *
     * @var string
     */
    public $apiBase = 'https://api.fastspring.com';

    /**
     * Global queries to apply every requests.
     *
     * @var array
     */
    public $globalQuery = [];

    /**
     * Guzzle client options.
     * Can be used to test class or process.
     *
     * @var array
     */
    public $clientOptions = [];

    /**
     * Create a new Fastspring API interface instance.
     *
     * @param string $username
     * @param string $password
     *
     * @return void
     */
    public function __construct($username = null, $password = null)
    {
        $this->username = $username
            ? $username
            : (getenv('FASTSPRING_USERNAME') ?: config('services.fastspring.username'));
        $this->password = $password
            ? $password
            : (getenv('FASTSPRING_PASSWORD') ?: config('services.fastspring.password'));
    }

    /**
     * Send a request to Fastspring API with given parameters.
     *
     * @param string $method         Method of HTTP request like PUT, GET, POST etc.
     * @param string $path           Path of API
     * @param string $query          Query parameters
     * @param string $formParameters Form parameters
     * @param string $jsonPayload    Json payload
     *
     * @return \GuzzleHttp\Psr7\Response
     */
    public function apiRequest($method, $path, $query = [], $formParameters = [], $jsonPayload = [])
    {
        // prepare guzzle options
        $clientOptions = $this->clientOptions ?: ['base_uri' => $this->apiBase];

        // create guzzle instance
        $client = new Client($clientOptions);

        // delete first slash character
        $path = ltrim($path, '/');

        // prepare options
        $options = [
            'auth'  => [$this->username, $this->password],
            'query' => $this->globalQuery,
        ];

        // set parameters
        $options['query'] = array_merge($options['query'], $query);

It seems like $query can also be of type string; however, parameter $array2 of array_merge() does only seem to accept null|array, maybe add an additional type check?

        if ($formParameters) {
            $options['form_params'] = $formParameters;
        }

        if ($jsonPayload) {
            $options['json'] = $jsonPayload;
        }

        // send request and get response
        $response = $client->request($method, $path, $options);

        // convert it to object
        return $this->handleResponse($response);
    }

    /**
     * Set guzzle client options.
     *
     * @param array $options Guzzle client options
     *
     * @see http://docs.guzzlephp.org/en/latest/quickstart.html Quickstart
     * @see http://docs.guzzlephp.org/en/latest/testing.html Testing
     *
     * @return void
     */
    public function setClientOptions($options)
    {
        return $this->clientOptions = $options;

The expression return $this->clientOptions = $options returns the type array which is incompatible with the documented return type void.

    }

    /**
     * Set global query items.
     *
     * @param array $query Queries like ['mode' => 'test']
     *
     * @return void
     */
    public function setGlobalQuery($query)
    {
        return $this->globalQuery = $query;

The expression return $this->globalQuery = $query returns the type array which is incompatible with the documented return type void.

    }

    /**
     * Handle JSON response and convert it to array.
     *
     * @param \GuzzleHttp\Psr7\Response $response Guzzle response
     *
     * @return object
     */
    protected function handleResponse($response)
    {
        $message = $response->getBody()->getContents();

        // json decode
        // we assume fastspring sends always json
        return json_decode($message);
    }

    // API methods

    /**
     * Create account.
     *
     * @param array $account Account details
     *
     * @see https://docs.fastspring.com/integrating-with-fastspring/fastspring-api/accounts  Account details
     *
     * @return object Response of fastspring
     */
    public function createAccount($account)
    {
        return $this->apiRequest('POST', 'accounts', [], [], $account);

array() of type array is incompatible with the type string expected by parameter $query of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

$account of type array is incompatible with the type string expected by parameter $jsonPayload of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $formParameters of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

    }

    /**
     * Update account.
     *
     * @param string $fastspringId Fastspring ID of related account
     * @param array  $account      Account details
     *
     * @see https://docs.fastspring.com/integrating-with-fastspring/fastspring-api/accounts  Account details
     *
     * @return object Response of fastspring
     */
    public function updateAccount($fastspringId, $account)
    {
        return $this->apiRequest('POST', implode('/', ['accounts', $fastspringId]), [], [], $account);

array() of type array is incompatible with the type string expected by parameter $formParameters of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

$account of type array is incompatible with the type string expected by parameter $jsonPayload of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $query of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

    }

    /**
     * Get account list.
     *
     * @param array $parameters Query parameters
     *
     * @return object Response of fastspring
     */
    public function getAccounts($parameters = [])
    {
        return $this->apiRequest('GET', 'accounts', $parameters, [], []);

$parameters of type array is incompatible with the type string expected by parameter $query of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $formParameters of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $jsonPayload of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

    }

    /**
     * Get the account with the given id.
     *
     * @param string|int $accountId  ID of the account
     * @param array      $parameters Query Parameters
     *
     * @return object Response of fastspring
     */
    public function getAccount($accountId, $parameters = [])
    {
        return $this->apiRequest('GET', implode('/', ['accounts', $accountId]), $parameters, [], []);

$parameters of type array is incompatible with the type string expected by parameter $query of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $formParameters of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $jsonPayload of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

    }

    /**
     * Create session.
     *
     * @param array $session Sessions details
     *
     * @see https://docs.fastspring.com/integrating-with-fastspring/fastspring-api/sessions  Session details
     *
     * @return object Response of fastspring
     */
    public function createSession($session)
    {
        return $this->apiRequest('POST', 'sessions', [], [], $session);

$session of type array is incompatible with the type string expected by parameter $jsonPayload of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $formParameters of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $query of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

    }

    /**
     * Get orders.
     *
     * @param array $parameters Query parameters
     *
     * @return object Response of fastspring
     */
    public function getOrders($parameters = [])
    {
        return $this->apiRequest('GET', 'accounts', $parameters, [], []);

array() of type array is incompatible with the type string expected by parameter $jsonPayload of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $formParameters of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

$parameters of type array is incompatible with the type string expected by parameter $query of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

    }

    /**
     * Get subscriptions.
     *
     * @param array $subscriptionIds Fastspring ids of subscriptions
     *
     * @see https://docs.fastspring.com/integrating-with-fastspring/fastspring-api/subscriptions#id-/subscriptions-Getoneormoresubscriptioninstances
     *
     * @return object Response of fastspring
     */
    public function getSubscriptions($subscriptionIds)
    {
        return $this->apiRequest('GET', implode(
            '/',
            ['subscriptions', implode(',', $subscriptionIds)]
        ), [], [], []);

array() of type array is incompatible with the type string expected by parameter $jsonPayload of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $query of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $formParameters of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

    }

    /**
     * Get subscription, returns one instance.
     *
     * @param array $subscriptionId Fastspring id of subscriptions
     *
     * @see https://docs.fastspring.com/integrating-with-fastspring/fastspring-api/subscriptions#id-/subscriptions-Getoneormoresubscriptioninstances
     *
     * @return object Response of fastspring
     */
    public function getSubscriptionsEntries($subscriptionIds)
    {
        return $this->apiRequest('GET', implode(
            '/',
            ['subscriptions', implode(',', $subscriptionIds), 'entries']
        ), [], [], []);

array() of type array is incompatible with the type string expected by parameter $formParameters of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $query of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $jsonPayload of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

    }

    /**
     * Update subscriptions.
     *
     * @param array $subscriptions Data of all subscriptions wanted to be updated (should include subscription => $id)
     *
     * @see https://docs.fastspring.com/integrating-with-fastspring/fastspring-api/subscriptions#id-/subscriptions-Updateexistingsubscriptioninstances
     *
     * @return object Response of fastspring
     */
    public function updateSubscriptions($subscriptions)
    {
        return $this->apiRequest('POST', 'subscriptions', [], [], [

array() of type array is incompatible with the type string expected by parameter $formParameters of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $query of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array('subscriptions' => $subscriptions) of type array<string,array> is incompatible with the type string expected by parameter $jsonPayload of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

            'subscriptions' => $subscriptions,
        ]);
    }

    /**
     * Cancel subscription.
     *
     * @param string|int $subscriptionId ID of the subscription
     * @param array      $parameters     Query Parameters for example to delete immediately pass ['billingPeriod' => 0]
     *
     * @return object Response of fastspring
     */
    public function cancelSubscription($subscriptionId, $parameters = [])
    {
        return $this->apiRequest('DELETE', implode('/', ['subscriptions', $subscriptionId]), $parameters, [], []);

array() of type array is incompatible with the type string expected by parameter $jsonPayload of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

$parameters of type array is incompatible with the type string expected by parameter $query of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $formParameters of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

    }

    /**
     * Uncancel subscription.
     *
     * @param string|int $subscriptionId ID of the subscription
     *
     * @return object Response of fastspring
     */
    public function uncancelSubscription($subscriptionId)
    {
        return $this->updateSubscriptions([
            [
                'subscription' => $subscriptionId,
                'deactivation' => null,
            ],
        ]);
    }

    /**
     * Get authenticated url of fastspring account management panel.
     *
     * @param string|int $accountId ID of the account
     *
     * @return object Response of fastspring
     */
    public function getAccountManagementURI($accountId)
    {
        return $this->apiRequest('GET', implode('/', ['accounts', $accountId, 'authenticate']), [], [], []);

array() of type array is incompatible with the type string expected by parameter $jsonPayload of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $formParameters of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

array() of type array is incompatible with the type string expected by parameter $query of Bgultekin\CashierFastspring\Fastspring\ApiClient::apiRequest().

    }

    /**
     * Swap subscription to another plan.
     *
     * @param string|int $subscriptionId ID of the subscription
     * @param string     $newPlan        Name of the new plan
     * @param bool       $prorate        Prorate parameter
     * @param int        $quantity       Quantity of the product
     * @param array      $coupons        Coupons wanted to be applied
     *
     * @return object Response of fastspring
     */
    public function swapSubscription($subscriptionId, $newPlan, $prorate, $quantity = 1, $coupons = [])
    {
        return $this->updateSubscriptions([
            [
                'subscription' => $subscriptionId,
                'product'      => $newPlan,
                'quantity'     => $quantity,
                'coupons'      => $coupons,
                'prorate'      => $prorate,
            ],
        ]);
    }
}