From bb2d37545090878f1224e6024eeb40a2f2e69abc Mon Sep 17 00:00:00 2001 From: Joel Male Date: Wed, 18 Feb 2026 10:45:27 +1000 Subject: [PATCH] docs: rewrite README for current package state - Replace broken Scrutinizer/poser.pugx badges with shields.io - Add PHP version badge - Add Laravel/PHP compatibility table - Fix migration command (remove deprecated --package flag) - Modernize usage example with FQCN resolution - Simplify and tighten all sections - Remove outdated Psy Shell version references - Fix middleware class path reference - Add testing section --- README.md | 130 +++++++++++++++++++++++++----------------------------- 1 file changed, 59 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index aa704e9..2e392a6 100644 --- a/README.md +++ b/README.md @@ -1,115 +1,103 @@ -# Wearepixel's Laravel QuickBooks Client +# Laravel QuickBooks Client -[![Latest Stable Version](https://poser.pugx.org/wearepixel/laravel-quickbooks/v/stable)](https://packagist.org/packages/wearepixel/laravel-quickbooks) -[![Latest Unstable Version](https://poser.pugx.org/wearepixel/laravel-quickbooks/v/unstable)](https://packagist.org/packages/wearepixel/laravel-quickbooks) -[![Total Downloads](https://poser.pugx.org/wearepixel/laravel-quickbooks/downloads)](https://packagist.org/packages/wearepixel/laravel-quickbooks) -[![License](https://poser.pugx.org/wearepixel/laravel-quickbooks/license)](https://packagist.org/packages/wearepixel/laravel-quickbooks) +[![Latest Stable Version](https://img.shields.io/packagist/v/wearepixel/laravel-quickbooks.svg)](https://packagist.org/packages/wearepixel/laravel-quickbooks) +[![Total Downloads](https://img.shields.io/packagist/dt/wearepixel/laravel-quickbooks.svg)](https://packagist.org/packages/wearepixel/laravel-quickbooks) +[![License](https://img.shields.io/packagist/l/wearepixel/laravel-quickbooks.svg)](https://packagist.org/packages/wearepixel/laravel-quickbooks) +[![PHP Version](https://img.shields.io/packagist/dependency-v/wearepixel/laravel-quickbooks/php.svg)](https://packagist.org/packages/wearepixel/laravel-quickbooks) -PHP client wrapping the [QuickBooks PHP SDK](https://github.com/intuit/QuickBooks-V3-PHP-SDK). +A Laravel package wrapping the [QuickBooks PHP SDK](https://github.com/intuit/QuickBooks-V3-PHP-SDK). Provides OAuth 2.0 authentication, automatic token management, and access to the QuickBooks Online API. -We solely use [Laravel](https://www.laravel.com) for our applications, so this package is written with Laravel in mind. If there is a request from the community to split this package into 2 parts to allow it to be used outside of Laravel, then we will consider doing that work. +## Compatibility -## Build Status - -| Branch | Status | Coverage | Code Quality | -| ------ | :----: | :------: | :----------: | -| Master | [![Build Status](https://github.com/wearepixel/laravel-quickbooks/workflows/CI/badge.svg?branch=master)](https://github.com/wearepixel/laravel-quickbooks/workflows/CI/badge.svg?branch=master) | [![Code Coverage](https://scrutinizer-ci.com/g/wearepixel/laravel-quickbooks/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/wearepixel/laravel-quickbooks/?branch=master) | [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/wearepixel/laravel-quickbooks/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/wearepixel/laravel-quickbooks/?branch=main) | +| Laravel | PHP | Package | +|---------|------|---------| +| 12.x | ^8.3 | ^1.0 | +| 11.x | ^8.3 | ^1.0 | +| 10.x | ^8.3 | ^1.0 | ## Installation -1. Install QuickBooks PHP Client: +1. Install the package: ```bash -$ composer require wearepixel/laravel-quickbooks +composer require wearepixel/laravel-quickbooks ``` -2. Run our migration to install the `quickbooks_tokens` table: +2. Run the migration to create the `quickbooks_tokens` table: ```bash -$ php artisan migrate --package=wearepixel/laravel-quickbooks +php artisan migrate ``` -The package uses the [auto registration feature](https://laravel.com/docs/packages#package-discovery) of Laravel. +The package uses Laravel's [auto-discovery](https://laravel.com/docs/packages#package-discovery), so no manual provider registration is needed. ## Configuration -1. You will need a ```quickBooksToken``` relationship on your ```User``` model. There is a trait named ```Wearepixel\QuickBooks\HasQuickBooksToken```, which you can include on your ```User``` model, which will setup the relationship. To do this implement the following: - -Add ```use Wearepixel\QuickBooks\HasQuickBooksToken;``` to your service container at the top of User.php -and also add the trait within the class. For example: +### 1. Add the trait to your User model ```php +use Wearepixel\QuickBooks\HasQuickBooksToken; + class User extends Authenticatable { - use Notifiable, HasQuickBooksToken; + use HasQuickBooksToken; +} ``` -**NOTE: If your ```User``` model is not ```App\Models\User```, then you will need to configure the path in the ```configs/quickbooks.php```.** +If your User model is not `App\Models\User`, publish the config and update the `user.model` value. -2. Add the appropriate values to your ```.env``` +### 2. Set your environment variables - #### Minimal Keys - ```bash - QUICKBOOKS_CLIENT_ID= - QUICKBOOKS_CLIENT_SECRET= - ``` +```bash +QUICKBOOKS_CLIENT_ID= +QUICKBOOKS_CLIENT_SECRET= +``` - #### Optional Keys - ```bash - QUICKBOOKS_API_URL= # Defaults to App's env value - QUICKBOOKS_DEBUG= # Defaults to App's debug value - ``` +Optional: -3. _[Optional]_ Publish configs & views +```bash +QUICKBOOKS_API_URL= # Defaults based on APP_ENV +QUICKBOOKS_DEBUG= # Defaults to APP_DEBUG +``` - #### Config - A configuration file named ```quickbooks.php``` can be published to ```config/``` by running... +### 3. Publish config and views (optional) - ```bash - php artisan vendor:publish --tag=quickbooks-config - ``` - - #### Views - View files can be published by running... - - ```bash - php artisan vendor:publish --tag=quickbooks-views - ``` +```bash +php artisan vendor:publish --tag=quickbooks-config +php artisan vendor:publish --tag=quickbooks-views +``` ## Usage -Here is an example of getting the company information from QuickBooks: - -### NOTE: Before doing these commands, go to your connect route (default: /quickbooks/connect) to get a QuickBooks token for your user +First, direct users to `/quickbooks/connect` to authorize their QuickBooks account. Once connected, you can access the API: ```php -php artisan tinker -Psy Shell v0.8.17 (PHP 7.1.14 — cli) by Justin Hileman ->>> Auth::logInUsingId(1) -=> App\Models\User {#1668 - id: 1, - // Other keys removed for example - } ->>> $quickbooks = app('Wearepixel\QuickBooks\Client') // or app('QuickBooks') -=> Wearepixel\QuickBooks\Client {#1613} ->>> $quickbooks->getDataService()->getCompanyInfo(); -=> QuickBooksOnline\API\Data\IPPCompanyInfo {#1673 - +CompanyName: "Sandbox Company_US_1", - +LegalName: "Sandbox Company_US_1", - // Other properties removed for example - } ->>> +$quickbooks = app(\Wearepixel\QuickBooks\Client::class); + +// Get company info +$company = $quickbooks->getDataService()->getCompanyInfo(); + +// Access reports +$reportService = $quickbooks->getReportService(); ``` -You can call any of the resources as documented [in the SDK](https://intuit.github.io/QuickBooks-V3-PHP-SDK/quickstart.html). +You can call any of the resources documented in the [QuickBooks PHP SDK](https://intuit.github.io/QuickBooks-V3-PHP-SDK/quickstart.html). ## Middleware -If you have routes that will be dependent on the user's account having a usable QuickBooks OAuth token, there is an included middleware ```Wearepixel\QuickBooks\Laravel\Filter``` that gets registered as ```quickbooks``` that will ensure the account is linked and redirect them to the `connect` route if needed. - -Here is an example route definition: +Protect routes that require a QuickBooks connection using the `quickbooks` middleware. Users without a valid token will be redirected to the connect page. ```php -Route::view('some/route/needing/quickbooks/token/before/using', 'some.view') +Route::get('quickbooks/invoices', InvoiceController::class) ->middleware('quickbooks'); ``` + +## Testing + +```bash +./vendor/bin/pest +``` + +## License + +MIT