Cms Bundle Laravel Package

Getting Started

This is not a Laravel package. piedweb/cms-bundle is a Symfony bundle — it targets symfony/framework-bundle, uses Doctrine ORM, Twig, and the Symfony DI container. You cannot composer require it into a Laravel app and expect controllers, routes, or entities to work. The only sane adoption paths are:

1. Standalone Symfony app — spin up a symfony/skeleton project and install the bundle there, then consume it over HTTP or share the database with your Laravel app.
2. Service split — keep Laravel for the product, run this CMS as a separate Symfony deployment whose job is admin editing + static/HTML output.

Minimal bootstrap for the Symfony host:

composer require piedweb/cms-bundle

// config/bundles.php — no Flex recipe is assumed, register manually
return [
    // ...
    PiedWeb\CmsBundle\PiedWebCmsBundle::class => ['all' => true],
];

# config/routes/piedweb_cms.yaml — confirm the exact resource path in the bundle
piedweb_cms:
    resource: '@PiedWebCmsBundle/Resources/config/routes.yaml'

# config/packages/piedweb_cms.yaml — keys are bundle-specific, verify them
piedweb_cms:
    # templates, locales, upload dir, etc.

You need a working Doctrine setup and a migration run before anything renders. Do not guess the schema — inspect the bundle's Entity/ directory, then php bin/console doctrine:schema:validate after your first doctrine:migrations:diff.

Where to look first, in this order:

1. src/ in the repo — the Entity/ folder is the real API surface (likely Page and Media or similar). Everything else orbits these.
2. Resources/config/ — routing, services, and the bundle's config tree. This tells you what is actually configurable versus hardcoded.
3. Resources/views/ — the front and admin Twig templates you will override.
4. php bin/console list — the static generator and any admin-setup commands live here. Run this before reading docs.

First use case: create one Page through the admin, confirm the front controller resolves it by slug, then override a single template to prove the theming path works. Only after that should you attempt the static generator — it assumes a working front-end first.

Also budget for an admin user: there is almost certainly no installer command, so you will create the first user manually via a console command, a fixture, or a direct DB insert, and wire a Symfony security.yaml firewall over the admin routes yourself.

Implementation Patterns

Treat the Page entity as the content contract. Read it, then read the repository class that resolves it. That pair defines what a "page" is — slug, locale, template, parent, published flag, SEO fields. Every integration you build (sitemaps, redirects, seeders) queries through that repository rather than raw DB.

Template override via bundle paths. Symfony resolves templates from templates/bundles/PiedWebCmsBundle/... before the bundle's own views. Copy the file you want to change from Resources/views/ into that directory, keeping the relative path identical. Never edit inside vendor/.

Programmatic content seeding — fixtures or a one-off command using the entity manager, so demo environments stay reproducible:

$page = (new Page())
    ->setSlug('about')
    ->setTitle('About');
// set the fields your inspected entity actually exposes
$em->persist($page);
$em->flush();

Static generation pipeline. The intended workflow is: edit in the admin → run the generator command → deploy the emitted directory. Shape it as a CI job, not a manual step:

php bin/console <piedweb static command> --env=prod
# rsync/copy the output directory to your host or CDN

Always build with --env=prod so Twig caching and asset resolution match production. Keep the generator's output directory out of git and out of public/ if your web server should serve the dynamic app.

Media handling. Uploads go through the admin form to a filesystem path configured in the bundle. If you generate static output, verify that the generator copies referenced media alongside the HTML — if it doesn't, you own that step and should script it as an rsync of the upload directory with the build.

Extending behaviour is via standard Symfony mechanisms, not a plugin API: an EventSubscriber on kernel.request for redirects, a custom controller registered in routes.yaml, a Twig extension for filters in page content. Because the bundle is thin, you are often better off writing a small service that wraps it than trying to hook into internals.

Laravel-side integration. If your Laravel app must read this content, prefer the database over the bundle's PHP classes — a read-only Eloquent model pointed at the page table costs you nothing and cannot break when the bundle's entity changes. Reserve HTTP calls for admin-triggered operations (cache flush, rebuild trigger):

// Laravel side: trigger a rebuild on the Symfony service
Http::withToken(config('cms.token'))->post(config('cms.url').'/admin/rebuild');

Gotchas and Tips

It is archived with 7 stars and zero dependents. There will be no security releases, no Symfony 7 compatibility work, and no answers to your issues. Pin the version in composer.json, commit composer.lock, and plan to fork the bundle into packages/ with a VCS repository entry if you ship anything that matters. Assume the default answer to "does it support X" is no.

The framework mismatch is the headline risk. Any tutorial, config snippet, .env key, or command you find online for Laravel is irrelevant here. Symfony's DI, its cache (var/cache), its console, and its security config are all different from what a Laravel developer reaches for first. The debug: commands are your primary debugging tool and there is no Laravel equivalent habit for them:

php bin/console debug:config piedweb_cms   # what config keys are real
php bin/console debug:router               # what routes the bundle registered
php bin/console debug:container | grep -i piedweb
php bin/console lint:twig templates/
php bin/console cache:clear

Config keys are undocumented in practice. Never assume a YAML key from a blog post. Run debug:config piedweb_cms and read the configuration tree in DependencyInjection/Configuration.php. Unknown keys are silently ignored in older Symfony versions, so a typo looks like "the feature doesn't work" rather than an error.

Config changes require a cache clear. Symfony compiles the container. Editing piedweb_cms.yaml, security.yaml, or routes.yaml and refreshing the browser will show stale behaviour until cache:clear, and in prod you must also warm the cache.

Doctrine entity extension is painful. The bundle owns its mappings. Subclassing Page to add columns means single-table inheritance, overriding the bundle's mapping, and fighting the repository. If you only need extra fields for SEO or analytics, add them as a separate entity with a OneToOne and a join — do not inherit.

Do not fight the routing catch-all. The front controller almost certainly resolves arbitrary slugs, which will shadow or be shadowed by your own app routes depending on import order. Put your application routes above the bundle import in your main routes.yaml, and confirm with debug:router that the order is what you expect. Slugs like login or admin can collide — reserve them.

Static generator limitations are load-bearing. Forms, search, pagination links with query strings, and any user-specific content will not survive static export. Decide early whether the site is genuinely static or "static plus one dynamic endpoint," and keep dynamic surfaces off the pages the generator touches. Also audit absolute URLs and asset paths in the exported HTML — a hardcoded http://localhost in a template will ship to production.

Media permissions and paths. On the default local filesystem adapter, public/uploads (or wherever it points) needs write permission for the web user and readable by whatever runs the static build. Two different users means two different failure modes. Check var/log/ first when uploads fail silently — the admin form often swallows the exception.

Security is your responsibility. The bundle ships an admin with an unknown default firewall. Explicitly put its route prefix behind a security.yaml firewall with form_login and access_control, and verify with an anonymous request. Do not assume the bundle is locked down because the route is under /admin.

Debugging the front end of an abandoned bundle: the stack traces will point into vendor/, which is often the only documentation. Read the controller, not the README. If a Twig error references a template you cannot find, run debug:twig to see the resolved path — the bundle's view namespace is frequently not what the class name suggests.

Extension point to prefer: a small EventSubscriber on kernel.request or a Twig extension. These survive bundle updates because they use Symfony contracts, whereas subclassing the bundle's controllers ties you to internal signatures that will never be documented.