Initial docs build using Sphinx

.github/workflows/sphinx.yml

@@ -0,0 +1,24 @@
+name: "Build Documentation"
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v3
+    - name: Build HTML
+      uses: ammaraskar/sphinx-action@master
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v3
+      with:
+        name: html-docs
+        path: docs/build/html/
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.ref == 'refs/heads/main'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/build/html

.gitignore

@@ -5,4 +5,6 @@ composer.lock
 /build
 *-container*
 *.phpunit*
-test.php
+test.php
+/.venv
+/docs/build

README.rst

@@ -0,0 +1,5 @@
+Laravel PayPal
+==============
+
+**Laravel Paypal** is Laravel-based wrapper for utilization of PayPal Rest API.
+

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/billing_plans.rst

@@ -0,0 +1,5 @@
+:orphan:
+
+Billing Plans
+=============
+

docs/source/conf.py

@@ -0,0 +1,28 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Laravel PayPal'
+copyright = '2023, Raza Mehdi'
+author = 'Raza Mehdi'
+release = '1.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

docs/source/documentation.rst

@@ -0,0 +1,4 @@
+Documentation
+=============
+
+* :doc:`billing_plans`

docs/source/helpers.rst

@@ -0,0 +1,122 @@
+
+Helper Methods
+==============
+
+This package contains a lot of helper methods to make setting up API calls a lot easier. Here are all the available helper methods for performing API calls.
+
+
+Subscription: Create Recurring Subscription (Daily)
+---------------------------------------------------
+
+.. code-block:: console
+
+    $response = $provider->addProduct('Demo Product', 'Demo Product', 'SERVICE', 'SOFTWARE')
+    ->addPlanTrialPricing('DAY', 7)
+    ->addDailyPlan('Demo Plan', 'Demo Plan', 1.50)
+    ->setReturnAndCancelUrl('https://example.com/paypal-success', 'https://example.com/paypal-cancel')
+    ->setupSubscription('John Doe', '[email protected]', '2021-12-10');
+
+
+Subscription: Create Recurring Subscription (Weekly)
+----------------------------------------------------
+
+.. code-block:: console
+
+    $response = $provider->addProduct('Demo Product', 'Demo Product', 'SERVICE', 'SOFTWARE')
+    ->addPlanTrialPricing('DAY', 7)
+    ->addWeeklyPlan('Demo Plan', 'Demo Plan', 30)
+    ->setReturnAndCancelUrl('https://example.com/paypal-success', 'https://example.com/paypal-cancel')
+    ->setupSubscription('John Doe', '[email protected]', '2021-12-10');
+
+
+Subscription: Create Recurring Subscription (Monthly)
+-----------------------------------------------------
+
+.. code-block:: console
+
+    $response = $provider->addProduct('Demo Product', 'Demo Product', 'SERVICE', 'SOFTWARE')
+    ->addPlanTrialPricing('DAY', 7)
+    ->addMonthlyPlan('Demo Plan', 'Demo Plan', 100)
+    ->setReturnAndCancelUrl('https://example.com/paypal-success', 'https://example.com/paypal-cancel')
+    ->setupSubscription('John Doe', '[email protected]', '2021-12-10'); 
+
+
+Subscription: Create Recurring Subscription (Annual)
+----------------------------------------------------
+
+.. code-block:: console
+
+    $response = $provider->addProduct('Demo Product', 'Demo Product', 'SERVICE', 'SOFTWARE')
+    ->addPlanTrialPricing('DAY', 7)
+    ->addAnnualPlan('Demo Plan', 'Demo Plan', 600)
+    ->setReturnAndCancelUrl('https://example.com/paypal-success', 'https://example.com/paypal-cancel')
+    ->setupSubscription('John Doe', '[email protected]', '2021-12-10');
+
+
+Subscription: Create Recurring Subscription (Custom Intervals)
+--------------------------------------------------------------
+
+.. code-block:: console
+
+    $response = $provider->addProduct('Demo Product', 'Demo Product', 'SERVICE', 'SOFTWARE')
+    ->addCustomPlan('Demo Plan', 'Demo Plan', 150, 'MONTH', 3)
+    ->setReturnAndCancelUrl('https://example.com/paypal-success', 'https://example.com/paypal-cancel')
+    ->setupSubscription('John Doe', '[email protected]', '2021-12-10');
+
+
+Subscription: Create Subscription with Existing Product & Billing Plan
+----------------------------------------------------------------------
+
+.. code-block:: console
+
+    $response = $this->client->addProductById('PROD-XYAB12ABSB7868434')
+    ->addBillingPlanById('P-5ML4271244454362WXNWU5NQ')
+    ->setReturnAndCancelUrl('https://example.com/paypal-success', 'https://example.com/paypal-cancel')
+    ->setupSubscription('John Doe', '[email protected]', '2021-12-10');   
+
+
+Subscription: Create Subscription with Setup Fee
+------------------------------------------------
+
+.. code-block:: console
+
+    $response = $this->client->addSetupFee(9.99)
+    ->addProductById('PROD-XYAB12ABSB7868434')
+    ->addBillingPlanById('P-5ML4271244454362WXNWU5NQ')
+    ->setReturnAndCancelUrl('https://example.com/paypal-success', 'https://example.com/paypal-cancel')
+    ->setupSubscription('John Doe', '[email protected]', '2021-12-10');  
+
+
+Subscription: Create Subscription with Shipping Address
+-------------------------------------------------------
+
+.. code-block:: console
+
+    $response = $this->client->addShippingAddress('John Doe', 'House no. 123', 'Street 456', 'Test Area', 'Test Area', 10001, 'US')
+    ->addProductById('PROD-XYAB12ABSB7868434')
+    ->addBillingPlanById('P-5ML4271244454362WXNWU5NQ')
+    ->setReturnAndCancelUrl('https://example.com/paypal-success', 'https://example.com/paypal-cancel')
+    ->setupSubscription('John Doe', '[email protected]', '2021-12-10'); 
+
+
+Subscription: Create Subscription with Payment Failure Threshold
+----------------------------------------------------------------
+
+.. code-block:: console
+
+    $response = $this->client->addPaymentFailureThreshold(5)
+    ->addProductById('PROD-XYAB12ABSB7868434')
+    ->addBillingPlanById('P-5ML4271244454362WXNWU5NQ')
+    ->setReturnAndCancelUrl('https://example.com/paypal-success', 'https://example.com/paypal-cancel')
+    ->setupSubscription('John Doe', '[email protected]', '2021-12-10');    
+
+
+Billing Plans: Update Pricing Schemes
+-------------------------------------
+
+.. code-block:: console
+
+    $response = $this->client->addBillingPlanById('P-5ML4271244454362WXNWU5NQ')
+    ->addPricingScheme('DAY', 7, 0, true)
+    ->addPricingScheme('MONTH', 1, 100)
+    ->processBillingPlanPricingUpdates();   

