Seo Bundle Laravel Package

Getting Started

• Reality check before you install anything: norsys/seo-bundle is a Symfony bundle, not a Laravel package. There is no ServiceProvider, no vendor:publish, no artisan command, and Laravel's package discovery will not register it. If you're in a Laravel codebase, you cannot composer require this and start using it. Your realistic entry points are: (a) a Symfony app you also maintain, or (b) a bridge where a Symfony app resolves the metadata and a Laravel front end consumes it.
• Install in a Symfony context:

  composer require norsys/seo-bundle
  

  Then register it in config/bundles.php:

  Norsys\SeoBundle\NorsysSeoBundle::class => ['all' => true],
  

  The last release is 2018-07-17 — check it against your symfony/framework-bundle and Twig versions before committing. Expect to need a constraint bump or a conflict block rather than a clean install.
• Where to look first: the bundle's DependencyInjection/Configuration.php (the config tree), then its Twig extension and templates. The config tree is the documentation — it tells you every meta key (title, description, robots, canonical) and the defaults. The README's quick-start is secondary.
• First use case: set site-wide SEO defaults in config/packages/norsys_seo.yaml and render them from a single base Twig layout, so individual controllers only override what differs. That's the whole point — keep meta tags out of controllers and out of page templates.
• If you're a Laravel dev evaluating this for a Laravel project: don't. Skim it for the pattern (config-driven defaults → base layout → per-route override) and reimplement it in ~150 lines with a SeoManager service, a Blade component, and a canonical-URL middleware.

Implementation Patterns

• Config-driven defaults, per-route overrides. Put the site title, default description, robots policy, and canonical base in the bundle config. Override only on the actions that differ. Keep the override mechanism in one base layout.html.twig so every page inherits canonical and robots automatically.
• One template owns <head>. Title, description, canonical, and robots get rendered in exactly one place. If the bundle exposes Twig functions, call them there. Never scatter meta rendering across partials — duplicate tags are an SEO bug, not a cosmetic one.
• Drive robots from an environment flag. Map APP_ENV (or an explicit SEO_INDEXABLE var) into the config so staging emits noindex, nofollow and production emits your intended default. This is the single most common SEO incident — a staging site leaking index, follow into Google.
• Canonical URLs come from config or a URL builder, not the controller. Build the canonical from the request plus a route-name→canonical map. That survives query strings, pagination, and tracking params — exactly where bad canonicals do damage.
• Extend via the bundle's definitions, not forks. If it exposes "definitions" for custom meta, add new ones in your app's service config. If it doesn't, wrap the bundle in a thin SeoMetadataBuilder service of your own — the same discipline you'd apply wrapping a Laravel package behind an app-level service.
• Bridging to Laravel: treat the Symfony app as a data source. Export the resolved payload (title/description/canonical/robots) as JSON via an internal endpoint or a shared table, then render in Blade:

  <x-seo-meta :meta="$meta" />
  

  Do not attempt to boot the Symfony bundle inside Laravel.
• Testing: assert the rendered <head> has exactly one <title>, one meta description, and one canonical. Snapshot the base layout. If you bridge to Laravel, unit-test the Blade component against a fixed payload — don't try to test Symfony internals from a Laravel PHPUnit run.
• The Laravel reimplementation (recommended long-term): a config/seo.php for defaults, a SeoManager singleton bound in a service provider, a <x-seo-meta> component for output, and middleware that fills the canonical from the current route. Same model, no Symfony coupling.

Gotchas and Tips

• It is not a Laravel package. If a blog post tells you to add Norsys\SeoBundle\... to config/app.php, it's wrong. No auto-discovery, no publish tags, no config:cache path for its configuration.
• Age is the biggest risk. One star, zero dependents, last release 2018. Expect Symfony 3/4-era APIs and unmaintained Twig signatures. Run composer why-not symfony/framework-bundle before adopting, and be prepared to pin hard.
• Zero dependents means zero community answers. There is no Stack Overflow safety net. Read the source — the bundle is small — instead of searching for docs. Configuration.php and the README are your entire documentation.
• Config alias mismatches fail silently. The key in config/packages/*.yaml must equal the bundle's getAlias() (typically norsys_seo). A typo leaves defaults unset and you get blank titles with no error. Diagnose with:

  bin/console debug:config norsys_seo
  bin/console debug:container | grep -i seo
  bin/console debug:twig | grep -i seo
  

• Duplicate tags from partials. The classic failure mode: the base layout renders the description and a page template renders it again. grep -R '<meta name="description"' templates/ and keep exactly one.
• Escaping. Titles and descriptions are content-derived. Rely on Twig autoescaping and never pipe SEO output through |raw — an unescaped quote breaks the attribute and can inject markup into <head>.
• Canonical + pagination + locale. Confirm the bundle doesn't emit a canonical that drops ?page= or locale prefixes. A self-referencing canonical that points page 2+ back to page 1 de-indexes your paginated content. Override it yourself rather than accepting a wrong one.
• Stale container cache in Symfony. After editing config/packages/norsys_seo.yaml, run bin/console cache:clear, and clear the prod cache on every deploy. "Config changes have no effect" is nearly always stale container cache.
• Vendor edits will vanish. With no maintainer momentum, patches to vendor/norsys/seo-bundle are lost on the next composer update. Use the config tree first, Symfony event listeners/decorators second, a compiler pass third — in that order.
• Debug responsibly. dump() inside a Twig base layout will wreck every response. Use Symfony's profiler and the bundle's logging rather than inline dumps.
• Strategic call: if the project is and will stay Symfony, this is a lightweight, workable fit — pin it, wrap it in your own service, and budget for replacement. If the project is Laravel, skip it and implement the same config-driven pattern natively; you'll get a maintained, testable result with no framework mismatch.