[Maintenance][DX] Add support for PDF generation abstraction

.github/workflows/build.yaml

@@ -22,7 +22,7 @@ jobs:
     tests:
         runs-on: ubuntu-latest
 
-        name: "Sylius ${{ matrix.sylius }}, PHP ${{ matrix.php }}, Symfony ${{ matrix.symfony }}, ${{ matrix.database == 'mysql' && format('MySQL {0}', matrix.mysql) || matrix.database == 'postgres' && format('PostgreSQL {0}', matrix.postgres) }}, wkhtmltopdf: ${{ matrix.wkhtmltopdf }}, State Machine Adapter ${{ matrix.state_machine_adapter }}"
+        name: "Sylius ${{ matrix.sylius }}, PHP ${{ matrix.php }}, Symfony ${{ matrix.symfony }}, ${{ matrix.database == 'mysql' && format('MySQL {0}', matrix.database_version) || matrix.database == 'postgres' && format('PostgreSQL {0}', matrix.database_version) }}, wkhtmltopdf: ${{ matrix.wkhtmltopdf }}, State Machine Adapter ${{ matrix.state_machine_adapter }}, legacy: ${{ matrix.legacy }}"
 
         strategy:
             fail-fast: false
@@ -35,6 +35,7 @@ jobs:
                 database_version: ["8.4"]
                 wkhtmltopdf: ["0.12.6.1-2"]
                 state_machine_adapter: ["symfony_workflow"]
+                legacy: [true, false]
 
                 include:
                     -
@@ -46,6 +47,29 @@ jobs:
                         database_version: "8.4"
                         wkhtmltopdf: "0.12.6.1-2"
                         state_machine_adapter: "winzou_state_machine"
+                        legacy: true
+
+                    -
+                        php: "8.3"
+                        symfony: "^7.4"
+                        sylius: "~2.2.0"
+                        node: "24.x"
+                        database: "mysql"
+                        database_version: "8.4"
+                        wkhtmltopdf: "0.12.6.1-2"
+                        state_machine_adapter: "winzou_state_machine"
+                        legacy: false
+
+                    -
+                        php: "8.3"
+                        symfony: "^7.4"
+                        sylius: "~2.2.0"
+                        node: "24.x"
+                        database: "mysql"
+                        database_version: "8.4"
+                        wkhtmltopdf: false
+                        state_machine_adapter: "symfony_workflow"
+                        legacy: true
 
                     -
                         php: "8.3"
@@ -56,6 +80,18 @@ jobs:
                         database_version: "8.4"
                         wkhtmltopdf: false
                         state_machine_adapter: "symfony_workflow"
+                        legacy: false
+
+                    -
+                        php: "8.3"
+                        symfony: "^7.4"
+                        sylius: "~2.2.0"
+                        node: "24.x"
+                        database: "postgres"
+                        database_version: "15.8"
+                        wkhtmltopdf: "0.12.6.1-2"
+                        state_machine_adapter: "symfony_workflow"
+                        legacy: true
 
                     -
                         php: "8.3"
@@ -66,12 +102,14 @@ jobs:
                         database_version: "15.8"
                         wkhtmltopdf: "0.12.6.1-2"
                         state_machine_adapter: "symfony_workflow"
+                        legacy: false
 
         env:
             APP_ENV: test
             DATABASE_URL: ${{ matrix.database == 'mysql' && format('mysql://root:root@127.0.0.1/sylius?serverVersion={0}', matrix.database_version) || format('pgsql://postgres:postgres@127.0.0.1/sylius?serverVersion={0}', matrix.database_version) }}
             TEST_SYLIUS_STATE_MACHINE_ADAPTER: "${{ matrix.state_machine_adapter }}"
             TEST_SYLIUS_REFUND_PDF_GENERATION_DISABLED: ${{ matrix.wkhtmltopdf == false }}
+            TEST_SYLIUS_REFUND_PDF_LEGACY: "${{ matrix.legacy }}"
 
         steps:
             -
@@ -184,7 +222,7 @@ jobs:
                 uses: actions/upload-artifact@v4
                 if: failure()
                 with:
