README

安装

通过 Composer

$ composer require ajay-patidar/laravel-quickbooks

发布包并运行迁移

$ php artisan vendor:publish --provider="AjayPatidar\LaravelQuickBooks\LaravelQuickBooksServiceProvider" --tag="quickbooks.config"
$ php artisan migrate

使用方法

配置

以下是在您的 .env 文件中需要设置的变量。

# Client ID from the app's keys tab.
QB_CLIENT_ID=

# Client Secret from the app's keys tab.
QB_CLIENT_SECRET=

# The redirect URI provided on the Redirect URIs part under keys tab.
QB_REDIRECT_URI=

# Quickbooks scope com.intuit.quickbooks.accounting or com.intuit.quickbooks.payment
QB_SCOPE=

# Development/Production
QB_BASE_URL=

令牌处理

由于每个应用程序的设置都不同，您需要创建一个扩展 QuickBooksTokenHandler 的类来在数据库中持久化令牌。默认情况下，令牌使用 Laravel 缓存 API 存储，有效期为 7 天。

例如，如果您使用 Laravel Options 包，您可以在项目中的某个位置创建以下类

namespace App\QuickBooks;

use AjayPatidar\LaravelQuickBooks\QuickBooksTokenHandler;

class TokenHandler extends QuickBooksTokenHandler
{
    public function set($key, $value)
    {
        option([$key => $value]);
    }

    public function get($key)
    {
        return option($key);
    }
}

然后在 AppServiceProvider.php 中绑定它

public function boot()
{        
    $this->app->bind(
        \AjayPatidar\LaravelQuickBooks\QuickBooksTokenHandlerInterface::class, 
        \App\QuickBooks\TokenHandler::class
    );
}

连接 QuickBooks 账户

要连接您的应用程序与 QuickBooks 公司，您可以使用 QuickBooksAuthenticator 助手。它有两个方法

• getAuthorizationUrl() - 返回重定向 URL 并将 quickbooks_auth cookie 放入 Laravel cookie 队列。Cookie 有效期为 30 分钟。
• processHook() - 验证 quickbooks_auth cookie 并设置 realm id、访问令牌和刷新令牌。

使用示例

namespace App\Http\Controllers;

use AjayPatidar\LaravelQuickBooks\QuickBooksAuthenticator;
use Cookie;

class QuickBooksController extends Controller
{
    public function connect()
    {
        return redirect(QuickBooksAuthenticator::getAuthorizationUrl())
            ->withCookies(Cookie::getQueuedCookies());
    }

    public function refreshTokens()
    {
        if (QuickBooksAuthenticator::processHook()) {
            return 'Tokens successfully refreshed.';
        }

        return 'There were some problems refreshing tokens.';
    }
}

同步 Eloquent 模型到 QuickBooks

您可以选择扩展已扩展 Eloquent 模型的 AjayPatidar\LaravelQuickBooks\QuickBooksEntity 类，或者您可以使用 AjayPatidar\LaravelQuickBooks\SyncsToQuickBooks 特性。

然后您需要定义

• quickBooksResource - QuickBooks 资源类之一（例如 \AjayPatidar\LaravelQuickBooks\Resources\Company::class）。
• getQuickBooksArray() - 此方法必须返回要同步到 QuickBooks 的关联数组。
• quickBooksIdColumn（可选）- 用于存储 QuickBooks ID 的列（默认为 quickbooks_id）

使用示例

namespace App\Models\Company;

use AjayPatidar\LaravelQuickBooks\QuickBooksEntity;
use AjayPatidar\LaravelQuickBooks\Resources\Customer;

class Company extends QuickBooksEntity
{
    /**
     * Database column name
     * This is optional default value is 'quickbooks_id'
     * @var string
     */
    protected $quickBooksIdColumn = 'quickbooks_id';
        
    /**
     * Use one of AjayPatidar\LaravelQuickBooks\Resources classes
     * @var array
     */
    protected $quickBooksResource = Customer::class;
    
    /**
     * @return array
     */
    protected function getQuickBooksArray(): array
    {
        return [
            'CompanyName'  => 'Example name',
            'DisplayName'  => 'Example display name',
            //...
        ];
    }
}

当您要同步资源时，必须调用 syncToQuickBooks()。如果同步成功，则方法返回 true。您可以使用方法 getLastQuickBooksError() 获取最后一个 QuickBooks 错误。

同步示例

/**
 * @return string
 * @throws \Exception
 */
public function syncExample()
{
    $company = Company::find(1);
    if ($company->syncToQuickBooks()){
        return 'Success';
    }
    return $company->getLastQuickBooksError();
}

使用 QuickBooks 资源类

您可以使用包含在 AjayPatidar\LaravelQuickBooks\Resources 中的资源类来创建、更新和查询 QuickBooks 中的资源。

示例

$customer = new AjayPatidar\LaravelQuickBooks\Resources\Customer;

// create
$customer->create([
    'GivenName'  => 'John',
    'FamilyName' => 'Smith',
]);

// update item with ID "123"
$customer->update(123, [
    'GivenName'  => 'John',
    'FamilyName' => 'Smith',
]);

// find by ID:
$customer->find(123);

// find by a specific field:
$customer->findBy('FamilyName', 'Smith');

// find multiple items:
$customer->query();

请参阅 QuickBooksResource.php 获取更多文档。

安全

如果您发现任何与安全相关的问题，请通过电子邮件联系作者而不是使用问题跟踪器。

致谢

• LifeOnScreen

许可证

MIT 许可证。有关更多信息，请参阅许可证文件。