README

A PHP package to integrate with QuickBooks Online (QBO), including authentication, customer management, and local synchronization.

Project Structure

src/
├── Auth/ # OAuth2 token handling
│ └── Authentication.php
├── Client/ # HTTP clients per QBO entity (13 files)
│ ├── BaseClient.php
│ ├── CustomerClient.php
│ ├── InvoiceClient.php
│ └── ...
├── Config/ # QBO SDK configuration
│ └── QboConfig.php
├── Contracts/ # Interfaces for DI
│ ├── HttpClientInterface.php
│ └── LoggerInterface.php
├── Controller/ # OAuth callback handling
│ └── OAuthController.php
├── Entities/ # Domain models
│ └── Customer.php
├── Facade/ # Main entry point
│ └── QuickBooksManager.php
├── Repositories/ # DB persistence layer (17 repos)
│ ├── TokenRepository.php
│ └── ...
├── Resources/views/ # HTML connect button view
├── Services/ # Sync logic (local → QBO)
│ ├── CustomerSyncService.php
│ └── ...
├── Support/ # Utilities: EnvLoader, DatabaseLogger, DefaultHttpClient
├── Utils/ # VendorNameGenerator.php
└── Validation/ # Input validators
 ├── BillValidator.php
 └── ...

Installation

You can install the package via Composer:

composer require excelle-insights/quickbooks:dev-main

Environment Setup

Create a .env file in your project root (or rely on the package .env):

# QuickBooks API
QBO_BASE_URL=https://quickbooks.api.intuit.com
QBO_CLIENT_ID=YOUR_CLIENT_ID
QBO_CLIENT_SECRET=YOUR_CLIENT_SECRET
QBO_REALM_ID=YOUR_COMPANY_ID
QBO_REDIRECT_URI=http://gimco.local/admin/debug_scripts/qbo-auth-callback.php
QBO_TABLE_PREFIX=qbo_beta

# Database connection
DB_DSN=mysql:host=127.0.0.1;dbname=myapp
DB_USER=root
DB_PASSWORD=secret

The package automatically loads its own .env if present.

Running Migrations

This package uses Phinx for database migrations.

1. Run the migrations:

php vendor/excelle-insights/quickbooks/migrate.php

For testing while developing the package, use the following command

php migrate.php --debug=true

Tables created include:

• api_access_tokens
• qbo_invoice_items
• http_request_logs
• qbo_accounts
• qbo_companies
• qbo_customers
• qbo_invoices
• qbo_invoice_items
• qbo_journal_entries
• qbo_journal_entry_lines
• qbo_payments
• qbo_payment_items
• qbo_vendors
• qbo_bills
• qbo_bill_items

Quick Start

1. Get the OAuth Authorization URL

This script generates a link for the user to authorize your app in QuickBooks:

<?php
require '../../vendor/autoload.php';

use ExcelleInsights\QuickBooks\Facade\QuickBooksManager;
use ExcelleInsights\QuickBooks\Controller\OAuthController;

// Initialize
$qbo = new QuickBooksManager(null, null, dirname(__DIR__, 2));
$oauth = new OAuthController($qbo);

// Get QuickBooks authorization URL
echo $qbo->getAuthUrl();

1. Handle OAuth Callback

After the user authorizes your app, QuickBooks redirects back to your callback URL. This script handles that callback:

<?php
require '../../vendor/autoload.php';

use ExcelleInsights\QuickBooks\Facade\QuickBooksManager;
use ExcelleInsights\QuickBooks\Controller\OAuthController;

$qbo = new QuickBooksManager();
$oauth = new OAuthController($qbo);

// Display result of OAuth callback
echo $oauth->handleCallback();

1. Create a Customer

This script creates a customer locally and attempts to sync it with QuickBooks Online:

<?php
require '../../vendor/autoload.php';

use ExcelleInsights\QuickBooks\Facade\QuickBooksManager;

// Initialize the manager
$qbo = new QuickBooksManager();

$index = 1;

$result = $qbo->createCustomer([
 'qbo_company_id' => 1,
 'name' => 'Test Customer'.$index,
 'email' => 'testcustomer'.$index.'@email.com',
 'phone' => '+254724565654'.$index,
 'company_name' => 'Test Company '.$index,
 'country' => 'Kenya',
 'city' => 'Nairobi',
 'postal_code' => '00100',
 'line' => 'Ngong Road',
]);

if ($result->status === 'synced') {
 echo "Customer synced with QBO ID: " . $result->qbo_id;
} else {
 echo "Customer queued for retry. Local ID: " . $result->local_id;
}

1. Create an Invoice

This script creates an invoice locally and attempts to sync it with QuickBooks Online:

<?php
require '../../vendor/autoload.php';

use ExcelleInsights\QuickBooks\Facade\QuickBooksManager;

// Initialize the manager
$qbo = new QuickBooksManager();

// Create an invoice
$result = $qbo->createInvoice([
 'qbo_company_id' => 1,
 'qbo_customer_id' => 11, // Replace with actual QBO customer ID
 'invoice_number' => 'INV-001',
 'txn_date' => '2026-01-22',
 'due_date' => '2026-02-05',
 'currency' => 'KES',
 'items' => [
 [
 'description' => 'Consulting Services',
 'quantity' => 1,
 'unit_price' => 5000,
 'amount' => 5000, // quantity * unit_price
 ],
 [
 'description' => 'Software License',
 'quantity' => 2,
 'unit_price' => 1500,
 'amount' => 3000,
 ],
 ],
]);

if ($result->status === 'synced') {
 echo "Invoice synced with QBO ID: " . $result->qbo_id;
} else {
 echo "Invoice queued for retry. Local ID: " . $result->local_id;
 if (!empty($result->error)) {
 echo "\nError: " . $result->error;
 }
}

Testing

The package uses PHPUnit for testing. To run tests:

vendor/bin/phpunit tests

Ensure your .env (or package .env) is configured with valid database and QBO credentials.

Features

• Automatic OAuth2 authentication with QuickBooks Online.
• Local persistence of customers in qbo_customers table.
• Queue system for failed QuickBooks syncs.
• Easy access to QuickBooks API via QuickBooksManager.
• Extensible for invoices, payments, and other QBO objects.

Example Workflow

• Initialize QuickBooksManager.
• Redirect user to QuickBooks authorization page using getAuthUrl().
• Handle the callback via OAuthController.
• Create customers locally and sync with QBO using createCustomer().
• Create invoices locally and sync with QBO using createInvoice().