### Install with Composer

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/installation.md

Install the cache-warmup library as a Composer dependency.

```bash
composer require eliashaeussler/cache-warmup
```

--------------------------------

### Install with PHIVE

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/installation.md

Install the cache-warmup tool using the PHIVE package manager.

```bash
phive install cache-warmup
```

--------------------------------

### Full Configurable Parser Example

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/configurable-parser.md

A complete example of a configurable parser implementing the Xml\ConfigurableParser interface, including the setOptions method and a fetchSitemap implementation.

```php
namespace Vendor\Xml;

use EliasHaeussler\CacheWarmup;
use GuzzleHttp\ClientInterface;
use Psr\Http\Message;

final class MyCustomParser implements CacheWarmup\Xml\ConfigurableParser
{
    private array $options = [
        'request_options' => [],
    ];

    public function __construct(array $options = [])
    {
        $this->setOptions($options);
    }

    public function parse(CacheWarmup\Sitemap\Sitemap $sitemap): CacheWarmup\Result\ParserResult
    {
        $xml = $this->fetchSitemap($sitemap);
        $sitemaps = $this->extractSitemapsFromXml($xml);
        $urls = $this->extractUrlsFromXml($xml);

        return new CacheWarmup\Result\ParserResult($sitemaps, $urls);
    }

    public function setOptions(array $options): void
    {
        $this->options = [...$this->options, ...$options];
    }

    private function fetchSitemap(CacheWarmup\Sitemap\Sitemap $sitemap): string
    {
        $client = $this->createClient();
        $response = $client->request(
            'GET',
            $sitemap->getUri(),
            $this->options['request_options'],
        );

        return (string) $response->getBody();
    }

    private function createClient(): ClientInterface
    {
        // ...
    }

    /**
     * @return list<CacheWarmup\Sitemap\Sitemap>
     */
    private function extractSitemapsFromXml(string $xml): array
    {
        // ...
    }

    /**
     * @return list<CacheWarmup\Sitemap\Url>
     */
    private function extractUrlsFromXml(string $xml): array
    {
        // ...
    }
}
```

--------------------------------

### YAML Configuration Example

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/configuration.md

Provide configuration options in YAML format. Ensure option names are in lowerCamelCase.

```yaml
sitemaps:
  - https://www.example.org/sitemap.xml
exclude:
  - '*foo*'
```

--------------------------------

### Full Logging Crawler Example

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/logging-crawler.md

This example demonstrates a complete `MyCustomCrawler` implementation that includes setting a logger and log level, and uses the logger to record successful and failed cache warmup attempts.

```php
namespace Vendor\Crawler;

use EliasHaeussler\CacheWarmup;
use Psr\Http\Message;
use Psr\Log;

final class MyCustomCrawler implements CacheWarmup\Crawler\LoggingCrawler
{
    private ?Log\LoggerInterface $logger = null;
    private string $logLevel = CacheWarmup\Log\LogLevel::ERROR;

    public function crawl(array $urls): CacheWarmup\Result\CacheWarmupResult
    {
        $result = new CacheWarmup\Result\CacheWarmupResult();

        foreach ($urls as $url) {
            if ($this->warmUp($url)) {
                $crawlingResult = CacheWarmup\Result\CrawlingResult::createSuccessful($url);
            } else {
                $crawlingResult = CacheWarmup\Result\CrawlingResult::createFailed($url);
            }

            $result->addResult($crawlingResult);
        }

        return $result;
    }

    public function setLogger(Log\LoggerInterface $logger): void
    {
        $this->logger = $logger;
    }

    public function setLogLevel(string $logLevel): void
    {
        $this->logLevel = $logLevel;
    }

    private function warmUp(Message\UriInterface $url): bool
    {
        $successful = /* ... */;

        if (null === $this->logger) {
            return $successful;
        }

        if ($successful) {
            $this->logger->info(
                'Successfully warmed up cache of {url}.',
                ['url' => $url]
            );
        } else {
            $this->logger->error(
                'Failed to warm up cache of {url}'.
                ['url' => $url]
            );
        }

        return $successful;
    }
}
```

--------------------------------

### JSON Configuration Example

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/configuration.md

Provide configuration options in JSON format. Ensure option names are in lowerCamelCase.

```json
{
    "sitemaps": [
        "https://www.example.org/sitemap.xml"
    ],
    "exclude": [
        "*foo*"
    ]
}
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/contribution-guide.md

Clone the repository and install project dependencies using Composer.

```bash
git clone https://github.com/eliashaeussler/cache-warmup.git
cd cache-warmup

composer install
```

--------------------------------

### Full Request Factory Example

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/request-factory.md

Demonstrates creating a RequestFactory, configuring headers and User-Agent, and generating both single and multiple requests.

```php

use EliasHaeussler\CacheWarmup;
use GuzzleHttp\Psr7;

$requestFactory = CacheWarmup\Http\Message\RequestFactory::create('GET');
$requestFactory = $requestFactory->withHeaders(['X-Foo' => 'Bar']);
$requestFactoryWithUserAgent = $requestFactory->withUserAgent();

// One GET request with X-Foo header
$request = $requestFactory->createRequest(
    new Psr7\Uri('https://www.example.com/'),
);

// Multiple GET requests with X-Foo headers
$requests = $requestFactory->createRequests([
    new Psr7\Uri('https://www.example.com/'),
    new Psr7\Uri('https://www.example.com/de/'),
    new Psr7\Uri('https://www.example.com/fr/'),
]);

