README

DownloadApi 客户端

Server-side PHP 客户端，用于从 Germania 的下载 API 中检索可用下载列表。

安装

版本 5 是一个完整的重写，因此没有升级过程。

$ composer require germania-kg/downloadsapi-client
$ composer require germania-kg/downloadsapi-client:^5.0

此包需要一个 PSR-18 HTTP 客户端 实现和一个 PSR-17 HTTP 请求工厂 实现。建议使用通过 Guzzle 7 的 guzzlehttp/guzzle 和 Nyholm 的 nyholm/psr7，尽管其名称如此，但它也提供了 PSR-17 工厂

$ composer require nyholm/psr7
$ composer require guzzlehttp/guzzle

基础

接口和抽象类

接口 DownloadsApiInterface 提供用于检索文档、所有、最新 和 请求 的公共方法，后者用于内部使用。所有这些方法都返回一个 可迭代对象。还有用于身份验证密钥的拦截器

// Provided by interface 
// Germania\DownloadsApi\DownloadsApiInterface

public function all() : iterable;
public function latest() : iterable;
public function request( string $path ) : iterable ;

public function setAuthentication( ?string $key ) : DownloadsApiInterface;
public function getAuthentication( ) : string;

抽象类 DownloadsApiAbstract 准备 all 和 latest 方法直接委托到 request 方法。它还使用了各种有用的特性，如 Psr\Log\LoggerAwareTrait、LoglevelTrait 和 AuthenticationTrait。因此，任何扩展此抽象类的类都将提供

// Inherited from abstract class 
// Germania\DownloadsApi\DownloadsApiAbstract
  
$api->setLogger( \Monolog\Logger( ... ) ); 

$api->setErrorLoglevel( \LogLevel::ERROR );
$api->setSuccessLoglevel( \LogLevel::INFO );

$api->setAuthentication( "secrete" );
$api->getAuthentication(); // "secret"

PSR-6 缓存支持

类 CacheDownloadsApiDecorator 包装现有的 DownloadsApi 实例，并添加对 PSR-6 缓存 的支持。它扩展了 DownloadsApiDecorator，而 DownloadsApiDecorator 又扩展了 DownloadsApiAbstract，因此该类也实现了 DownloadsApiInterface。

构造函数需要一个 DownloadsApi（或 DownloadsApiInterface）实例和一个 PSR-6 Cache Item Pool。您可以可选地传递一个 缓存有效期（以秒为单位），默认为 14400（4 小时）。

<?php
use Germania\DownloadsApi\DownloadsApi;
use Germania\DownloadsApi\CacheDownloadsApiDecorator;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;

$api = new DownloadsApi( ... );
$psr6 = new FilesystemAdapter( ... );

$cached_api = new CacheDownloadsApiDecorator( $api, $psr6);
$cached_api = new CacheDownloadsApiDecorator( $api, $psr6, 14400);

API 客户端

DownloadsApi API 客户端扩展了 DownloadsApiAbstract 并因此实现了 DownloadsApiInterface。构造函数需要一个 PSR-18 HTTP 客户端、一个 PSR-17 请求工厂 和一个 API 密钥。要获取 API 密钥，请联系 Germania KG 的网页开发者。

<?php
use Germania\DownloadsApi\DownloadsApi;
use GuzzleHttp\Client;
use Nyholm\Psr7\Factory\Psr17Factory;

$psr18 = new Client;
$psr17 = new Psr17Factory;
$key = "secret"
  
$api = new DownloadsApi($psr18, $psr17, $key);

检索文档

公共方法 all 和 latest 返回一个包含 Germania 文档 API 提供的文档的 Array 可迭代对象。

$downloads = $api->latest();
$downloads = $api->all();

foreach( $downloads as $document):
	print_r( $document );
endforeach;

示例记录

上面的 print_r( $document ) 将显示类似以下内容

Array (
    [company] =>
    [brand] => mybrand
    [title] => Brand<sup>®</sup> Window Styling
    [subtitle] =>
    [subtitle2] =>
    [description] =>
    [picture] => Array (
        [src] =>
        [fallback] =>
    )

    [language] => de
    [download] => https://download.example.com/document.pdf
    [categories] => Array(
        [0] => montageanleitung
    )

    [keywords] => Array ()

    [products] => Array (
        [0] => dachflaechen
        [1] => plissee
        [2] => duette
        [3] => jalousie
        [4] => rollo
    )

    [fileSize] => 2298631
    [lastModified] => Array  (
        [date] => 2018-02-19 10:21:14.000000
        [timezone_type] => 2
        [timezone] => GMT
    )

    [daysAgo] => 420
)

过滤结果

为了缩小结果范围，all 和 latest 方法都接受一个包含过滤值的 数组。过滤值可以包含多个值，由逗号分隔。

将过滤数组项视为 WHERE … AND… 子句，将逗号分隔的值视为 'a' OR 'b'

$filters = array(
  'company' => "ACME",
  'brand'   => "mybrand",
  'category' => "brochure",
  'language' => "en",
  'keyword' => "customers,retailers",
  'product' => "cars,bikes"
);

$downloads = $api->latest($filters);
$downloads = $api->all($filters);

错误和异常

应该足够注意 \Germania\DownloadsApi\Exceptions\DownloadsApiExceptionInterface，因为所有具体的异常类都实现了此接口。

<?php
use Germania\DownloadsApi\DownloadsApiExceptionInterface;
use Germania\DownloadsApi\DownloadsApiRuntimeException;
use Germania\DownloadsApi\DownloadsApiResponseException;
use Germania\DownloadsApi\DownloadsApiUnexpectedValueException;

try {
  $client->latest();
}
catch (\Germania\DownloadsApi\DownloadsApiExceptionInterface $e) {
	echo $e->getMessage();
}

请求期间发生异常：每当 PSR-18 客户端请求失败时，将抛出 DownloadsApiRuntimeException。此类实现了 DownloadsApiExceptionInterface 并扩展了 \RuntimeException。

HTTP 错误响应：当 API 调用返回 HTTP 错误响应时，将抛出 DownloadsApiResponseException。此类实现了 DownloadsApiExceptionInterface 并扩展了 \RuntimeException。

响应中的意外值：每当响应（即使是状态 200 OK）无法解码为有用的数组时，将抛出 DownloadsApiUnexpectedValueException。此类实现了 DownloadsApiExceptionInterface 并扩展了 \UnexpectedValueException。

单元测试和开发

将 phpunit.xml.dist 复制到 phpunit.xml 并填写您从德国尼亚获得的 认证数据。

• 当您手头有下载 API 的认证令牌时，填写 AUTH_TOKEN。
• 否则，填写 AUTH_API、AUTH_USER 和 AUTH_PASS。在每次测试之前，将从德国尼亚的认证 API 中获取认证令牌。

要运行单元测试，请像这样运行 PhpUnit

$ composer test
# or
$ vendor/bin/phpunit

问题

查看 完整问题列表