---
title: "Migration"
manual: "Warming"
version: "5.3"
permalink: "https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:migration@5.3"
source: "Migration/Index.rst"
rendered: "2026-11-05T08:37:00+00:00"
---

# Migration {#migration}

This page lists all notable changes and required migrations when
upgrading to a new major version of this extension.

> [!NOTE]
> **See also**
>
> Make sure to check out the [migration guide](https://cache-warmup.dev/migration.html)
> of the [`eliashaeussler/cache-warmup`](https://packagist.org/packages/eliashaeussler/cache-warmup) library as well.

## Version 5.0.0 {#version-5-0-0}

### Removal of deprecated functionality {#removal-of-deprecated-functionality}

-   Several getter methods in `\EliasHaeussler\Typo3Warming\Configuration\Configuration`
    are now finally removed (see [deprecation notices](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:version-4-2-0@5.3)).

### Use of a different secret for `User-Agent` header value {#use-of-a-different-secret-for-php-user-agent-header-value}

-   The additional secret used to HMAC-hash the generated `User-Agent` header value has
    been changed.
-   Values of the `User-Agent` header are now different compared to their previous
    representation.
-   Make sure to adapt all places that rely on the `User-Agent` header (e.g. exclusions
    in stats software like Matomo).

## Version 4.2.0 {#version-4-2-0}

### Use of properties in [Configuration API](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:configuration-api@5.3) {#use-of-properties-in-ref-configuration-api-configuration-api}

-   Several class methods in `\EliasHaeussler\Typo3Warming\Configuration\Configuration`
    are converted to class properties.
-   Make sure to access the appropriate properties directly instead of calling the
    class methods.
-   Calling the legacy class methods is deprecated and won't be possible anymore with version
    5.0 of the extension.

### Deprecation of `getUserAgent()` method in [Configuration API](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:configuration-api@5.3) {#deprecation-of-php-getuseragent-method-in-ref-configuration-api-configuration-api}

-   Access to the generated `User-Agent` header is moved from the [Configuration API](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:configuration-api@5.3)
    to a dedicated `\EliasHaeussler\Typo3Warming\Http\Message\Request\RequestOptions` class.
-   Migrate calls from `\EliasHaeussler\Typo3Warming\Configuration\Configuration::getUserAgent`
    to `\EliasHaeussler\Typo3Warming\Http\Message\Request\RequestOptions::getUserAgent`.
-   Calling the legacy method is deprecated and won't be possible anymore with version 5.0
    of the extension.

## Version 4.0.0 {#version-4-0-0}

### Upgrade of [`eliashaeussler/cache-warmup`](https://packagist.org/packages/eliashaeussler/cache-warmup) library {#upgrade-of-composer-eliashaeussler-cache-warmup-library}

-   Crawler option `client_config` is removed and must be migrated to
    extension configuration [clientOptions](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:confval-clientoptions@5.3).
-   Extension configuration `parserClientOptions` is renamed to
    [parserOptions](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:confval-parseroptions@5.3). Existing configuration must
    be migrated to extension configuration [clientOptions](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:confval-clientoptions@5.3).
-   Crawling response body is no longer attached to response objects. Enable
    crawler option `write_response_body` to restore previous behavior.
-   Read more in the library's [release notes](https://github.com/eliashaeussler/cache-warmup/releases/tag/4.0.0).

## Version 3.0.0 {#version-3-0-0}

### Upgrade of [`eliashaeussler/cache-warmup`](https://packagist.org/packages/eliashaeussler/cache-warmup) library {#upgrade-of-composer-eliashaeussler-cache-warmup-library-1}

-   Custom crawlers must be rewritten to match the updated codebase.
-   Read more in the library's [release notes](https://github.com/eliashaeussler/cache-warmup/releases/tag/3.0.0).

### `StreamResponseHandler` is now result-aware {#php-streamresponsehandler-is-now-result-aware}

-   `\EliasHaeussler\Typo3Warming\Http\Message\Handler\StreamResponseHandler`
    now depends on a given
    `\EliasHaeussler\CacheWarmup\Result\CacheWarmupResult`.
-   The result object is generated and updated by the
    `\EliasHaeussler\CacheWarmup\Http\Message\Handler\ResultCollectorHandler`.
-   Make sure to use both handlers together when using the stream response handler.
-   Pass the result object from result collection handler when instantiating the
    stream response handler.
-   See `\EliasHaeussler\Typo3Warming\Crawler\ConcurrentUserAgentCrawler`
    for a dedicated example.

## Version 2.0.0 {#version-2-0-0}

### Integration of [EXT:sitemap_locator](https://extensions.typo3.org/extension/sitemap_locator) {#integration-of-t3ext-sitemap-locator}

-   Sitemaps cache was extracted to [EXT:sitemap_locator](https://extensions.typo3.org/extension/sitemap_locator). Use
    `\EliasHaeussler\Typo3SitemapLocator\Cache\SitemapsCache`
    instead of `\EliasHaeussler\Typo3Warming\Cache\SitemapsCache`.
-   Sitemap providers were extracted to [EXT:sitemap_locator](https://extensions.typo3.org/extension/sitemap_locator). Use
    `\EliasHaeussler\Typo3SitemapLocator\Sitemap\Provider\Provider`
    instead of `\EliasHaeussler\Typo3Warming\Sitemap\Provider\Provider`
    for custom provider implementations.
-   Sitemap locator was extracted to [EXT:sitemap_locator](https://extensions.typo3.org/extension/sitemap_locator). Use
    `\EliasHaeussler\Typo3SitemapLocator\Sitemap\SitemapLocator`
    instead of `\EliasHaeussler\Typo3Warming\Sitemap\SitemapLocator`.

### Relocated sitemap model {#relocated-sitemap-model}

-   The default `\EliasHaeussler\Typo3Warming\Sitemap\SiteAwareSitemap`
    model was moved to `\EliasHaeussler\Typo3Warming\Domain\Model\SiteAwareSitemap`.
    Update references to this class in your code.

## Version 1.0.0 {#version-1-0-0}

### Default crawlers {#default-crawlers}

-   Default crawlers are now `final`. Custom crawlers can no
    longer extend default crawlers. Implement the
    [\\EliasHaeussler\\CacheWarmup\\Crawler\\Crawler](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:eliashaeussler-cachewarmup-crawler-crawler@5.3)
    or [\\EliasHaeussler\\CacheWarmup\\Crawler\\VerboseCrawler](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:eliashaeussler-cachewarmup-crawler-verbosecrawler@5.3)
    interface instead.
-   `CrawlerFactory` from [`eliashaeussler/cache-warmup`](https://packagist.org/packages/eliashaeussler/cache-warmup) library
    is now used to instantiate crawlers. Dependency injection is no
    longer possible.
-   `\EliasHaeussler\Typo3Warming\Crawler\ConfigurableClientTrait`
    was removed. Use
    `\EliasHaeussler\Typo3Warming\Http\Client\ClientFactory::get`
    instead.
-   `\EliasHaeussler\Typo3Warming\Crawler\RequestAwareInterface`
    and `\EliasHaeussler\Typo3Warming\Crawler\RequestAwareTrait`
    were removed. Use
    [\\EliasHaeussler\\Typo3Warming\\Crawler\\StreamableCrawler](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:eliashaeussler-typo3warming-crawler-streamablecrawler@5.3)
    in combination with
    `\EliasHaeussler\Typo3Warming\Http\Message\Handler\StreamResponseHandler`
    instead.
-   `\EliasHaeussler\Typo3Warming\Crawler\UserAgentTrait`
    was removed. Provide an own implementation that calls
    [\\EliasHaeussler\\Typo3Warming\\Configuration\\Configuration::getUserAgent](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:eliashaeussler-typo3warming-configuration-configuration-getuseragent@5.3)
    instead.

### Warmup request handling {#warmup-request-handling}

-   `\EliasHaeussler\Typo3Warming\ValueObject\Request\WarmupRequest`
    is now `final`.
-   `\EliasHaeussler\Typo3Warming\ValueObject\Request\WarmupRequest::$updateCallback`
    was removed. Streamed warmup requests must now be handled by using
    `\EliasHaeussler\Typo3Warming\Http\Message\Handler\StreamResponseHandler`
    in a custom crawler instead.
-   Crawling result handling within
    `\EliasHaeussler\Typo3Warming\ValueObject\Request\WarmupRequest`
    was removed. Use the returned
    `\EliasHaeussler\Typo3Warming\Result\CacheWarmupResult`
    from [\\EliasHaeussler\\Typo3Warming\\Service\\CacheWarmupService::warmup](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:eliashaeussler-typo3warming-service-cachewarmupservice-warmup@5.3)
    instead.
-   `\EliasHaeussler\Typo3Warming\Service\CacheWarmupService::warmupPages`
    and `\EliasHaeussler\Typo3Warming\Service\CacheWarmupService::warmupSites`
    were combined to a new method
    [\\EliasHaeussler\\Typo3Warming\\Service\\CacheWarmupService::warmup](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:eliashaeussler-typo3warming-service-cachewarmupservice-warmup@5.3).
    Use this method with dedicated instances of
    `\EliasHaeussler\Typo3Warming\ValueObject\Request\SiteWarmupRequest` and
    `\EliasHaeussler\Typo3Warming\ValueObject\Request\PageWarmupRequest`.

### Sitemap providers {#sitemap-providers}

-   `\EliasHaeussler\Typo3Warming\Sitemap\Provider\ProviderInterface`
    was renamed to
    `\EliasHaeussler\Typo3Warming\Sitemap\Provider\Provider`.
-   `\EliasHaeussler\Typo3Warming\Sitemap\Provider\AbstractProvider`
    was removed. Custom sitemap providers must now implement
    `\EliasHaeussler\Typo3Warming\Sitemap\Provider\Provider`
    directly. The previously available trait method is now available within
    `\EliasHaeussler\Typo3Warming\Utility\HttpUtility::getSiteUrlWithPath`.
-   `\EliasHaeussler\Typo3Warming\Sitemap\Provider\Provider::get`
    now returns an array of `\EliasHaeussler\Typo3Warming\Sitemap\SiteAwareSitemap`
    instances.
-   A new sitemap provider
    `\EliasHaeussler\Typo3Warming\Sitemap\Provider\PageTypeProvider`
    was added. It is configured with highest priority. Read more at
    [Sitemap providers](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:sitemap-providers@5.3).

### Language handling {#language-handling}

-   `\EliasHaeussler\Typo3Warming\Sitemap\SiteAwareSitemap`
    now requires a site language to be set.
-   Page uri generation now respects configured language
    overlays and is moved to
    `\EliasHaeussler\Typo3Warming\Utility\HttpUtility::generateUri`.

### Extension configuration {#extension-configuration}

-   Extension configuration `exclude` was added. Read more at
    [exclude](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:extconf-exclude@5.3).
-   Extension configuration `strategy` was added. Read more at
    [strategy](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:extconf-strategy@5.3).

### Command options {#command-options}

-   New command option `--format` was added. Read more at
    [warming:cachewarmup](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:warming-cachewarmup@5.3).
-   New command option `--strategy` was added. Read more at
    [warming:cachewarmup](https://docs.typo3.org/permalink/eliashaeussler/typo3-warming:warming-cachewarmup@5.3).

### Template paths {#template-paths}

-   Template paths were rewritten:

    -   `CacheWarmupToolbarItem.html` was rewritten
        to `Toolbar/CacheWarmupToolbarItem.html`
    -   `CacheWarmupToolbarItemActions.html` was rewritten
        to `Modal/SitesModal.html`
-   Partial paths were rewritten:

    -   `ToolbarItem.html` was inlined to template
        `Toolbar/CacheWarmupToolbarItem.html`
    -   `ToolbarItemAction.html` was split into
        `Modal/Sites/SiteGroup.html` and `Modal/Sites/SiteGroupItem.html`
    -   `ToolbarItemMissing.html` was rewritten to
        `Modal/Alert/NoSites.html`
    -   `ToolbarItemPlaceholder.html` was removed
    -   `ToolbarItemUserAgent.html` was removed