// One GET request with X-Foo and User-Agent headers
$userAgentRequest = $requestFactoryWithUserAgent->createRequest(
    new Psr7\Uri('https://www.example.com/'),
);

// Multiple GET requests with X-Foo and User-Agent headers
$userAgentRequests = $requestFactoryWithUserAgent->createRequests([
    new Psr7\Uri('https://www.example.com/'),
    new Psr7\Uri('https://www.example.com/de/'),
    new Psr7\Uri('https://www.example.com/fr/'),
]);

```

--------------------------------

### PHP CacheWarmer Class API Example

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Programmatically configure and run cache warmup using the CacheWarmer class. This example demonstrates setting up event listeners, constructing the CacheWarmer with various options, adding sitemaps and URLs, and inspecting the results.

```php
use EliasHaeussler\CacheWarmup;
use Symfony\Component\EventDispatcher;

// Build an event dispatcher with listeners
$eventDispatcher = new EventDispatcher\EventDispatcher();
$eventDispatcher->addListener(
    CacheWarmup\Event\Parser\SitemapParsed::class,
    function (CacheWarmup\Event\Parser\SitemapParsed $event): void {
        echo 'Parsed sitemap: ' . $event->getSitemap() . PHP_EOL;
    },
);
$eventDispatcher->addListener(
    CacheWarmup\Event\Crawler\UrlCrawlingSucceeded::class,
    function (CacheWarmup\Event\Crawler\UrlCrawlingSucceeded $event): void {
        echo 'Warmed up: ' . $event->getUrl() . PHP_EOL;
    },
);

// Construct CacheWarmer with all options
$cacheWarmer = new CacheWarmup\CacheWarmer(
    limit: 200,
    crawler: new CacheWarmup\Crawler\ConcurrentCrawler(),
    strategy: new CacheWarmup\Crawler\Strategy\SortByPriorityStrategy(),
    parser: new CacheWarmup\Xml\SitemapXmlParser(),
    strict: false,                          // allow sitemap parse failures
    excludePatterns: [
        CacheWarmup\Config\Option\ExcludePattern::create('*no_cache=1*'),
        CacheWarmup\Config\Option\ExcludePattern::createFromRegularExpression('#/admin/#'),
    ],
    eventDispatcher: $eventDispatcher,
);

// Add sitemaps (string, object, or array)
$cacheWarmer->addSitemaps('https://www.example.org/sitemap.xml');
$cacheWarmer->addSitemaps([
    CacheWarmup\Sitemap\Sitemap::createFromString('https://www.example.org/de/sitemap.xml'),
    CacheWarmup\Sitemap\Sitemap::createFromString('https://www.example.org/fr/sitemap.xml'),
]);

// Add individual URLs directly
$cacheWarmer->addUrl('https://www.example.org/special-page');
$cacheWarmer->addUrl(new CacheWarmup\Sitemap\Url('https://www.example.org/another-page'));

// Inspect what was collected
echo 'Limit: ' . ($cacheWarmer->getLimit() === 0 ? 'none' : $cacheWarmer->getLimit()) . PHP_EOL;
echo 'URLs queued: ' . count($cacheWarmer->getUrls()) . PHP_EOL;
echo 'Sitemaps parsed: ' . count($cacheWarmer->getSitemaps()) . PHP_EOL;
echo 'Sitemaps failed: ' . count($cacheWarmer->getFailedSitemaps()) . PHP_EOL;
echo 'Sitemaps excluded: ' . count($cacheWarmer->getExcludedSitemaps()) . PHP_EOL;
echo 'URLs excluded: ' . count($cacheWarmer->getExcludedUrls()) . PHP_EOL;

// Execute cache warmup
$result = $cacheWarmer->run();

// Process results
foreach ($result->getSuccessful() as $successfulResult) {
    echo 'OK: ' . $successfulResult . PHP_EOL;
}
foreach ($result->getFailed() as $failedResult) {
    echo 'FAILED: ' . $failedResult . PHP_EOL;
}

```

--------------------------------

### Download PHAR file

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/installation.md

Download the PHAR file and make it executable. This is the recommended installation method.

```bash
curl -O https://cache-warmup.dev/cache-warmup.phar
chmod +x cache-warmup.phar
```

--------------------------------

### Run Cache Warmup with GitHub Actions

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/ci.md

Integrate cache warmup into your GitHub Actions workflow. Ensure the action is configured with the correct sitemap URL. This example uses PHP setup and the cache warmup action.

```yaml
# .github/workflows/cache-warmup.yaml

name: Cache Warmup
on:
  push:
    tags:
      - '*'

jobs:
  cache-warmup:
    runs-on: ubuntu-latest
    steps:
      # Checkout is only required when using a config file
      # - uses: actions/checkout@v4

      - name: Set up environment
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.4
          coverage: none

      - name: Run cache warmup
        uses: eliashaeussler/cache-warmup-action@v1
        with:
          sitemaps: "https://www.example.com/sitemap.xml"
```

--------------------------------

### Full Configurable Crawler Example

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/configurable-crawler.md

A complete example of a custom crawler implementing `ConfigurableCrawler`. It includes the `setOptions` method and a `warmUp` method that uses the configured request method.

```php
namespace Vendor\Crawler;

use EliasHaeussler\CacheWarmup;
use GuzzleHttp\ClientInterface;
use Psr\Http\Message;

final class MyCustomCrawler implements CacheWarmup\Crawler\ConfigurableCrawler
{
    private array $options = [
        'request_method' => 'GET',
    ];

    public function __construct(array $options = [])
    {
        $this->setOptions($options);
    }

