[Gateway] New Contract Propposal

docs/contracts/gateway/index.md

@@ -0,0 +1,51 @@
+---
+title: Gateway Contract
+---
+
+Gateway is to help handle payment processing. With so many different payment
+processors our there, there should be a standard interface that developers can
+use to be able to access all of them.
+
+## Installation
+
+```shell
+composer require sonsofphp/pager-contract
+```
+
+## Scope
+
+In Scope:
+- Credit Cards, eCheck, and Tokens as Payment Methods
+- authorize, capture, void, refund
+  - Supports redirect response
+
+Out of Scope
+- Recurring Billing (Might be another component)
+- Webhooks?
+- Usage Based Billing?
+
+## Meta
+
+```php
+<?php
+
+$processor = new PaymentProcessor(key: '...', secret: '...');
+$gateway = new Gateway($processor);
+
+$card = new CreditCard();
+$card->setNumber(...)->setCvv(...);
+
+$transaction = $gateway->authorize(['card' => $card]);
+$transaction = $gateway->capture(['card' => $card]);
+
+// Token Based processors
+$transaction = $gateway->purchase($token);
+
+// Void and Refund
+$transaction = $gateway->void(...);
+$transaction = $gateway->refund(...);
+```
+
+Special Processor Examples
+- Round Robin Processor
+- Capped Processor

src/SonsOfPHP/Contract/Gateway/.gitattributes

@@ -0,0 +1,2 @@
+/.gitattributes export-ignore
+/.gitignore export-ignore

src/SonsOfPHP/Contract/Gateway/.gitignore

@@ -0,0 +1,2 @@
+composer.lock
+vendor/

src/SonsOfPHP/Contract/Gateway/AddressInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Gateway;
+
+/**
+ * @author Joshua Estes <joshua@sonsofphp.com>
+ */
+interface AddressInterface
+{
+}

src/SonsOfPHP/Contract/Gateway/AuthorizableInterface.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Gateway;
+
+/**
+ * @author Joshua Estes <joshua@sonsofphp.com>
+ */
+interface AuthorizableInterface
+{
+    public function authorize(array $options): void;
+
+    public function authorizeComplete(array $options): void;
+}

src/SonsOfPHP/Contract/Gateway/CapturableInterface.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Gateway;
+
+/**
+ * @author Joshua Estes <joshua@sonsofphp.com>
+ */
+interface CapturableInterface
+{
+    public function capture($options): void;
+}

src/SonsOfPHP/Contract/Gateway/CreditCardInterface.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Gateway;
+
+/**
+ * @author Joshua Estes <joshua@sonsofphp.com>
+ */
+interface CreditCardInterface
+{
+    /**
+     * name on card
+     */
+    public function getCardHolder(): string;
+
+    public function setCardHolder(string $cardHolder): self;
+
+    public function getCardNumber(): string;
+
+    public function setCardNumber(string $cardNumber): self;
+
+    /**
+     * Returns month in format MM
+     */
+    public function getExpirationMonth(): string;
+
+    /**
+     * Returns year in format YY
+     */
+    public function getExpirationYear(): string;
+
+    /**
+     * Month and Year SHOULD be in MM and YY format, however this should
+     * also be able to take a full year (2020) or just a single month (4)
+     */
+    public function setExpiration(string|int $month, string|int $year): self;
+
+    /**
+     * Returns the 4DBC, CVC, CVV code for the credit card
+     */
+    public function getSecurityCode(): string;
+
+    public function setSecurityCode(string $securityCode): self;
+}

src/SonsOfPHP/Contract/Gateway/GatewayExceptionInterface.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Gateway;
+
+/**
+ * @author Joshua Estes <joshua@sonsofphp.com>
+ */
+interface GatewayExceptionInterface {}

src/SonsOfPHP/Contract/Gateway/GatewayInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Gateway;
+
+/**
+ * @author Joshua Estes <joshua@sonsofphp.com>
+ */
+interface GatewayInterface extends PurchasableInterface, RefundableInterface, VoidableInterface
+{
+}

src/SonsOfPHP/Contract/Gateway/LICENSE