-                    name: "Behat logs - ${{ matrix.sylius }}-${{ github.run_id }}-${{ github.run_number }}"
+                    name: "Behat logs - ${{ matrix.sylius }}-legacy-${{ matrix.legacy }}-${{ github.run_id }}-${{ github.run_number }}"
                     path: etc/build/
                     if-no-files-found: ignore
                     compression-level: 6

UPGRADE-2.1.md

@@ -0,0 +1,64 @@
+# UPGRADE FROM 2.0 TO 2.1
+
+1. Support for the `SyliusPdfGenerationBundle` has been added as an alternative to the legacy PDF generation
+   which was using `KnpSnappyBundle` with a hardcoded `wkhtmltopdf` binary.
+   To use it, set the `legacy` option to `false` in your configuration:
+
+    ```yaml
+    sylius_refund:
+        pdf_generator:
+            legacy: false
+    ```
+
+   The bundle is preconfigured with `knp_snappy` adapter and `gaufrette` storage by default, with a `sylius_refund` context making it a drop-in replacement.
+
+1. The following services now accept new argument types from the `SyliusPdfGenerationBundle`. Passing the old types is deprecated and will be removed in 3.0:
+
+   - `Sylius\RefundPlugin\Generator\CreditMemoPdfFileGenerator`:
+
+     ```diff
+     public function __construct(
+         private RepositoryInterface $creditMemoRepository,
+         private FileLocatorInterface $fileLocator,
+         private string $template,
+         private string $creditMemoLogoPath,
+     -   private TwigToPdfGeneratorInterface $twigToPdfGenerator,
+     +   private TwigToPdfGeneratorInterface|TwigToPdfRendererInterface $twigToPdfRenderer,
+         private CreditMemoFileNameGeneratorInterface $creditMemoFileNameGenerator,
+     )
+     ```
+
+   - `Sylius\RefundPlugin\Resolver\CreditMemoFileResolver`:
+
+     ```diff
+     public function __construct(
+         private CreditMemoRepositoryInterface $creditMemoRepository,
+         private CreditMemoFileProviderInterface $creditMemoFileProvider,
+         private CreditMemoPdfFileGeneratorInterface $creditMemoPdfFileGenerator,
+     -   private CreditMemoFileManagerInterface $creditMemoFileManager,
+     +   private CreditMemoFileManagerInterface|PdfFileManagerInterface $creditMemoFileManager,
+     +   private ?CreditMemoFileNameGeneratorInterface $creditMemoFileNameGenerator = null,
+     )
+     ```
+
+   - `Sylius\RefundPlugin\Resolver\CreditMemoFilePathResolver`:
+
+     ```diff
+     public function __construct(
+     -   private string $creditMemosPath,
+     +   private string|PdfFileManagerInterface $creditMemosPath,
+     )
+     ```
+
+1. The following classes, interfaces, and services have been deprecated and will be removed in 3.0:
+
+   | Deprecated                                                        | Replacement                                                                  |
+   |-------------------------------------------------------------------|------------------------------------------------------------------------------|
+   | `Sylius\RefundPlugin\Generator\TwigToPdfGeneratorInterface`       | `Sylius\PdfGenerationBundle\Core\Renderer\TwigToPdfRendererInterface`        |
+   | `Sylius\RefundPlugin\Generator\TwigToPdfGenerator`                | `Sylius\PdfGenerationBundle\Core\Renderer\TwigToPdfRendererInterface`        |
+   | `Sylius\RefundPlugin\Generator\PdfOptionsGeneratorInterface`      | `sylius/pdf-generation-bundle` option processors                             |
+   | `Sylius\RefundPlugin\Generator\PdfOptionsGenerator`               | `sylius/pdf-generation-bundle` option processors                             |
+   | `Sylius\RefundPlugin\Manager\CreditMemoFileManagerInterface`      | `Sylius\PdfGenerationBundle\Core\Filesystem\Manager\PdfFileManagerInterface` |
+   | `Sylius\RefundPlugin\Manager\CreditMemoFileManager`               | `Sylius\PdfGenerationBundle\Core\Filesystem\Manager\PdfFileManager`          |
+
+   The corresponding services (`sylius_refund.generator.twig_to_pdf`, `sylius_refund.generator.pdf_options`, and `sylius_refund.manager.credit_memo_file`) are also deprecated.

