Kuma Extra Bundle Laravel Package

Getting Started

First, the reality check. Despite the Laravel framing, hmp/kuma-extra-bundle is a Symfony bundle for Kunstmaan Bundles CMS (Kuma). It has no relation to Laravel's container, Eloquent, Blade, or Artisan. There is no adapter, no PSR-only surface, and no standalone library boundary — its features are wired directly into Kunstmaan's admin bundle and page/node model. If you are on Laravel, you cannot install this in any meaningful way; treat the repo as reference source and reimplement what you need. The steps below assume you (or a teammate) are actually working inside a Kuma/Symfony app.

1. Confirm the baseline. You need an existing Kuma project (kunstmaan/bundles-cms / the kuma metapackage). The bundle does nothing useful standalone.
2. Pin and install.

   composer require hmp/kuma-extra-bundle:^1.0
   

   With 1 star and 0 dependents, pin an explicit version or a commit SHA (:dev-master#<sha>) so a force-push or untagged change doesn't silently land. Confirm the composer.json constraint matrix (PHP + Symfony major + Kunstmaan bundle versions) against your app before committing — the constraints reflect the era the agency built it, so Symfony 6/7 support is unlikely and must be verified from the manifest, not the README.
3. Register the bundle.
   • Symfony 4/5+ in config/bundles.php:

     return [
         // ...
         Hmp\KumaExtraBundle\KumaExtraBundle::class => ['all' => true],
     ];
     

   • Symfony 3 / app/AppKernel.php: register it after the Kunstmaan bundles so its service definitions and template overrides win.
4. Where to look first (read the source, in this order):
   • src/ — the actual feature set: page parts, form types, Twig extensions, event subscribers.
   • Resources/config/ — service definitions and any Configuration tree (this tells you what's actually configurable vs. hardcoded).
   • Resources/views/ — Twig templates, especially PagePart/ and any admin overrides.
   • composer.json — the real compatibility story.
5. First use case. The typical payoff is drop-in page parts plus admin/Twig helpers. After registering: bin/console cache:clear, open the Kuma admin page editor, and check whether new page parts appear in the "Add page part" chooser. Drag one into a page and render it through your normal page template loop.

Implementation Patterns

Treat page parts as first-class Kuma citizens. Kuma renders parts through your page templates ({% for part in page.pageParts %} loops or the pagepart Twig helpers). Once the bundle is registered its parts behave like any other — the work is making sure your render loop covers every part type, usually via {% include part.template %} or a render_pagepart helper.

Override templates, never edit vendor. Copy any view you want to change from vendor/hmp/kuma-extra-bundle/Resources/views/... into templates/bundles/KumaExtraBundle/... (Symfony 4+) or app/Resources/KumaExtraBundle/views/... (Symfony 3). This is the upgrade-safe seam for both front-end parts and admin views — and given the maintenance status, an upgrade-safe seam is the whole ballgame.

Subclass supplied page parts rather than forking them.

namespace App\PagePart;

use Hmp\KumaExtraBundle\PagePart\SomeExtraPagePart as BasePart;

class TailoredPagePart extends BasePart
{
    public function getDefaultView(): string
    {
        return '@App/PagePart/TailoredPagePart/view.html.twig';
    }
}

Register the override in your own service config and point the admin form type at it. This lets you take upstream bug fixes (if any) while owning your divergence.

Wrap the bundle behind your own interface. Any helper/Twig extension you actually depend on should be re-exposed through a thin app-level service or Twig extension that you control. When the bundle is archived (a real possibility), a swap touches one class, not domain code. This is the single highest-leverage pattern for an unmaintained dependency.

Config layering. The bundle advertises "sensible defaults that stay easy to override" via standard Symfony config. Put your overrides in config/packages/kuma_extra.yaml (or app/config/config.yml on older apps), not in a compiler pass — keep it declarative so bin/console debug:config kuma_extra shows the effective tree. Read the bundle's Configuration class to know exactly which keys exist; the README is unlikely to be exhaustive.

Admin/editor conveniences (form types, list view tweaks) integrate through Kuma's admin conventions. Follow Kunstmaan's own docs for the pattern; the bundle is just supplying additional classes into that same pipeline. Verify each one by exercising the admin UI manually — there's no test suite you can trust as a signal.

Vendor or fork if you adopt. Given the bus factor of one, commit the source (or a fork under your org) into your repo, add it to dependency-review, and own the patch path. Do this on day one, not after the upstream repo disappears.

Gotchas and Tips

• Zero community means zero safety net. 1 star, 0 dependents, single maintainer. There is no one to catch a Symfony minor-version break. Every framework upgrade becomes an internal fork exercise — budget for it.
• Composer conflicts will surface first on framework upgrades and will block them until you patch. Watch for these on day one of any Symfony bump; they're the leading indicator that you're now maintaining the code.
• Silent admin UI breakage is the failure mode to plan for. Features half-wired into Kunstmaan base classes tend to fail quietly, not loudly. After any Symfony or Kuma upgrade, do a manual editor QA pass over every page part this bundle introduces — there's no automated signal.
• The "Laravel developer" trap. Do not attempt to boot this inside Laravel. Running two full-stack frameworks in one process to obtain a handful of admin conveniences is orders of magnitude more expensive than reimplementing the feature delta natively (a few days vs. weeks of Symfony/Doctrine/Kunstmaan ramp-up).
• Read composer.json, not the README, for compatibility. The declared constraints are the source of truth; test the actual matrix in a throwaway Symfony app before touching a product repo.
• Cache is the usual culprit for "nothing happened." After registering or after any config change: bin/console cache:clear (and cache:warmup in prod-like environments). If a new page part doesn't show in the admin chooser, suspect cache or a service-registration ordering issue first.
• Bundle order matters on Symfony 3. Kuma's templates and services are opinionated; registering after the Kunstmaan bundles is what lets overrides win. On Symfony 4+ bundle order is less of a lever, but template and service priority rules still apply — verify empirically.
• Pin aggressively and vendor immediately. composer require a tagged version or a SHA; then copy or fork the source. This mitigates abandonment: the repo can be archived or deleted and you lose history/issue context, but not the code.
• Extension points worth knowing: the bundle's service definitions in Resources/config/ (override via your app's services.yaml), template overrides under templates/bundles/KumaExtraBundle/, and Configuration-declared keys (override in your app's config). These three seams cover almost everything you'd need to tailor — use them rather than reaching into vendor code.
• The strategic signal outweighs the tactical value. One star, zero dependents, single agency maintainer is a data point on Kunstmaan ecosystem momentum. If your team is still on Kuma, the more useful output of this evaluation is a CMS consolidation timeline — not an adoption decision on a 1-star bundle. For a Laravel shop, that's the real takeaway: reimplement the feature inventory natively and keep ownership in-house.