docs/source/index.rst

@@ -0,0 +1,16 @@
+.. Laravel PayPal documentation master file, created by
+   sphinx-quickstart on Wed Sep  6 01:27:06 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Laravel PayPal's documentation!
+==========================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   usage
+   helpers
+   documentation

docs/source/installation.rst

@@ -0,0 +1,90 @@
+
+Installation
+============
+
+This package utilizes PayPal Rest API under the hood. If you are using PayPal Express Checkout, please refer to the README for v1 here:
+
+https://github.com/srmklive/laravel-paypal/blob/v1.0/README.md
+
+
+For installation, run the following commands:
+
+Laravel 5.1 to 5.8
+------------------
+
+.. code-block:: console
+
+    composer require srmklive/paypal:~2.0
+
+Laravel 6 & above
+-----------------
+
+.. code-block:: console
+
+    composer require srmklive/paypal:~3.0
+
+
+Publishing Assets
+=================
+
+After installation, you can use the following commands to publish the assets:
+
+.. code-block:: console
+
+    php artisan vendor:publish --provider "Srmklive\PayPal\Providers\PayPalServiceProvider"
+
+
+Configuration
+=============
+
+.. code-block:: console
+
+    # PayPal API Mode
+    # Values: sandbox or live (Default: live)
+    PAYPAL_MODE=
+
+    #PayPal Setting & API Credentials - sandbox
+    PAYPAL_SANDBOX_CLIENT_ID=
+    PAYPAL_SANDBOX_CLIENT_SECRET=
+
+    #PayPal Setting & API Credentials - live
+    PAYPAL_LIVE_CLIENT_ID=
+    PAYPAL_LIVE_CLIENT_SECRET=
+    PAYPAL_LIVE_APP_ID=
+
+    # Payment Action. Can only be 'Sale', 'Authorization' or 'Order'
+    PAYPAL_PAYMENT_ACTION=Sale
+
+    # Currency. Default is USD. If you need to update it, then set the value through the PAYPAL_CURRENCY environment variable.
+    PAYPAL_CURRENCY=EUR
+
+    # Validate SSL when creating api client. By default, the value is great. To disable validation set to false.
+    PAYPAL_VALIDATE_SSL=false
+
+
+Configuration File
+==================
+
+The configuration file **paypal.php** is located in the **config** folder. Following are its contents when published:
+
+.. code-block:: console
+
+    return [
+        'mode'    => env('PAYPAL_MODE', 'sandbox'), // Can only be 'sandbox' Or 'live'. If empty or invalid, 'live' will be used.
+        'sandbox' => [
+            'client_id'         => env('PAYPAL_SANDBOX_CLIENT_ID', ''),
+            'client_secret'     => env('PAYPAL_SANDBOX_CLIENT_SECRET', ''),
+            'app_id'            => 'APP-80W284485P519543T',
+        ],
+        'live' => [
+            'client_id'         => env('PAYPAL_LIVE_CLIENT_ID', ''),
+            'client_secret'     => env('PAYPAL_LIVE_CLIENT_SECRET', ''),
+            'app_id'            => '',
+        ],
+
+        'payment_action' => env('PAYPAL_PAYMENT_ACTION', 'Sale'), // Can only be 'Sale', 'Authorization' or 'Order'
+        'currency'       => env('PAYPAL_CURRENCY', 'USD'),
+        'notify_url'     => env('PAYPAL_NOTIFY_URL', ''), // Change this accordingly for your application.
+        'locale'         => env('PAYPAL_LOCALE', 'en_US'), // force gateway language  i.e. it_IT, es_ES, en_US ... (for express checkout only)
+        'validate_ssl'   => env('PAYPAL_VALIDATE_SSL', true), // Validate SSL when creating api client.
+    ];