bjuppa / metatagbag
A convenient collection for HTML meta tags
Installs: 4 165
Dependents: 1
Suggesters: 0
Security: 0
Stars: 0
Watchers: 2
Forks: 0
Open Issues: 6
Requires
- php: ^7.1.0 || ^8.0
- illuminate/contracts: ^5.6 || ^6 || ^7 || ^8
- illuminate/support: ^5.6 || ^6 || ^7 || ^8
Requires (Dev)
- phpunit/phpunit: ^9.3.8
README
A PHP class for collecting and manipulating HTML meta tags
before echoing in the <head>
.
Works well with Laravel, and without.
Inspired by Laravel's MessageBag
.
composer require bjuppa/metatagbag
Table of contents
- Creating a
MetaTagBag
- Input Formats
- HTML Output
- Adding Tags
- Removing Tags
- Filtering Tags
- Inspecting a
MetaTagBag
- Sorting Tags
- Optional Manipulation
- Converting to json
- Alternative packages
Creating a MetaTagBag
use Bjuppa\MetaTagBag\MetaTagBag; $bag = new MetaTagBag( ['name' => 'description', 'content' => 'A description'], ['name' => 'keywords', 'content' => 'key,words'] ); // ...or using a static creator: $bag = MetaTagBag::make( ['name' => 'description', 'content' => 'A description'], ['name' => 'keywords', 'content' => 'key,words'] );
Input Formats
All methods that operate on some kind of list of meta tags will accept almost any type of map-like (key-value) input, optionally nested in some kind of list.
Tags can be in separate arguments
The most terse syntax can be seen in the creation examples above, where multiple tags are supplied, each as its own argument to the method.
Lists of tags are flattened
If some kind of nested list is encountered, it will be flattened so that any item lacking a "string" key will become its own tag in the resulting one-dimensional list of tags.
$bag = new MetaTagBag( [ ['name' => 'description', 'content' => 'A description'], ['name' => 'keywords', 'content' => 'key,words'], [ ['name' => 'nested', 'content' => 'This will end up in the top-level with the other tags'], ] ] );
Json strings are deserialized
If a string is encountered within a supplied list, attempts will be made to deserialize it from json.
MetaTagBag::make('[{"name":"description","content":"A description"},{"name":"keywords","content":["key","words"]}]');
Objects are converted to arrays
If an object is encountered within a supplied list, it will be converted to an array, and merged into the flattened list.
Implementations of Laravel's Arrayable
,
like Laravel's Collection
and other MetaTagBag
s will work just fine.
Implementations of
Bjuppa\MetaTagBag\Contracts\MetaTagProvider
will pull out that instance's MetaTagBag
.
MetaTagBag::make(new MetaTagBag(['name' => 'description', 'content' => 'A description']));
HTML Output
The MetaTagBag
should usually be rendered first within the <head>
element, before any other elements like <title>
.
This is because it may contain a charset
meta tag that should come before any other content.
// Return a string of HTML tags from the bag's contents $bag->toHtml();
MetaTagBag
implements
Laravel's Htmlable
contract
so in a Blade template you can echo the tags
by putting any instance within curly braces:
<head> {{ Bjuppa\MetaTagBag\MetaTagBag::make(['name' => 'description', 'content' => 'A description']) }} <title>Page title</title> </head>
Casting a MetaTagBag
to string
will also bring out the HTML representation:
echo $bag; //Implicit string casting $html = (string) $bag; //Explicit string casting
Output of comma-separated list attributes
For HTML, any array attribute will be imploded into a comma-separated list.
This can for example be used with a name="keywords"
meta tag,
where the keywords in the content
attribute can be treated as a list until the time of rendering.
Adding Tags
The add(...$tags)
method will modify the MetaTagBag
instance, adding any tags supplied without checking for duplicates.
The merge(...$tags)
method will also modify the MetaTagBag
instance, but will overwrite any existing tags having the same
name
, http-equiv
, itemprop
, or property
attributes.
Merging array attributes
If a tag to be merged has an array as its content
attribute,
that array will be merged with the content
of any existing matching tag in the bag.
This can for example be used with name="keywords"
meta tags,
where one may want to add keywords, rather than overwriting them.
Removing Tags
The forget(...$attributes)
method will remove all matching tags from the MetaTagBag
instance.
Filtering Tags
The match(...$attributes)
method can be used to filter out matching tags into a new MetaTagBag
.
The unique()
method returns a new MetaTagBag
where all duplicate tags have been removed
(keeping the last).
In addition, if unique(...$attributes)
is called with arguments,
matching tags will only appear once in the returned MetaTagBag
(also keeping the last).
Inspecting a MetaTagBag
The methods count(...$attributes)
and has(...$attributes)
can be used to count matching tags
or check if any matching tags exist in a bag.
Of course, count()
can be called without arguments to return the total number of tags in the bag,
while calling has()
without arguments will always return false
.
The content($attributes)
method will pull out the value of the content
attribute of the last matching tag.
It's a wrapper around getLastMatchingAttributeValue($attributeToGet, $attributesToMatch)
that does the same for any attribute.
Sorting Tags
The sort()
method called without arguments will return a new MetaTagBag
instance where charset
and http-equiv="X-UA-Compatible"
tags are placed first.
If a callback is given, it will be used just like
PHP's uasort
parameters.
Optional Manipulation
The pipe(callable $callback)
method passes the MetaTagBag
to the given callback and returns the result.
For example it can be used to fluently check if a MetaTagBag
contains some tag, and if so add or remove some other tag.
Converting to json
MetaTagBag
is JsonSerializable
so instances can be supplied directly to PHP's json_encode()
function.
Also, because MetaTagBag
implements
Laravel's Jsonable
contract,
there's also the toJson()
method.
Alternative packages
For a more opinionated end-to-end solution for meta tags in Laravel apps you should check out butschster/LaravelMetaTags.