README

安装

composer require whitecube/winbooks-on-web-php-client

使用

认证

在您可以进行任何操作之前，您必须通过 API 进行认证。这通过 OAuth 2.0 完成，因此您需要 Winbooks On Web 提供的电子邮件和 Exchange Token。您可以通过遵循 以下步骤 来获取这些信息。

当您准备好了，您可以使用它们来请求 API 授予您访问令牌和刷新令牌。访问令牌是授权每个请求所必需的，而刷新令牌用于在访问令牌过期时获取新的访问令牌。

当您创建 Winbooks 客户端实例时，如果您已经有了它们，可以直接给它访问令牌和刷新令牌。如果没有，您可以在之后简单地调用 authenticate($email, $exchange_token)，这将为您授予那些令牌，然后您应该保存并重新使用它们，在下一次创建客户端实例时。

use Whitecube\Winbooks\Winbooks;

// $access_token and $refresh_token can be null if you do not have them yet
$winbooks = new Winbooks($access_token, $refresh_token);

if(! $winbooks->authenticated()) {
    [$access_token, $refresh_token] = $winbooks->authenticate($email, $exchange_token);
    // Store the tokens somewhere safe
}

// Now you can start using the API

指定文件夹

您可以设置文件夹一次，之后的所有请求都将使用它。

$winbooks->folder('TEST_FOLDER');

$winbooks->get(/*...*/)

获取数据

所有获取方法将直接从 WoW 返回 JSON 数据，如果可能，已经解码并包装到对象模型实例中。

返回所有数据

要获取对象模型的所有结果，请使用 all($object_model, $max_level = 1) 方法。

$customers = $winbooks->all('Customers');

警告：根据您的数据集大小和服务器内存限制，由于结果未分页，all() 可能会导致严重的服务器错误。API 包装器将继续获取对象，直到 Winbook 的 REST API 指示已传输所有内容。这是一个相当大的问题，在 Winbook 的文档 中进行了记录，并且在此包中不会修复，直到 Winbook 的 REST API 实现适当的分页选项。如果您需要分页，则建议 使用查询。

返回单个对象模型的数据

要获取对象模型的单个结果，请使用 get($object_model, $code, $max_level = 1) 方法。

注意：如果您有 ID，可以用 $code 替换。

$vlad = $winbooks->get('Customer', 'VLADIMIR');
// With ID
$vlad = $winbooks->get('Customer', '4713a22f-ebc0-ea11-80c7-0050s68cc4a2');

要指定您想要嵌套的数据量（maxLevel 参数），可以将它作为第三个参数传递给 get 方法。

$vlad = $winbooks->get('Customer', 'VLADIMIR', 3);

查询数据

列出对象模型通常比获取所有结果更复杂。为了获得更精确的结果，建议使用此包中提供的查询构建器。这将使 API 交互更加精确，因此是一种提高性能的绝佳方式。

可以使用 query($object_model, $query_builder, $max_level = 1) 方法发送查询。

$results = $winbooks->query('Customers', function($query) {
    // Build your query...
    $query->select('Id', 'Code')->orderBy('Created', 'desc')->paginate(20);
});

选择（投影列表）

要仅投影少量属性而不是完整的对象模型，建议使用 select(...$properties) 方法

$query->select('Id', 'VatApplicable', 'Memo');

要执行特定的选择，请使用 selectOperator($operator, ...$properties) 方法

use Whitecube\Winbooks\Query\Operator;

$query->selectOperator(Operator::distinct(), 'Id', 'VatApplicable', 'Memo');

条件（WHERE）

简单的 = 条件可以按以下方式应用

$query->where('Id', '4713a22f-ebc0-ea11-80c7-0050s68cc4a2');

对于其他比较方法，使用常见的 >、>=、< 和 <= 符号。

$query->where('Amount', '>=', 1000.00);

甚至更复杂的操作符（这里是可以使用的 操作符完整列表）

use Whitecube\Winbooks\Query\Operator;

$query->where('Name', 'like', '%Vlad%');
// or
$query->where('Name', Operator::having(), 'something');

