README

安装

您可以通过composer安装此包

composer require morningtrain/economic

基本概念

此SDK旨在使处理和使用e-conomic REST API变得简单。您可以在以下位置阅读e-conomic REST API文档：https://restdocs.e-conomic.com/

驱动器

SDK使用驱动器来处理与e-conomic REST API的通信。我们没有在此包中实现驱动器，因为我们想使其能够与不同的框架一起使用。

您可以使用我们的一些实现，或者创建自己的驱动器

如果您创建自己的驱动器，则必须实现Morningtrain\Economic\Interfaces\EconomicDriver接口，并像这样初始化API

use Morningtrain\Economic\EconomicApi;

EconomicApiService::setDriver(new YourDriver($appSecretToken, $agreementGrantToken));

日志记录器

我们已经实现了一个PSR日志记录器接口，因此您可以将来自e-conomic REST API的所有请求和响应记录下来。

您可以通过在Morningtrain\Economic\Services\EconomicLoggerService类上调用registerLogger方法来注册PSR日志记录器。

资源

此SDK中每个e-conomic REST API资源都由一个类表示。资源位于src/Resources文件夹中。

某些资源根据REST API被划分为子资源。

每个资源类都实现了与API端点对应的函数。

某些资源只是DTO（数据传输对象），在REST API中没有端点表示。这些资源用于使与其他资源表示的对象更容易操作。

集合

集合用于从e-conomic REST API获取多个资源。我们使用Laravel的延迟集合来简化集合的处理。这意味着，您可以在SDK返回的集合上使用Laravel集合类中的所有方法。延迟集合会自动获取您需要的资源并为您处理分页。仅在需要资源时才会调用API，因此集合在需要之前不会包含数据。

过滤

从e-conomic REST API获取资源时，如果端点允许，您可以过滤要获取的资源。有关每个资源支持哪些过滤器的更多信息，请参阅https://restdocs.e-conomic.com/#endpoints。SDK使用类似于查询构建器的简单方式来过滤资源。

一个简单的例子可以是

use Morningtrain\Economic\Resources\Customer;

$customer = Customer::where('email', 'ms@morningtrain.dk')
                ->orWhere('name', 'Morningtrain')
                ->first();

排序

尚未实现。

用法

此SDK中每个e-conomic REST API资源都由一个类表示。每个类都实现了与API端点对应的函数。

获取多个资源

从e-conomic REST API获取多个资源时，您将获得一个资源集合。该集合是Laravel延迟集合的实现，因此您可以在集合上使用Laravel集合类中的所有方法。

要从e-conomic REST API获取多个资源，您可以在资源类上使用all方法。

use Morningtrain\Economic\Resources\Customer;

$customers = Customer::all();

过滤

您可以筛选您想要获取的资源，如果端点允许的话。有关每个资源支持的筛选器的更多信息，请参阅https://restdocs.e-conomic.com/#endpoints。这将返回与筛选器匹配的资源集合。

use Morningtrain\Economic\Resources\Customer;

$customers = Customer::where('email', 'ms@morningtrain.dk');

获取单个资源

当从e-conomic REST API获取单个资源时，您将得到您请求的资源类的一个实例。

要从e-conomic REST API获取单个资源，您可以在资源类上使用find方法。find方法使用主键来查找资源。主键因资源而异，因此您需要在e-conomic REST API文档中查找您要获取的资源的主键。主键的类型是混合的，因此您可以使用字符串或整数来查找资源。

use Morningtrain\Economic\Resources\Customer;
use Morningtrain\Economic\Resources\Product;

$customer = Customer::find(1); // Where 1 is the customer number

$product = Product::find('proudct-1'); // Where 'product-1' is the product number

创建资源

一些资源可以在E-conomic中创建。创建成功后，您将得到您刚刚创建的资源。我们在资源类上实现了一个create方法，因此您可以像这样创建资源：

在创建资源时需要提供的参数因资源而异，因此您需要查看资源类的实现，以了解您需要提供哪些参数。一些参数是必需的，而另一些是可选的。您可以在资源类的实现中查看哪些参数是必需的，哪些是可选的。要仅使用一些可选参数，您可以在PHP中使用命名参数。

use Morningtrain\Economic\Resources\Product;

$product = Product::create(
    'Product 1', // product name
    1, // product group number
    'p-1', // product number
    barCode: '1234567890', 
    costPrice: 100.0, 
    recommendedPrice: 150.0, 
    salesPrice: 199.95, 
    description: 'test', 
    unit: 1 // unit number
);

一些资源可以通过使用new方法以替代方式创建。这将创建资源类的具有所需属性的新实例。其中一些资源可以使用save方法在E-conomic中创建资源。

use Morningtrain\Economic\Resources\Invoice\DraftInvoice;

$draftInvoice = DraftInvoice::new(
    'DKK',
    1,
    new DateTime('2024-02-13T12:20:18+00:00'),
    14,
    1,
    Recipient::new(
        'John Doe',
        new VatZone(1),
    ),
    [
        ProductLine::new(
            description: 'T-shirt - Size L',
            product: new Product([
                'productNumber' => 1,
            ]),
            quantity: 1,
            unitNetPrice: 500
        )
    ]
    notes: Note::new(
        heading: 'Heading',
        textLine1: 'Text line 1',
        textLine2: 'Text line 2'
    )
);

$draftInvoice->save();

更新资源

一些资源在创建后可以更新。可以按照以下方式完成：

use Morningtrain\Economic\Resources\Customer;

$customer = new Customer::find(1); // Where 1 is the customer number

$customer->name = 'New name';

$customer->save();

这将更新E-conomic中的客户名称。您也可以在实例化客户时简单地提供所有新值。

use Morningtrain\Economic\Resources\Customer;

$customer = new Customer([
    'customerNumber' => 1,
    'name' => 'New Name',
]);

$customer->save();

删除资源

一些资源可以在E-conomic中删除。可以使用资源类上的delete方法完成此操作。

use Morningtrain\Economic\Resources\Customer;

$customer = new Customer::find(1); // Where 1 is the customer number

$customer->delete();

这将删除E-conomic中的客户。

您还可以通过调用静态方法deleteByPrimaryKey来删除资源。

use Morningtrain\Economic\Resources\Customer;

Customer::deleteByPrimaryKey(1); // Where 1 is the customer number

示例

获取所有客户

use Morningtrain\Economic\Resources\Customer;

$customers = Customer::all();

foreach ($customers as $customer) {
    echo $customer->name;
}

获取单个客户

use Morningtrain\Economic\Resources\Customer;

$customer = Customer::find(1); // Where 1 is the customer number

if(!empty($customer)) {
    echo $customer->name;
}

按电子邮件获取客户

use Morningtrain\Economic\Resources\Customer;

$customer = Customer::where('email', 'ms@morningtrain.dk');

if(!empty($customer)) {
    echo $customer->name;
}

测试

composer test

变更日志

有关最近更改的更多信息，请参阅CHANGELOG。

贡献

有关详细信息，请参阅CONTRIBUTING。

安全漏洞

有关如何报告安全漏洞的信息，请参阅我们的安全策略。

鸣谢

• Martin Schadegg Brønniche
• Simon Jønsson
• 所有贡献者

许可证

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