Website Bundle Laravel Package

Getting Started

First, resolve the stack question — it dominates everything else.

Despite the "Laravel/PHP" framing in the package metadata, integrated/website-bundle is a Symfony bundle, not a Laravel package. There is no service provider, no config/website-bundle.php, no Blade views. Day-to-day leverage therefore depends entirely on which of these you can commit to:

1. Native Symfony app — the only pattern where the bundle delivers its advertised value directly.
2. Satellite Symfony service on a subdomain/reverse-proxied path, with your Laravel app continuing to own authenticated surfaces.
3. Skip it — consume Integrated's content API from Laravel/Blade or a JS front end and treat this repo as a reference implementation of the content model.

If you cannot deploy and maintain a Symfony runtime, stop reading the rest of this section: the correct first step is opening the bundle's Controller/ and Resources/views/ directories to learn Integrated's content model, then building your own thin rendering layer.

Minimal steps (Pattern 1/2)

composer create-project symfony/skeleton my-site
cd my-site
composer require integrated/website-bundle

Then:

1. Register the bundle in config/bundles.php (Symfony ≤6 skeleton) or rely on Flex auto-registration.
2. Publish/merge its config:

   php bin/console config:dump-reference integrated_website
   php bin/console debug:config integrated_website
   

   The DependencyInjection/Configuration.php file in the bundle is the authoritative list of config keys — read it, because there is no published docs site.
