From dddff35df63de883e05154aca613aa908bc32d72 Mon Sep 17 00:00:00 2001 From: Justin Hartman Date: Sun, 17 Nov 2019 10:03:11 +0200 Subject: [PATCH] Docblock comments for most files. Listeners still need to be done. --- composer.json | 3 -- src/Billable.php | 63 +++++++++++++--------- src/CashierServiceProvider.php | 13 ++++- src/Exceptions/NotImplementedException.php | 9 +++- src/Fastspring/ApiClient.php | 50 +++++++++-------- src/Fastspring/Fastspring.php | 33 ++++++++---- src/Http/Controllers/WebhookController.php | 16 +++++- src/Invoice.php | 17 +++++- src/Subscription.php | 15 +++++- src/SubscriptionBuilder.php | 45 ++++++++++------ src/SubscriptionPeriod.php | 17 +++++- 11 files changed, 197 insertions(+), 84 deletions(-) diff --git a/composer.json b/composer.json index 780b645..d59fd54 100644 --- a/composer.json +++ b/composer.json @@ -44,9 +44,6 @@ } }, "extra": { - "branch-alias": { - "dev-master": "8.0-dev" - }, "laravel": { "providers": [ "TwentyTwoDigital\\CashierFastspring\\CashierServiceProvider" diff --git a/src/Billable.php b/src/Billable.php index 3dd853f..dbaaf7d 100644 --- a/src/Billable.php +++ b/src/Billable.php @@ -1,21 +1,33 @@ + * @author Justin Hartman + * @copyright 2019 22 Digital + * @license MIT + * @since v0.1 + */ namespace TwentyTwoDigital\CashierFastspring; use TwentyTwoDigital\CashierFastspring\Exceptions\NotImplementedException; use TwentyTwoDigital\CashierFastspring\Fastspring\Fastspring; use Exception; +/** + * Billable trait. + * + * {@inheritDoc} + */ trait Billable { /** * Make a "one off" charge on the customer for the given amount. * - * @param int $amount - * @param array $options + * @param int $amount The amount to charge + * @param array $options Array of options * - * @throws \InvalidArgumentException - * @throws Exceptions\NotImplementedException + * @throws \TwentyTwoDigital\CashierFastspring\Exceptions\NotImplementedException */ public function charge($amount, array $options = []) { @@ -25,11 +37,10 @@ public function charge($amount, array $options = []) /** * Refund a customer for a charge. * - * @param string $charge - * @param array $options + * @param string $charge The amount to refund + * @param array $options Array of options * - * @throws \InvalidArgumentException - * @throws Exceptions\NotImplementedException + * @throws \TwentyTwoDigital\CashierFastspring\Exceptions\NotImplementedException */ public function refund($charge, array $options = []) { @@ -39,8 +50,8 @@ public function refund($charge, array $options = []) /** * Begin creating a new subscription. * - * @param string $subscription - * @param string $plan + * @param string $subscription Subscription name + * @param string $plan The plan name * * @return \TwentyTwoDigital\CashierFastspring\SubscriptionBuilder */ @@ -52,8 +63,8 @@ public function newSubscription($subscription, $plan) /** * Determine if the subscription is on trial. * - * @param string $subscription - * @param string|null $plan + * @param string $subscription Subscription name + * @param string|null $plan Plan name * * @return bool */ @@ -72,8 +83,8 @@ public function onTrial($subscription = 'default', $plan = null) /** * Determine if the model has a given subscription. * - * @param string $subscription - * @param string|null $plan + * @param string $subscription Subscription name + * @param string|null $plan Plan name * * @return bool */ @@ -131,8 +142,8 @@ public function invoices() /** * Determine if the model is actively subscribed to one of the given plans. * - * @param array|string $plans - * @param string $subscription + * @param string|null $plans Plan name + * @param string $subscription Subscription name * * @return bool */ @@ -156,7 +167,7 @@ public function subscribedToPlan($plans, $subscription = 'default') /** * Determine if the entity is on the given plan. * - * @param string $plan + * @param string $plan Plan name * * @return bool */ @@ -180,7 +191,7 @@ public function hasFastspringId() /** * Generate authenticated url of fastspring account management panel. * - * @return bool + * @return \TwentyTwoDigital\CashierFastspring\Fastspring\Fastspring */ public function accountManagementURI() { @@ -192,9 +203,9 @@ public function accountManagementURI() /** * Create a Fastspring customer for the given user model. * - * @param array $options + * @param array $options Options array of customer information * - * @return object + * @return \TwentyTwoDigital\CashierFastspring\Fastspring\Fastspring */ public function createAsFastspringCustomer(array $options = []) { @@ -223,16 +234,16 @@ public function createAsFastspringCustomer(array $options = []) } /** - * Update the related account on the Fastspring-side the given user model. + * Update the related account on Fastspring, given user-model. * - * @param array $options + * @param array $options array of customer information + * + * @throws Exception No valid Fastspring ID * * @return object */ public function updateAsFastspringCustomer(array $options = []) { - // check the fastspring_id first - // if there is non, no need to try if (!$this->hasFastspringId()) { throw new Exception('User has no fastspring_id'); } @@ -258,6 +269,8 @@ public function updateAsFastspringCustomer(array $options = []) /** * Get the Fastspring customer for the model. * + * @throws Exception No valid Fastspring ID + * * @return object */ public function asFastspringCustomer() diff --git a/src/CashierServiceProvider.php b/src/CashierServiceProvider.php index e2f055d..f3f7450 100644 --- a/src/CashierServiceProvider.php +++ b/src/CashierServiceProvider.php @@ -1,9 +1,20 @@ + * @copyright 2019 22 Digital + * @since v0.1 + */ namespace TwentyTwoDigital\CashierFastspring; use Illuminate\Support\ServiceProvider; +/** + * This class describes the Laravel Cashier Service Provider. + * + * {@inheritDoc} + */ class CashierServiceProvider extends ServiceProvider { /** diff --git a/src/Exceptions/NotImplementedException.php b/src/Exceptions/NotImplementedException.php index 5e953b6..8c304e7 100644 --- a/src/Exceptions/NotImplementedException.php +++ b/src/Exceptions/NotImplementedException.php @@ -1,9 +1,16 @@ + * @copyright 2019 22 Digital + * @since v0.1 + */ namespace TwentyTwoDigital\CashierFastspring\Exceptions; use BadMethodCallException; class NotImplementedException extends BadMethodCallException { + // } diff --git a/src/Fastspring/ApiClient.php b/src/Fastspring/ApiClient.php index fb665ef..27e7485 100644 --- a/src/Fastspring/ApiClient.php +++ b/src/Fastspring/ApiClient.php @@ -1,17 +1,12 @@ getAccounts(); * ``` * - * @author Bilal Gultekin - * - * @version 0.1 + * @author Bilal Gultekin + * @version v0.1: + * @copyright 2019 22 Digital + * @license MIT + * @see https://docs.fastspring.com/integrating-with-fastspring/fastspring-api + */ +namespace TwentyTwoDigital\CashierFastspring\Fastspring; + +use GuzzleHttp\Client; + +/** + * This class describes an api client. * - * @see https://docs.fastspring.com/integrating-with-fastspring/fastspring-api + * {@inheritDoc} */ class ApiClient { @@ -66,8 +70,8 @@ class ApiClient /** * Create a new Fastspring API interface instance. * - * @param string $username - * @param string $password + * @param string $username Fastspring API username + * @param string $password Fastspring API password * * @return void */ @@ -84,7 +88,7 @@ public function __construct($username = null, $password = null) /** * Send a request to Fastspring API with given parameters. * - * @param string $method Method of HTTP request like PUT, GET, POST etc. + * @param string $method Method of HTTP request like PUT, GET, POST * @param string $path Path of API * @param string $query Query parameters * @param string $formParameters Form parameters @@ -170,14 +174,12 @@ protected function handleResponse($response) 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 + * @see https://docs.fastspring.com/integrating-with-fastspring/fastspring-api/accounts Account details * * @return object Response of fastspring */ @@ -192,7 +194,7 @@ public function createAccount($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 + * @see https://docs.fastspring.com/integrating-with-fastspring/fastspring-api/accounts Account details * * @return object Response of fastspring */ @@ -231,7 +233,7 @@ public function getAccount($accountId, $parameters = []) * * @param array $session Sessions details * - * @see https://docs.fastspring.com/integrating-with-fastspring/fastspring-api/sessions Session details + * @see https://docs.fastspring.com/integrating-with-fastspring/fastspring-api/sessions Session details * * @return object Response of fastspring */ @@ -289,7 +291,8 @@ public function getSubscriptionsEntries($subscriptionIds) /** * Update subscriptions. * - * @param array $subscriptions Data of all subscriptions wanted to be updated (should include subscription => $id) + * @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 * @@ -306,7 +309,8 @@ public function updateSubscriptions($subscriptions) * Cancel subscription. * * @param string|int $subscriptionId ID of the subscription - * @param array $parameters Query Parameters for example to delete immediately pass ['billingPeriod' => 0] + * @param array $parameters Query Parameters for example to delete + * immediately pass ['billingPeriod' => 0] * * @return object Response of fastspring */ diff --git a/src/Fastspring/Fastspring.php b/src/Fastspring/Fastspring.php index 9dd307b..9228c6f 100644 --- a/src/Fastspring/Fastspring.php +++ b/src/Fastspring/Fastspring.php @@ -1,15 +1,20 @@ + * @version 0.1: + * @copyright 2019 22 Digital + * @license MIT + * @see https://docs.fastspring.com/integrating-with-fastspring/fastspring-api + */ namespace TwentyTwoDigital\CashierFastspring\Fastspring; /** - * This class helps to reach Fastspring class with laravel config and static methods. - * - * @author Bilal Gultekin + * This class describes the Fastspring implementation. * - * @version 0.1 - * - * @see https://docs.fastspring.com/integrating-with-fastspring/fastspring-api + * {@inheritDoc} */ class Fastspring { @@ -21,13 +26,19 @@ class Fastspring public static $instance; /** - * It is not useful to construct this Fastspring class everytime. - * This helps to construct this class with the current config. + * Static method. + * + * It is not useful to construct this Fastspring class everytime. This helps + * to construct this class with the current config. if there is not any + * constructed instance then construct and save it to self::$instance + * + * @param string $method The method + * @param array $parameters The parameters for username and password + * + * @return self */ public static function __callStatic($method, $parameters) { - // if there is not any constructed instance - // construct and save it to self::$instance if (!self::$instance) { $username = (getenv('FASTSPRING_USERNAME') ?: config('services.fastspring.username')); $password = (getenv('FASTSPRING_PASSWORD') ?: config('services.fastspring.password')); diff --git a/src/Http/Controllers/WebhookController.php b/src/Http/Controllers/WebhookController.php index af60b32..b30a9ae 100644 --- a/src/Http/Controllers/WebhookController.php +++ b/src/Http/Controllers/WebhookController.php @@ -1,5 +1,13 @@ + * @author Justin Hartman + * @copyright 2019 22 Digital + * @license MIT + * @since v0.1 + */ namespace TwentyTwoDigital\CashierFastspring\Http\Controllers; use TwentyTwoDigital\CashierFastspring\Events; @@ -12,6 +20,12 @@ use Log; use Symfony\Component\HttpFoundation\Response; +/** + * Controls the data flow into a webhook object and updates the view + * whenever data changes. + * + * {@inheritDoc} + */ class WebhookController extends Controller { /** diff --git a/src/Invoice.php b/src/Invoice.php index 17c5c34..27b60a5 100644 --- a/src/Invoice.php +++ b/src/Invoice.php @@ -1,9 +1,22 @@ + * @author Justin Hartman + * @copyright 2019 22 Digital + * @license MIT + * @since v0.1 + */ namespace TwentyTwoDigital\CashierFastspring; use Illuminate\Database\Eloquent\Model; +/** + * This class describes an invoice. + * + * {@inheritDoc} + */ class Invoice extends Model { /** @@ -27,6 +40,8 @@ class Invoice extends Model /** * Get the user that owns the invoice. + * + * @return self */ public function user() { diff --git a/src/Subscription.php b/src/Subscription.php index bc081da..840f0e8 100644 --- a/src/Subscription.php +++ b/src/Subscription.php @@ -1,5 +1,13 @@ + * @author Justin Hartman + * @copyright 2019 22 Digital + * @license MIT + * @since v0.1 + */ namespace TwentyTwoDigital\CashierFastspring; use TwentyTwoDigital\CashierFastspring\Fastspring\Fastspring; @@ -8,6 +16,11 @@ use Illuminate\Database\Eloquent\Model; use LogicException; +/** + * This class describes a subscription. + * + * {@inheritDoc} + */ class Subscription extends Model { /** diff --git a/src/SubscriptionBuilder.php b/src/SubscriptionBuilder.php index 1d06185..8d57cfa 100644 --- a/src/SubscriptionBuilder.php +++ b/src/SubscriptionBuilder.php @@ -1,10 +1,23 @@ + * @author Justin Hartman + * @copyright 2019 22 Digital + * @license MIT + * @since v0.1 + */ namespace TwentyTwoDigital\CashierFastspring; use TwentyTwoDigital\CashierFastspring\Fastspring\Fastspring; use GuzzleHttp\Exception\ClientException; +/** + * Front-end to create subscription objects step by step. + * + * {@inheritDoc} + */ class SubscriptionBuilder { /** @@ -45,9 +58,9 @@ class SubscriptionBuilder /** * Create a new subscription builder instance. * - * @param mixed $owner - * @param string $name - * @param string $plan + * @param mixed $owner Owner details + * @param string $name Plan name + * @param string $plan Plan * * @return void */ @@ -61,7 +74,7 @@ public function __construct($owner, $name, $plan) /** * Specify the quantity of the subscription. * - * @param int $quantity + * @param int $quantity Number of items * * @return $this */ @@ -75,7 +88,7 @@ public function quantity($quantity) /** * The coupon to apply to a new subscription. * - * @param string $coupon + * @param string $coupon Coupon string to use * * @return $this */ @@ -89,7 +102,7 @@ public function withCoupon($coupon) /** * Create a new Fastspring session and return it as object. * - * @return object + * @return \TwentyTwoDigital\CashierFastspring\Fastspring\Fastspring */ public function create() { @@ -101,6 +114,13 @@ public function create() /** * Get the fastspring id for the current user. * + * If an email key exists in error node then we assume this error is related + * to the fact there is already an account with this email in + * fastspring-side error message. It will also returns account link but + * messages are easily changable so we can't rely on that. + * + * @throws Exception + * * @return int|string */ protected function getFastspringIdOfCustomer() @@ -113,11 +133,6 @@ protected function getFastspringIdOfCustomer() $response = $e->getResponse(); $content = json_decode($response->getBody()->getContents()); - // if email key exists in error node - // then we assume this error is related to that - // there is already an account with this email in fastspring-side - // error message also returns account link but messages are easily - // changable so we can't rely on that if (isset($content->error->email)) { $response = Fastspring::getAccounts(['email' => $this->owner->email]); @@ -129,10 +144,6 @@ protected function getFastspringIdOfCustomer() $this->owner->save(); } } else { - // if we are not sure about the exception - // then throw it again - // if returns it is yours, if doesn't it has never been yours - // (the previous line is a bad joke don't mind) throw $e; // @codeCoverageIgnore } } @@ -144,6 +155,8 @@ protected function getFastspringIdOfCustomer() /** * Build the payload for session creation. * + * @param int $fastspringId The fastspring identifier + * * @return array */ protected function buildPayload($fastspringId) diff --git a/src/SubscriptionPeriod.php b/src/SubscriptionPeriod.php index df86f17..88a82df 100644 --- a/src/SubscriptionPeriod.php +++ b/src/SubscriptionPeriod.php @@ -1,9 +1,22 @@ + * @author Justin Hartman + * @copyright 2019 22 Digital + * @license MIT + * @since v0.1 + */ namespace TwentyTwoDigital\CashierFastspring; use Illuminate\Database\Eloquent\Model; +/** + * This class describes a subscription period. + * + * {@inheritDoc} + */ class SubscriptionPeriod extends Model { /** @@ -25,6 +38,8 @@ class SubscriptionPeriod extends Model /** * Get the user that owns the subscription. + * + * @return object Subscription object. */ public function subscription() {