README

提供对Fakturoid API的简化访问。

安装

Composer

1. 将SDK仓库和包添加到您的composer.json

{
    // ...
    "repositories": [
        // ...
        { "type": "vcs", "url": "https://github.com/jahudka/fakturoid-sdk" }
        // ...
    ],
    "require": {
        // ...
        "jahudka/fakturoid-sdk": "dev-master"
        // ...
    }
    // ...
}

1. 在项目目录中运行composer update

没有Composer

1. 在此处下载最新的SDK PHAR存档：https://github.com/jahudka/fakturoid-sdk/releases

2. 解压缩存档到您希望的位置，并按如下方式加载

<?php

require '/path/to/fakturoid-sdk.phar';

使用方法

创建客户端

<?php
$api = Jahudka\FakturoidSDK\Client::create($email, $apiToken, $slug, $userAgent);

// or construct the instance yourself:
$httpClient = new GuzzleHttp\Client();
$api = new Jahudka\FakturoidSDK\Client($httpClient, $email, $apiToken, $slug, $userAgent);

SDK涵盖了API文档中指定的所有当前可用的API端点（http://docs.fakturoid.apiary.io/）。端点通过Client实例上的属性提供，例如，发票端点可通过$api->invoices访问。属性名称与它们访问的API端点名称相同。

API的数据总是被封装在适当的实体对象中返回。实体对象具有与各自的端点相同的属性，除了属性名称是camelCase而不是pascal_case。

缓存

Fakturoid建议API客户端利用常见的HTTP缓存机制来加快客户端应用并节省带宽。使用FakturoidSDK非常容易做到这一点，因为您只需在SDK的GuzzleHttp\Client实例中安装任何选择的缓存中间件即可。例如，请参阅https://github.com/Kevinrob/guzzle-cache-middleware。

遍历API

使用SDK读取列表端点很容易：端点属性本身是一个迭代聚合，这意味着在简单的情况下，当您想要读取给定端点的所有条目时，可以直接在foreach循环中使用端点，例如

<?php

foreach ($api->invoices as $invoice) {
    // $invoice is an instance of Jahudka\FakturoidSDK\Entity\Invoice
    
    // Data can be accessed either through properties...
    echo $invoice->number;
    $invoice->number = '2016-123';
    
    // ... or through getters and setters.
    echo $invoice->getNumber();
    $invoice->setNumber('2016-123');
    
}

端点迭代器当然支持API支持的所有过滤和搜索选项，以及SQL风格的限制，例如

<?php

$invoices = $api->invoices
    ->setOption('status', 'open');

foreach ($invoices as $invoice) {
    echo $invoice->number . "\n";
    // ...
}

// limiting can be done by calling the getIterator() method manually
// and supplying the optional $offset and $limit arguments like this:
foreach ($api->invoices->getIterator(100, 100) as $invoice) {
    // do something with invoices #100 - #199
}

获取、创建、更新和删除条目

<?php

// Getting entries is simple:
$invoice = $api->invoices->get(981);
echo $invoice->getNumber();

// Creating new entries can be done
// using the endpoint's create() method:
$data = [
    'name' => 'Josef Novak',
    'street' => 'Dlouha 123',
    'city' => 'Nove Mesto',
    'zip' => '123 45',
    'country' => 'CZ',
    'registration_no' => '123456789',
];

$subject = $api->subjects->create($data);
echo $subject->getId();

// Or you can manually create the entity
// and use the endpoint's save() method:
$subject = new Jahudka\FakturoidSDK\Entity\Subject();

$subject->setName('Josef Novak');
// ...

$api->subjects->save($subject);

// The entity object is updated by the data returned
// from the server, so this still works:
echo $subject->getId();

// The save() method is useful for updating existing
// entries, either entities you previously loaded from
// the API somehow or even entities you constructed by hand:
$pepa = new Jahudka\FakturoidSDK\Entity\Subject();
$pepa->setId(3042);
$pepa->setPhone('+420 123 456 789');

$api->subjects->save($pepa);

// Same as before, the entity object is not only
// saved, but also updated using the data
// returned from the server:
echo $pepa->getBankAccount();

// Deleting entries can be done using the delete() method:
$api->subjects->delete($pepa);

// You can pass in just the ID:
$api->subjects->delete(123);