README

为 Billomat API 客户端 提供的 Symfony 2 扩展包。

安装

通过命令行添加扩展包

php composer.phar require phobetor/billomat-bundle

或手动添加到 composer.json 文件中

{
    "require": {
        "phobetor/billomat-bundle": "~1.3"
    }
}

获取所需的文件

$ php composer.phar update phobetor/billomat-bundle

这将安装扩展包和客户端到您项目的 vendor 目录。

将扩展包添加到您的项目 AppKernel

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // […]
        new PhobetorBillomatBundle\PhobetorBillomatBundle()
    );
}

配置

将您的凭据添加到 app/config/config.yml

# app/config/config.yml
phobetor_billomat:
  id: 'my-id'       # your Billomat id (required)
  api_key: 'my-key' # your Billomat API key (required)
  application:      # your Billomat API application credentials
                    # (if you have a registered application)
    id: 'my-app-id'         # your Billomat API application’s id
    secret: 'my-app-secret' # your Billomat API application’s secret

由于更高的限制率，强烈建议使用已注册应用程序的 Billomat API。

使用方法

从 Symfony 的 DI 容器获取客户端

$billomat = $this->get('phobetor_billomat')->getClient();

自动处理速率限制

如果在此客户端用于异步过程或 CLI 命令中，您可以激活自动等待速率限制重置。在此模式下，所有会抛出 \Phobetor\Billomat\Exception\TooManyRequestsException 的方法调用将等待速率限制重置并自动重试。您不应当在同步请求（例如网站请求）中使用此功能，因为在此模式下所有方法调用都可能非常耗时，可能比您服务器的网关超时时间还要长。有两种实现方式。

在配置中

# app/config/config.yml
phobetor_billomat:
  # […]
  wait_for_rate_limit_reset: true

在从容器获取后

$billomat = $this->get('phobetor_billomat')->getClient();
$billomat->setDoWaitForRateLimitReset(true);

多配置

您可以在您的 app/config/config.yml 中添加多个配置。这允许您配置多个用户、应用程序或组合。

# app/config/config.yml
phobetor_billomat:
  id: 'my-id'
  api_key: 'my-key'

  clients:
    cli:
      id: 'my-id'
      api_key: 'my-key'
      application:
        id: 'my-app-id'
        secret: 'my-app-secret'
      wait_for_rate_limit_reset: true

此示例配置了一个默认客户端，没有应用程序（这赋予请求高达标准用户限制率 300 请求），并且没有自动速率限制处理。此外，还配置了一个具有应用程序的 cli 客户端（这赋予请求高达标准应用程序限制率 1000 请求）以及自动速率限制处理。

这样，您可以在异步（可能长时间运行）的 CLI 命令中使用具有自动速率限制处理的客户端

$billomat = $this->get('phobetor_billomat')->getClient('cli');
// e. g. create a huge bunch of invoices

同时，您可以使用未配置应用程序的客户端（这提供较低的，但独立的速率限制）用于您应用程序的请求

$billomat = $this->get('phobetor_billomat')->getClient();
// e. g. fetch and show a list of invoices in your internal application