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

Author: eliashaeussler

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

@@ -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.

docs/config-reference/index.md

@@ -25,6 +25,7 @@
 
 $symfonySet = PHPStanConfig\Set\SymfonySet::create()
     ->withConsoleApplicationLoader('tests/build/console-application.php')
+    ->withContainerXmlPath('.build/container.xml')
 ;
 
 return PHPStanConfig\Config\Config::create(__DIR__)

phpstan.php

@@ -26,10 +26,12 @@
 use EliasHaeussler\CacheWarmup\CacheWarmer;
 use EliasHaeussler\CacheWarmup\Config;
 use EliasHaeussler\CacheWarmup\Crawler;
+use EliasHaeussler\CacheWarmup\DependencyInjection;
 use EliasHaeussler\CacheWarmup\Event;
 use EliasHaeussler\CacheWarmup\Exception;
 use EliasHaeussler\CacheWarmup\Formatter;
 use EliasHaeussler\CacheWarmup\Helper;
+use EliasHaeussler\CacheWarmup\Http;
 use EliasHaeussler\CacheWarmup\Log;
 use EliasHaeussler\CacheWarmup\Result;
 use EliasHaeussler\CacheWarmup\Sitemap;
@@ -66,20 +68,19 @@ final class CacheWarmupCommand extends Console\Command\Command
 
     private readonly Crawler\Strategy\CrawlingStrategyFactory $crawlingStrategyFactory;
     private readonly Config\Component\OptionsParser $optionsParser;
-    private readonly Xml\ParserFactory $parserFactory;
     private readonly Time\TimeTracker $timeTracker;
     private Config\CacheWarmupConfig $config;
     private Console\Style\SymfonyStyle $io;
     private Formatter\Formatter $formatter;
     private Crawler\CrawlerFactory $crawlerFactory;
+    private Xml\ParserFactory $parserFactory;
     private bool $firstRun = true;
 
     public function __construct(
         private readonly EventDispatcherInterface $eventDispatcher = new EventDispatcher\EventDispatcher(),
     ) {
         $this->crawlingStrategyFactory = new Crawler\Strategy\CrawlingStrategyFactory();
         $this->optionsParser = new Config\Component\OptionsParser();
-        $this->parserFactory = new Xml\ParserFactory();
         $this->timeTracker = new Time\TimeTracker();
 
         parent::__construct('cache-warmup');
@@ -171,6 +172,13 @@ protected function configure(): void
 
    <comment>%command.full_name% --limit 50</comment>
 
+<info>Client options</info>
+<info>==============</info>
+Parsing and crawling of XML sitemaps and URLs is done by a shared Guzzle client.
+Use the <comment>--client-options</comment> option to provide additional config for the client:
+
+   <comment>%command.full_name% --client-options '{"auth": ["username", "password"]}'</comment>
+
 <info>Crawler</info>
 <info>=======</info>
 By default, cache warmup will be done using concurrent HEAD requests.
@@ -283,6 +291,12 @@ protected function configure(): void
             Console\Input\InputOption::VALUE_NONE,
             'Show progress bar during cache warmup',
         );
+        $this->addOption(
+            'client-options',
+            't',
+            Console\Input\InputOption::VALUE_REQUIRED,
+            'Additional config for client used for parsing and crawling XML sitemaps',
+        );
         $this->addOption(
             'crawler',
             'c',
@@ -407,13 +421,17 @@ protected function initialize(Console\Input\InputInterface $input, Console\Outpu
             }
         }
 
-        $this->crawlerFactory = new Crawler\CrawlerFactory(
+        // Create container factory for crawler and parser factory
+        $containerFactory = new DependencyInjection\ContainerFactory(
             $output,
             $logger,
-            $logLevel,
-            $stopOnFailure,
             $this->eventDispatcher,
+            new Http\Client\ClientFactory($this->config->getClientOptions()),
         );
+
+        // Create factories
+        $this->crawlerFactory = new Crawler\CrawlerFactory($containerFactory, $logLevel, $stopOnFailure);
+        $this->parserFactory = new Xml\ParserFactory($containerFactory);
     }
 
     protected function interact(Console\Input\InputInterface $input, Console\Output\OutputInterface $output): void
@@ -472,6 +490,13 @@ protected function execute(Console\Input\InputInterface $input, Console\Output\O
             $this->firstRun = false;
         }
 
+        // Print client options
+        if ($this->formatter->isVerbose() && $this->io->isVerbose() && [] !== $this->config->getClientOptions()) {
+            $this->io->section('Using custom client options:');
+            $this->io->writeln((string) json_encode($this->config->getClientOptions(), JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
+            $this->io->newLine();
+        }
+
         // Initialize components
         $crawler = $this->initializeCrawler();
         $cacheWarmer = $this->timeTracker->track(fn () => $this->initializeCacheWarmer($crawler));