fix: remove content* methods from UrlPdfBuilder and UrlScreenshotBuilder

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.

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<object> $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()]);
+            }
         }
     }
 

docs/pdf/HtmlPdfBuilder.md

@@ -304,6 +304,15 @@ Adds a file, like an image, font, stylesheet, and so on.<br /><br />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).<br /><br />By default, the assets files are fetch in the assets folder of your application.<br />If your assets are in another folder, you can override the default value of assets_directory in your<br />configuration file config/sensiolabs_gotenberg.yml.<br />
 
@@ -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.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
+The raw html string to use as the page footer.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
 
 > [!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.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
+The raw html string to use as the page header.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
 
 > [!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)

docs/pdf/MarkdownPdfBuilder.md

@@ -377,6 +377,15 @@ Adds a file, like an image, font, stylesheet, and so on.<br /><br />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).<br /><br />By default, the assets files are fetch in the assets folder of your application.<br />If your assets are in another folder, you can override the default value of assets_directory in your<br />configuration file config/sensiolabs_gotenberg.yml.<br />
 
@@ -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.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
+The raw html string to use as the page footer.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
 
 > [!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.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
+The raw html string to use as the page header.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
 
 > [!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)

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.<br /><br />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).<br /><br />By default, the assets files are fetch in the assets folder of your application.<br />If your assets are in another folder, you can override the default value of assets_directory in your<br />configuration file config/sensiolabs_gotenberg.yml.<br />
 
@@ -739,48 +745,14 @@ 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.<br /><br />As assets files, by default the HTML files are fetch in the assets folder of your application.<br />If your HTML files are in another folder, you can override the default value of assets_directory in your<br />configuration file config/sensiolabs_gotenberg.yml.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
-
-```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.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
-
-```php
-return $gotenberg
-    // Your builder call as ->html() and the rest of your configuration code
-    ->contentRaw('<html><body><h2>The content</h2></body></html>')
-    ->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'])
+    ->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.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
+The raw html string to use as the page footer.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
 
 > [!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.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
+The raw html string to use as the page header.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
 
 > [!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)

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.<br /><br />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).<br /><br />By default, the assets files are fetch in the assets folder of your application.<br />If your assets are in another folder, you can override the default value of assets_directory in your<br />configuration file config/sensiolabs_gotenberg.yml.<br />
 
@@ -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.<br /><br />As assets files, by default the HTML files are fetch in the assets folder of your application.<br />If your HTML files are in another folder, you can override the default value of assets_directory in your<br />configuration file config/sensiolabs_gotenberg.yml.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
-
-> [!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.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
-
-> [!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('<html><body><h6>The footer</h6></body></html>')
-    ->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.<br /><br />As assets files, by default the HTML files are fetch in the assets folder of your application.<br />If your HTML files are in another folder, you can override the default value of assets_directory in your<br />configuration file config/sensiolabs_gotenberg.yml.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
-
-> [!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.<br /><br />Warning: Assets (css, images, etc...) cannot be parsed and loaded dynamically.<br />Assets can still be loaded using https://gotenberg.dev/docs/convert-with-chromium/convert-html-to-pdf#assets.<br />
-
-> [!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('<html><body><h1>The header</h1></body></html>')
-    ->generate()
-    ->stream()
-;
-```
-
 
 ### emulatedMediaFeatures(array \$emulatedMediaFeatures)
 You can simulate specific browser conditions by overriding CSS media features.<br />This is particularly useful for forcing "Dark Mode" or testing layouts with reduced motion.<br />