From 910c18aa883df4625ee8fb3222421b19bcb6d084 Mon Sep 17 00:00:00 2001 From: Marilena Ruffelaere Date: Tue, 19 May 2026 10:02:49 +0200 Subject: [PATCH 1/3] refactor: extract PageMarginalTrait from ContentTrait header*, footer* methods move to the new PageMarginalTrait. The original methods remain in ContentTrait as deprecated no-ops (E_USER_DEPRECATED, will be removed in 2.0) for BC, allowing existing code to receive a deprecation warning rather than a runtime error. ChromiumPdfTrait is updated to prefer PageMarginalTrait over the deprecated ContentTrait stubs via insteadof. Screenshot builders keep using ContentTrait directly since Gotenberg does not support headers and footers for screenshots; the deprecated stubs are filtered out of the generated documentation. The deprecation message was corrected: the stubs in ContentTrait are only ever called by builders that do not use PageMarginalTrait (e.g. screenshot builders), so saying "Use PageMarginalTrait instead" would be misleading. The message now states that header/footer support is not available on the current builder. --- UPGRADE-1.2.md | 12 ++ docs/pdf/HtmlPdfBuilder.md | 15 +- docs/pdf/MarkdownPdfBuilder.md | 15 +- docs/screenshot/HtmlScreenshotBuilder.md | 101 ++---------- docs/screenshot/MarkdownScreenshotBuilder.md | 101 ++---------- .../Behaviors/Chromium/ContentTrait.php | 92 +++++------ .../Behaviors/Chromium/PageMarginalTrait.php | 145 ++++++++++++++++++ src/Builder/Behaviors/ChromiumPdfTrait.php | 9 +- 8 files changed, 242 insertions(+), 248 deletions(-) create mode 100644 src/Builder/Behaviors/Chromium/PageMarginalTrait.php diff --git a/UPGRADE-1.2.md b/UPGRADE-1.2.md index dcbb65ad..7596b385 100644 --- a/UPGRADE-1.2.md +++ b/UPGRADE-1.2.md @@ -1 +1,13 @@ # UPGRADE FROM 1.1.0 to 1.2.0 + +## Deprecations + +### `ContentTrait`: header and footer methods moved to `PageMarginalTrait` + +The `header()`, `headerRaw()`, `headerFile()`, `footer()`, `footerRaw()` and `footerFile()` methods have been moved out of `ContentTrait` into the new dedicated `PageMarginalTrait`. These methods are still accessible through `ContentTrait` in 1.2 but will be removed in 2.0. + +If you use `ContentTrait` directly in your own builders, add `PageMarginalTrait` instead to handle headers and footers. + +### `UrlPdfBuilder` and `UrlScreenshotBuilder`: `content*` methods deprecated + +The `content()`, `contentRaw()` and `contentFile()` methods are deprecated on `UrlPdfBuilder` and `UrlScreenshotBuilder`. Since the page body is provided by the URL itself, these methods have no effect. Use `url()` or `route()` instead. They will be removed in 2.0. diff --git a/docs/pdf/HtmlPdfBuilder.md b/docs/pdf/HtmlPdfBuilder.md index 1740881f..f8d0164a 100644 --- a/docs/pdf/HtmlPdfBuilder.md +++ b/docs/pdf/HtmlPdfBuilder.md @@ -304,6 +304,15 @@ Adds a file, like an image, font, stylesheet, and so on.

By default, > [!TIP] > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets) +```php +return $gotenberg + // Your builder call as ->html() and the rest of your configuration code + ->addAsset('../img/ceo.jpeg', __DIR__'/../../public/admin.jpeg') + ->generate() + ->stream() +; +``` + ### assets(Stringable|string ...\$paths) Adds additional files, like images, fonts, stylesheets, and so on (overrides any previous files).

By default, the assets files are fetch in the assets folder of your application.
If your assets are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.
@@ -774,7 +783,7 @@ return $gotenberg ```php return $gotenberg // Your builder call as ->html() and the rest of your configuration code - ->footer('header.html.twig', ['my_var' => 'value']) + ->footer('footer.html.twig', ['my_var' => 'value']) ->generate() ->stream() ; @@ -796,7 +805,7 @@ return $gotenberg ``` ### footerRaw(string \$html) -The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
+The raw html string to use as the page footer.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
> [!TIP] > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) @@ -839,7 +848,7 @@ return $gotenberg ``` ### headerRaw(string \$html) -The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
+The raw html string to use as the page header.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
> [!TIP] > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) diff --git a/docs/pdf/MarkdownPdfBuilder.md b/docs/pdf/MarkdownPdfBuilder.md index d3ec5702..70249935 100644 --- a/docs/pdf/MarkdownPdfBuilder.md +++ b/docs/pdf/MarkdownPdfBuilder.md @@ -377,6 +377,15 @@ Adds a file, like an image, font, stylesheet, and so on.

By default, > [!TIP] > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets) +```php +return $gotenberg + // Your builder call as ->html() and the rest of your configuration code + ->addAsset('../img/ceo.jpeg', __DIR__'/../../public/admin.jpeg') + ->generate() + ->stream() +; +``` + ### assets(Stringable|string ...\$paths) Adds additional files, like images, fonts, stylesheets, and so on (overrides any previous files).

