[RELEASE_8.15.0] Add split feature (#132)

* [RELEASE_8.15.0] Add split feature
sensiolabs · Jan 8, 2025 · 7f1e8e9 · 7f1e8e9
1 parent 884eb43
commit 7f1e8e9
Show file tree

Hide file tree

Showing 26 changed files with 1,050 additions and 133 deletions.
diff --git a/README.md b/README.md
@@ -242,7 +242,8 @@ class YourController
    `xltx`, `xlw`, `xml`, `xpm`, `zabw`
 6. [Merge Builder](./docs/pdf/merge-builder.md)
 7. [Convert Builder](./docs/pdf/convert-builder.md)
-8. [PDF customization](./docs/pdf/customization.md) (available for every builder except LibreOffice and Merge)
+8. [Split Builder](./docs/pdf/split-builder.md)
+9. [PDF customization](./docs/pdf/customization.md) (available for every builder except LibreOffice, Merge and Split)
 
 #### Screenshot
 

diff --git a/config/builder_pdf.php b/config/builder_pdf.php
@@ -5,6 +5,7 @@
 use Sensiolabs\GotenbergBundle\Builder\Pdf\LibreOfficePdfBuilder;
 use Sensiolabs\GotenbergBundle\Builder\Pdf\MarkdownPdfBuilder;
 use Sensiolabs\GotenbergBundle\Builder\Pdf\MergePdfBuilder;
+use Sensiolabs\GotenbergBundle\Builder\Pdf\SplitPdfBuilder;
 use Sensiolabs\GotenbergBundle\Builder\Pdf\UrlPdfBuilder;
 use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
 use function Symfony\Component\DependencyInjection\Loader\Configurator\service;
@@ -89,4 +90,15 @@
         ->call('setLogger', [service('logger')->nullOnInvalid()])
         ->tag('sensiolabs_gotenberg.pdf_builder')
     ;
+
+    $services->set('.sensiolabs_gotenberg.pdf_builder.split', SplitPdfBuilder::class)
+        ->share(false)
+        ->args([
+            service('sensiolabs_gotenberg.client'),
+            service('sensiolabs_gotenberg.asset.base_dir_formatter'),
+            service('.sensiolabs_gotenberg.webhook_configuration_registry'),
+        ])
+        ->call('setLogger', [service('logger')->nullOnInvalid()])
+        ->tag('sensiolabs_gotenberg.pdf_builder')
+    ;
 };
diff --git a/docs/builders_api.md b/docs/builders_api.md
@@ -8,6 +8,7 @@
 * [LibreOfficePdfBuilder](./pdf/builders_api/LibreOfficePdfBuilder.md)
 * [MergePdfBuilder](./pdf/builders_api/MergePdfBuilder.md)
 * [ConvertPdfBuilder](./pdf/builders_api/ConvertPdfBuilder.md)
+* [SplitPdfBuilder](./pdf/builders_api/SplitPdfBuilder.md)
 
 ## Screenshot
 

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -231,6 +231,15 @@ sensiolabs_gotenberg:
                 # Enable PDF for Universal Access for optimal accessibility - default false.
                 pdf_universal_access: null
 
+                # Either intervals or pages. - default None. https://gotenberg.dev/docs/routes#split-chromium
+                split_mode: null
+
+                # Either the intervals or the page ranges to extract, depending on the selected mode. - default None. https://gotenberg.dev/docs/routes#split-chromium
+                split_span: null
+
+                # Specify whether to put extracted pages into a single file or as many files as there are page ranges. Only works with pages mode. - default false. https://gotenberg.dev/docs/routes#split-chromium
+                split_unify: null
+
                 # Webhook configuration name or definition.
                 webhook:
 
@@ -419,6 +428,15 @@ sensiolabs_gotenberg:
                 # Enable PDF for Universal Access for optimal accessibility - default false.
                 pdf_universal_access: null
 