composer.json

@@ -22,10 +22,11 @@
         "php": "^8.2",
         "knplabs/knp-snappy-bundle": "^1.10",
         "myclabs/php-enum": "^1.8",
+        "sylius/pdf-generation-bundle": "^1.0",
         "sylius/resource-bundle": "^1.12",
         "sylius/sylius": "^2.0",
         "sylius/telemetry": "^1.0",
-        "symfony/messenger": "^6.4 || ^7.1",
+        "symfony/messenger": "^6.4 || ^7.4",
         "php-http/discovery": "^1.20"
     },
     "require-dev": {
@@ -47,11 +48,11 @@
         "phpunit/phpunit": "^10.5",
         "sylius-labs/coding-standard": "^4.2",
         "sylius/test-application": "^2.0.0@alpha",
-        "symfony/browser-kit": "^6.4 || ^7.1",
-        "symfony/debug-bundle": "^6.4 || ^7.1",
-        "symfony/dotenv": "^6.4 || ^7.1",
-        "symfony/intl": "^6.4 || ^7.1",
-        "symfony/web-profiler-bundle": "^6.4 || ^7.1",
+        "symfony/browser-kit": "^6.4 || ^7.4",
+        "symfony/debug-bundle": "^6.4 || ^7.4",
+        "symfony/dotenv": "^6.4 || ^7.4",
+        "symfony/intl": "^6.4 || ^7.4",
+        "symfony/web-profiler-bundle": "^6.4 || ^7.4",
         "symfony/webpack-encore-bundle": "^2.2"
     },
     "autoload": {

config/services.xml

@@ -80,6 +80,7 @@
 
         <service id="sylius_refund.manager.credit_memo_file" class="Sylius\RefundPlugin\Manager\CreditMemoFileManager">
             <argument type="service" id="gaufrette.sylius_refund_credit_memo_filesystem" />
+            <deprecated package="sylius/refund-plugin" version="2.1">The "%service_id%" service is deprecated. Use Sylius\PdfGenerationBundle\Core\Filesystem\Manager\PdfFileManagerInterface from sylius/pdf-generation-bundle instead.</deprecated>
         </service>
         <service id="Sylius\RefundPlugin\Manager\CreditMemoFileManagerInterface" alias="sylius_refund.manager.credit_memo_file" />
     </services>

config/services/generators.xml

@@ -59,13 +59,15 @@
             <argument type="service" id="file_locator" />
             <argument>%knp_snappy.pdf.options%</argument>
             <argument>%sylius_refund.pdf_generator.allowed_files%</argument>
+            <deprecated package="sylius/refund-plugin" version="2.1">The "%service_id%" service is deprecated. PDF options are now handled by sylius/pdf-generation-bundle adapters.</deprecated>
         </service>
         <service id="Sylius\RefundPlugin\Generator\PdfOptionsGeneratorInterface" alias="sylius_refund.generator.pdf_options" />
 
         <service id="sylius_refund.generator.twig_to_pdf" class="Sylius\RefundPlugin\Generator\TwigToPdfGenerator">
             <argument type="service" id="twig" />
             <argument type="service" id="knp_snappy.pdf" />
             <argument type="service" id="sylius_refund.generator.pdf_options" />
+            <deprecated package="sylius/refund-plugin" version="2.1">The "%service_id%" service is deprecated. Use Sylius\PdfGenerationBundle\Core\Renderer\TwigToPdfRendererInterface from sylius/pdf-generation-bundle instead.</deprecated>
         </service>
         <service id="Sylius\RefundPlugin\Generator\TwigToPdfGeneratorInterface" alias="sylius_refund.generator.twig_to_pdf" />
     </services>

config/services/resolvers.xml

@@ -22,6 +22,7 @@
             <argument type="service" id="sylius_refund.provider.credit_memo_file" />
             <argument type="service" id="sylius_refund.generator.credit_memo_pdf_file" />
             <argument type="service" id="sylius_refund.manager.credit_memo_file" />
+            <argument type="service" id="sylius_refund.generator.credit_memo_file_name" />
         </service>
         <service id="Sylius\RefundPlugin\Resolver\CreditMemoFileResolverInterface" alias="sylius_refund.resolver.credit_memo_file" />
 

src/DependencyInjection/Configuration.php

@@ -62,7 +62,8 @@ private function addPdfGeneratorSection(ArrayNodeDefinition $node): void
                         ->end()
                     ->end()
                     ->children()
-                        ->booleanNode('enabled')->defaultTrue()
+                        ->booleanNode('enabled')->defaultTrue()->end()
+                        ->booleanNode('legacy')->defaultTrue()->end()
                     ->end()
                 ->end()
             ->end()

src/DependencyInjection/SyliusRefundExtension.php

@@ -15,16 +15,21 @@
 
 use Sylius\Bundle\CoreBundle\DependencyInjection\PrependDoctrineMigrationsTrait;
 use Sylius\Bundle\ResourceBundle\DependencyInjection\Extension\AbstractResourceExtension;
+use Sylius\PdfGenerationBundle\Core\Filesystem\Manager\PdfFileManagerInterface;
+use Sylius\PdfGenerationBundle\Core\Renderer\TwigToPdfRendererInterface;
 use Sylius\RefundPlugin\Converter\LineItem\LineItemsConverterUnitRefundAwareInterface;
 use Sylius\RefundPlugin\Converter\Request\RequestToRefundUnitsConverterInterface;
+use Sylius\RefundPlugin\Generator\RefundAllowedFilesOptionsProcessor;
 use Sylius\RefundPlugin\ProcessManager\UnitsRefundedProcessStepInterface;
 use Sylius\RefundPlugin\Provider\RefundUnitTotalProviderInterface;
 use Sylius\RefundPlugin\Refunder\RefunderInterface;
 use Symfony\Component\Config\Definition\ConfigurationInterface;
 use Symfony\Component\Config\FileLocator;
 use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Definition;
 use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
 use Symfony\Component\DependencyInjection\Loader\XmlFileLoader;
+use Symfony\Component\DependencyInjection\Reference;
 
 final class SyliusRefundExtension extends AbstractResourceExtension implements PrependExtensionInterface
 {
@@ -50,6 +55,22 @@ public function load(array $configs, ContainerBuilder $container): void
         ]);
 
         $container->setParameter('sylius_refund.pdf_generator.allowed_files', $configs['pdf_generator']['allowed_files']);
