Api-Platform：为资源添加自定义PDF下载路由的最佳实践

// app/src/Entity/Invoice.php
#[ApiResource(itemOperations: [
    'get',
    'put',
    'patch',
    'delete',
    'get_document' => [
        'method' => 'GET',
        'path' => '/invoices/{id}/document',
        'controller' => DocumentController::class,
        'output_formats' => ['application/pdf']
    ],
])]
class Invoice
{
    // ... 实体属性和方法
}

// app/src/Entity/Invoice.php
<?php

namespace App\Entity;

use ApiPlatform\Metadata\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;

#[ORM\Entity]
#[ApiResource(
    operations: [
        // ... 其他标准操作
    ],
    normalizationContext: ['groups' => ['read:invoice']]
)]
class Invoice
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column(type: 'integer')]
    private ?int $id = null;

    #[ORM\Column(type: 'string', length: 255)]
    #[Groups(['read:invoice'])]
    private ?string $invoiceNumber = null;

    // ... 其他属性

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getInvoiceNumber(): ?string
    {
        return $this->invoiceNumber;
    }

    public function setInvoiceNumber(string $invoiceNumber): self
    {
        $this->invoiceNumber = $invoiceNumber;
        return $this;
    }

    /**
     * 获取发票PDF文档的URL。
     * 该方法会通过序列化组暴露给API消费者。
     */
    #[Groups(["read:invoice"])]
    public function getDocumentUrl(): string
    {
        // 假设路由名为 'app_invoice_document'
        // 实际应用中，应使用Symfony的Router服务生成URL，以确保正确性
        // 例如：$this->router->generate('app_invoice_document', ['id' => $this->id], UrlGeneratorInterface::ABSOLUTE_URL);
        return "/invoices/{$this->id}/document";
    }
}

// app/src/Controller/InvoiceDocumentController.php
<?php

namespace App\Controller;

use App\Entity\Invoice;
use App\Service\InvoiceDocumentService;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\BinaryFileResponse;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\ResponseHeaderBag;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\Security\Http\Attribute\IsGranted; // 用于安全控制

class InvoiceDocumentController extends AbstractController
{
    private InvoiceDocumentService $documentService;

    public function __construct(InvoiceDocumentService $invoiceDocumentService)
    {
        $this->documentService = $invoiceDocumentService;
    }

    /**
     * 处理发票PDF文档的下载请求。
     *
     * @param Invoice $invoice Symfony的ParamConverter会自动将{id}转换为Invoice对象
     */
    #[Route('/invoices/{id}/document', name: 'app_invoice_document', methods: ['GET'])]
    // 确保只有授权用户才能访问该文档
    #[IsGranted('VIEW', subject: 'invoice')]
    public function __invoke(Invoice $invoice): Response
    {
        // 1. 调用服务生成PDF文档的路径或内容
        // 假设服务返回一个文件路径
        $pdfFilePath = $this->documentService->createDocumentForInvoice($invoice);

        if (!file_exists($pdfFilePath)) {
            throw $this->createNotFoundException('The invoice document was not found.');
        }

        // 2. 创建BinaryFileResponse以发送文件
        $response = new BinaryFileResponse($pdfFilePath);

        // 3. 设置正确的Content-Type
        $response->headers->set('Content-Type', 'application/pdf');

        // 4. 设置Content-Disposition以强制浏览器下载文件，并指定文件名
        $response->setContentDisposition(
            ResponseHeaderBag::DISPOSITION_ATTACHMENT, // DISPOSITION_INLINE 会尝试在浏览器中打开
            'invoice_' . $invoice->getInvoiceNumber() . '.pdf'
        );

        // 5. 可选：设置缓存控制头
        $response->setPublic();
        $response->setMaxAge(3600); // 缓存1小时

        return $response;
    }
}

// app/src/Service/InvoiceDocumentService.php
<?php

namespace App\Service;

use App\Entity\Invoice;
// 假设你使用一个PDF生成库，例如wkhtmltopdf或MPDF
// use Knp\Snappy\Pdf; // 示例

class InvoiceDocumentService
{
    // private Pdf $snappyPdf; // 注入PDF生成器

    // public function __construct(Pdf $snappyPdf)
    // {
    //     $this->snappyPdf = $snappyPdf;
    // }

    /**
     * 为指定发票创建PDF文档。
     *
     * @param Invoice $invoice
     * @return string PDF文件的临时或永久存储路径
     */
    public function createDocumentForInvoice(Invoice $invoice): string
    {
        // 实际的PDF生成逻辑
        // 例如：
        // $htmlContent = $this->generateHtmlForInvoice($invoice);
        // $pdfContent = $this->snappyPdf->getOutputFromHtml($htmlContent);

        // 假设将PDF保存到临时文件
        $tempFilePath = sys_get_temp_dir() . '/invoice_' . $invoice->getInvoiceNumber() . '.pdf';
        // file_put_contents($tempFilePath, $pdfContent); // 写入PDF内容

        // 模拟生成一个空PDF文件以供演示
        file_put_contents($tempFilePath, "This is a dummy PDF for Invoice " . $invoice->getInvoiceNumber());

        return $tempFilePath;
    }

    // private function generateHtmlForInvoice(Invoice $invoice): string
    // {
    //     // 根据发票数据生成HTML内容，用于PDF转换
    //     return "<h1>Invoice #{$invoice->getInvoiceNumber()}</h1><p>...</p>";
    // }
}