By default, the assets files are fetch in the assets folder of your application.
If your assets are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.
@@ -825,7 +834,7 @@ return $gotenberg ```php return $gotenberg // Your builder call as ->html() and the rest of your configuration code - ->footer('header.html.twig', ['my_var' => 'value']) + ->footer('footer.html.twig', ['my_var' => 'value']) ->generate() ->stream() ; @@ -847,7 +856,7 @@ return $gotenberg ``` ### footerRaw(string \$html) -The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
+The raw html string to use as the page footer.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
> [!TIP] > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) @@ -890,7 +899,7 @@ return $gotenberg ``` ### headerRaw(string \$html) -The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
+The raw html string to use as the page header.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
> [!TIP] > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) diff --git a/docs/screenshot/HtmlScreenshotBuilder.md b/docs/screenshot/HtmlScreenshotBuilder.md index 02f00eeb..a1b76d91 100644 --- a/docs/screenshot/HtmlScreenshotBuilder.md +++ b/docs/screenshot/HtmlScreenshotBuilder.md @@ -107,12 +107,6 @@ class YourController - [content](#contentstring-template-array-context) - [contentFile](#contentfilestring-path) - [contentRaw](#contentrawstring-html) -- [footer](#footerstring-template-array-context) -- [footerFile](#footerfilestring-path) -- [footerRaw](#footerrawstring-html) -- [header](#headerstring-template-array-context) -- [headerFile](#headerfilestring-path) -- [headerRaw](#headerrawstring-html) - [emulatedMediaFeatures](#emulatedmediafeaturesarray-emulatedmediafeatures) - [failOnConsoleExceptions](#failonconsoleexceptionsbool-bool) - [failOnHttpStatusCodes](#failonhttpstatuscodesarray-statuscodes) @@ -147,6 +141,15 @@ Adds a file, like an image, font, stylesheet, and so on.

By default, > [!TIP] > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets) +```php +return $gotenberg + // Your builder call as ->html() and the rest of your configuration code + ->addAsset('../img/ceo.jpeg', __DIR__'/../../public/admin.jpeg') + ->generate() + ->stream() +; +``` + ### assets(Stringable|string ...\$paths) Adds additional files, like images, fonts, stylesheets, and so on (overrides any previous files).

By default, the assets files are fetch in the assets folder of your application.
If your assets are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.
@@ -484,92 +487,6 @@ return $gotenberg ; ``` -### footer(string \$template, array \$context) -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->footer('header.html.twig', ['my_var' => 'value']) - ->generate() - ->stream() -; -``` - -### footerFile(string \$path) -HTML file containing the footer.

As assets files, by default the HTML files are fetch in the assets folder of your application.
If your HTML files are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->footerFile('../templates/html/footer.html') - ->generate() - ->stream() -; -``` - -### footerRaw(string \$html) -The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->footerRaw('
The footer
') - ->generate() - ->stream() -; -``` - -### header(string \$template, array \$context) -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->header('header.html.twig', ['my_var' => 'value']) - ->generate() - ->stream() -; -``` - -### headerFile(string \$path) -HTML file containing the header.

As assets files, by default the HTML files are fetch in the assets folder of your application.
If your HTML files are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->headerFile('../templates/html/header.html') - ->generate() - ->stream() -; -``` - -### headerRaw(string \$html) -The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->headerRaw('

The header

') - ->generate() - ->stream() -; -``` - ### emulatedMediaFeatures(array \$emulatedMediaFeatures) You can simulate specific browser conditions by overriding CSS media features.
This is particularly useful for forcing "Dark Mode" or testing layouts with reduced motion.
diff --git a/docs/screenshot/MarkdownScreenshotBuilder.md b/docs/screenshot/MarkdownScreenshotBuilder.md index c5b881ad..9e696980 100644 --- a/docs/screenshot/MarkdownScreenshotBuilder.md +++ b/docs/screenshot/MarkdownScreenshotBuilder.md @@ -150,12 +150,6 @@ class YourController - [waitForExpression](#waitforexpressionstring-expression) - [waitForSelector](#waitforselectorstring-selector) - [contentRaw](#contentrawstring-html) -- [footer](#footerstring-template-array-context) -- [footerFile](#footerfilestring-path) -- [footerRaw](#footerrawstring-html) -- [header](#headerstring-template-array-context) -- [headerFile](#headerfilestring-path) -- [headerRaw](#headerrawstring-html) - [emulatedMediaFeatures](#emulatedmediafeaturesarray-emulatedmediafeatures) - [failOnConsoleExceptions](#failonconsoleexceptionsbool-bool) - [failOnHttpStatusCodes](#failonhttpstatuscodesarray-statuscodes) @@ -236,6 +230,15 @@ Adds a file, like an image, font, stylesheet, and so on.

By default, > [!TIP] > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets) +```php +return $gotenberg + // Your builder call as ->html() and the rest of your configuration code + ->addAsset('../img/ceo.jpeg', __DIR__'/../../public/admin.jpeg') + ->generate() + ->stream() +; +``` + ### assets(Stringable|string ...\$paths) Adds additional files, like images, fonts, stylesheets, and so on (overrides any previous files).

