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并设置领域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许可。请参阅许可文件以获取更多信息。

lifeonscreen/ laravel-quickbooks

维护者

详细信息