+                # Either intervals or pages. - default None. https://gotenberg.dev/docs/routes#split-chromium
+                split_mode: null
+
+                # Either the intervals or the page ranges to extract, depending on the selected mode. - default None. https://gotenberg.dev/docs/routes#split-chromium
+                split_span: null
+
+                # Specify whether to put extracted pages into a single file or as many files as there are page ranges. Only works with pages mode. - default false. https://gotenberg.dev/docs/routes#split-chromium
+                split_unify: null
+
                 # Webhook configuration name or definition.
                 webhook:
 
@@ -607,6 +625,15 @@ sensiolabs_gotenberg:
                 # Enable PDF for Universal Access for optimal accessibility - default false.
                 pdf_universal_access: null
 
+                # Either intervals or pages. - default None. https://gotenberg.dev/docs/routes#split-chromium
+                split_mode: null
+
+                # Either the intervals or the page ranges to extract, depending on the selected mode. - default None. https://gotenberg.dev/docs/routes#split-chromium
+                split_span: null
+
+                # Specify whether to put extracted pages into a single file or as many files as there are page ranges. Only works with pages mode. - default false. https://gotenberg.dev/docs/routes#split-chromium
+                split_unify: null
+
                 # Webhook configuration name or definition.
                 webhook:
 
@@ -755,6 +782,15 @@ sensiolabs_gotenberg:
 
                 # Enable PDF for Universal Access for optimal accessibility - default false.
                 pdf_universal_access: null
+
+                # Either intervals or pages. - default None. https://gotenberg.dev/docs/routes#split-libreoffice
+                split_mode: null
+
+                # Either the intervals or the page ranges to extract, depending on the selected mode. - default None. https://gotenberg.dev/docs/routes#split-libreoffice
+                split_span: null
+
+                # Specify whether to put extracted pages into a single file or as many files as there are page ranges. Only works with pages mode. - default false. https://gotenberg.dev/docs/routes#split-libreoffice
+                split_unify: null
             merge:
 
                 # Convert PDF into the given PDF/A format - default None.
@@ -810,6 +846,15 @@ sensiolabs_gotenberg:
                             name:
                                 name:                 ~
                                 value:                ~
+            split:
+                # Either intervals or pages. - default None. https://gotenberg.dev/docs/routes#split-libreoffice
+                split_mode: null
+
+                # Either the intervals or the page ranges to extract, depending on the selected mode. - default None. https://gotenberg.dev/docs/routes#split-libreoffice
+                split_span: null
+
+                # Specify whether to put extracted pages into a single file or as many files as there are page ranges. Only works with pages mode. - default false. https://gotenberg.dev/docs/routes#split-libreoffice
+                split_unify: null
         screenshot:
             html:
 

diff --git a/docs/generate.php b/docs/generate.php
@@ -6,6 +6,7 @@
 use Sensiolabs\GotenbergBundle\Builder\Pdf\LibreOfficePdfBuilder;
 use Sensiolabs\GotenbergBundle\Builder\Pdf\MarkdownPdfBuilder;
 use Sensiolabs\GotenbergBundle\Builder\Pdf\MergePdfBuilder;
+use Sensiolabs\GotenbergBundle\Builder\Pdf\SplitPdfBuilder;
 use Sensiolabs\GotenbergBundle\Builder\Pdf\UrlPdfBuilder;
 use Sensiolabs\GotenbergBundle\Builder\Screenshot\HtmlScreenshotBuilder;
 use Sensiolabs\GotenbergBundle\Builder\Screenshot\MarkdownScreenshotBuilder;
@@ -27,6 +28,7 @@
         LibreOfficePdfBuilder::class,
         MergePdfBuilder::class,
         ConvertPdfBuilder::class,