    public function crawl(array $urls): CacheWarmup\Result\CacheWarmupResult
    {
        $result = new CacheWarmup\Result\CacheWarmupResult();

        foreach ($urls as $url) {
            if ($this->warmUp($url)) {
                $crawlingResult = CacheWarmup\Result\CrawlingResult::createSuccessful($url);
            } else {
                $crawlingResult = CacheWarmup\Result\CrawlingResult::createFailed($url);
            }

            $result->addResult($crawlingResult);
        }

        return $result;
    }

    public function setOptions(array $options): void
    {
        $this->options = [...$this->options, ...$options];
    }

    private function warmUp(Message\UriInterface $url): bool
    {
        $client = $this->createClient();
        $response = $client->request($this->options['request_method'], $url);

        return $response < 400;
    }

    private function createClient(): ClientInterface
    {
        // ...
    }
}
```

--------------------------------

### PHP Configuration Example

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/configuration.md

Configure cache warmup options using a PHP file that returns a closure. This closure receives and can modify the configuration object.

```php
use EliasHaeussler\CacheWarmup;

return static function (CacheWarmup\Config\CacheWarmupConfig $config) {
    $config->addSitemap(
        CacheWarmup\Sitemap\Sitemap::createFromString('https://www.example.org/sitemap.xml'),
    );
    $config->addExcludePattern(
        CacheWarmup\Config\Option\ExcludePattern::create('*foo*'),
    );

    return $config;
};
```

--------------------------------

### Example Verbose Crawler Implementation

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/verbose-crawler.md

A complete example demonstrating how to use `VerboseCrawler` with a progress bar. It injects output and iterates through URLs, updating the progress bar accordingly.

```php
namespace Vendor\Crawler;

use EliasHaeussler\CacheWarmup;
use Psr\Http\Message;
use Symfony\Component\Console;

final class MyCustomCrawler implements CacheWarmup\Crawler\VerboseCrawler
{
    private ?Console\Output\OutputInterface $output = null;

    public function crawl(array $urls): CacheWarmup\Result\CacheWarmupResult
    {
        $result = new CacheWarmup\Result\CacheWarmupResult();
        $output = $this->output ?? new Console\Output\NullOutput();
        $progressBar = new Console\Helper\ProgressBar($output);

        foreach ($progressBar->iterate($urls) as $url) {
            if ($this->warmUp($url)) {
                $crawlingResult = CacheWarmup\Result\CrawlingResult::createSuccessful($url);
            } else {
                $crawlingResult = CacheWarmup\Result\CrawlingResult::createFailed($url);
            }

            $result->addResult($crawlingResult);
        }

        return $result;
    }

    public function setOutput(Console\Output\OutputInterface $output): void
    {
        $this->output = $output;
    }

    private function warmUp(Message\UriInterface $url): bool
    {
        // ...
    }
}
```

--------------------------------

### Install cache-warmup via Docker

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Pull the official Docker image for cache-warmup to use it in containerized environments.

```bash
docker pull eliashaeussler/cache-warmup
docker pull ghcr.io/eliashaeussler/cache-warmup
```

--------------------------------

### PHP configuration file for cache warmup

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Example of a PHP configuration file for cache-warmup, programmatically setting sitemaps, exclusion patterns, and crawler options.

```php
// cache-warmup.php
use EliasHaeussler\CacheWarmup;

return static function (CacheWarmup\Config\CacheWarmupConfig $config): CacheWarmup\Config\CacheWarmupConfig {
    $config->addSitemap(
        CacheWarmup\Sitemap\Sitemap::createFromString('https://www.example.org/sitemap.xml'),
    );
    $config->addExcludePattern(
        CacheWarmup\Config\Option\ExcludePattern::createFromRegularExpression('#(no_cache|no_warming)=1#'),
    );
    $config->setCrawlerOption('concurrency', 5);
    $config->setStrategy(new CacheWarmup\Crawler\Strategy\SortByPriorityStrategy());

    return $config;
};

```

--------------------------------

### Example JSON Output

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/config-reference/format.md

This is an example of the complete JSON structure produced by the JSON formatter, detailing cache warmup results, parser results, and timing information.

```json
{
    "cacheWarmupResult": {
        "cancelled": [
            "https://www.google.com/intl/de/forms/about/",
            "https://www.google.com/intl/cs/forms/about/",
            "https://www.google.com/intl/et/forms/about/",
            "https://www.google.com/intl/es/forms/about/",
            "https://www.google.com/intl/es-419/forms/about/"
        ],
        "failure": [
            "https://www.google.com/intl/en-gb/forms/about/"
        ],
        "success": [
            "https://www.google.com/forms/about/",
            "https://www.google.com/intl/af/forms/about/",
            "https://www.google.com/intl/ca/forms/about/",
            "https://www.google.com/intl/id/forms/about/",
            "https://www.google.com/intl/ms/forms/about/",
            "https://www.google.com/intl/da/forms/about/"
        ]
    },
    "parserResult": {
        "excluded": {
            "sitemaps": [
                "https://www.google.com/gmail/sitemap.xml"
            ]
        },
        "failure": {
            "urls": [
                "https://www.google.com/intl/zu/forms/about/"
            ]
        },
        "success": {
            "sitemaps": [
                "https://www.google.com/sitemap.xml",
                "https://www.google.com/forms/sitemaps.xml"
            ],
            "urls": [
                "https://www.google.com/forms/about/",
                "https://www.google.com/intl/af/forms/about/",
                "https://www.google.com/intl/id/forms/about/",
                "https://www.google.com/intl/ca/forms/about/",
                "https://www.google.com/intl/da/forms/about/",
                "https://www.google.com/intl/ms/forms/about/",
                "https://www.google.com/intl/en-gb/forms/about/"
            ]
        }
    },
    "time": {
        "parse": "0.18s",
        "crawl": "0.212s"
    }
}

