MetaTag API 

The MetaTag API is available for setting meta tags in a flexible way.

The API uses MetaTagManagers to manage the tags for a "family" of meta tags. The Core e.g. ships an OpenGraph MetaTagManager that is responsible for all OpenGraph tags. In addition to the MetaTagManagers included in the Core, you can also register your own MetaTagManager , see Creating your own MetaTagManager. All registered managers are made available through the \TYPO3\CMS\Core\MetaTag\MetaTagManagerRegistry .

Using the MetaTag API 

To use the API, first get the right MetaTagManager for your tag from the MetaTagManagerRegistry . You can use that manager to add your meta tag; see the example below for the og:title meta tag. Inject the MetaTagManagerRegistry via Dependency Injection.

EXT:my_extension/Classes/Controller/MyController.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use TYPO3\CMS\Core\MetaTag\MetaTagManagerRegistry;

final class MyController
{
  public function __construct(
    private readonly MetaTagManagerRegistry $metaTagManagerRegistry,
  ) {}

  public function addOgTitle(): void
  {
    $metaTagManager = $this->metaTagManagerRegistry->getManagerForProperty('og:title');
    $metaTagManager->addProperty(
      'og:title',
      'This is the OG title from a controller',
    );
  }
}
Copied!

This code will result in a <meta property="og:title" content="This is the OG title from a controller" /> tag in frontend.

If you need to specify sub-properties, e.g. og:image:width , you can use the following code:

EXT:my_extension/Classes/Controller/MyController.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use TYPO3\CMS\Core\MetaTag\MetaTagManagerRegistry;

final class MyController
{
  public function __construct(
    private readonly MetaTagManagerRegistry $metaTagManagerRegistry,
  ) {}

  public function addOgImage(): void
  {
    $metaTagManager = $this->metaTagManagerRegistry->getManagerForProperty('og:image');
    $metaTagManager->addProperty(
      'og:image',
      '/path/to/image.jpg',
      [
        'width' => 400,
        'height' => 400,
      ],
    );
  }
}
Copied!

You can also remove a specific property:

EXT:my_extension/Classes/Controller/MyController.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use TYPO3\CMS\Core\MetaTag\MetaTagManagerRegistry;

final class MyController
{
  public function __construct(
    private readonly MetaTagManagerRegistry $metaTagManagerRegistry,
  ) {}

  public function removeOgTitle(): void
  {
    $metaTagManager = $this->metaTagManagerRegistry->getManagerForProperty('og:title');
    $metaTagManager->removeProperty('og:title');
  }
}
Copied!

Or remove all previously set meta tags of a specific manager:

EXT:my_extension/Classes/Controller/MyController.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Controller;

use TYPO3\CMS\Core\MetaTag\MetaTagManagerRegistry;

final class MyController
{
  public function __construct(
    private readonly MetaTagManagerRegistry $metaTagManagerRegistry,
  ) {}

  public function removeAllOgProperties(): void
  {
    $metaTagManager = $this->metaTagManagerRegistry->getManagerForProperty('og:title');
    $metaTagManager->removeAllProperties();
  }
}
Copied!

Creating your own MetaTagManager 

If you need to specify the settings and rendering of a specific meta tag (for example when you want to make it possible to have multiple occurrences of a specific tag), you can create your own MetaTagManager . This MetaTagManager must implement \TYPO3\CMS\Core\MetaTag\MetaTagManagerInterface (usually by extending AbstractMetaTagManager ).

Changed in version 15.0 Feature: #110287 - Register meta tag managers as tagged services

Meta tag managers are now registered as tagged services via dependency injection instead of calling \TYPO3\CMS\Core\MetaTag\MetaTagManagerRegistry::registerManager() in ext_localconf.php.

To register the manager, add the PHP attribute AsMetaTagManager to the class, and declare the properties it handles via the $handledProperties array:

EXT:my_extension/Classes/MetaTag/CustomMetaTagManager.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\MetaTag;

use TYPO3\CMS\Core\Attribute\AsMetaTagManager;
use TYPO3\CMS\Core\MetaTag\AbstractMetaTagManager;

#[AsMetaTagManager(identifier: 'custom')]
final class CustomMetaTagManager extends AbstractMetaTagManager
{
  protected $handledProperties = [
    'my-custom-tag' => [],
  ];
}
Copied!

The manager order is defined via the optional before and after attribute arguments, referencing the identifiers of other managers. A manager without constraints is ordered before the generic manager shipped with TYPO3 Core, which handles every property and therefore always comes last. If you for example want to implement your own OpenGraphMetaTagManager , you can use the following code:

EXT:my_extension/Classes/MetaTag/MyOpenGraphMetaTagManager.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\MetaTag;

use TYPO3\CMS\Core\Attribute\AsMetaTagManager;
use TYPO3\CMS\Core\MetaTag\AbstractMetaTagManager;

#[AsMetaTagManager(identifier: 'myOwnOpenGraphManager', before: ['opengraph'])]
final class MyOpenGraphMetaTagManager extends AbstractMetaTagManager
{
  protected $handledProperties = [
    'og:title' => [],
  ];
}
Copied!

This will result in MyOpenGraphMetaTagManager having a higher priority and it will first check if your own manager can handle the tag before it checks the default manager provided by the Core.

Alternatively, the service tag metatag.manager can be used directly in Configuration/Services.yaml, with before and after given as comma-separated lists:

EXT:my_extension/Configuration/Services.yaml
services:
  # Place here the default dependency injection configuration

  MyVendor\MyExtension\MetaTag\CustomMetaTagManager:
    tags:
      - name: metatag.manager
        identifier: 'custom'
Copied!

TypoScript and PHP 

You can set your meta tags by TypoScript and PHP (for example from plugins). First the meta tags from content (plugins) will be handled. After that the meta tags defined in TypoScript will be handled.

It is possible to override earlier set meta tags by TypoScript if you explicitly say this should happen. Therefore the meta.*.replace option was introduced. It is a boolean flag with these values:

  • 1: The meta tag set by TypoScript will replace earlier set meta tags
  • 0: (default) If the meta tag is not set before, the meta tag will be created. If it is already set, it will ignore the meta tag set by TypoScript.
EXT:my_extension/Configuration/Sets/Main/setup.typoscript
page.meta {
  og:site_name = TYPO3
  og:site_name.attribute = property
  og:site_name.replace = 1
}
Copied!

When you set the property replace to 1 at the specific tag, the tag will replace tags that are set from plugins.

By using the new API it is not possible to have duplicate metatags, unless this is explicitly allowed. If you use custom meta tags and want to have multiple occurrences of the same meta tag, you have to create your own MetaTagManager .