README

一个用于与持有发票数据的 SQS 消息队列交互的 PHP 库。

通过 composer.json 添加到项目中

要将此库包含在 PHP 项目中，请将以下行添加到项目 composer.json 文件的 require 部分

{
  "require": {
    "serato/sqs-invoice-queue": "^1.0.0"
  }
}

有关所有可用版本的列表，请参阅 Packagist

要求

此库需要 PHP 7.1 或更高版本。

风格指南

请确保代码遵循 PHP-FIG PSR-2 编码风格指南

使用 PHP_CodeSniffer 验证代码是否遵循编码标准

$ ./vendor/bin/phpcs

PHPStan

使用 PHPStan 进行静态代码分析

$ vendor/bin/phpstan analyse

单元测试

PHPUnit 的配置定义在 phpunit.xml 中。

要运行测试

$ php vendor/bin/phpunit

用法

发票验证器

Serato\InvoiceQueue\InvoiceValidator 类可以验证字符串或数组是否符合表示有效发票数据的 JSON 架构。

InvoiceValidator::validateJsonString 和 InvoiceValidator::validateArray 方法返回一个布尔值，表示验证成功与否。使用 InvoiceValidator::getErrors 方法遍历验证错误数组。

InvoiceValidator::validateJsonString 和 InvoiceValidator::validateArray 方法可以可选地接受一个 $defintion 参数，它将输入与具有 JSON 架构文档的命名定义进行验证。如果没有提供，则输入将与 JSON 架构的根元素进行验证。

use Serato\InvoiceQueue\InvoiceValidator;

$validator = new Serato\InvoiceQueue\InvoiceValidator;

# Validate an array against the root schema.
if ($validator->validateArray(['my' => 'data'])) {
  // Data conforms to schema
} else {
  // Data does not conform to schema
  foreach ($validator->getErrors() as $error) {
    print_r($error);
  }
}

# Validate a string against an named definition within the JSON schema
if ($validator->validateJsonString('{"my":"data"}', 'line_item')) {
  // Data conforms to schema
} else {
  // Data does not conform to schema
  foreach ($validator->getErrors('line_item') as $error) {
    print_r($error);
  }
}

发票模型

Serato\InvoiceQueue\Invoice 类是用于处理发票数据的模型。

它为单个发票属性提供获取和设置方法、添加行项目的方法、从数组填充整个模型的方法，以及从模型中提取符合 发票 JSON 架构的数据数组的方法。

use Serato\InvoiceQueue\Invoice;

# Constructor is private.
# Always create using Invoice::create() static method
$invoice = Invoice::create();

# Set individual properties
$invoice
  ->setInvoiceId('MyInvoiceId')
  ->setCurrency(Invoice::CURRENCY_EUR)
  ->setBillingAddressCompanyName('Acme Inc');
// ...etc

# Get individual properties
echo $invoice->getInvoiceId();
echo $invoice->getCurrency();
echo $invoice->getBillingAddressCompanyName();
// ...etc

# Create an Invoice Item
use Serato\InvoiceQueue\InvoiceItem;

$item = InvoiceItem::create();
$item
  ->setSku('MySkuCode')
  ->setQuantity(1)
  ->setAmountGross(2000)
  ->setAmountTax(0)
  ->setAmountNet(1000)
  ->setUnitPrice(1000)
  ->setTaxCode(Invoice::TAXCODE_V);

# Add the Item to an Invoice
$invoice->addItem($item);

# Gets all items in invoice (returns an array of InvoiceItem objects)
$invoice->getItems();

# Get complete invoice data that conforms to JSON schema
$data = $invoice->getData();

# Use the `Invoice::load` static method to populate model with data
# $data can be an array of string of JSON
# (the data will be validated against the JSON schema)
$invoice = Invoice::load($data);

# If loading multiple invoices, create a single InvoiceValidator
# instance and pass it to `Invoice::load` for better performance.
$validator = new Serato\InvoiceQueue\InvoiceValidator;
$invoice1 = Invoice::load($data1, $validator);
$invoice2 = Invoice::load($data2, $validator);

Sqs 客户端

Serato\InvoiceQueue\SqsQueue 提供了与包含发票数据的 AWS SQS 消息队列交互的功能。

SqsQueue 可以返回队列 URL、将 Serato\InvoiceQueue\Invoice 实例发送到队列（单个或批量）以及如果队列不存在则创建队列。

use Aws\Sdk;
use Serato\InvoiceQueue\SqsQueue;
use Monolog\Logger;
use Serato\InvoiceQueue\MonologLogFormatter;
use Serato\InvoiceQueue\InvoiceValidator;

# Create AWS SQS client instance
$awsSdk = new Sdk();
$awsSqsClient->createSqs();

# Create a PSR LogInterface instance.
# Monolog is recommended. Use in combination with a custom formatter
# that makes the log entries more legible in Cloudwatch Logs.
$logger = new Logger('My-App-Logger');
foreach ($logger->getHandlers() as $handler) {
    $handler->setFormatter(new MonologLogFormatter());
}

# Constructor requires:
# - An AWS SQS client
# - Environment string (one of 'test' or 'production')
# - PSR LogInterface
$queue = new SqsQueue($awsSqsClient, 'test', $logger, 'My App');

# Get the queue name or URL of the underlying SQS queue
$queue->getQueueUrl();
$queue->getQueueName();

# *** Send a single Invoice to the queue ***

# Invoice data will be validated against the JSON schema
$invoice = Invoice::create();
// ... populate $invoice
$messageId = $queue->sendInvoice($invoice);

# *** Send multiple Invoices to the queue in batches ***

# Invoice data will be validated against the JSON schema
# Batch will sent when interal batch size limit is reached or when
# SqsQueue instance is destroyed
$invoice1 = Invoice::create();
// ... populate $invoice1
$invoice2 = Invoice::create();
// ... populate $invoice2

# You MUST provide a InvoiceValidator when calling SqsQueue::sendInvoiceToBatch
$validator = new InvoiceValidator;

$queue
  ->sendInvoiceToBatch($invoice1, $validator)
  ->sendInvoiceToBatch($invoice2, $validator);

# A callback can be provided to the SqsQueue. This callback is called after every
# batch is sent to SQS.
#
# The callback as takes two arguments:
#
# - array $successfulInvoices      An array of Serato\InvoiceQueue\Invoice
#                                  instances that were successfully delivered to SQS.
# - array $failedInvoices          An array of Serato\InvoiceQueue\Invoice
#                                  instances that failed to deliver to SQS.

$queue->setOnSendMessageBatchCallback(function ($successfulInvoices, $failedInvoices ) {
  // Process invoices based on success or otherwise
});