MetaTag API
The MetaTag API is available for setting meta tags in a flexible way.
Note
Usually, it is sufficient to set meta tags using the API of the
\TYPO3\ which uses the MetaTag API
internally. For all other cases, use the MetaTag API directly.
The API uses
Meta 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
Meta, see
Creating your own MetaTagManager. All
registered managers are made available through the
\TYPO3\.
Using the MetaTag API
To use the API, first get the right
Meta for your tag from the
Meta.
You can use that manager to add your meta tag; see the example below for the
og: meta tag.
Inject the
Meta via Dependency Injection.
<?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',
);
}
}
This code will result in a
<meta property="og: tag in frontend.
If you need to specify sub-properties, e.g.
og:, you can use the following code:
<?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,
],
);
}
}
You can also remove a specific property:
<?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');
}
}
Or remove all previously set meta tags of a specific manager:
<?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();
}
}
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
Meta.
This
Meta must implement
\TYPO3\ (usually by
extending
Abstract).
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\ in
ext_localconf.php.
To register the manager, add the PHP attribute
As to the class,
and declare the properties it handles via the
$handled array:
<?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' => [],
];
}
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
Open, you can use the following code:
<?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' => [],
];
}
This will result in
My 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. can be used directly in
Configuration/Services.yaml, with
before
and
after
given as comma-separated lists:
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.*. option was introduced. It is a boolean flag with these values:
1: The meta tag set by TypoScript will replace earlier set meta tags0: (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.
page.meta {
og:site_name = TYPO3
og:site_name.attribute = property
og:site_name.replace = 1
}
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
Meta.
See also
config.meta in the TypoScript reference