aybarsm / laravel-pandle
Highly customisable Laravel service provider package for Pandle (pandle.com) bookkeeping platform API.
Requires
- php: ^8.3
- laravel/framework: ^11.37.0
Requires (Dev)
- laravel/pint: ^1.18.1
- pestphp/pest: ^3.5.0
- pestphp/pest-plugin-arch: ^3.0.0
- phpstan/phpstan: ^1.12.7
- symfony/var-dumper: ^7.2.0
README
A highly customizable Laravel service provider package for the Pandle (pandle.com) bookkeeping platform API.
Installation
You can install the package via composer:
composer require aybarsm/laravel-pandle
Configuration
Publish the configuration file:
php artisan vendor:publish --provider="Aybarsm\Laravel\Pandle\PandleServiceProvider"
Add the following environment variables to your .env
file:
# Pandle E-Mail PANDLE_EMAIL=your-pandle-email # Pandle Password PANDLE_PASSWORD=your-pandle-password # Pandle Base URL (optional, defaults to https://my.pandle.com/api/v1) PANDLE_BASE_URL=https://my.pandle.com/api/v1 # Pandle Default Company ID (optional, defaults to null) # If set, the package will use this company ID for company-specific operations. # However, $client->company(123456) will create a new company instance for the given ID (123456). PANDLE_COMPANY_ID=your-company-id # Cache is being used to store access tokens. # Cache is always encrypted. # Cache Enabled PANDLE_CACHE_ENABLED=false # Cache Store PANDLE_CACHE_STORE=database # Cache Key PANDLE_CACHE_KEY=pandle
Usage
Basic Usage
use Aybarsm\Laravel\Pandle\Contracts\ClientContract as PandleClient; class YourController extends Controller { public function __construct(protected PandleClient $pandle) {} public function index() { // Get authenticated user info $me = $this->pandle->me(); // Get company instance $company = $this->pandle->company(123456); // Get bank accounts $bankAccounts = $company->getBankAccounts(); // Get customers $customers = $company->getCustomers(); } }
Architecture & Design
Dependency Injection
This package implements a clean dependency injection pattern with no circular dependencies. All concrete implementations are referenced through their corresponding interfaces (abstracts):
use Aybarsm\Laravel\Pandle\Contracts\ClientContract; use Aybarsm\Laravel\Pandle\Contracts\HandlerContract; use Aybarsm\Laravel\Pandle\Contracts\CompanyContract; use Aybarsm\Laravel\Pandle\Contracts\AccessTokenContract; // Example of clean DI in action class Company implements CompanyContract { public function __construct( protected ClientContract $client ) {} }
This architectural decision provides several key benefits:
- Performance: No circular dependencies means faster instantiation and reduced memory usage
- Testability: Easy to mock dependencies for unit testing
- Maintainability: Clear separation of concerns and dependencies
- Flexibility: Simple to replace any component without affecting others
- Reliability: Prevents complex dependency chains that can lead to runtime issues
Customisation
The concretes in this package are not extensible. However, the package is designed to be highly customisable. All core components can be replaced with your own implementations by binding them before the PandleServiceProvider registers its defaults.
<?php declare(strict_types=1); namespace Aybarsm\Laravel\Pandle; use Aybarsm\Laravel\Pandle\Contracts\AccessTokenContract; use Aybarsm\Laravel\Pandle\Contracts\ClientContract; use Aybarsm\Laravel\Pandle\Contracts\CompanyContract; use Aybarsm\Laravel\Pandle\Contracts\HandlerContract; use Illuminate\Support\ServiceProvider; final class PandleServiceProvider extends ServiceProvider { public function register(): void { $this->mergeConfigFrom( __DIR__.'/../config/pandle.php', 'pandle' ); $this->app->bindIf(AccessTokenContract::class, AccessToken::class); $this->app->singletonIf(HandlerContract::class, Handler::class); $this->app->bindIf(CompanyContract::class, Company::class); $this->app->singletonIf(ClientContract::class, Client::class); } public function boot(): void { if ($this->app->runningInConsole()) { $this->publishes([ __DIR__.'/../config/pandle.php' => config_path('pandle.php'), ]); } } }
Available Contracts for Customisation
-
AccessTokenContract
- Default Abstract:
Aybarsm\Laravel\Pandle\Contracts\AccessTokenContract::class
- Default Concrete:
Aybarsm\Laravel\Pandle\AccessToken::class
- Handles access token management
- Default Abstract:
-
HandlerContract
- Default Abstract:
Aybarsm\Laravel\Pandle\Contracts\HandlerContract::class
- Default Concrete:
Aybarsm\Laravel\Pandle\Handler::class
- Manages HTTP requests and response handling
- Singleton by default for consistent request handling
- Default Abstract:
-
CompanyContract
- Default Abstract:
Aybarsm\Laravel\Pandle\Contracts\CompanyContract::class
- Default Concrete:
Aybarsm\Laravel\Pandle\Company::class
- Handles company-specific operations
- Default Abstract:
-
ClientContract
- Default Abstract:
Aybarsm\Laravel\Pandle\Contracts\ClientContract::class
- Default Concrete:
Aybarsm\Laravel\Pandle\Client::class
- Main client interface for API interactions
- Singleton by default for connection pooling
- Default Abstract:
Example: Custom Handler Concrete Implementation
Here's an example of implementing a custom handler with logging capabilities:
You can customize the implementations in your AppServiceProvider
's register method:
<?php namespace App\Providers; use Aybarsm\Laravel\Pandle\Contracts\HandlerContract; use Your\Custom\PandleHandler; class AppServiceProvider extends ServiceProvider { public function register(): void { $this->app->singleton(HandlerContract::class, function ($app){ return new PandleHandler(); }); } }
Error Handling
The package throws PandleException
for API-related errors. You can catch these exceptions to handle errors gracefully:
use Aybarsm\Laravel\Pandle\Exceptions\PandleException; try { $company->createCustomer($data); } catch (PandleException $e) { // Handle the error $statusCode = $e->getCode(); $message = $e->getMessage(); }
Security
If you discover any security related issues, please email hello@aybarsm.com instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.