3. Set the Integrated backend connection values (base URL, API token, or DB DSN — determinable from the bundle's service definitions).
4. Import the bundle's routes in config/routes.yaml:

   integrated_website:
       resource: '@IntegratedWebsiteBundle/Resources/config/routing.xml'
   

5. php bin/console debug:router — confirm the bundle's slug/page routes registered and note their order relative to your own routes.
6. Hit a page.

Where to look first, in order

First use case to validate

A single page with a slug route, rendered through a layout that includes the navigation menu and SEO metadata. That one page exercises page management, menus, SEO, and settings simultaneously — if all four work, the bundle is viable for your site; if any one requires heavy fighting, scope accordingly before building twenty templates on top of it.

Implementation Patterns

Template override, not template edit. Never edit files under vendor/. Symfony's bundle override convention resolves templates/bundles/IntegratedWebsiteBundle/<path>.twig before the vendor copy. Adopt this as a hard rule from day one and keep a manifest of every override you create — that manifest is your fork cost estimate.

templates/bundles/IntegratedWebsiteBundle/
├── layout.html.twig
├── page/show.html.twig
└── partials/navigation.html.twig

Layout composition. Have your project base template extend the bundle layout rather than the other way around, and keep the <head> SEO block, canonical URL, and menu partial as isolated overridable blocks:

{% extends '@IntegratedWebsiteBundle/layout.html.twig' %}

{% block head_meta %}
    {{ parent() }}
    {# project-specific og:image, JSON-LD, etc. #}
{% endblock %}

This keeps your additions outside the bundle's file and makes a future swap a rewrite of one layout, not twenty templates.

Navigation as a cached service. Menus are usually the second-most-hit query after page content. Decorate or wrap the bundle's menu provider with a cache layer keyed on the menu identifier, and invalidate on publish. Do not call the menu builder from every template without caching — a nav tree rendered on every request across a large site is a classic silent performance drain.

SEO metadata centralisation. Generate meta tags, canonical URLs, and sitemap entries in your application layer (a Twig extension or a dedicated SEO service), using the bundle only as the content source. This is the pattern that survives the bundle being replaced or forked. Canonical URL logic in particular — trailing slashes, pagination, multi-domain — is the first thing that goes wrong when it lives inside vendor code.

Settings: config vs. content. Distinguish between settings that belong in bundle config (backend URL, template defaults, environment flags) and settings that are editorial content (site name, footer text, social links). The former goes in config/packages/integrated_website.yaml with environment-specific overrides; the latter stays in Integrated so editors can change it without a deploy.

Route ordering discipline. Import the bundle's routes after your application's specific routes, or use a prefix, so the slug catch-all doesn't swallow /admin, /login, or API paths. Assert the final route table in CI:

php bin/console debug:router --show-controllers | grep integrated_website

Caching as a first-class layer. Assume the bundle ships no caching primitives until you find them. Front it with Symfony's HTTP cache or a CDN, tag responses by page ID and menu ID, and purge on Integrated's publish webhook. This is also your outage mitigation — see Gotchas.

Satellite integration (Pattern 2). If running alongside Laravel, put the Symfony service behind a reverse proxy, share the compiled design-system CSS/JS via a common build step (so the two apps cannot drift visually), and proxy only the public content routes. Do not attempt to share sessions — the two apps will have different security stacks.

Local development against staged content. Point local config at a staging Integrated instance with read-only credentials, and keep a small fixture set for offline work. Any workflow that requires a live backend to render a template will slow every UI change.

Gotchas and Tips

The slug catch-all will eat your routes. This is the single most common first-day failure with content-driven bundles. Symptom: /admin or /api/... returns a "page not found" rendered by the CMS layout. Fix: explicit requirements on the bundle's page route, or a negative-lookahead regex, or prefix your app routes. Run debug:router early and often.

Zero community means zero folklore. With 0 stars and 0 dependents there is no Stack Overflow history, no issue tracker archaeology, no blog posts. Every behavioural question is answered by reading vendor/integrated/website-bundle/src/. Budget for that explicitly; it is not a background activity.

Pin exact versions. No dependents means no compatibility evidence. In composer.json:

"integrated/website-bundle": "1.2.3"

Then treat minor bumps as reviewable PRs with a visual regression pass over key pages, not as composer update collateral. A silent template change in an overridden block is invisible until a customer sees it.

Config caching bites hard. After any change to config/packages/integrated_website.yaml, run php bin/console cache:clear. Symfony caches compiled config and the container in production mode; a config change that appears to "do nothing" is almost always this.

Published assets: commit them or build them, pick one. If the bundle ships assets you publish via assets:install, decide whether they live in public/ (committed) or are built in CI. Mixing the two produces environments where staging looks right and production is missing a stylesheet.

Backend outage becomes site outage. A rendering layer bound to a remote CMS fails visibly and hard unless you insulate it. Test it: stop pointing at Integrated and load a page. If it throws a 500, put a full-page cache in front before launch, not after. This is the operational risk that matters most day-to-day.

Debugging toolkit.

php bin/console debug:router                          # route collisions
php bin/console debug:container | grep -i integrated  # service IDs for decoration
php bin/console debug:twig --filter=menu              # Twig functions available
php bin/console config:dump-reference integrated_website

In dev, use the Symfony profiler's Twig panel to see which template file actually rendered — this instantly tells you whether your override is being picked up or silently ignored (wrong path, wrong bundle name, stale cache).

Extension points, in order of safety. Prefer: (1) config keys, (2) service decoration via services.yaml decorates:, (3) Twig template overrides, (4) Twig extension to add functions around the bundle's services. Avoid: editing vendor files, monkey-patching controllers, or copying the whole bundle into src/ as a starting point unless you genuinely intend to fork — a half-fork is the worst of both worlds.

Write the smoke tests the package doesn't have. There is no upstream test suite you can rely on. A handful of functional tests — homepage 200, a deep slug 200, unknown slug 404, nav present in markup, canonical tag present — will catch nearly every bundle upgrade regression for a fraction of the cost of visual QA.

Define your exit before launch. Document which templates you override, which routes point at bundle controllers, and how content would be re-read if you swapped to a headless integration. If that list is long, you already own a fork in all but name — say so and budget accordingly.

If you are Laravel-only, revisit the decision honestly. Adopting this means a second runtime, second deploy pipeline, and Symfony/Twig fluency for whoever owns it — realistically 2–4 weeks to productive contribution, with single-owner risk unless someone else is trained. For a small brochure site the template scaffolding may still be worth it; for anything with heavy interaction or a hard performance budget, consuming Integrated's API directly from Laravel is the lower-risk path, and this bundle is your documentation of the content model.