By default, the assets files are fetch in the assets folder of your application.
If your assets are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.
@@ -551,92 +554,6 @@ return $gotenberg ; ``` -### footer(string \$template, array \$context) -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->footer('header.html.twig', ['my_var' => 'value']) - ->generate() - ->stream() -; -``` - -### footerFile(string \$path) -HTML file containing the footer.

As assets files, by default the HTML files are fetch in the assets folder of your application.
If your HTML files are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->footerFile('../templates/html/footer.html') - ->generate() - ->stream() -; -``` - -### footerRaw(string \$html) -The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->footerRaw('
The footer
') - ->generate() - ->stream() -; -``` - -### header(string \$template, array \$context) -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->header('header.html.twig', ['my_var' => 'value']) - ->generate() - ->stream() -; -``` - -### headerFile(string \$path) -HTML file containing the header.

As assets files, by default the HTML files are fetch in the assets folder of your application.
If your HTML files are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->headerFile('../templates/html/header.html') - ->generate() - ->stream() -; -``` - -### headerRaw(string \$html) -The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->headerRaw('

The header

') - ->generate() - ->stream() -; -``` - ### emulatedMediaFeatures(array \$emulatedMediaFeatures) You can simulate specific browser conditions by overriding CSS media features.
This is particularly useful for forcing "Dark Mode" or testing layouts with reduced motion.
diff --git a/src/Builder/Behaviors/Chromium/ContentTrait.php b/src/Builder/Behaviors/Chromium/ContentTrait.php index 730bdfe4..80c87563 100644 --- a/src/Builder/Behaviors/Chromium/ContentTrait.php +++ b/src/Builder/Behaviors/Chromium/ContentTrait.php @@ -71,14 +71,14 @@ public function contentFile(string $path): self } /** + * @deprecated since 1.2, header/footer support has been moved to PageMarginalTrait. Will be removed in 2.0. + * * @param string $template #Template * @param array $context * * @throws PartRenderingException if the template could not be rendered * * @see https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer - * - * @example header('header.html.twig', ['my_var' => 'value']) */ #[WithConfigurationNode(new ArrayNodeBuilder('header', children: [ new ScalarNodeBuilder('template', required: true, restrictTo: 'string'), @@ -86,33 +86,44 @@ public function contentFile(string $path): self ]))] public function header(string $template, array $context = []): static { - return $this->withRenderedPart(Part::Header, $template, $context); + @trigger_error(\sprintf('Since sensiolabs/gotenberg-bundle 1.2: "%s" is deprecated and will be removed in 2.0. Header/footer support has been moved to "%s"; this builder does not support it.', __METHOD__, PageMarginalTrait::class), \E_USER_DEPRECATED); + + return $this; } /** - * The raw html string to convert into PDF. - * - * Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically. - * Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets. - * + * @deprecated since 1.2, header/footer support has been moved to PageMarginalTrait. Will be removed in 2.0. * @see https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer - * - * @example headerRaw('

The header

