iamolayemi/laravel-paystack

A laravel package for working with paystack api

v1.0.1 2023-07-02 16:57 UTC

README

Latest Version on Packagist Total Downloads Build Status Code Quality Code Coverage PHP Version License

A comprehensive Laravel package for seamless integration with the Paystack payment gateway. This package provides an expressive and convenient way to interact with the Paystack API within your Laravel application.

โœจ Features

  • ๐Ÿš€ Fluent API Interface - Clean and intuitive method chaining
  • ๐Ÿ›ก๏ธ Comprehensive Error Handling - Custom exception classes for different error types
  • ๐Ÿ”’ Security First - Built-in validation and security checks
  • ๐Ÿ“Š Full API Coverage - Support for all Paystack API endpoints
  • ๐Ÿงช Extensive Testing - High test coverage with mock support
  • ๐Ÿ“š Excellent Documentation - Comprehensive guides and examples
  • ๐Ÿ”ง Developer Friendly - Easy setup and configuration
  • โšก Performance Optimized - Efficient HTTP client with retry logic
  • ๐ŸŒ Multi-Currency Support - NGN, GHS, USD, and more
  • ๐Ÿ”„ Webhook Support - Built-in webhook handling and verification

๐Ÿ“‹ Requirements

  • PHP: ^8.1|^8.2|^8.3
  • Laravel: ^9.0|^10.0|^11.0
  • Composer: ^2.0

๐Ÿš€ Installation

You can install the package via Composer:

composer require iamolayemi/laravel-paystack

The package will automatically register itself if you're using Laravel's auto-discovery feature.

โš™๏ธ Configuration

Environment Variables

Add your Paystack credentials to your .env file:

PAYSTACK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxx
PAYSTACK_PUBLIC_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxx
PAYSTACK_CALLBACK_URL=https://yourdomain.com/paystack/callback
PAYSTACK_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxx

Publishing Configuration (Optional)

php artisan vendor:publish --provider="Iamolayemi\Paystack\PaystackServiceProvider"

๐Ÿ“– Quick Start

Basic Usage

use Iamolayemi\Paystack\Facades\Paystack;

// Initialize a payment
$paymentData = [
    'amount' => 500000, // 5000 NGN in kobo
    'email' => 'customer@example.com',
    'reference' => 'PAY_' . uniqid(),
    'callback_url' => 'https://yourdomain.com/payment/callback',
];

$response = Paystack::transaction()
    ->initialize($paymentData)
    ->response();

if ($response['status']) {
    $authorizationUrl = $response['data']['authorization_url'];
    // Redirect user to $authorizationUrl
}

Using Helper Function

// Using the helper function
$response = paystack()->transaction()
    ->initialize($paymentData)
    ->response();

Getting Specific Data

// Get only the authorization URL
$authorizationUrl = Paystack::transaction()
    ->initialize($paymentData)
    ->response('data.authorization_url');

// Or use the dedicated method
$authorizationUrl = Paystack::transaction()
    ->initialize($paymentData)
    ->authorizationURL();

Verifying Transactions

// Verify a transaction
$reference = 'PAY_xxxxxxxxx';
$verification = Paystack::transaction()
    ->verify($reference)
    ->response();

if ($verification['status'] && $verification['data']['status'] === 'success') {
    // Payment was successful
    $amount = $verification['data']['amount'];
    $customerEmail = $verification['data']['customer']['email'];
}

๐Ÿ”ง Available Endpoints

The package provides access to all Paystack API endpoints:

Transactions

Paystack::transaction()->initialize($data);
Paystack::transaction()->verify($reference);
Paystack::transaction()->list($params);
Paystack::transaction()->fetch($id);

Customers

Paystack::customer()->create($data);
Paystack::customer()->list($params);
Paystack::customer()->fetch($emailOrCode);
Paystack::customer()->update($code, $data);

Transfers

Paystack::transfer()->initiate($data);
Paystack::transfer()->finalize($data);
Paystack::transfer()->list($params);
Paystack::transfer()->fetch($code);

Plans & Subscriptions

Paystack::plan()->create($data);
Paystack::plan()->list($params);
Paystack::subscription()->create($data);
Paystack::subscription()->list($params);

And Many More...

  • Banks: List banks, resolve account numbers
  • Countries: List countries and states
  • Invoices: Create and manage invoices
  • Products: Product management
  • Refunds: Process refunds
  • Settlements: Settlement management
  • Splits: Split payment configuration
  • Sub-accounts: Sub-account management

๐Ÿ›ก๏ธ Error Handling

The package provides comprehensive error handling with custom exception classes:

use Iamolayemi\Paystack\Exceptions\PaystackApiException;
use Iamolayemi\Paystack\Exceptions\PaystackValidationException;
use Iamolayemi\Paystack\Exceptions\PaystackConnectionException;

try {
    $response = Paystack::transaction()->initialize($data)->response();
} catch (PaystackValidationException $e) {
    // Handle validation errors
    $errors = $e->getErrors();
} catch (PaystackApiException $e) {
    // Handle API errors
    $message = $e->getMessage();
    $endpoint = $e->getEndpoint();
} catch (PaystackConnectionException $e) {
    // Handle connection errors
    $url = $e->getUrl();
}

๐Ÿงช Testing

Running Tests

# Run all tests
composer test