+        SplitPdfBuilder::class,
     ],
     'screenshot' => [
         HtmlScreenshotBuilder::class,

diff --git a/docs/pdf/builders_api/HtmlPdfBuilder.md b/docs/pdf/builders_api/HtmlPdfBuilder.md
@@ -138,6 +138,15 @@ Resets the metadata.
 * `addMetadata(string $key, string $value)`:
 The metadata to write.
 
+* `splitMode(?Sensiolabs\GotenbergBundle\Enumeration\SplitMode $splitMode)`:
+Either intervals or pages. (default None).
+
+* `splitSpan(string $splitSpan)`:
+Either the intervals or the page ranges to extract, depending on the selected mode. (default None).
+
+* `splitUnify(bool $bool)`:
+Specify whether to put extracted pages into a single file or as many files as there are page ranges. Only works with pages mode. (default false).
+
 * `downloadFrom(array $downloadFrom)`:
 
 * `webhookConfiguration(string $name)`:

diff --git a/docs/pdf/builders_api/LibreOfficePdfBuilder.md b/docs/pdf/builders_api/LibreOfficePdfBuilder.md
@@ -85,6 +85,15 @@ Specify if the resolution of each image is reduced to the resolution specified b
 * `maxImageResolution(Sensiolabs\GotenbergBundle\Enumeration\ImageResolutionDPI $resolution)`:
 If the form field reduceImageResolution is set to true, tell if all images will be reduced to the given value in DPI. Possible values are: 75, 150, 300, 600 and 1200.
 
+* `splitMode(?Sensiolabs\GotenbergBundle\Enumeration\SplitMode $splitMode)`:
+Either intervals or pages. (default None).
+
+* `splitSpan(string $splitSpan)`:
+Either the intervals or the page ranges to extract, depending on the selected mode. (default None).
+
+* `splitUnify(bool $bool)`:
+Specify whether to put extracted pages into a single file or as many files as there are page ranges. Only works with pages mode. (default false).
+
 * `downloadFrom(array $downloadFrom)`:
 
 * `webhookConfiguration(string $name)`:

diff --git a/docs/pdf/builders_api/MarkdownPdfBuilder.md b/docs/pdf/builders_api/MarkdownPdfBuilder.md
@@ -141,6 +141,15 @@ Resets the metadata.
 * `addMetadata(string $key, string $value)`:
 The metadata to write.
 
+* `splitMode(?Sensiolabs\GotenbergBundle\Enumeration\SplitMode $splitMode)`:
+Either intervals or pages. (default None).
+
+* `splitSpan(string $splitSpan)`:
+Either the intervals or the page ranges to extract, depending on the selected mode. (default None).
+
+* `splitUnify(bool $bool)`:
+Specify whether to put extracted pages into a single file or as many files as there are page ranges. Only works with pages mode. (default false).
+
 * `downloadFrom(array $downloadFrom)`:
 
 * `webhookConfiguration(string $name)`:

diff --git a/docs/pdf/builders_api/SplitPdfBuilder.md b/docs/pdf/builders_api/SplitPdfBuilder.md
@@ -0,0 +1,31 @@
+# SplitPdfBuilder
+
+Split `n` pdf files.
+
+* `splitMode(?Sensiolabs\GotenbergBundle\Enumeration\SplitMode $splitMode)`:
+Either intervals or pages. (default None).
+
+* `splitSpan(string $splitSpan)`:
+Either the intervals or the page ranges to extract, depending on the selected mode. (default None).
+
+* `splitUnify(bool $bool)`:
+Specify whether to put extracted pages into a single file or as many files as there are page ranges. Only works with pages mode. (default false).
+
+* `files(string $paths)`:
+
+* `downloadFrom(array $downloadFrom)`:
+
+* `webhookConfiguration(string $name)`:
+Providing an existing $name from the configuration file, it will correctly set both success and error webhook URLs as well as extra_http_headers if defined.
+
+* `webhookUrl(string $url, ?string $method)`:
+Sets the webhook for cases of success.
+Optionaly sets a custom HTTP method for such endpoint among : POST, PUT or PATCH.
+
+* `errorWebhookUrl(?string $url, ?string $method)`:
+Sets the webhook for cases of error.
+Optionaly sets a custom HTTP method for such endpoint among : POST, PUT or PATCH.
+
+* `webhookExtraHeaders(array $extraHeaders)`:
+Extra headers that will be provided to the webhook endpoint. May it either be Success or Error.
+
diff --git a/docs/pdf/builders_api/UrlPdfBuilder.md b/docs/pdf/builders_api/UrlPdfBuilder.md
@@ -140,6 +140,15 @@ Resets the metadata.
 * `addMetadata(string $key, string $value)`:
 The metadata to write.
 
+* `splitMode(?Sensiolabs\GotenbergBundle\Enumeration\SplitMode $splitMode)`:
+Either intervals or pages. (default None).
+
+* `splitSpan(string $splitSpan)`:
+Either the intervals or the page ranges to extract, depending on the selected mode. (default None).
+
+* `splitUnify(bool $bool)`:
+Specify whether to put extracted pages into a single file or as many files as there are page ranges. Only works with pages mode. (default false).
+
 * `downloadFrom(array $downloadFrom)`:
 
 * `webhookConfiguration(string $name)`:

diff --git a/docs/pdf/customization.md b/docs/pdf/customization.md
@@ -23,6 +23,9 @@
 [landscape](#landscape)  
 [scale](#scale)  
 [nativePageRanges](#nativePageRanges)  
+[splitMode](#splitMode)  
+[splitSpan](#splitSpan)  
+[splitUnify](#splitUnify)  
 
 ### Additional content 
 [header and footer](#header-and-footer)   
@@ -424,6 +427,96 @@ class YourController
     }
 }
 ```
+
+## splitMode
+
+default: `None`
+
+Either `intervals` or `pages`.
+
+```php
+namespace App\Controller;
+
+use Sensiolabs\GotenbergBundle\Enum\SplitMode;
+use Sensiolabs\GotenbergBundle\GotenbergPdfInterface;
+
+class YourController
+{
+    public function yourControllerMethod(GotenbergPdfInterface $gotenberg): Response
+    {
+        return $gotenberg->html()
+            ->content('content.html.twig', [
+                'my_var' => 'value'
+            ])
+            ->splitMode(SplitMode::Intervals)
+            ->splitSpan('1')
+            ->generate()
+            ->stream()
+         ;
+    }
+}
+```
+
+## splitSpan
+
+default: `None`
+
+Either the intervals or the page ranges to extract, depending on the selected `splitMode`.
+
+```php
+namespace App\Controller;
+
+use Sensiolabs\GotenbergBundle\Enumeration\SplitMode;
+use Sensiolabs\GotenbergBundle\GotenbergPdfInterface;
+
+class YourController
+{
+    public function yourControllerMethod(GotenbergPdfInterface $gotenberg): Response
+    {
+        return $gotenberg->html()
+            ->content('content.html.twig', [
+                'my_var' => 'value'
+            ]))
+            ->splitMode(SplitMode::Intervals)
+            ->splitSpan('1')
+            ->generate()
+            ->stream()
+         ;
+    }
+}
+```
+
+## splitUnify
+
+Default: `false`
+
+Specify whether to put extracted pages into a single file or as many files as
+there are page ranges. Only works with `pages` mode.
+
+```php
+namespace App\Controller;
+
+use Sensiolabs\GotenbergBundle\Enum\SplitMode;
+use Sensiolabs\GotenbergBundle\GotenbergPdfInterface;
+
+class YourController
+{
+    public function yourControllerMethod(GotenbergPdfInterface $gotenberg): Response
+    {
+        return $gotenberg->html()
+            ->content('content.html.twig', [
+                'my_var' => 'value'
+            ])
+            ->splitMode(SplitMode::Pages)
+            ->splitSpan('1-2')
+            ->splitUnify() // is same as ->splitUnify(true)
+            ->generate()
+            ->stream()
+         ;
+    }
+}
+```
+
 ## Additional content
 
 > [!WARNING]