') */ public function headerRaw(string $html): static { - return $this->withRawPart(Part::Header, $html); + @trigger_error(\sprintf('Since sensiolabs/gotenberg-bundle 1.2: "%s" is deprecated and will be removed in 2.0. Header/footer support has been moved to "%s"; this builder does not support it.', __METHOD__, PageMarginalTrait::class), \E_USER_DEPRECATED); + + return $this; } /** + * @deprecated since 1.2, header/footer support has been moved to PageMarginalTrait. Will be removed in 2.0. + * @see https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer + * + * @throws PartRenderingException if the file could not be loaded + */ + public function headerFile(string $path): static + { + @trigger_error(\sprintf('Since sensiolabs/gotenberg-bundle 1.2: "%s" is deprecated and will be removed in 2.0. Header/footer support has been moved to "%s"; this builder does not support it.', __METHOD__, PageMarginalTrait::class), \E_USER_DEPRECATED); + + return $this; + } + + /** + * @deprecated since 1.2, header/footer support has been moved to PageMarginalTrait. Will be removed in 2.0. + * * @param string $template #Template * @param array $context * * @throws PartRenderingException if the template could not be rendered * * @see https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer - * - * @example footer('header.html.twig', ['my_var' => 'value']) */ #[WithConfigurationNode(new ArrayNodeBuilder('footer', children: [ new ScalarNodeBuilder('template', required: true, restrictTo: 'string'), @@ -120,64 +131,33 @@ public function headerRaw(string $html): static ]))] public function footer(string $template, array $context = []): static { - return $this->withRenderedPart(Part::Footer, $template, $context); + @trigger_error(\sprintf('Since sensiolabs/gotenberg-bundle 1.2: "%s" is deprecated and will be removed in 2.0. Header/footer support has been moved to "%s"; this builder does not support it.', __METHOD__, PageMarginalTrait::class), \E_USER_DEPRECATED); + + return $this; } /** - * The raw html string to convert into PDF. - * - * Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically. - * Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets. - * + * @deprecated since 1.2, header/footer support has been moved to PageMarginalTrait. Will be removed in 2.0. * @see https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer - * - * @example footerRaw('
The footer
') */ public function footerRaw(string $html): static { - return $this->withRawPart(Part::Footer, $html); - } + @trigger_error(\sprintf('Since sensiolabs/gotenberg-bundle 1.2: "%s" is deprecated and will be removed in 2.0. Header/footer support has been moved to "%s"; this builder does not support it.', __METHOD__, PageMarginalTrait::class), \E_USER_DEPRECATED); - /** - * HTML file containing the header. - * - * As assets files, by default the HTML files are fetch in the assets folder of your application. - * If your HTML files are in another folder, you can override the default value of assets_directory in your - * configuration file config/sensiolabs_gotenberg.yml. - * - * Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically. - * Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets. - * - * @see https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer - * - * @throws PartRenderingException if the template could not be rendered - * - * @example headerFile('../templates/html/header.html') - */ - public function headerFile(string $path): static - { - return $this->withFilePart(Part::Header, $path); + return $this; } /** - * HTML file containing the footer. - * - * As assets files, by default the HTML files are fetch in the assets folder of your application. - * If your HTML files are in another folder, you can override the default value of assets_directory in your - * configuration file config/sensiolabs_gotenberg.yml. - * - * Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically. - * Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets. - * + * @deprecated since 1.2, header/footer support has been moved to PageMarginalTrait. Will be removed in 2.0. * @see https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer * - * @throws PartRenderingException if the template could not be rendered - * - * @example footerFile('../templates/html/footer.html') + * @throws PartRenderingException if the file could not be loaded */ public function footerFile(string $path): static { - return $this->withFilePart(Part::Footer, $path); + @trigger_error(\sprintf('Since sensiolabs/gotenberg-bundle 1.2: "%s" is deprecated and will be removed in 2.0. Header/footer support has been moved to "%s"; this builder does not support it.', __METHOD__, PageMarginalTrait::class), \E_USER_DEPRECATED); + + return $this; } /** @@ -227,8 +207,6 @@ protected function withFilePart(Part $part, string $path): static #[NormalizeGotenbergPayload] private function normalizeContent(): \Generator { - yield 'header.html' => NormalizerFactory::content(); yield 'index.html' => NormalizerFactory::content(); - yield 'footer.html' => NormalizerFactory::content(); } } diff --git a/src/Builder/Behaviors/Chromium/PageMarginalTrait.php b/src/Builder/Behaviors/Chromium/PageMarginalTrait.php new file mode 100644 index 00000000..e8af95fa --- /dev/null +++ b/src/Builder/Behaviors/Chromium/PageMarginalTrait.php @@ -0,0 +1,145 @@ + $context */ + abstract protected function withRenderedPart(Part $part, string $template, array $context = []): static; + + abstract protected function withRawPart(Part $part, string $html): static; + + /** @throws PartRenderingException */ + abstract protected function withFilePart(Part $part, string $path): static; + + /** + * @param string $template #Template + * @param array $context + * + * @throws PartRenderingException if the template could not be rendered + * + * @see https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer + * + * @example header('header.html.twig', ['my_var' => 'value']) + */ + #[WithConfigurationNode(new ArrayNodeBuilder('header', children: [ + new ScalarNodeBuilder('template', required: true, restrictTo: 'string'), + new ArrayNodeBuilder('context', normalizeKeys: false, prototype: 'variable'), + ]))] + public function header(string $template, array $context = []): static + { + return $this->withRenderedPart(Part::Header, $template, $context); + } + + /** + * The raw html string to use as the page header. + * + * Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically. + * Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets. + * + * @see https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer + * + * @example headerRaw('