@@ -0,0 +1,19 @@
+Copyright 2022 to Present Joshua Estes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/SonsOfPHP/Contract/Gateway/PaymentMethodInterface.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Gateway;
+
+/**
+ * Payment Method
+ *   - Credit Card
+ *   - eCheck
+ *   - token
+ *
+ * @author Joshua Estes <joshua@sonsofphp.com>
+ */
+interface PaymentMethodInterface
+{
+}

src/SonsOfPHP/Contract/Gateway/PaymentProcessorInterface.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Gateway;
+
+/**
+ * Processors are basically merchant accounts. They will take credit cards or
+ * other payment types and charge a customer.
+ *
+ * Processor Examples
+ *   - Stripe
+ *   - Authorize.net
+ *   - Dummy or Mock
+ *   - Round Robin
+ *   - Capped
+ *
+ * @author Joshua Estes <joshua@sonsofphp.com>
+ */
+interface PaymentProcessorInterface
+{
+    /**
+     * MUST return the friendly name such as "Stripe"
+     *
+     * This MAY BE used as a display on the frontend
+     */
+    public function getName(): string;
+
+    /**
+     * Request is sent to the payment processor and a response is returned
+     */
+    public function request(RequestInterface $request): ResponseInterface;
+}

src/SonsOfPHP/Contract/Gateway/PurchasableInterface.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Gateway;
+
+/**
+ * @author Joshua Estes <joshua@sonsofphp.com>
+ */
+interface PurchasableInterface extends AuthorizableInterface, CapturableInterface
+{
+    public function purchase($options): void;
+
+    public function purchaseComplete($options): void;
+}

src/SonsOfPHP/Contract/Gateway/README.md

@@ -0,0 +1,19 @@
+Sons of PHP - Gateway Contract
+==============================
+
+The Gateway Contract is an abstract way to interact with payment gateways or
+processors. An example of this would be Stripe.
+
+## Learn More
+
+* [Documentation][docs]
+* [Contributing][contributing]
+* [Report Issues][issues] and [Submit Pull Requests][pull-requests] in the [Mother Repository][mother-repo]
+* Get Help & Support using [Discussions][discussions]
+
+[discussions]: https://github.com/orgs/SonsOfPHP/discussions
+[mother-repo]: https://github.com/SonsOfPHP/sonsofphp
+[contributing]: https://docs.sonsofphp.com/contributing/
+[docs]: https://docs.sonsofphp.com/contracts/gateway/
+[issues]: https://github.com/SonsOfPHP/sonsofphp/issues?q=is%3Aopen+is%3Aissue+label%3AGateway
+[pull-requests]: https://github.com/SonsOfPHP/sonsofphp/pulls?q=is%3Aopen+is%3Apr+label%3AGateway

src/SonsOfPHP/Contract/Gateway/RefundableInterface.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Gateway;
+
+/**
+ * @author Joshua Estes <joshua@sonsofphp.com>
+ */
+interface RefundableInterface
+{
+    public function refund($options): void;
+}

src/SonsOfPHP/Contract/Gateway/RequestInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Gateway;
+
+/**
+ * @author Joshua Estes <joshua@sonsofphp.com>
+ */
+interface RequestInterface
+{
+}

src/SonsOfPHP/Contract/Gateway/ResponseInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Gateway;
+
+/**
+ * @author Joshua Estes <joshua@sonsofphp.com>
+ */
+interface ResponseInterface
+{
+}

src/SonsOfPHP/Contract/Gateway/TokenInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Gateway;
+
+/**
+ * @author Joshua Estes <joshua@sonsofphp.com>
+ */
+interface TokenInterface
+{
+}

src/SonsOfPHP/Contract/Gateway/TransactionInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Gateway;
+
+/**
+ * @author Joshua Estes <joshua@sonsofphp.com>
+ */
+interface TransactionInterface
+{
+}

src/SonsOfPHP/Contract/Gateway/VoidableInterface.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SonsOfPHP\Contract\Gateway;
+
+/**
+ * @author Joshua Estes <joshua@sonsofphp.com>
+ */
+interface VoidableInterface
+{
+    public function void($options): void;
+}