setono/tag-bag

Inject dynamic tags programmatically

v2.3.0 2024-05-21 09:28 UTC

Requires

• php: >=8.1
• ext-hash: *
• psr/event-dispatcher: ^1.0
• psr/log: ^1.1 || ^2.0 || ^3.0
• webmozart/assert: ^1.11

Requires (Dev)

• infection/infection: ^0.26.21
• phpunit/phpunit: ^10.5.20
• psalm/plugin-phpunit: ^0.19
• setono/code-quality-pack: ^2.7

MIT

• Joachim Løvgaard

README

Tag bag is an object oriented and very extendable way of adding content/tags to your pages.

A very common use case for the tag bag is tracking events on your pages.

Installation

composer require setono/tag-bag

Basic usage

<?php
declare(strict_types=1);

use Setono\TagBag\Renderer\ElementRenderer;
use Setono\TagBag\Tag\InlineScriptTag;
use Setono\TagBag\TagBag;

$tagBag = new TagBag();

// in a controller or service
$tagBag->add(InlineScriptTag::create('trackSomething();'));

// in your template
$tagBag->renderAll();

The above call to TagBagInterface::renderAll() would output the following:

<script>trackSomething();</script>

Here we introduced two important concepts of the tag bag: The tags and the rendering of the tags.

Tags are PHP classes implementing the TagInterface and they are designed to make it easier for you to output content on your pages. The ones included are pretty basic, and you may find that you'd want to use some other more advanced tags that you can read about in the tags section below.

Tags

The base library includes the following tags:

Content tag

<?php
use Setono\TagBag\Tag\ContentTag;

$tag = ContentTag::create('<div class="class-name">tag</div>');

Renders as:

<div class="class-name">tag</div>

Element tag

<?php
use Setono\TagBag\Tag\ElementTag;

$tag = ElementTag::createWithContent('div', 'content');

Renders as:

<div>content</div>

Inline script tag

<?php
use Setono\TagBag\Tag\InlineScriptTag;

$tag = InlineScriptTag::create('alert("Hey!");');

Renders as:

<script>
alert("Hey!");
</script>

You can also add attributes to the inline script tag:

<?php
use Setono\TagBag\Tag\InlineScriptTag;

$tag = InlineScriptTag::create('{"@context": "https://schema.org/"}')->withType('application/ld+json');

The above renders as:

<script type="application/ld+json">
{"@context": "https://schema.org/"}
</script>

Link tag

<?php
use Setono\TagBag\Tag\LinkTag;

$tag = LinkTag::create('stylesheet', 'https://example.com/style.css');

Renders as:

<link rel="stylesheet" href="https://example.com/style.css">

Style tag

<?php
use Setono\TagBag\Tag\StyleTag;

$tag = StyleTag::create('body { background-color: red; }');

Renders as:

<style>
body { background-color: red; }
</style>

Twig tag

Render using twig templates. See installation instructions and usage here.

PHP templates tag

Render using PHP templates. See installation instructions and usage here.

Gtag tag

If you're using Google's services, some of them allow you to track events using the gtag.

To make it easier to create these tags, you can use the gtag extension for the tag bag.

Renderers

The base library contains two renderers. A renderer implements the RendererInterface.

Just as with the tags there are also renderers in the sub packages.

Content renderer

The ContentRenderer renders the content you've input in the tag.

Element renderer

The ElementRenderer renders 'element tag', e.g. <script>, <style>, <meta>, <link>, all tags based on HTML elements basically.

Storage

The intended use of the tag bag is to save the tag bag upon end of request and restore it upon starting the request life cycle. The TagBagInterface has store and restore methods for these events respectively.

<?php
use Setono\TagBag\Tag\InlineScriptTag;
use Setono\TagBag\TagBagInterface;

/** @var TagBagInterface $tagBag */

// in a controller or service
$tagBag->add(new InlineScriptTag('trackSomething();'));

// this stores the contents of the tag bag
$tagBag->store();

// this restores the contents of the tag bag
$tagBag->restore();

Framework integration

• Symfony: TagBagBundle