The header

') + */ + public function headerRaw(string $html): static + { + return $this->withRawPart(Part::Header, $html); + } + + /** + * HTML file containing the header. + * + * As assets files, by default the HTML files are fetch in the assets folder of your application. + * If your HTML files are in another folder, you can override the default value of assets_directory in your + * configuration file config/sensiolabs_gotenberg.yml. + * + * Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically. + * Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets. + * + * @see https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer + * + * @throws PartRenderingException if the file could not be loaded + * + * @example headerFile('../templates/html/header.html') + */ + public function headerFile(string $path): static + { + return $this->withFilePart(Part::Header, $path); + } + + /** + * @param string $template #Template + * @param array $context + * + * @throws PartRenderingException if the template could not be rendered + * + * @see https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer + * + * @example footer('footer.html.twig', ['my_var' => 'value']) + */ + #[WithConfigurationNode(new ArrayNodeBuilder('footer', children: [ + new ScalarNodeBuilder('template', required: true, restrictTo: 'string'), + new ArrayNodeBuilder('context', normalizeKeys: false, prototype: 'variable'), + ]))] + public function footer(string $template, array $context = []): static + { + return $this->withRenderedPart(Part::Footer, $template, $context); + } + + /** + * The raw html string to use as the page footer. + * + * Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically. + * Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets. + * + * @see https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer + * + * @example footerRaw('
The footer
') + */ + public function footerRaw(string $html): static + { + return $this->withRawPart(Part::Footer, $html); + } + + /** + * HTML file containing the footer. + * + * As assets files, by default the HTML files are fetch in the assets folder of your application. + * If your HTML files are in another folder, you can override the default value of assets_directory in your + * configuration file config/sensiolabs_gotenberg.yml. + * + * Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically. + * Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets. + * + * @see https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer + * + * @throws PartRenderingException if the file could not be loaded + * + * @example footerFile('../templates/html/footer.html') + */ + public function footerFile(string $path): static + { + return $this->withFilePart(Part::Footer, $path); + } + + #[NormalizeGotenbergPayload] + private function normalizePageMarginal(): \Generator + { + yield 'header.html' => NormalizerFactory::content(); + yield 'footer.html' => NormalizerFactory::content(); + } +} diff --git a/src/Builder/Behaviors/ChromiumPdfTrait.php b/src/Builder/Behaviors/ChromiumPdfTrait.php index b40b51fd..78d1d74e 100644 --- a/src/Builder/Behaviors/ChromiumPdfTrait.php +++ b/src/Builder/Behaviors/ChromiumPdfTrait.php @@ -5,7 +5,14 @@ trait ChromiumPdfTrait { use Chromium\AssetTrait; - use Chromium\ContentTrait; + use Chromium\ContentTrait, Chromium\PageMarginalTrait { + Chromium\PageMarginalTrait::header insteadof Chromium\ContentTrait; + Chromium\PageMarginalTrait::headerRaw insteadof Chromium\ContentTrait; + Chromium\PageMarginalTrait::headerFile insteadof Chromium\ContentTrait; + Chromium\PageMarginalTrait::footer insteadof Chromium\ContentTrait; + Chromium\PageMarginalTrait::footerRaw insteadof Chromium\ContentTrait; + Chromium\PageMarginalTrait::footerFile insteadof Chromium\ContentTrait; + } use Chromium\CookieTrait; use Chromium\CustomHttpHeadersTrait; use Chromium\EmulatedMediaFeaturesTrait; From da877c380e824ecb4baf6f8720be52a4b113daf4 Mon Sep 17 00:00:00 2001 From: Marilena Ruffelaere Date: Tue, 19 May 2026 10:03:27 +0200 Subject: [PATCH 2/3] deprecate: content* methods in UrlPdfBuilder and UrlScreenshotBuilder Since the page body is fetched from the URL itself, content(), contentRaw() and contentFile() are meaningless on URL-based builders. They are now deprecated via DeprecatedBodyContentTrait (no-op + E_USER_DEPRECATED) and will be removed in 2.0. --- docs/pdf/UrlPdfBuilder.md | 52 ++----- docs/screenshot/UrlScreenshotBuilder.md | 139 ++---------------- .../Chromium/DeprecatedBodyContentTrait.php | 41 ++++++ src/Builder/Pdf/UrlPdfBuilder.php | 8 +- .../Screenshot/UrlScreenshotBuilder.php | 8 +- 5 files changed, 76 insertions(+), 172 deletions(-) create mode 100644 src/Builder/Behaviors/Chromium/DeprecatedBodyContentTrait.php diff --git a/docs/pdf/UrlPdfBuilder.md b/docs/pdf/UrlPdfBuilder.md index 7aa6e420..5a490b65 100644 --- a/docs/pdf/UrlPdfBuilder.md +++ b/docs/pdf/UrlPdfBuilder.md @@ -114,9 +114,6 @@ class YourController - [waitDelay](#waitdelaystring-delay) - [waitForExpression](#waitforexpressionstring-expression) - [waitForSelector](#waitforselectorstring-selector) -- [content](#contentstring-template-array-context) -- [contentFile](#contentfilestring-path) -- [contentRaw](#contentrawstring-html) - [footer](#footerstring-template-array-context) - [footerFile](#footerfilestring-path) - [footerRaw](#footerrawstring-html) @@ -310,6 +307,15 @@ Adds a file, like an image, font, stylesheet, and so on.

