README

查看contributing.md以获取待办事项列表。

安装

通过 Composer

$ composer require lifeonscreen/laravel-quickbooks

发布包并运行迁移

$ php artisan vendor:publish
$ 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 LifeOnScreen\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(
        \LifeOnScreen\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 LifeOnScreen\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 模型的 LifeOnScreen\LaravelQuickBooks\QuickBooksEntity 类，或者您可以使用 LifeOnScreen\LaravelQuickBooks\SyncsToQuickBooks 特性。

然后您必须定义

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

用法示例

namespace App\Models\Company;

use LifeOnScreen\LaravelQuickBooks\QuickBooksEntity;
use LifeOnScreen\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 LifeOnScreen\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 资源类

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

示例

$customer = new LifeOnScreen\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 以获取更多文档。

变更日志

请参阅changelog以获取有关最近更改的更多信息。

贡献

请参阅contributing.md以获取详细信息及待办事项列表。

安全

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

鸣谢

• Jani Cerar，Aaron Harp

许可证

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