README

简介

一个用于生成PDF格式的业务文档的PHP API。

使用方法

一旦API通过以下任一方法运行，以下端点即可使用：

POST /invoice
POST /purchaseOrder

示例发票请求

请将正文数据以 application/json 原始内容类型发送。

{
  "logoHeight": 55,
  "emailTelUnderLogo": true,
  "company": {
    "name": "Example Limited",
    "number": "12345678",
    "vatNumber": "GB12345678901",
    "email": "hello@example.com",
    "telephone": "01234 567 890",
    "logoUrl": "https://example.com/logo.png",
    "address": {
      "line1": "123 House Street",
      "line2": "Townville",
      "city": "Citybourne",
      "postcode": "PO57 C0D"
    }
  },
  "invoice": {
    "ref": "INV-123",
    "summary": "For the provision of services.",
    "notes": "",
    "instructions": "Please make BACS direct credit payments to: Example Limited | Account Number: 00000000 | Sorting code: 00-00-00",
    "symbol": "&pound;",
    "net": 1234.56,
    "tax": 100.00,
    "gross": 1334.56,
    "company": {
      "name": "Customer Limited",
      "address": {
        "line1": "1a Flat Towers",
        "line2": "Low High Street",
        "city": "Uptown",
        "postcode"     : "C0D P057"
      }
    },
    "items": [
      {
        "quantity": 1,
        "description": "Provision of services relating to particulars",
        "unitPrice": 354.17,
        "taxPercent": 20,
        "net": 425
      },
      {
        "quantity": 1,
        "description": "Production of widgets conforming to specification J-21",
        "unitPrice": 354.17,
        "taxPercent": 20,
        "net": 425
      }
    ],
    "keyValuePairs": [
      {
        "key": "Tax Point",
        "value": "2019-09-02"
      },
      {
        "key": "Period",
        "value": "2019-08-01 to 2019-08-31"
      }
    ]
  }
}

Docker

要以Docker容器运行API，需要公开单个HTTP端点，例如在主机机器上的 3002。

docker run -p 3002:80 voquis/pdfapi

要以前台模式运行，在镜像名称之前添加 -d。

开发

API使用Laravel Lumen 框架，并利用基于 TCPDF 的库 voquis/pdflib。

Docker中的开发

首先以前台模式启动一个开发容器，并将源代码作为卷挂载

docker run \
-d \
--name pdfapi_dev \
--hostname pdfapi_dev \
-v /local/path/to/source:/pdfapi \
-p 3000:80 \
-p 3001:9000 \
-w /pdfapi \
php:7.3.5-apache

要使用当前目录而不是指定完整的本地路径，请使用 -v `pwd`:/pdfapi 。如果使用docker for windows，请更改路径到 //c/path/to/source://pdfapi。然后以交互模式（-i）连接到正在运行的容器，并使用 TTY (-t)。请注意，如果使用git for Windows，可能需要前缀 winpty。如果使用CentOS/RHEL或其他启用了SELinux的发行版，请使用 :Z（仅此容器独享）或 :z（与其他容器共享）在卷挂载的末尾设置适当的权限，例如 -v /local/path/to/source:/pdfapi:Z。有关更多详细信息，请参阅此 StackOverflow问题/答案。

docker exec -it pdfapi_dev bash

要断开连接并留下容器运行，请按 Ctrl+P 然后按 Ctrl+Q。

安装和启用依赖项

注意，基本的Docker PHP镜像有一个名为 docker-php-ext-install 的实用程序，用于安装和启用PHP扩展。使用 gd 扩展来解析页眉中的图像徽标。在测试期间使用 xsl 扩展，但生产中不需要（请参阅 Dockerfile 以进行生产优化）。

apt-get update
apt-get install -y libpng-dev vim git unzip libxslt1-dev
docker-php-ext-install gd xsl

安装工具

安装Xdebug并添加配置文件。xdebug扩展对于生成单元测试覆盖率报告是必需的。如果将使用远程调试，则需要 xdebug.remote_enable 和 xdebug.remote_autostart 选项（端口号 9000）。

pecl install xdebug
echo "zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_autostart=1" > /usr/local/etc/php/conf.d/xdebug.ini

增加内存限制

静态代码分析（phpstan）可能会遇到默认PHP内存限制，要增加此限制，请运行以下命令。请注意，这将创建一个新的 ini 配置文件。

echo "memory_limit=512M" > /usr/local/etc/php/conf.d/memory.ini

安装和运行composer

使用 curl 获取最新的composer版本，并将其输出（-o）到系统二进制路径，遵循任何重定向（-L）。更新权限以允许执行（+x）。指示composer从git检出（--prefer-source），如果需要，这将允许开发任何供应商库。

curl -Lo /usr/local/bin/composer https://getcomposer.org.cn/composer.phar
chmod +x /usr/local/bin/composer
composer install --prefer-source

配置可写目录

允许apache写入 storage 和子目录。

chown -R www-data storage

配置Apache

启用apache2的 rewrite 模块，然后更新配置以将默认webroot目录更改为挂载卷中项目文件的位置（/pdflib）。

a2enmod rewrite
sed -ri -e 's!/var/www/html!/pdfapi/public!g' /etc/apache2/sites-available/*.conf
sed -ri -e 's!/var/www/!/pdfapi!g' /etc/apache2/apache2.conf /etc/apache2/conf-available/*.conf
service apache2 restart

请注意，重新启动apache2将终止容器，因此需要运行 docker container start pdfapi_dev 然后重新连接。

贡献

欢迎以问题报告和拉取请求的形式贡献，请克隆仓库并应用任何建议的更改。请确保保持100%的单元测试代码覆盖率，并在推送更改前使用composer test在本地运行测试。要生成单元测试覆盖率报告，请运行composer phpunit-html。这些命令在composer.json中的scripts部分定义。

voquis / pdfapi

维护者

详细信息