By default, > [!TIP] > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets) +```php +return $gotenberg + // Your builder call as ->html() and the rest of your configuration code + ->addAsset('../img/ceo.jpeg', __DIR__'/../../public/admin.jpeg') + ->generate() + ->stream() +; +``` + ### assets(Stringable|string ...\$paths) Adds additional files, like images, fonts, stylesheets, and so on (overrides any previous files).

By default, the assets files are fetch in the assets folder of your application.
If your assets are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.
@@ -739,40 +745,6 @@ return $gotenberg ``` -### content(string \$template, array \$context) -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->content('content.html.twig', ['my_var' => 'value']) - ->generate() - ->stream() -; -``` - -### contentFile(string \$path) -The HTML file to convert into PDF.

As assets files, by default the HTML files are fetch in the assets folder of your application.
If your HTML files are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->contentFile('../public/content.html') - ->generate() - ->stream() -; -``` - -### contentRaw(string \$html) -The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->contentRaw('

The content

') - ->generate() - ->stream() -; -``` - ### footer(string \$template, array \$context) > [!TIP] > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) @@ -780,7 +752,7 @@ return $gotenberg ```php return $gotenberg // Your builder call as ->html() and the rest of your configuration code - ->footer('header.html.twig', ['my_var' => 'value']) + ->footer('footer.html.twig', ['my_var' => 'value']) ->generate() ->stream() ; @@ -802,7 +774,7 @@ return $gotenberg ``` ### footerRaw(string \$html) -The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
+The raw html string to use as the page footer.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
> [!TIP] > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) @@ -845,7 +817,7 @@ return $gotenberg ``` ### headerRaw(string \$html) -The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
+The raw html string to use as the page header.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
> [!TIP] > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) diff --git a/docs/screenshot/UrlScreenshotBuilder.md b/docs/screenshot/UrlScreenshotBuilder.md index 1fd4c5b6..17b97e84 100644 --- a/docs/screenshot/UrlScreenshotBuilder.md +++ b/docs/screenshot/UrlScreenshotBuilder.md @@ -92,15 +92,6 @@ class YourController - [waitDelay](#waitdelaystring-delay) - [waitForExpression](#waitforexpressionstring-expression) - [waitForSelector](#waitforselectorstring-selector) -- [content](#contentstring-template-array-context) -- [contentFile](#contentfilestring-path) -- [contentRaw](#contentrawstring-html) -- [footer](#footerstring-template-array-context) -- [footerFile](#footerfilestring-path) -- [footerRaw](#footerrawstring-html) -- [header](#headerstring-template-array-context) -- [headerFile](#headerfilestring-path) -- [headerRaw](#headerrawstring-html) - [emulatedMediaFeatures](#emulatedmediafeaturesarray-emulatedmediafeatures) - [failOnConsoleExceptions](#failonconsoleexceptionsbool-bool) - [failOnHttpStatusCodes](#failonhttpstatuscodesarray-statuscodes) @@ -162,6 +153,15 @@ Adds a file, like an image, font, stylesheet, and so on.

By default, > [!TIP] > See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets) +```php +return $gotenberg + // Your builder call as ->html() and the rest of your configuration code + ->addAsset('../img/ceo.jpeg', __DIR__'/../../public/admin.jpeg') + ->generate() + ->stream() +; +``` + ### assets(Stringable|string ...\$paths) Adds additional files, like images, fonts, stylesheets, and so on (overrides any previous files).

By default, the assets files are fetch in the assets folder of your application.
If your assets are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.
@@ -465,127 +465,6 @@ return $gotenberg ``` -### content(string \$template, array \$context) -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->content('content.html.twig', ['my_var' => 'value']) - ->generate() - ->stream() -; -``` - -### contentFile(string \$path) -The HTML file to convert into PDF.