```

--------------------------------

### YAML configuration file for cache warmup

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Example of a YAML configuration file for cache-warmup, specifying sitemaps, exclusion patterns, and crawler options.

```yaml
# cache-warmup.yaml
sitemaps:
  - https://www.example.org/sitemap.xml
exclude:
  - '#(no_cache|no_warming)=1#'
limit: 500
strategy: sort-by-priority
format: json
crawlerOptions:
  concurrency: 5
  request_method: GET
  request_options:
    timeout: 10

```

--------------------------------

### JSON configuration file for cache warmup

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Example of a JSON configuration file for cache-warmup, including sitemaps, exclusion patterns, limits, and crawler options.

```json
{
    "$schema": "https://cache-warmup.dev/config.schema.json",
    "sitemaps": [
        "https://www.example.org/sitemap.xml",
        "https://www.example.org/de/sitemap.xml"
    ],
    "exclude": [
        "#(no_cache|no_warming)=1#",
        "*?debug=*"
    ],
    "limit": 500,
    "strategy": "sort-by-priority",
    "format": "json",
    "crawlerOptions": {
        "concurrency": 5,
        "request_method": "GET",
        "request_options": {
            "timeout": 10,
            "delay": 200
        }
    },
    "clientOptions": {
        "auth": ["username", "password"]
    },
    "logFile": "/var/log/cache-warmup.log",
    "logLevel": "warning"
}
```

--------------------------------

### Example Usage of StoppableCrawler

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/stoppable-crawler.md

This example demonstrates a complete implementation of a StoppableCrawler, including the stopOnFailure logic within the crawl method.

```php
namespace Vendor\Crawler;

use EliasHaeussler\CacheWarmup;
use Psr\Http\Message;

final class MyCustomCrawler implements CacheWarmup\Crawler\StoppableCrawler
{
    private bool $stopOnFailure = false;

    public function crawl(array $urls): CacheWarmup\Result\CacheWarmupResult
    {
        $result = new CacheWarmup\Result\CacheWarmupResult();

        foreach ($urls as $url) {
            $successful = $this->warmUp($url);

            if ($successful) {
                $crawlingResult = CacheWarmup\Result\CrawlingResult::createSuccessful($url);
            } else {
                $crawlingResult = CacheWarmup\Result\CrawlingResult::createFailed($url);
            }

            $result->addResult($crawlingResult);

            if (!$successful && $this->stopOnFailure) {
                break;
            }
        }

        return $result;
    }

    public function stopOnFailure(bool $stopOnFailure = true): void
    {
        $this->stopOnFailure = $stopOnFailure;
    }

    private function warmUp(Message\UriInterface $url): bool
    {
        // ...
    }
}
```

--------------------------------

### get Method

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/client-factory.md

Create a new Guzzle client with a given set of additional client configuration. Additional configuration will be merged with default configuration from the constructor.

```APIDOC
## get