+
+        if (!$configs['pdf_generator']['legacy']) {
+            $container->getDefinition('sylius_refund.generator.credit_memo_pdf_file')
+                ->replaceArgument(4, new Reference(TwigToPdfRendererInterface::class))
+            ;
+
+            $container->getDefinition('sylius_refund.resolver.credit_memo_file')
+                ->replaceArgument(3, new Reference(PdfFileManagerInterface::class))
+            ;
+
+            $container->getDefinition('sylius_refund.resolver.credit_memo_file_path')
+                ->replaceArgument(0, new Reference(PdfFileManagerInterface::class))
+            ;
+
+            $this->registerAllowedFilesProcessor($container, $configs['pdf_generator']['allowed_files']);
+        }
     }
 
     public function prepend(ContainerBuilder $container): void
@@ -58,6 +79,10 @@ public function prepend(ContainerBuilder $container): void
 
         $container->setParameter('sylius_refund.pdf_generator.enabled', $config['pdf_generator']['enabled']);
 
+        if (!$config['pdf_generator']['legacy']) {
+            $this->prependPdfBundleConfiguration($container);
+        }
+
         $this->registerResources('sylius_refund', 'doctrine/orm', $config['resources'], $container);
 
         $this->prependDoctrineMigrations($container);
@@ -99,4 +124,39 @@ private function tagsAutoconfiguration(ContainerBuilder $container, array $tagge
             $container->registerForAutoconfiguration($interface)->addTag($tag);
         }
     }