As assets files, by default the HTML files are fetch in the assets folder of your application.
If your HTML files are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->contentFile('../public/content.html') - ->generate() - ->stream() -; -``` - -### contentRaw(string \$html) -The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->contentRaw('

The content

') - ->generate() - ->stream() -; -``` - -### footer(string \$template, array \$context) -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->footer('header.html.twig', ['my_var' => 'value']) - ->generate() - ->stream() -; -``` - -### footerFile(string \$path) -HTML file containing the footer.

As assets files, by default the HTML files are fetch in the assets folder of your application.
If your HTML files are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->footerFile('../templates/html/footer.html') - ->generate() - ->stream() -; -``` - -### footerRaw(string \$html) -The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->footerRaw('
The footer
') - ->generate() - ->stream() -; -``` - -### header(string \$template, array \$context) -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->header('header.html.twig', ['my_var' => 'value']) - ->generate() - ->stream() -; -``` - -### headerFile(string \$path) -HTML file containing the header.

As assets files, by default the HTML files are fetch in the assets folder of your application.
If your HTML files are in another folder, you can override the default value of assets_directory in your
configuration file config/sensiolabs_gotenberg.yml.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->headerFile('../templates/html/header.html') - ->generate() - ->stream() -; -``` - -### headerRaw(string \$html) -The raw html string to convert into PDF.

Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.
Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.
- -> [!TIP] -> See: [https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer](https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#header--footer) - -```php -return $gotenberg - // Your builder call as ->html() and the rest of your configuration code - ->headerRaw('

The header