### Description
Create a new Guzzle client with a given set of additional [client configuration](https://docs.guzzlephp.org/en/stable/quickstart.html#creating-a-client). Additional configuration will be merged with default configuration from the constructor.

### Method
get

### Parameters
#### Request Body
- **config** (array) - Optional - An array of additional Guzzle client configurations to merge with defaults.
```

--------------------------------

### GitHub Actions CI/CD Integration

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Integrate cache warmup into GitHub Actions using the official `cache-warmup-action`. This example demonstrates setting up PHP and running the action with a sitemap URL.

```yaml
# GitHub Actions — using the official cache-warmup-action
# .github/workflows/cache-warmup.yaml
name: Cache Warmup
on:
  push:
    tags:
      - '*'

jobs:
  cache-warmup:
    runs-on: ubuntu-latest
    steps:
      - name: Set up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.4
          coverage: none

      - name: Run cache warmup
        uses: eliashaeussler/cache-warmup-action@v1
        with:
          sitemaps: "https://www.example.com/sitemap.xml"

```

--------------------------------

### CrawlingStarted

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/events.md

Dispatched right before crawling is started. Available via Console command and PHP API.

```APIDOC
## CrawlingStarted

### Description
Dispatched right before crawling is started.

### Method
N/A (Event)

### Endpoint
N/A (Event)

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Enable Progress Bar in Configuration (PHP)

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/config-reference/progress.md

Call the `enableProgressBar()` method on the configuration object in your PHP setup to show the progress bar.

```php
use EliasHaeussler\CacheWarmup;

return static function (CacheWarmup\Config\CacheWarmupConfig $config) {
    $config->enableProgressBar();

    return $config;
};
```

--------------------------------

### GitLab CI/CD Integration

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Integrate cache warmup into GitLab CI by using the official Docker image. This example shows how to configure the image, run the cache warmup command, and specify artifacts.

```yaml
# GitLab CI — using the Docker image directly
# .gitlab-ci.yml
cache-warmup:
  image:
    name: eliashaeussler/cache-warmup
    entrypoint: [""]
  script:
    - /cache-warmup.phar "https://www.example.com/sitemap.xml" --format json
  artifacts:
    reports:
      dotenv: cache-warmup-result.env

```

--------------------------------

### Example JSON Output Structure

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Illustrates the structure of the JSON output, including results for cache warmup, parser operations, messages, and timing. Useful for understanding the data returned in JSON format.

```json
{
    "cacheWarmupResult": {
        "success": [
            "https://www.example.org/",
            "https://www.example.org/about"
        ],
        "failure": [
            "https://www.example.org/broken-page"
        ]
    },
    "parserResult": {
        "success": {
            "sitemaps": ["https://www.example.org/sitemap.xml"],
            "urls": ["https://www.example.org/", "https://www.example.org/about", "https://www.example.org/broken-page"]
        },
        "excluded": { "sitemaps": [], "urls": [] },
        "failure": { "sitemaps": [], "urls": [] }
    },
    "messages": { "error": [], "warning": [], "info": [], "success": [] },
    "time": { "parse": "0.12s", "crawl": "0.45s" }
}
```

--------------------------------

### Implement setOptions Method

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/configurable-crawler.md

The `setOptions` method is called with custom crawler options. Persist these options within the crawler to modify its behavior. This example shows initializing options and merging new ones.

```php
namespace Vendor\Crawler;

use EliasHaeussler\CacheWarmup;
use Psr\Http\Message;

final class MyCustomCrawler implements CacheWarmup\Crawler\ConfigurableCrawler
{
    private array $options = [
        'request_method' => 'GET',
    ];

    public function __construct(array $options = [])
    {
        $this->setOptions($options);
    }

    public function crawl(array $urls): CacheWarmup\Result\CacheWarmupResult
    {
        // ...
    }

    public function setOptions(array $options): void
    {
        $this->options = [...$this->options, ...$options];
    }

    private function warmUp(Message\UriInterface $url): bool
    {
        // ...
    }
}
```

--------------------------------

### Configure Custom Crawler via CLI

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Activate a custom crawler by specifying its class name using the `--crawler` option in the CLI command. This example also shows how to configure logging.

```bash
./cache-warmup.phar "https://www.example.org/sitemap.xml" \
  --crawler "Vendor\Crawler\InjectedServicesCrawler" \
  --log-file /var/log/cache-warmup.log

```

--------------------------------

### Run cache warmup with Composer

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/installation.md

Execute the cache warmup process using the Composer-installed binary.

```bash
./vendor/bin/cache-warmup "https://www.example.com/sitemap.xml"
```

--------------------------------

### Instantiate Client Factory with Defaults

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/client-factory.md

Use the constructor to pass default client configurations. This configuration will be applied to all generated clients.

```php
use EliasHaeussler\CacheWarmup;
use GuzzleHttp\HandlerStack;

$defaults = [
    'handler' => HandlerStack::create(/* ... */),
];

$clientFactory = new CacheWarmup\Http\Client\ClientFactory($defaults);
```

--------------------------------

### Get Parsed Sitemaps

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/methods.md

Retrieves a list of all XML sitemaps that have been successfully parsed.

```php
use EliasHaeussler\CacheWarmup;

$cacheWarmer = new CacheWarmup\CacheWarmer();
$sitemaps = $cacheWarmer->getSitemaps();

echo 'The following XML sitemaps were parsed:'.PHP_EOL;

foreach ($sitemaps as $sitemap) {
    echo ' * '.$sitemap.PHP_EOL;
}
```

--------------------------------

### Get Excluded URLs

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/methods.md

Retrieves a list of URLs that were skipped because they matched a configured exclude pattern.

```php
use EliasHaeussler\CacheWarmup;

$cacheWarmer = new CacheWarmup\CacheWarmer();
$urls = $cacheWarmer->getExcludedUrls();

echo 'The following URLs were skipped:'.PHP_EOL;

foreach ($urls as $url) {
    echo ' * '.$url.PHP_EOL;
}
```

--------------------------------

### Instantiate and Run Cache Warmer (PHP)

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/index.md

Instantiate the CacheWarmer class, add sitemaps, run the warmup process, and retrieve successful and failed URLs. This is the main entry point for the PHP API.

```php
use EliasHaeussler\CacheWarmup;

// Instantiate and run cache warmer
$cacheWarmer = new CacheWarmup\CacheWarmer();
$cacheWarmer->addSitemaps('https://www.example.org/sitemap.xml');
$result = $cacheWarmer->run();

// Get successful and failed URLs
$successfulUrls = $result->getSuccessful();
$failedUrls = $result->getFailed();
```

--------------------------------

### CLI cache warmup with JSON output and priority strategy

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Run cache warmup with JSON output format and use a strategy that sorts URLs by priority.

```bash
./cache-warmup.phar "https://www.example.com/sitemap.xml" \
  --format json \
  --strategy sort-by-priority
```

--------------------------------

### Get Excluded Sitemaps

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/methods.md

Retrieves a list of XML sitemaps that were skipped because they matched a configured exclude pattern.

```php
use EliasHaeussler\CacheWarmup;

$cacheWarmer = new CacheWarmup\CacheWarmer();
$sitemaps = $cacheWarmer->getExcludedSitemaps();

echo 'The following XML sitemaps were skipped:'.PHP_EOL;

foreach ($sitemaps as $sitemap) {
    echo ' * '.$sitemap.PHP_EOL;
}
```

--------------------------------

### CLI cache warmup with multiple sitemaps, exclude, and limit

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Execute cache warmup with multiple sitemap URLs, an exclusion pattern, and a limit on the number of URLs to process.

```bash
./cache-warmup.phar \
  "https://www.example.com/sitemap.xml" \
  "https://www.example.com/de/sitemap.xml" \
  --exclude "*no_cache=1*" \
  --limit 100
```

--------------------------------

### Get URLs to be Warmed Up

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/methods.md

Retrieves the list of all URLs that are configured to be crawled in the next cache warmup run.

```php
use EliasHaeussler\CacheWarmup;

$cacheWarmer = new CacheWarmup\CacheWarmer();
$urls = $cacheWarmer->getUrls();

echo 'The following URLs will be crawled:'.PHP_EOL;

foreach ($urls as $url) {
    echo ' * '.$url.PHP_EOL;
}
```

--------------------------------

### Configure Basic Auth Credentials

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/faq.md

Configure basic authentication credentials for cache warmup using various methods like CLI, JSON, PHP, YAML, or .env files. This is achieved via the `clientOptions` configuration.

```bash
./cache-warmup.phar --client-options '{"auth": ["username", "password"]}'
```

```json
{
    "clientOptions": {
        "auth": ["username", "password"]
    }
}
```

```php
use EliasHaeussler\CacheWarmup;
use GuzzleHttp\RequestOptions;

return static function (CacheWarmup\Config\CacheWarmupConfig $config) {
    $config->setClientOption(RequestOptions::AUTH, ['username', 'password']);

    return $config;
};
```

```yaml
clientOptions:
  auth: ['username', 'password']
```

```.env
CACHE_WARMUP_CLIENT_OPTIONS='{"auth": ["username", "password"]}'
```

--------------------------------

### Constructor

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/client-factory.md

Use the constructor to pass a set of default client configuration. It will be used for each generated client.

```APIDOC
## __construct

### Description
Use the constructor to pass a set of default [client configuration](https://docs.guzzlephp.org/en/stable/quickstart.html#creating-a-client). It will be used for each generated client.

### Method
__construct

### Parameters
#### Request Body
- **defaults** (array) - Required - An array of default Guzzle client configurations.
```

--------------------------------

### Get Failed Sitemaps

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/methods.md

Retrieves a list of XML sitemaps that could not be parsed due to errors. This list will be empty if strict mode is enabled.

```php
use EliasHaeussler\CacheWarmup;

$cacheWarmer = new CacheWarmup\CacheWarmer();
$sitemaps = $cacheWarmer->getFailedSitemaps();

echo 'The following XML sitemaps could not be parsed:'.PHP_EOL;

foreach ($sitemaps as $sitemap) {
    echo ' * '.$sitemap.PHP_EOL;
}
```

--------------------------------

### Run cache warmup with PHIVE

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/installation.md

Execute the cache warmup process using the PHIVE-installed tool.

```bash
./tools/cache-warmup "https://www.example.com/sitemap.xml"
```

--------------------------------

### CLI cache warmup using a config file

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Specify a configuration file to manage all cache warmup options.

```bash
./cache-warmup.phar --config cache-warmup.json
```

--------------------------------

### Add URLs via CLI

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/config-reference/urls.md

Use the `-u` or `--urls` flags to provide additional URLs for cache warmup. Multiple URLs can be specified.

```bash
./cache-warmup.phar -u "https://www.example.org/" -u "https://www.example.org/de/"
./cache-warmup.phar --urls "https://www.example.org/" --urls "https://www.example.org/de/"
```

--------------------------------

### Run cache warmup with PHAR

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/installation.md

Execute the cache warmup process by passing an XML sitemap URL to the downloaded PHAR file.

```bash
./cache-warmup.phar "https://www.example.com/sitemap.xml"
```

--------------------------------

### Run cache warmup with Docker

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/installation.md

Execute the cache warmup process using a Docker container, specifying the sitemap URL.

```bash
# Docker Hub
docker run --rm -it eliashaeussler/cache-warmup \
    "https://www.example.com/sitemap.xml"

# GitHub Container Registry
docker run --rm -it ghcr.io/eliashaeussler/cache-warmup \
    "https://www.example.com/sitemap.xml"
```

--------------------------------

### Get Cache Warmup URL Limit

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/methods.md

Retrieves the configured limit for the number of URLs to be processed during cache warmup. A limit of 0 indicates no limit is set.

```php
use EliasHaeussler\CacheWarmup;

$cacheWarmer = new CacheWarmup\CacheWarmer();
$limit = $cacheWarmer->getLimit();

if ($limit === 0) {
    echo 'No limit configured.'.PHP_EOL;
} else {
    echo 'Cache warmup limited to '.$limit.' URLs.'.PHP_EOL;
}
```

--------------------------------

### Configure Client Options in YAML

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/config-reference/client-options.md

Specify client options using YAML syntax in your configuration files.

```yaml
clientOptions:
  auth: ['username', 'password']
```

--------------------------------

### Add URL Sitemap via CLI

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/config-reference/sitemaps.md

Use the CLI to specify a URL for an XML sitemap to be warmed up. Ensure the URL includes the protocol.

```bash
./cache-warmup.phar "https://www.example.org/sitemap.xml"
```

--------------------------------

### Add Multiple Sitemaps via CLI

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/config-reference/sitemaps.md

Use the CLI to specify multiple XML sitemaps, including both URLs and local file paths.

```bash
./cache-warmup.phar "https://www.example.org/sitemap.xml" "/var/www/html/sitemap.xml"
```

--------------------------------

### Command Line Configuration

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/configuration.md

Set configuration options directly via command-line parameters. Use `--config` to specify a configuration file.

```bash
./cache-warmup.phar "https://www.example.org/sitemap.xml" --exclude "*foo*"
```

```bash
./cache-warmup.phar --config cache-warmup.json
```

--------------------------------

### Implement Custom Crawler for Cache Warmer

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Implement the `Crawler\Crawler` interface to create a custom crawler. For advanced features like options, logging, and stop-on-failure, implement `ConfigurableCrawler`, `LoggingCrawler`, and `StoppableCrawler` respectively. The example demonstrates a crawler that uses Guzzle for HTTP requests and supports custom options, logging, and failure handling.

```php
namespace Vendor\Crawler;

use EliasHaeussler\CacheWarmup;
use GuzzleHttp\Client;
use Psr\Http\Message;
use Psr\Log;

final class MyCustomCrawler implements
    CacheWarmup\Crawler\ConfigurableCrawler,
    CacheWarmup\Crawler\LoggingCrawler,
    CacheWarmup\Crawler\StoppableCrawler
{
    private array $options = [
        'request_method' => 'GET',
        'timeout'        => 10,
    ];

    private ?Log\LoggerInterface $logger = null;
    private string $logLevel = CacheWarmup\Log\LogLevel::ERROR;
    private bool $stopOnFailure = false;

    public function __construct(array $options = [])
    {
        $this->setOptions($options);
    }

    public function crawl(array $urls): CacheWarmup\Result\CacheWarmupResult
    {
        $result = new CacheWarmup\Result\CacheWarmupResult();
        $client = new Client(['timeout' => $this->options['timeout']]);

        foreach ($urls as $url) {
            try {
                $response = $client->request($this->options['request_method'], (string) $url);
                $successful = $response->getStatusCode() < 400;
            } catch (\Throwable $e) {
                $successful = false;
            }

            if ($successful) {
                $crawlingResult = CacheWarmup\Result\CrawlingResult::createSuccessful($url);
                $this->logger?->info('Warmed up {url}', ['url' => $url]);
            } else {
                $crawlingResult = CacheWarmup\Result\CrawlingResult::createFailed($url);
                $this->logger?->log($this->logLevel, 'Failed to warm up {url}', ['url' => $url]);
            }

            $result->addResult($crawlingResult);

            if (!$successful && $this->stopOnFailure) {
                break;
            }
        }

        return $result;
    }

    public function setOptions(array $options): void
    {
        $this->options = [...$this->options, ...$options];
    }

    public function setLogger(Log\LoggerInterface $logger): void
    {
        $this->logger = $logger;
    }

    public function setLogLevel(string $logLevel): void
    {
        $this->logLevel = $logLevel;
    }

    public function stopOnFailure(bool $stopOnFailure = true): void
    {
        $this->stopOnFailure = $stopOnFailure;
    }
}

// Usage
$cacheWarmer = new CacheWarmup\CacheWarmer(
    crawler: new MyCustomCrawler(['request_method' => 'HEAD', 'timeout' => 5]),
);
$cacheWarmer->addSitemaps('https://www.example.org/sitemap.xml');
$result = $cacheWarmer->run();

```

--------------------------------

### run

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/methods.md

Executes the cache warmup process using the configured crawler and strategy. Returns a Result object containing successful and failed crawling results.

```APIDOC
## run

### Description
Uses the configured [crawler](options.md#crawler) to crawl all configured and collected URLs. In case a [strategy](options.md#strategy) is configured, the URLs are prepared first.

Once cache warmup is finished, this method returns an instance of
[`Result\CacheWarmupResult`](../../src/Result/CacheWarmupResult.php)
with all successful and failed crawling results.

### Method
`run()`

### Returns
[`Result\CacheWarmupResult`](../../src/Result/CacheWarmupResult.php)

### Example
```php
use EliasHaeussler\CacheWarmup;

$cacheWarmer = new CacheWarmup\CacheWarmer();
$result = $cacheWarmer->run();

foreach ($result->getSuccessful() as $successfulResult) {
    echo 'Success: '.$successfulResult.PHP_EOL;
}
foreach ($result->getFailed() as $failedResult) {
    echo 'Failed: '.$failedResult.PHP_EOL;
}
```
```

--------------------------------

### Listen to Cache Warmup Lifecycle Events in PHP

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

This snippet demonstrates how to use a custom EventDispatcher to listen to various lifecycle events during cache warmup. It includes listeners for parser events (sitemap added, parsed, failed, excluded; URL added, excluded) and crawler events (started, succeeded, failed, finished).

```php
use EliasHaeussler\CacheWarmup;
use Symfony\Component\EventDispatcher;

$dispatcher = new EventDispatcher\EventDispatcher();

// Parser events
$dispatcher->addListener(
    CacheWarmup\Event\Parser\SitemapAdded::class,
    fn ($e) => printf("Sitemap added: %s\n", $e->getSitemap()),
);
$dispatcher->addListener(
    CacheWarmup\Event\Parser\SitemapParsed::class,
    fn ($e) => printf("Sitemap parsed: %s (%d URLs)\n", $e->getSitemap(), count($e->getResult()->getUrls())),
);
$dispatcher->addListener(
    CacheWarmup\Event\Parser\SitemapParsingFailed::class,
    fn ($e) => printf("Parse error for %s: %s\n", $e->getSitemap(), $e->getException()->getMessage()),
);
$dispatcher->addListener(
    CacheWarmup\Event\Parser\SitemapExcluded::class,
    fn ($e) => printf("Excluded sitemap: %s\n", $e->getSitemap()),
);
$dispatcher->addListener(
    CacheWarmup\Event\Parser\UrlAdded::class,
    fn ($e) => printf("URL added: %s\n", $e->getUrl()),
);
$dispatcher->addListener(
    CacheWarmup\Event\Parser\UrlExcluded::class,
    fn ($e) => printf("URL excluded: %s\n", $e->getUrl()),
);

// Crawler events
$dispatcher->addListener(
    CacheWarmup\Event\Crawler\CrawlingStarted::class,
    fn ($e) => printf("Starting crawl of %d URLs\n", count($e->getUrls())),
);
$dispatcher->addListener(
    CacheWarmup\Event\Crawler\UrlCrawlingSucceeded::class,
    fn ($e) => printf("OK: %s\n", $e->getUrl()),
);
$dispatcher->addListener(
    CacheWarmup\Event\Crawler\UrlCrawlingFailed::class,
    fn ($e) => printf("FAIL: %s\n", $e->getUrl()),
);
$dispatcher->addListener(
    CacheWarmup\Event\Crawler\CrawlingFinished::class,
    fn ($e) => printf("Crawl finished. Successful: %d, Failed: %d\n",
        count($e->getResult()->getSuccessful()),
        count($e->getResult()->getFailed()),
    ),
);

$cacheWarmer = new CacheWarmup\CacheWarmer(eventDispatcher: $dispatcher);
$cacheWarmer->addSitemaps('https://www.example.org/sitemap.xml');
$cacheWarmer->run();

```

--------------------------------

### Download and verify cache-warmup PHAR

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Download the standalone PHAR archive for the cache-warmup CLI tool and verify its integrity using GPG.

```bash
curl -O https://cache-warmup.dev/cache-warmup.phar
chmod +x cache-warmup.phar

curl -O https://cache-warmup.dev/cache-warmup.phar.asc
gpg --keyserver keys.openpgp.org --recv-keys E73F20790A629A2CEF2E9AE57C1C5363490E851E
gpg --verify cache-warmup.phar.asc cache-warmup.phar
```

--------------------------------

### Implement Custom XML Sitemap Parser

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Replace the default `SitemapXmlParser` by implementing the `Xml\Parser` interface. The `parse()` method should accept a `Sitemap\Sitemap` object and return a `Result\ParserResult` containing discovered sub-sitemaps and URLs. This example shows a custom parser using Guzzle to fetch sitemap content and includes placeholder methods for extracting sitemaps and URLs from XML.

```php
namespace Vendor\Xml;

use EliasHaeussler\CacheWarmup;
use GuzzleHttp\Client;

final class MyCustomParser implements CacheWarmup\Xml\Parser
{
    public function __construct(private readonly Client $client = new Client()) {}

    public function parse(CacheWarmup\Sitemap\Sitemap $sitemap): CacheWarmup\Result\ParserResult
    {
        $xml      = $this->fetchSitemap($sitemap);
        $sitemaps = $this->extractSitemapsFromXml($xml);
        $urls     = $this->extractUrlsFromXml($xml);

        return new CacheWarmup\Result\ParserResult($sitemaps, $urls);
    }

    private function fetchSitemap(CacheWarmup\Sitemap\Sitemap $sitemap): string
    {
        return (string) $this->client->get((string) $sitemap->getUri())->getBody();
    }

    /** @return list<CacheWarmup\Sitemap\Sitemap> */
    private function extractSitemapsFromXml(string $xml): array
    {
        // custom extraction logic …
        return [];
    }

    /** @return list<CacheWarmup\Sitemap\Url> */
    private function extractUrlsFromXml(string $xml): array
    {
        // custom extraction logic …
        return [];
    }
}

// Usage
$parser = new MyCustomParser(new \GuzzleHttp\Client(['auth' => ['user', 'pass']]));
$cacheWarmer = new CacheWarmup\CacheWarmer(parser: $parser);
$cacheWarmer->addSitemaps('https://www.example.org/sitemap.xml');
$cacheWarmer->run();

```

--------------------------------

### Pass Client Options via CLI

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/config-reference/client-options.md

Use the `--client-options` parameter to pass JSON-encoded client configurations directly on the command line.

```bash
./cache-warmup.phar --client-options '{"auth": ["username", "password"]}'
```

--------------------------------

### Configure Client Options in JSON

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/config-reference/client-options.md

Define client options within a JSON configuration file for the cache warmup process.

```json
{
    "clientOptions": {
        "auth": ["username", "password"]
    }
}
```

--------------------------------

### Configure Parser via PHP Callback

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/config-reference/parser.md

Use a PHP callback function to configure the cache warmup settings, specifically setting the parser using its FQCN.

```php
use EliasHaeussler\CacheWarmup;

return static function (CacheWarmup\Config\CacheWarmupConfig $config) {
    $config->setParser(\Vendor\Xml\MyCustomParser::class);

    return $config;
};
```

--------------------------------

### Docker equivalent for CLI cache warmup

Source: https://context7.com/eliashaeussler/cache-warmup/llms.txt

Run the cache warmup process using the Docker image, mirroring the CLI command.

```bash
docker run --rm -it eliashaeussler/cache-warmup \
  "https://www.example.com/sitemap.xml" --format json
```

--------------------------------

### Run Cache Warmup

Source: https://github.com/eliashaeussler/cache-warmup/blob/main/docs/api/methods.md

Initiates the cache warmup process using the configured crawler. Returns a result object containing successful and failed crawls.

```php
use EliasHaeussler\CacheWarmup;

$cacheWarmer = new CacheWarmup\CacheWarmer();
$result = $cacheWarmer->run();
```

```php
foreach ($result->getSuccessful() as $successfulResult) {
    echo 'Success: '.$successfulResult.PHP_EOL;
}
foreach ($result->getFailed() as $failedResult) {
    echo 'Failed: '.$failedResult.PHP_EOL;
}
```