# Run with coverage
composer test-coverage

# Run specific test
vendor/bin/phpunit --filter=TransactionTest

Mock Testing

use Illuminate\Support\Facades\Http;

Http::fake([
    'api.paystack.co/transaction/initialize' => Http::response([
        'status' => true,
        'message' => 'Authorization URL created',
        'data' => [
            'authorization_url' => 'https://checkout.paystack.com/0x234567',
            'reference' => 'TEST_REF_123',
        ],
    ], 200),
]);

๐Ÿ“š Documentation

For detailed documentation, visit https://laravel-paystack.netlify.app

Additional Resources

๐Ÿ”ง Development

Prerequisites

  • PHP: ^8.1|^8.2|^8.3
  • Composer: ^2.0
  • Node.js: ^16.0 (for documentation)

Quick Setup

# Clone the repository
git clone https://github.com/iamolayemi/laravel-paystack.git
cd laravel-paystack

# Install dependencies
composer install

# Run all checks to ensure everything is working
make ci

Available Commands

The project uses a comprehensive Makefile for development tasks:

# Show all available commands
make help

# Install dependencies
make install

# Development workflow
make dev-setup          # Complete development setup
make dev-install        # Install development dependencies

Testing Commands

# Run all tests
make test

# Run tests with coverage report
make test-coverage

# Run specific test file
vendor/bin/phpunit tests/Unit/TransactionEndpointTest.php

# Run tests with specific filter
vendor/bin/phpunit --filter=testTransactionInitialization

Code Quality Commands

# Run static analysis with PHPStan
make analyse

# Fix code style issues automatically
make fix

# Check code style without fixing
make fix-dry-run

# Run all code quality checks
make check

Security & Validation

# Check for security vulnerabilities
make security-check

# Validate composer.json
make validate

CI/CD Commands

# Run complete CI pipeline (test + analyse + style + security)
make ci

# Run all checks (test + analyse + style)
make check

Maintenance Commands

# Clean build artifacts
make clean

# Update dependencies
make update

# Update only composer.lock
make update-lock

# Build the package for production
make build

Documentation Commands

# Generate documentation
make docs

# Build documentation (if using docs package)
cd docs && npm install && npm run build

Docker Commands (Optional)

# Build Docker image
make docker-build

# Run tests in Docker
make docker-test

# Run shell in Docker container
make docker-shell

Release Commands

# Release patch version (1.0.0 -> 1.0.1)
make release-patch

# Release minor version (1.0.0 -> 1.1.0)
make release-minor

# Release major version (1.0.0 -> 2.0.0)
make release-major

Development Workflow

  1. Setup: make dev-setup
  2. Make changes: Edit code
  3. Test: make test
  4. Check quality: make analyse
  5. Fix style: make fix
  6. Full validation: make ci
  7. Commit: git commit -m "Your message"
  8. Push: git push

Code Quality Standards

The project enforces high code quality standards:

  • PHPStan Level 8: Strict static analysis
  • Laravel Pint: PSR-12 coding standards
  • PHPUnit: 100% test coverage target
  • Security Checker: Vulnerability scanning

Testing Strategy

# Run all tests
make test

# Run with coverage (generates HTML report)
make test-coverage

# Run specific test suite
vendor/bin/phpunit --testsuite=Unit
vendor/bin/phpunit --testsuite=Feature

# Run tests with verbose output
vendor/bin/phpunit --verbose

# Run tests with stop on failure
vendor/bin/phpunit --stop-on-failure

Static Analysis

# Run PHPStan analysis
make analyse

# Run with specific level
vendor/bin/phpstan analyse --level=8

# Generate baseline (for ignoring existing errors)
vendor/bin/phpstan analyse --generate-baseline

Code Style

# Fix all code style issues
make fix

# Check what would be fixed
make fix-dry-run

# Fix specific file
vendor/bin/pint src/Endpoints/Transaction.php

Troubleshooting

# If tests fail, try cleaning and reinstalling
make clean
composer install
make test

# If PHPStan fails, check configuration
vendor/bin/phpstan analyse --debug

# If style check fails, auto-fix
make fix

IDE Setup

For the best development experience:

  1. PHPStorm/IntelliJ: Enable PHPStan integration
  2. VS Code: Install PHP extensions
  3. EditorConfig: Project includes .editorconfig
  4. PHP CS Fixer: Configuration in .php-cs-fixer.php

Pre-commit Hooks

Consider setting up pre-commit hooks:

# Create pre-commit hook
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/sh
make ci
EOF

chmod +x .git/hooks/pre-commit

๐Ÿค Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

  1. Fork the repository
  2. Clone your fork
  3. Install dependencies: composer install
  4. Run tests: make test
  5. Make your changes
  6. Ensure all tests pass: make ci
  7. Submit a pull request

๐Ÿ› Bug Reports

If you discover any bugs, please create an issue on GitHub.

๐Ÿ”’ Security

If you discover any security-related issues, please email olatayo.olayemi.peter@gmail.com instead of using the issue tracker.

๐Ÿ“„ License

The MIT License (MIT). Please see License File for more information.

๐Ÿ™ Credits

๐Ÿ”— Links

๐Ÿ“Š Statistics

  • Downloads: Total Downloads
  • Stars: GitHub stars
  • Forks: GitHub forks