') - ->generate() - ->stream() -; -``` - - ### emulatedMediaFeatures(array \$emulatedMediaFeatures) You can simulate specific browser conditions by overriding CSS media features.
This is particularly useful for forcing "Dark Mode" or testing layouts with reduced motion.
diff --git a/src/Builder/Behaviors/Chromium/DeprecatedBodyContentTrait.php b/src/Builder/Behaviors/Chromium/DeprecatedBodyContentTrait.php new file mode 100644 index 00000000..ed55a908 --- /dev/null +++ b/src/Builder/Behaviors/Chromium/DeprecatedBodyContentTrait.php @@ -0,0 +1,41 @@ + $context + */ + public function content(string $template, array $context = []): static + { + @trigger_error(\sprintf('Since sensiolabs/gotenberg-bundle 1.2: "%s" is deprecated and will be removed in 2.0. The page body is provided by the URL.', __METHOD__), \E_USER_DEPRECATED); + + return $this; + } + + /** + * @deprecated since 1.2, will be removed in 2.0. The page body is provided by the URL. + */ + public function contentRaw(string $html): static + { + @trigger_error(\sprintf('Since sensiolabs/gotenberg-bundle 1.2: "%s" is deprecated and will be removed in 2.0. The page body is provided by the URL.', __METHOD__), \E_USER_DEPRECATED); + + return $this; + } + + /** + * @deprecated since 1.2, will be removed in 2.0. The page body is provided by the URL. + */ + public function contentFile(string $path): static + { + @trigger_error(\sprintf('Since sensiolabs/gotenberg-bundle 1.2: "%s" is deprecated and will be removed in 2.0. The page body is provided by the URL.', __METHOD__), \E_USER_DEPRECATED); + + return $this; + } +} diff --git a/src/Builder/Pdf/UrlPdfBuilder.php b/src/Builder/Pdf/UrlPdfBuilder.php index 906b7971..adf1eb0a 100644 --- a/src/Builder/Pdf/UrlPdfBuilder.php +++ b/src/Builder/Pdf/UrlPdfBuilder.php @@ -5,6 +5,7 @@ use Sensiolabs\GotenbergBundle\Builder\AbstractBuilder; use Sensiolabs\GotenbergBundle\Builder\Attributes\NormalizeGotenbergPayload; use Sensiolabs\GotenbergBundle\Builder\Attributes\WithBuilderConfiguration; +use Sensiolabs\GotenbergBundle\Builder\Behaviors\Chromium\DeprecatedBodyContentTrait; use Sensiolabs\GotenbergBundle\Builder\Behaviors\ChromiumPdfTrait; use Sensiolabs\GotenbergBundle\Builder\Behaviors\Dependencies\RequestContextAwareTrait; use Sensiolabs\GotenbergBundle\Builder\BuilderAssetInterface; @@ -19,7 +20,12 @@ #[WithBuilderConfiguration(type: 'pdf', name: 'url')] final class UrlPdfBuilder extends AbstractBuilder implements BuilderAssetInterface { - use ChromiumPdfTrait; + use ChromiumPdfTrait, DeprecatedBodyContentTrait { + DeprecatedBodyContentTrait::content insteadof ChromiumPdfTrait; + DeprecatedBodyContentTrait::contentRaw insteadof ChromiumPdfTrait; + DeprecatedBodyContentTrait::contentFile insteadof ChromiumPdfTrait; + } + use RequestContextAwareTrait; public const ENDPOINT = '/forms/chromium/convert/url'; diff --git a/src/Builder/Screenshot/UrlScreenshotBuilder.php b/src/Builder/Screenshot/UrlScreenshotBuilder.php index 32a32956..2917acab 100644 --- a/src/Builder/Screenshot/UrlScreenshotBuilder.php +++ b/src/Builder/Screenshot/UrlScreenshotBuilder.php @@ -5,6 +5,7 @@ use Sensiolabs\GotenbergBundle\Builder\AbstractBuilder; use Sensiolabs\GotenbergBundle\Builder\Attributes\NormalizeGotenbergPayload; use Sensiolabs\GotenbergBundle\Builder\Attributes\WithBuilderConfiguration; +use Sensiolabs\GotenbergBundle\Builder\Behaviors\Chromium\DeprecatedBodyContentTrait; use Sensiolabs\GotenbergBundle\Builder\Behaviors\ChromiumScreenshotTrait; use Sensiolabs\GotenbergBundle\Builder\Behaviors\Dependencies\RequestContextAwareTrait; use Sensiolabs\GotenbergBundle\Builder\BuilderAssetInterface; @@ -19,7 +20,12 @@ #[WithBuilderConfiguration(type: 'screenshot', name: 'url')] final class UrlScreenshotBuilder extends AbstractBuilder implements BuilderAssetInterface { - use ChromiumScreenshotTrait; + use ChromiumScreenshotTrait, DeprecatedBodyContentTrait { + DeprecatedBodyContentTrait::content insteadof ChromiumScreenshotTrait; + DeprecatedBodyContentTrait::contentRaw insteadof ChromiumScreenshotTrait; + DeprecatedBodyContentTrait::contentFile insteadof ChromiumScreenshotTrait; + } + use RequestContextAwareTrait; public const ENDPOINT = '/forms/chromium/screenshot/url'; From b84f329be67262d0620f24ecbd5d67f6637b5a99 Mon Sep 17 00:00:00 2001 From: Marilena Ruffelaere Date: Tue, 19 May 2026 10:03:42 +0200 Subject: [PATCH 3/3] fix: correct doc generator merge logic and filter deprecated methods Three bugs fixed in docs/generate.php: - @example merge: when a method appears in multiple traits (e.g. via insteadof resolution), the @example from the winning trait was silently discarded because the merge loop did not handle the example tag. The last seen @example now wins. - Description merge: a docblock containing only tags (@deprecated, @see, etc.) produces an empty description array [], which is distinct from [''] and incorrectly satisfied the overwrite condition, erasing a previously collected verbose description. The condition now guards against both empty forms. - Deprecated method filtering: public methods whose resolved docblock carries @deprecated are now excluded from the generated output. This prevents no-op stubs from appearing in the documentation without any useful content. --- docs/generate.php | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/generate.php b/docs/generate.php index b5a9a424..cbc1b20c 100755 --- a/docs/generate.php +++ b/docs/generate.php @@ -131,6 +131,7 @@ private function prepareBuilder(ReflectionClass $class): void $this->prepareBuilderFromClass($class); $this->cleanBuilderFromClass($class); + $this->filterDeprecatedMethods($class); foreach ($this->parts['methods']['@'] as $methodName => $parts) { $package = $parts['package'] ?? '@'; @@ -341,7 +342,7 @@ private function prepareBuilderFromClass(ReflectionClass $class): void $this->parts['methods']['@'][$method->getShortName()]['package'] = $newPackage; } - if (isset($parsedDocBlock['description']) && [''] !== $parsedDocBlock['description']) { + if (isset($parsedDocBlock['description']) && [] !== $parsedDocBlock['description'] && [''] !== $parsedDocBlock['description']) { $this->parts['methods']['@'][$method->getShortName()]['description'] = $parsedDocBlock['description']; } @@ -355,6 +356,24 @@ private function prepareBuilderFromClass(ReflectionClass $class): void $parsedDocBlock['tags']['see'], ))); } + + if (isset($parsedDocBlock['tags']['example']) && [] !== $parsedDocBlock['tags']['example']) { + $this->parts['methods']['@'][$method->getShortName()]['tags']['example'] = $parsedDocBlock['tags']['example']; + } + } + } + + /** + * @param ReflectionClass $class + */ + private function filterDeprecatedMethods(ReflectionClass $class): void + { + foreach ($class->getMethods(ReflectionMethod::IS_PUBLIC) as $method) { + if (str_contains($method->getDocComment() ?: '', '@deprecated')) { + unset($this->methodsSignature[$method->getName()]); + unset($this->methodsLink[$method->getName()]); + unset($this->parts['methods']['@'][$method->getShortName()]); + } } }