Corebundle Laravel Package

Getting Started

umbrella2/corebundle is the core entity and service layer of the Umbrella CMS, not a standalone library. It only makes sense if you're maintaining an existing Umbrella-based Symfony application (typically pulled in transitively via umbrella2/umbrella).

Minimal steps:

1. Install the meta-package rather than the core bundle directly, so you also get the dependent bundles (umbrella2/adminbundle, umbrella2/blockbundle, taxonomy/media bundles, etc.):

   composer require umbrella2/umbrella
   

   If you must pin it explicitly, note the last tag is 2021-05-31; check composer show umbrella2/corebundle and align with the Symfony version your app is on (4.x era).

2. Register the bundle in config/bundles.php (or AppKernel::registerBundles() for older skeletons):

   Umbrella\CoreBundle\UmbrellaCoreBundle::class => ['all' => true],
   

3. Import the routing and enable the config tree. The bundle exposes an extension alias, so a minimal config/packages/umbrella_core.yaml with the defaults is enough — dump the full reference with:

   bin/console config:dump-reference umbrella_core
   

4. Schema: because the core bundle ships Doctrine mappings for its base entities, run your migrations (or doctrine:schema:validate) after enabling it, and inspect the generated tables before applying.

Where to look first: the bundle's base entities (Node, Term, User/Role, File/Media, Menu) and its service definitions. Those are the two things you'll extend or override 90% of the time. Check Resources/config/ for service wiring and Resources/views/ for the Twig layout blocks you'll inherit.

First use case: fetching a content node by its path and rendering it in a controller:

// controller
$node = $nodeRepository->findOneByPath('/about');
return $this->render('page/show.html.twig', ['node' => $node]);

If that works end-to-end (routing, tree lookup, template), the bundle is wired correctly; everything else is incremental.

Implementation Patterns

Extend the base entities, don't modify the bundle. Umbrella is designed around Doctrine mapped-superclass / single-table inheritance. Put your own App\Entity\Page extends Umbrella\CoreBundle\Entity\Node in src/Entity, register the discriminator, and let the bundle's repositories query through. This is the single most important pattern: keep vendor code pristine.

Work through the container, not new. The core bundle exposes services for the tree, breadcrumbs, node resolution, media handling and menu building. Inject them by their service ID (check bin/console debug:container --show-private | grep umbrella) rather than re-implementing path/tree logic yourself.

Config-driven behavior over code. Most Umbrella features (available node types, menu locations, default templates, upload paths) are toggled in umbrella_core config. Prefer a config change over an event subscriber when you need to enable/disable a feature — the bundle reads config at container compile time in several places.

Override templates via the standard bundle override path. Create templates/bundles/UmbrellaCoreBundle/... with the same relative path as the vendor template. This is safer than editing vendor files and survives composer install.

Integrate through Symfony events, not patching. If your app needs extra behavior on node save/publish, use Doctrine lifecycle listeners on your own entity subclasses, or a kernel.request listener that resolves the current node. The bundle was built pre-messenger, so hook into its service methods by decorating the relevant service (decorates: umbrella_core.<service_id>).

Typical workflow for a content-type addition:

1. Create the entity extending the core base class.
2. Add the Doctrine mapping / migration.
3. Register the node type in umbrella_core config (or the admin bundle's type registry).
4. Add the form type and template block.
5. Clear cache (bin/console cache:clear) — the bundle caches config and routing aggressively.

When integrating into a modern Symfony app: treat the bundle as a black box behind a repository/service facade of your own. Wrap every call to a core service in a thin adapter class so you can later replace it, since the package is archived and won't receive Symfony 6/7 compatibility.

Gotchas and Tips

• It is archived and unmaintained. Last release May 2021, zero dependents. Do not plan new features on it; budget for a migration path. Any Symfony/PHP upgrade is effectively a fork. Vendor it (composer path repository) if you need to patch it.
• Version pinning is essential. Because it's unmaintained, its composer.json constraints will resolve to outdated Symfony/Doctrine versions. Expect conflicts — resolve by pinning your framework version or by --ignore-platform-reqs in CI only, never locally.
• Config cache blindness. The extension pre-computes several values at compile time. After any change to umbrella_core.yaml you must cache:clear (or delete var/cache), otherwise behavior silently stays stale — a classic source of "my config change does nothing."
• Doctrine mapping collisions. Mapped-superclass entities will clash if you also declare the base table in your own mapping. Use @MappedSuperclass semantics from the bundle and never re-map the base class in your config.
• Tree/path bugs on bulk imports. Node paths are often computed in application code, not by the DB. When importing content in bulk, ensure path/nested-set values are recalculated by the bundle's service, or you'll get duplicate/incorrect paths that look fine in the DB but break routing.
• Template resolution surprises. Bundle templates win over app templates in older Symfony unless overridden with the bundles/... directory. If a Twig block appears missing, check debug:twig for which file actually won.
• Debugging checklist: bin/console debug:container | grep umbrella, config:dump-reference umbrella_core, doctrine:schema:validate, debug:router | grep umbrella. In that order.
• Extension points that still work: service decoration, form-type extension (AbstractTypeExtension), Twig extension override, and event subscribers on your own entity subclasses. Avoid overriding the bundle's controllers directly — you'll be stuck at the next (nonexistent) fix.
• License is fine (MIT) — you can fork and maintain privately with minimal legal friction; that's likely your practical escape hatch if the app lives on.