有时需要比较对象模型的属性。

use Whitecube\Winbooks\Query;

$query->where('Code', '=', Query::property('Id'));

排序

要按特定方式排序结果，请使用 orderBy($property, $direction) 方法。

注意：可以通过链式调用多个 orderBy() 调用来定义更细致的结果排序。

$query->orderBy('Amount', 'desc');

关系和连接（关联）

大多数对象模型都与子模型在此包中定义的关联，这使得查询关联对象模型的关系变得容易。如果遗漏了某些关联，请随时提交一个 PR。

$query->with('third');

with($relation, $configurator) 方法允许通过提供第二个参数的回调函数来覆盖默认关系配置。

$query->with('third', function($join) {
    $join->on('Third_Id', 'Id')->owner('something')->alias('person');
});

对于更高级或不可用的关系，也可以使用您自己的连接来关联数据。

use Whitecube\Winbooks\Models\Logistics\DocumentHeader;

$query->join(DocumentHeader::class, function($join) {
    $join->on('DocumentHeader_Id', '=', 'Some_Property')->alias('header');
});

限制结果和分页

限制查询结果的数量通常很有必要，以避免无休止的请求。只需使用 take($amount) 方法来限制结果数量到所需数量。

$query->take(50);

要获取下一批结果，首先需要使用 skip($amount) 跳过上一批结果。

$query->skip(50);

这基本上就是分页，因此我们还添加了一个简写方法，使用 paginate($perPage, $page) 方法将这两个概念结合起来，实现更全面、直接的排序。

// Only take 50 results to display on the first page
$query->paginate(50);
// Query the 50 next results (on page 2)
$query->paginate(50, 2);

插入数据

插入数据的一种通用方法是使用 add($object_model, $code, $data) 方法。

$winbooks->add('Customer', 'VLADIMIR', [
    'Memo' => 'A Memo for Vladimir',
    // ...
]);

// You can also add multiple objects at once:

$winbooks->addMany('Customers', [
    [
        'Code' => 'VLADIMIR',
        'Memo' => 'A Memo for Vladimir',
        // ...
    ],
    [
        'Code' => 'ALICE',
        'Memo' => 'A Memo for Alice',
        // ...
    ]
]);

您还可以使用提供的 Model 类。这些类的名称与 Winbooks On Web 文档 中记录的对象模型名称相同。

use Whitecube\Winbooks\Models\Customer;

$vlad = new Customer(['Code' => 'VLADIMIR']);
$alice = new Customer(['Code' => 'ALICE']);

$winbooks->addModel($vlad);
// or multiple
$winbooks->addModels([$vlad, $alice]);

更新数据

$winbooks->update('Customer', 'ALICE', [
    'Memo' => 'This is an updated memo for Alice',
]);

// Or multiple

$winbooks->updateMany('Customers', [
    [
        'Code' => 'VLADIMIR',
        'Memo' => 'This is an updated memo for Vladimir',
    ],
    [
        'Code' => 'ALICE',
        'Memo' => 'This is an updated memo for Alice',
    ]
]);

删除数据

$winbooks->delete('Customer', 'VLADIMIR');

测试

本项目使用 PEST 进行测试。

首先，从 .env.example 创建一个 .env 文件，并填写您的 API 测试凭据。

要运行测试

./vendor/bin/pest

包含代码覆盖率（需要 pcov 或 xdebug）

./vendor/bin/pest --coverage

💖 赞助

如果您在生产应用中依赖此包，请考虑 赞助我们！这是帮助我们继续我们所热爱的事情：制作优秀的开源软件的最佳方式。

贡献

请随时提出更改建议、要求新功能或自行修复错误。我们确信还有很多可以改进的地方，并且我们非常乐意合并有用的拉取请求。

谢谢！

用 ❤️ 为开源制作

在 Whitecube，我们每天都在使用大量的开源软件。因此，当我们有机会回馈的时候，我们非常兴奋！

我们希望您会喜欢我们从这个小小的贡献中得到的收获，如果您在项目中发现它很有用，我们非常愿意 听到您的声音。关注我们的 Twitter 获取更多更新！