README

A lightweight Symfony bundle to manage SEO metadata (title, description, H1) and navigational breadcrumbs with Twig-powered templating and CLI importers.

Features
Requirements
Installation
Configure your entities
Bundle configuration
Database/migrations
Usage in Twig
Importing from routes (CLI)
Route parameters and templating
Global variables with Bags
Customizing the breadcrumbs template
Troubleshooting
License

Features

SEO metadata service that renders title, meta description and H1 using Twig templates.
Breadcrumbs service that renders a breadcrumb trail using a provided Twig partial.
Both features read from your Doctrine entities; you control persistence in your app.
Twig variables come from your controller arguments and from optional shared “bags”.
Two console commands to import missing items from your Symfony routes.

Requirements

PHP >= 8.4
Symfony 7.3 (FrameworkBundle, Console, Routing, TwigBundle)
Doctrine ORM 3.x
Twig 3.21+

Installation

Install the package via Composer

composer require inwebo/seo-bundle

Symfony will auto-register the bundle (type: symfony-bundle). No manual steps needed.

Configure your entities

This bundle ships mapped superclasses you should extend to create concrete Doctrine entities in your project.

Example: App entity for breadcrumbs

<?php

namespace App\Entity\Seo;

use Doctrine\ORM\Mapping as ORM;
use Inwebo\SeoBundle\Entity\Breadcrumb as BaseBreadcrumb;

#[ORM\Entity]
#[ORM\Table(name: 'seo_breadcrumb')]
class Breadcrumb extends BaseBreadcrumb
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    protected ?int $id = null;
}

Example: App entity for metadata

<?php

namespace App\Entity\Seo;

use Doctrine\ORM\Mapping as ORM;
use Inwebo\SeoBundle\Entity\Metadata as BaseMetadata;

#[ORM\Entity]
#[ORM\Table(name: 'seo_metadata')]
class Metadata extends BaseMetadata
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    protected ?int $id = null;
}

Bundle configuration

Tell the bundle which FQCNs to use and optionally which routes to ignore for metadata resolution.

# config/packages/inwebo_seo.yaml
inwebo_seo:
  breadcrumb:
    entity: App\Entity\Seo\Breadcrumb
  metadata:
    entity: App\Entity\Seo\Metadata
    excluded_routes:      # metadata resolution is skipped when route name starts with any of these prefixes
      - _                 # useful to ignore Symfony internals (e.g. _profiler, _wdt)
      - admin_            # example: skip your back-office

Notes

Doctrine mapping for the bundle’s mapped superclasses is auto-prepended, so extending them is enough.
You decide where and how to persist data (fixtures, admin UI, CLI importers below, etc.).

Database/migrations

After creating your concrete entities, generate and run a migration in your app:

php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate

Usage in Twig

Drop these helpers into your base layout or individual templates:

<title>{{ inwebo_seo_title() }}</title>
<meta name="description" content="{{ inwebo_seo_description() }}" />
<h1>{{ inwebo_seo_h1() }}</h1>

{# Render the breadcrumb trail #}
{{ inwebo_seo_breadcrumbs() }}

Importing from routes (CLI)

The bundle provides commands that scan your router and create missing records so you can fill them later.

# Import missing breadcrumbs for known routes
php bin/console inwebo_seo:import:breadcrumbs   # alias: is:i:b

# Import missing metadata for known routes
php bin/console inwebo_seo:import:metadata     # alias: is:i:m

Each command prints a table of newly persisted rows or a message if nothing is needed.
You can safely run these commands multiple times; they only create missing items.

Route parameters and templating

All breadcrumb and metadata string fields (e.g., breadcrumb name/title, metadata title/description/h1) are rendered using Twig.
Available Twig variables include:
- Controller arguments for the current request (by name)
- Values stored in the corresponding Bag (see below)
You can reference route parameters by name in your templates. Example:
- Breadcrumb.name: Category: {{ category.name }}
- Breadcrumb.title: Back to {{ category.name }}
- Metadata.title: {{ product.name }} | My Shop

Global variables with Bags

Sometimes you want to provide extra variables not present in controller arguments. Use the provided Bags.

MetadataBag provides variables for metadata templates
BreadcrumbBag provides variables for breadcrumb templates

Add values anywhere before rendering (e.g., in a listener or controller):

<?php
use Inwebo\SeoBundle\Model\MetadataBag;
use Inwebo\SeoBundle\Model\BreadcrumbBag;

MetadataBag::create()::add(['siteName' => 'Acme']);
BreadcrumbBag::create()::add(['locale' => 'en']);

Then in your templates stored in DB you can do:

{{ siteName }}
{{ locale }}

Customizing the breadcrumbs template

The breadcrumbs HTML is rendered via the template path: @InweboSeo/_breadcrumbs.html.twig

Options to customize:

Easiest: copy the file from vendor/inwebo/seo-bundle/templates/_breadcrumbs.html.twig into your app and add a Twig path with higher priority for the InweboSeo namespace, or override via the standard bundles override path if configured.
Or, keep the function and style via CSS.

Troubleshooting

I see an exception like " is not a valid metadata object."
- Ensure you created and configured your concrete Metadata entity and that a row exists for the current route.
- Check inwebo_seo.metadata.entity is set to your FQCN and that the route name matches.
Breadcrumbs don’t show up:
- Ensure a Breadcrumb row exists for the current route. Use the importer to create missing ones.
- If you need parameters, set routeParameters on the breadcrumb so URLs can be generated.
Metadata not applied on some routes:
- Use excluded_routes config to skip areas like _profiler, admin_, etc.

License

GPL-3.0-or-later. See LICENSE file for details.

inwebo / seo-bundle

Maintainers

Details