+
+    private function prependPdfBundleConfiguration(ContainerBuilder $container): void
+    {
+        $container->prependExtensionConfig('sylius_pdf_generation', [
+            'contexts' => [
+                'sylius_refund' => [
+                    'adapter' => 'knp_snappy',
+                    'storage' => [
+                        'type' => 'gaufrette',
+                        'filesystem' => 'gaufrette.sylius_refund_credit_memo_filesystem',
+                        'local_cache_directory' => '%kernel.cache_dir%/sylius_refund_pdf/',
+                    ],
+                ],
+            ],
+        ]);
+    }
+
+    /** @param list<string> $allowedFiles */
+    private function registerAllowedFilesProcessor(ContainerBuilder $container, array $allowedFiles): void
+    {
+        if ([] === $allowedFiles) {
+            return;
+        }
+
+        $definition = new Definition(RefundAllowedFilesOptionsProcessor::class, [
+            new Reference('file_locator'),
+            $allowedFiles,
+        ]);
+        $definition->addTag('sylius_pdf_generation.options_processor', [
+            'adapter' => 'knp_snappy',
+            'context' => 'sylius_refund',
+        ]);
+
+        $container->setDefinition('sylius_refund.options_processor.knp_snappy.allowed_files', $definition);
+    }
 }

src/Generator/CreditMemoPdfFileGenerator.php

@@ -14,6 +14,7 @@
 namespace Sylius\RefundPlugin\Generator;
 
 use Sylius\Component\Resource\Repository\RepositoryInterface;
+use Sylius\PdfGenerationBundle\Core\Renderer\TwigToPdfRendererInterface;
 use Sylius\RefundPlugin\Entity\CreditMemoInterface;
 use Sylius\RefundPlugin\Exception\CreditMemoNotFound;
 use Sylius\RefundPlugin\Model\CreditMemoPdf;
@@ -26,9 +27,19 @@ public function __construct(
         private FileLocatorInterface $fileLocator,
         private string $template,
         private string $creditMemoLogoPath,
-        private TwigToPdfGeneratorInterface $twigToPdfGenerator,
+        private TwigToPdfGeneratorInterface|TwigToPdfRendererInterface $twigToPdfRenderer,
         private CreditMemoFileNameGeneratorInterface $creditMemoFileNameGenerator,
     ) {
+        if ($this->twigToPdfRenderer instanceof TwigToPdfGeneratorInterface) {
+            trigger_deprecation(
+                'sylius/refund-plugin',
+                '2.1',
+                'Passing an instance of %s to %s is deprecated and it will not be supported in 3.0, use an instance of %s instead.',
+                TwigToPdfGeneratorInterface::class,
+                self::class,
+                TwigToPdfRendererInterface::class,
+            );
+        }
     }
 
     public function generate(string $creditMemoId): CreditMemoPdf
@@ -51,7 +62,11 @@ public function generate(string $creditMemoId): CreditMemoPdf
     /** @param array<string, mixed> $templateParams */
     private function generateFromTemplate(array $templateParams): string
     {
-        return $this->twigToPdfGenerator->generate($this->template, $templateParams);
+        if ($this->twigToPdfRenderer instanceof TwigToPdfRendererInterface) {
+            return $this->twigToPdfRenderer->render($this->template, $templateParams, 'sylius_refund');
+        }
+
+        return $this->twigToPdfRenderer->generate($this->template, $templateParams);
     }
 
     private function generateFileName(CreditMemoInterface $creditMemo): string

src/Generator/PdfOptionsGenerator.php

@@ -15,6 +15,9 @@
 
 use Symfony\Component\Config\FileLocatorInterface;
 
+/**
+ * @deprecated since sylius/refund-plugin 2.1, use sylius/pdf-generation-bundle's option processors instead.
+ */
 final readonly class PdfOptionsGenerator implements PdfOptionsGeneratorInterface
 {
     /**

src/Generator/PdfOptionsGeneratorInterface.php

@@ -13,6 +13,9 @@
 
 namespace Sylius\RefundPlugin\Generator;
 
+/**
+ * @deprecated since sylius/refund-plugin 2.1, use sylius/pdf-generation-bundle's adapter options instead.
+ */
 interface PdfOptionsGeneratorInterface
 {
     /** @return array<string, mixed> */