mirror of
https://github.com/wearepixel/laravel-quickbooks.git
synced 2026-11-14 22:11:50 +00:00
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
This commit is contained in:
Joel Male
@@ -1,115 +1,103 @@
|
||||
# Wearepixel's Laravel QuickBooks Client
|
||||
# Laravel QuickBooks Client
|
||||
|
||||
[](https://packagist.org/packages/wearepixel/laravel-quickbooks)
|
||||
[](https://packagist.org/packages/wearepixel/laravel-quickbooks)
|
||||
[](https://packagist.org/packages/wearepixel/laravel-quickbooks)
|
||||
[](https://packagist.org/packages/wearepixel/laravel-quickbooks)
|
||||
[](https://packagist.org/packages/wearepixel/laravel-quickbooks)
|
||||
[](https://packagist.org/packages/wearepixel/laravel-quickbooks)
|
||||
[](https://packagist.org/packages/wearepixel/laravel-quickbooks)
|
||||
[](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 | [](https://github.com/wearepixel/laravel-quickbooks/workflows/CI/badge.svg?branch=master) | [](https://scrutinizer-ci.com/g/wearepixel/laravel-quickbooks/?branch=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=<client id given by QuickBooks>
|
||||
QUICKBOOKS_CLIENT_SECRET=<client secret>
|
||||
```
|
||||
```bash
|
||||
QUICKBOOKS_CLIENT_ID=<your client id>
|
||||
QUICKBOOKS_CLIENT_SECRET=<your client secret>
|
||||
```
|
||||
|
||||
#### Optional Keys
|
||||
```bash
|
||||
QUICKBOOKS_API_URL=<Development|Production> # Defaults to App's env value
|
||||
QUICKBOOKS_DEBUG=<true|false> # Defaults to App's debug value
|
||||
```
|
||||
Optional:
|
||||
|
||||
3. _[Optional]_ Publish configs & views
|
||||
```bash
|
||||
QUICKBOOKS_API_URL=<Development|Production> # Defaults based on APP_ENV
|
||||
QUICKBOOKS_DEBUG=<true|false> # 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
|
||||
|
||||
Reference in New Issue
Block a user