cubemage / paging-seal-bundle
A Symfony Bundle to process PDF files, such as generating counter-signature seals or stamping images.
Installs: 4
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 0
Forks: 0
Open Issues: 0
Type:symfony-bundle
Requires
- php: >=8.1
- setasign/fpdf: ^1.8
- setasign/fpdi: ^2.3
- symfony/config: ^6.0|^7.0
- symfony/dependency-injection: ^6.0|^7.0
- symfony/framework-bundle: ^6.0|^7.0
- symfony/http-kernel: ^6.0|^7.0
README
一个为 Symfony 项目提供 PDF 骑缝章、盖章等处理功能的组件。
本组件的核心功能是提供一个可配置、可重用的服务,能够接收 PDF 文件,并以「骑缝章」或「单页盖章」的模式,专业地将印章图片叠加到PDF文档上。
系统要求
- PHP 8.1+
- Symfony 6.0+
gd
PHP 扩展(用于图像处理)
安装
第一步:通过 Composer 安装
在您的 Symfony 项目根目录下,执行以下命令:
composer require cubemage/paging-seal-bundle
第二步:启用 Bundle
如果您项目中启用了 Symfony Flex,这一步会自动完成。如果没有,请手动将以下这行加入到您项目的 config/bundles.php
文件中:
// config/bundles.php return [ // ... 其他的 bundle CubeMage\PagingSealBundle\CubeMagePagingSealBundle::class => ['all' => true], ];
配置 (可选)
安装后,您可以选择性地在 config/packages/
目录下创建一个 cube_mage_paging_seal.yaml
文件,来覆写组件的默认配置。
# config/packages/cube_mage_paging_seal.yaml cube_mage_paging_seal: # 自定义您希望存放临时PDF文件的路径 # 默认路径是: '%kernel.project_dir%/var/cubemage/paging-seal' pdf_path: '%kernel.project_dir%/var/cubemage/paging-seal' # 设置一个全局的、默认使用的公章图片的绝对路径 # 如果不设置,则每次调用服务时都必须提供公章图片路径 default_seal_path: '%kernel.project_dir%/assets/images/default_company_seal.png'
使用方法
本组件的核心是一个名为 PagingSealGenerator
的服务。在您的应用程序中(例如 Controller 或其他 Service),您只需要通过依赖注入来获取并使用它即可。
Controller 使用示例
以下是一个完整的控制器示例,展示了如何创建一个 API 端点,它接收用户上传的PDF和可选的公章图片,处理后强制用户下载生成的新文件。
<?php namespace App\Controller; // 1. 引入核心服务类 use CubeMage\PagingSealBundle\Service\PagingSealGenerator; use Symfony\Bundle\FrameworkBundle\Controller\AbstractController; use Symfony\Component\HttpFoundation\File\UploadedFile; use Symfony\Component\HttpFoundation\Request; use Symfony\Component\HttpFoundation\BinaryFileResponse; use Symfony\Component\Routing\Annotation\Route; class MyPdfController extends AbstractController { // 2. 通过构造函数自动注入服务 public function __construct( private PagingSealGenerator $sealGenerator ) {} #[Route('/api/contracts/process-seal', name: 'api_process_seal', methods: ['POST'])] public function processPdfAction(Request $request): BinaryFileResponse { // 3. 从请求中获取上传的文件 /** @var UploadedFile|null $documentFile */ $documentFile = $request->files->get('pdf'); /** @var UploadedFile|null $sealFile */ $sealFile = $request->files->get('seal_image'); // 这是可选的公章图片 // 进行必要的檔案验证... if (!$documentFile || !$documentFile->isValid()) { throw new \InvalidArgumentException("必须上传有效的PDF文件。"); } $sealPath = null; if ($sealFile && $sealFile->isValid()) { // 如果用户上传了自定义公章,使用它的临时路径 $sealPath = $sealFile->getPathname(); } try { // 4. 调用组件服务的核心方法来生成骑缝章PDF // 如果 $sealPath 为 null,服务会自动使用您在配置文件中配置的 default_seal_path $generatedPdfPath = $this->sealGenerator->generate( $documentFile->getPathname(), $sealPath, 'right', // 盖章位置: 'right', 'left', 'top', 'bottom' 30, // 印章尺寸 (mm) 5 // 页边距 (mm) ); // 5. 将生成的文件以二进制响应的形式,回传给用户下载 // ->deleteFileAfterSend(true) 会在下载完成后自动删除服务器上的临时文件,非常方便 return $this->file($generatedPdfPath, 'processed-document.pdf')->deleteFileAfterSend(true); } catch (\Exception $e) { // 在真实应用中,应该记录日志并返回一个更友好的错误响应 throw $this->createNotFoundException('PDF处理失败: ' . $e->getMessage()); } } }
授权协议 (License)
本组件基于 MIT 协议发布。详情请见 LICENSE
文件。