Contao Head bundle

Enhance your website's SEO and social media presence with more meta- and structured data.

Features

• Set open graph tags like og:title, og:description, og:url and og:image
• Provide a nice api to set head tags like meta, title, base, link
• Provide additional schema.org json-ld data
• Sets important meta tags like og:title, og:description, og:url and twitter:card out of the box
• Allow setting open graph and twitter fallback image on root page
• Allow setting twitter author per root page

Usage

Setup

1. Install with composer
2. Update your database
3. Optional: Set fallback image and twitter author in root page(s)

Add additional meta tags

In your root page, you can activate to add fallback image (og:image) and X/Twitter username (twitter:site) meta tags to you web page.

Add additional schema.org data

In your root page, you can activate additional structured data for your web page. Following schema.org types are available:

• @Organization
• @WebSite

Add (meta-)tags from template (twig)

The bundle provides Twig functions to add head tags from Twig templates:

{# Set tags #}
{% do add_head_tag('title', 'Hello World') %}
{% do add_head_tag('base', 'https://example.org') %}
{# you can also set meta tags with meta_ prefix, but it is easier with add_head_meta_tag function #}
{% do add_head_tag('meta_description', 'Lorem ipsum!') %}

{# Add meta tags #}
{% do add_head_meta_tag('description', 'Lorem ipsum!') %}
{% do add_head_meta_tag('og:title', 'Hello World') %}
{% do add_head_meta_tag('twitter:image', figure) %}

{# Add multiple tags at once #}
{# Pass as key => value or a AbstractHeadTag object #}
{# Value can be a string, null or a Contao Figure. If a Figure is passed, its image source will be used as the tag content. #}
{% do add_head_tags({
    'title': 'Hello World',
    'base': 'https://example.org',
    'meta_description': 'Lorem ipsum!',
    'meta_og:title': 'Hello World',
    'meta_twitter:image': figure,
}) %}

{# Shorthand for news #}
{%- do add_head_tags(get_head_news_tags(model, figure|default)) -%} 

Function	Description
add_head_tag(name, value)	Add all kinds of head tag. Meta tag names must be prefixed with meta_, for example meta_description or meta_og:title.
add_head_meta_tag(name, value)	Shorthand for meta tags. The function adds the meta_ prefix automatically.
add_head_tags(array)	Add multiple tags at once. Pass as key => value or a AbstractHeadTag object. Meta tags must be prefixed with meta when passed as key.
get_head_news_tags(model, figure)	Create an array of tags for news models. The function automatically adds og:title, og:description, og:url and og:image tags. Pass a figure to override default news article image.

The value argument can be a string, null or a Contao Figure. If a Figure is passed, its image source is used as the tag content.

Integration

Use head bundle api set in your code.

Set head content

To set base, title, meta and link tags, use the HtmlHeadTagManager service:

use HeimrichHannot\HeadBundle\HeadTag\BaseTag;
use HeimrichHannot\HeadBundle\HeadTag\LinkTag;
use HeimrichHannot\HeadBundle\HeadTag\MetaTag;
use HeimrichHannot\HeadBundle\HeadTag\Meta\CharsetMetaTag;
use HeimrichHannot\HeadBundle\HeadTag\Meta\HttpEquivMetaTag;
use HeimrichHannot\HeadBundle\HeadTag\Meta\PropertyMetaTag;
use HeimrichHannot\HeadBundle\HeadTag\TitleTag;
use HeimrichHannot\HeadBundle\Manager\HtmlHeadTagManager;
use Symfony\Component\HttpFoundation\Request;

class SomeEventListener
{
    private HtmlHeadTagManager $headTagManager;

    public function updateBaseTag(Request $request): void
    {
        // Set base tag to null to remove it
        $this->headTagManager->setBaseTag(null);
        
        //Set base tag from object or url
        $this->headTagManager->setBaseTag(new BaseTag($request->getSchemeAndHttpHost()));
        $this->headTagManager->setBaseTag('https://example.org');
    }
    
    public function updatedTitleTag(): void
    {
        // Set title to "Hello World"
        $this->headTagManager->setTitleTag('Hello World');
        
        // Set title tag from object and adjust output format
        $this->headTagManager->setTitleTag(new TitleTag('Foo Bar', '%s | {{page::rootPageTitle}}'));
        // Will output: <title>Foo Bar | My Great Website Page Title</title>
    }
    
    public function setMetaTags(): void
    {
        // Add a new meta tag. If a tag with the same name already exists, it will be overridden
        $this->headTagManager->addMetaTag(new MetaTag('author', 'John Doe'));
        
        // Get an existing tag
        $description = ($tag = $this->headTagManager->getMetaTag('og:description')) ? $tag->getContent() : '';
        
        // Remove a tag
        $this->headTagManager->removeMetaTag('twitter:site');
        
        // Create a tag for property meta tags
        $this->headTagManager->addMetaTag(new PropertyMetaTag('og:type', 'article'));
        
        // Create a http-equiv tag
        $this->headTagManager->addMetaTag(new HttpEquivMetaTag('refresh', '30'));
        
        // Set a charset tag
        $this->headTagManager->addMetaTag(new CharsetMetaTag('UTF-8'));
        
        // Create tags without class (usefull when creating tags in a loop without custom checks)
        $this->headTagManager->addMetaTag(
            $this->headTagManager->getHeadTagFactory()->createMetaTag('description', 'Lorem ipsum!')
        );
        $this->headTagManager->addMetaTag(
            $this->headTagManager->getHeadTagFactory()->createTagByName('meta_og:url', 'https://example.org')
        );
    }
    
    public function setLinkTags(): void
    {
        // Add a new link tag. If a tag with the same name already exists, it will be overridden
        $this->headTagManager->addLinkTag(new LinkTag('next', 'https://example.org?page=2'));
        
        // Get an existing tag
        $this->headTagManager->getLinkTag('prev');
        
        // Remove a tag
        $this->headTagManager->removeLinkTag('prev');
    }
}

Developers

Backend field

Get tag options for a select field. If you want to define options by your own, prepend meta tag options with meta_.

use HeimrichHannot\HeadBundle\Helper\DcaHelper;

class HeadTagOptionsListener {
    private DcaHelper $dcaHelper;

    public function __invoke() {
        return $this->dcaHelper->getTagOptions([
            // filter: (array|null) If set, only tags fulfill given filters will be returned. See FILTER constants for available options. Default null
            'filter' => [DcaHelper::FILTER_META, DcaHelper::FILTER_TITLE],
            // skip_tags: (array) Skip specific tags. Default empty
            'skip_tag' => ['og:locale'],
        ]);
    }
}

Example how to evaluate field values:

use Contao\ContentModel;
use HeimrichHannot\HeadBundle\Manager\HtmlHeadTagManager;

class SomeEventListener {
    private HtmlHeadTagManager $headTagManager;
    
    public function __invoke(ContentModel $contentModel){
        $tag = $this->headTagManager->getHeadTagFactory()->createTagByName($contentModel->headTag);
        if ($tag) {
            $tag->setAttribute("content", $contentModel->headTagContent);
            $this->headTagManager->addTag($tag);
        }
    }
}