README

可扩展的PHP库，用于将领域数据导出到用于备份目的的格式化文档，并将其放置在远程存储中。

它适用于关键任务数据需要通过辅助渠道即时访问的场景，即使主基础设施出现故障。

该库旨在与Symfony Messenger一起使用，但可以直接调用CreateDocument命令处理程序。可选地，可以实现PSR-3 Logger。

大多数文档生成策略都需要包含来自文件系统的模板。请确保模板路径不是由用户提供的或列入白名单，并且您的PHP安装保护可以访问的文件。

**需要临时文件** 请确保您的系统允许生成临时文件。

开始使用

将库包含到您的项目中，并配置您的框架/DI容器以提供CreateDocumentHandler作为服务或消息处理程序。

使用CreateDocument命令收集生成文档所需的所有详细信息。

生成文档通常需要许多依赖项，如PHP库或外部二进制文件。为了减少对供应商文件夹和容器的污染，您可能希望创建一个单独的工作应用程序，通过消息总线连接到主应用程序。

支持的文档生成策略

Twig + Chromium

使用Twig模板语言生成HTML，使用无头Chromium将其转换为PDF。最容易创建看起来好的PDF，但需要编写CSS和HTML。您可以选择提供模板文件或提供在TemplateReference配置的template属性中的动态模板。

**需要安装composer包：twig/twig 和 chrome-php/chrome，以及系统路径中的chromium二进制文件。** 在选择策略时，请注意，chromium（在Alpine Docker中）会增加600+ MB到您的映像。

Word模板：Microsoft Office Open XML (.docx)

使用带有占位符的MS Word文档（例如${name}）来生成MS Word文档。这使用PHPOffice/PHPWord模板处理能力。目前，只能进行简单的值替换，计划支持块和行的复制。

此策略不允许在文档中包含图片。

理论上，可以通过PHPWord实现其他输出格式，但PDF支持非常有限。PDF转换可以通过第三方工具在远程存储位置处理传入的文件来完成。

**需要安装composer包phpoffice/phpword 和 'mpdf', 'tcpdf', 'dompdf' 之一**

自定义

您可以通过实现DocumentGenerator接口并提供给CreateDocumentHandler来创建自定义策略。

存储

对于每次文档生成，必须定义备份目标。这包括文件名、存储类型和特定类型的存储配置。

本地

文件可以存储在本地

存储配置

[
   'root' => '/root/path/', // required
]

WebDAV

存储配置

[
    'baseUri' => 'http://your-webdav-server.org/', // required
    'userName' => 'your_user',
    'password' => 'superSecret1234'
]

FTP

存储配置

[
   'host' => 'hostname', // required
   'root' => '/root/path/', // required
   'username' => 'username', // required
   'password' => 'password', // required
   'port' => 21,
   'ssl' => false,
   'timeout' => 90,
   'utf8' => false,
   'passive' => true,
   'transferMode' => FTP_BINARY,
   'systemType' => null, // 'windows' or 'unix'
   'ignorePassiveAddress' => null, // true or false
   'timestampsOnUnixListingsEnabled' => false, // true or false
   'recurseManually' => true // true
]

自定义

如果您需要其他存储系统，请检查官方phpleague/flysystem适配器。如果存在适配器（非常可能），请创建一个拉取请求，扩展此库中的flysystem适配器，以允许实例化适配器。

如果flysystem无法满足您的需求，您可以实现自己的BackupFilesystem版本，并提供给CreateDocumentHandler。

模板设计

注意：创建文档命令的数据对象中的键名不得以 _ 开头（保留给供应商特定的模板变量使用）。

开发

库中包含一个Dockerfile，用于生成包含所有必需工具的镜像。所有常规命令都在composer.json中进行了别名设置。

构建包含的Docker镜像

注意：如果您想创建自己的镜像来使用库，请检查工作应用的构建以获取灵感。

需要可写目录以用于临时文件和模板缓存。

docker build -t php-tools-chromium:8.3 -f Dockerfile .