[!!!][FEATURE] Introduce ClientFactory and clientOptions config

Author: eliashaeussler

.gitattributes

@@ -10,6 +10,7 @@
 /CODEOWNERS               export-ignore
 /composer.lock            export-ignore
 /CONTRIBUTING.md          export-ignore
+/dependency-checker.json  export-ignore
 /package.json             export-ignore
 /package-lock.json        export-ignore
 /phpstan.php              export-ignore

.github/workflows/cgl.yaml

@@ -48,7 +48,7 @@ jobs:
 
       # Check dependencies
       - name: Check Composer dependencies
-        run: composer-require-checker check
+        run: composer-require-checker check --config-file dependency-checker.json
       - name: Check for unused Composer dependencies
         run: composer-unused --excludePackage=ext-zlib
       - name: Check for unused Frontend dependencies

composer.json

@@ -46,8 +46,9 @@
 		"phpstan/phpstan-phpunit": "^2.0",
 		"phpstan/phpstan-symfony": "^2.0",
 		"phpunit/phpunit": "^11.5.1",
+		"symfony/config": "^5.4.35 || ^6.4.3 || ^7.0.3",
 		"symfony/event-dispatcher-contracts": "^2.5.3 || ^3.4.2",
-		"symfony/string": "^6.4.3 || ^7.0.3"
+		"symfony/string": "^5.4.35 || ^6.4.3 || ^7.0.3"
 	},
 	"conflict": {
 		"cuyz/valinor": "1.14.0"
@@ -97,7 +98,10 @@
 		"sca": [
 			"@sca:php"
 		],
-		"sca:php": "phpstan analyse -c phpstan.php",
+		"sca:php": [
+			"@php tests/build/service-container.php",
+			"phpstan analyse -c phpstan.php"
+		],
 		"test": [
 			"@test:e2e",
 			"@test:unit"

composer.lock

@@ -0,0 +1,5 @@
+{
+	"symbol-whitelist": [
+		"Symfony\\Component\\Config\\ConfigCache"
+	]
+}

dependency-checker.json

@@ -103,6 +103,13 @@ export default defineConfig({
                             {text: 'Endless mode', link: '/config-reference/repeat-after'},
                         ],
                     },
+                    {
+                        text: 'Client',
+                        collapsed: true,
+                        items: [
+                            {text: 'Client options', link: '/config-reference/client-options'},
+                        ],
+                    },
                     {
                         text: 'Crawling',
                         collapsed: true,
@@ -163,6 +170,10 @@ export default defineConfig({
                             {text: 'Configurable Parser', link: '/api/configurable-parser'},
                         ],
                     },
+                    {
+                        text: 'Dependency injection',
+                        link: '/api/dependency-injection',
+                    },
                     {
                         text: 'Events',
                         link: '/api/events',

docs/.vitepress/config.mts

@@ -20,20 +20,6 @@ final class MyCustomCrawler implements CacheWarmup\Crawler\Crawler
 }
 ```
 
-## Dependency Injection <Badge type="tip" text="3.2+" />
-
-When a crawler is created using
-[`EliasHaeussler\CacheWarmup\Crawler\CrawlerFactory`](../../src/Crawler/CrawlerFactory.php),
-a limited service container is built to instantiate the crawler.
-This allows custom crawlers to define dependencies to a limited
-set of services, including:
-
-* Current output (implementation of `OutputInterface`)
-* Current logger (implementation of `LoggerInterface`), only
-  available if the [`--log-file`](../config-reference/log-file.md)
-  command option is passed
-* Current event dispatcher (implementation of `EventDispatcherInterface`)
-
 ## Method Reference
 
 The default crawler describes the following method:

docs/api/crawler.md

@@ -0,0 +1,25 @@
+# Dependency injection <Badge type="tip" text="3.2+" />
+
+A limited service container is built to instantiate crawlers and
+parsers. This allows custom crawlers to define dependencies to a
+limited set of services.
+
+## Included services
+
+The container includes the following runtime services:
+
+| Service                                                                                                               | Description                                                                                                                      | Added&nbsp;in                     |
+|-----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|
+| [`OutputInterface`](https://github.com/symfony/console/blob/v5.4.35/Output/OutputInterface.php)                       | Current output, either extracted from console application or constructed as `ConsoleOutput`                                      | <Badge type="tip" text="3.2.0" /> |
+| [`LoggerInterface`](https://github.com/php-fig/log/blob/2.0.0/src/LoggerInterface.php)                                | Current logger, only available if the [`logFile`](../config-reference/log-file.md) configuration option is passed                | <Badge type="tip" text="3.2.0" /> |
+| [`EventDispatcherInterface`](https://github.com/php-fig/event-dispatcher/blob/1.0.0/src/EventDispatcherInterface.php) | Current event dispatcher instance, either extracted from console application or constructed as new instance                      | <Badge type="tip" text="3.2.0" /> |
+| [`ClientFactory`](../../src/Http/Client/ClientFactory.php)                                                            | Factory to create Guzzle client with defaults from [`clientOptions`](../config-reference/client-options.md) configuration option | <Badge type="tip" text="4.0.0" /> |
+| [`ClientInterface`](https://github.com/guzzle/guzzle/blob/7.8.2/src/ClientInterface.php)                              | Shared Guzzle client, constructed with [`clientOptions`](../config-reference/client-options.md) configuration option             | <Badge type="tip" text="4.0.0" /> |
+
+## Supported factories
+
+The service container is built when creating crawlers and parsers
+through their respective factories, including:
+
+* [`EliasHaeussler\CacheWarmup\Crawler\CrawlerFactory`](../../src/Crawler/CrawlerFactory.php)
+* [`EliasHaeussler\CacheWarmup\Xml\ParserFactory`](../../src/Xml/ParserFactory.php)

docs/api/dependency-injection.md

@@ -0,0 +1,60 @@
+---
+outline: [2,3]
+---
+
+# Client options <Badge type="tip" text="4.0+" />
+
+<small>📝&nbsp;Name: `clientOptions` &middot; 🖥️&nbsp;Option:  `-t`, `--client-options`</small>
+
+> Additional [configuration](https://docs.guzzlephp.org/en/stable/quickstart.html#creating-a-client)
+> for shared Guzzle client.
+
+::: info
+The shared Guzzle client is used in default crawlers and default parser. Custom
+crawlers and parsers may also use it, if properly configured via
+[dependency injection](../api/dependency-injection.md).
+:::
+
+## Example
+
+Pass client options in the expected input format.
+
+::: warning IMPORTANT
+When passing client options as **command parameter** or **environment variable**,
+make sure to pass them as **JSON-encoded string**.
+:::
+
+::: code-group
+
+```bash [CLI]
+./cache-warmup.phar --client-options '{"auth": ["username", "password"]}'
+```
+
+```json [JSON]
+{
+    "clientOptions": {
+        "auth": ["username", "password"]
+    }
+}
+```
+
+```php [PHP]
+use EliasHaeussler\CacheWarmup;
+
+return static function (CacheWarmup\Config\CacheWarmupConfig $config) {
+    $config->setClientOption('auth', ['username', 'password']);
+
+    return $config;
+};
+```
+
+```yaml [YAML]
+clientOptions:
+  auth: ['username', 'password']
+```
+
+```bash [.env]
+CACHE_WARMUP_CLIENT_OPTIONS='{"auth": ["username", "password"]}'
+```
+
+:::

docs/config-reference/client-options.md

@@ -44,6 +44,12 @@ Defines how to format cache warmup progress and result.
 * [Progress](progress.md)
 * [Endless mode](repeat-after.md)
 
+## Client
+
+Describes options to customize the shared Guzzle client.
+
+* [Client options](client-options.md)
+
 ## Crawling
 
 Describes options to modify and customize the crawling behavior.