Block Bundle Laravel Package

Getting Started

First, calibrate what you are looking at. rz/block-bundle is a Symfony 2/3 bundle (RZBlockBundle, Resources/config/ layout, Doctrine entities, tagged services, compiler passes). It is not a Laravel package and will not composer require cleanly into a modern Laravel app. It is archived, has zero stars, zero dependents, and no upstream. A Laravel developer therefore has exactly two realistic entry points:

1. Legacy Symfony maintenance — you inherited an RZ Project CMS install and need to add or change a block type without breaking things. You will be working inside Symfony conventions, not Laravel ones.
2. Reference/fork — you are building a native Laravel block/region system and want to lift the data model and registry pattern. This is the path most Laravel devs should take.

If you are maintaining a legacy Symfony install, in this order:

1. Register the bundle in config/bundles.php (or AppKernel::registerBundles() on older Symfony) as new RZ\BlockBundle\RZBlockBundle().
2. Open DependencyInjection/Configuration.php first. This — not the README — is the authoritative options list. The block and block-type entity class parameters are meant to be overridden with your own subclasses; do not assume the defaults fit.
3. Run bin/console doctrine:schema:update --dump-sql and read the SQL before applying. You expect a block table plus a block-type/discriminator column. Empty output means your mapping configuration is wrong, not that the schema is fine.
4. Read these directories in order: Block/ (manager + interfaces), BlockType/ (the extension point), DependencyInjection/Compiler/ (how block types are collected), Resources/views/ (Twig surface), Resources/config/ (service wiring and tags). That is a ~1 hour read and it will teach you more than any doc that ever existed.

Your first end-to-end loop (the real "hello world"): create a concrete block type class extending the bundle's abstract type, register it as a service with the block-type tag, create a block record through the manager, assign it to a zone string, and render that zone from a Twig template. When that renders, you understand the bundle.

If you are reimplementing in Laravel (recommended): clone the repo, read composer.json for the PHP/Symfony/Doctrine constraints, then read the block-resolution logic in Block/ and the block-type registry in BlockType/. Your deliverable is a written spec (block type contract, zone model, caching strategy), not a dependency. Sequence it as: spike (read + spec) → data model + registry contract in Eloquent → Blade renderers → cache layer → admin authoring → pilot on one content surface.

Implementation Patterns

Symfony-side patterns (if you're in the legacy install):

• Block types are tagged services. One class per content shape (text, image, teaser, menu), each declaring a name and a form type. A compiler pass collects them into a registry. Adding a block type is: new class + new form type + one service definition + one Twig template. No core edits — preserve that discipline.
• The manager is the only write path. Do not inject the EntityManager for block writes. Go through the block manager for create, save, and zone lookups so events, timestamps, and cache hooks stay consistent. Repository is fine for read-only queries.
• Zones are strings, not entities. Blocks carry a zone/position discriminator. This is simple but turns zone names into a de-facto schema. Define zone constants in exactly one class and reference them from both PHP and Twig — never repeat string literals across templates.
• Render through the bundle's Twig extension / function, not by hand-querying blocks into a template. The extension is where caching and block-type dispatch live.

Laravel-side patterns (reimplementation — the pattern worth stealing):

• Registry contract, not convention. Bind a BlockTypeRegistry interface in a service provider; block types register explicitly (a compiler pass analogue is a provider boot() loop or a config array). Avoid auto-resolving block types by string class name — it is the source of silent-failure bugs in the original.
• Eloquent over Doctrine. Model the same concepts — blocks, block_types, zone/placement column, ordering, visibility — in one or two tables with a polymorphic payload column (JSON) per block type. Keep the type descriptor as a string key, not an entity relation.
• Rendering via Blade renderers, one per type. Mirror Resources/views/ but as a render(Block $block): View method on each block type class, so a missing template is a typed error, not a null.
• Caching is design-in, not bolt-on. Per-page rendering of N blocks is where these systems fall over. Cache the rendered fragment keyed by block:{id}:{updated_at} and tag it by zone (or key-prefix by zone) so a shared block edit invalidates every page region that renders it. Laravel's cache tags (Redis/Memcached) map almost 1:1 onto the block/zone model.
• Admin authoring is its own surface. Blocks are edited in an admin UI (Sonata admin in the original). Plan a separate form/field mapping per block type — the block type class owns its form schema, the manager owns persistence, the renderer owns output. Keep those three concerns apart so a new type never touches the manager or the dispatcher.

Gotchas and Tips

• It is not a Laravel package. The *Bundle suffix, rzproject vendor, compiler-pass wiring, and Doctrine coupling all point away from Laravel. Do not try to shoehorn it in via a service provider — you will spend more time shimming than the model is worth. Fork or reimplement.
• Archived means you own it. No security patches, no PHP version tracking, no issue triage. Any code you vendor is code you maintain. Verify the license before copying anything — archived repos frequently omit one.
• Do not trust the opportunity score. The high score reflects that lightweight content-block tooling is underserved, not that this package is viable. Every community-health signal (stars, dependents, activity) contradicts it.
• Silent render failure is the classic bug. A block whose type is unregistered, or whose template is missing, will typically render empty rather than throw. Make your reimplementation fail loudly — throw on unknown block type, throw on missing renderer. Debugging a blank zone in the original means checking, in order: is the service tagged? is the compiler pass output in the container (debug:container --tag=rz_block.block_type on Symfony)? is the template in the expected Resources/views/ path? is the block actually assigned to the zone string you're rendering?
• Zone names are schema. Renaming a zone string orphans every block pointing at it with no migration tooling in the bundle. Treat zone names like database columns: constants, reviewed changes, migration plan.
• Doctrine entity coupling is the hidden migration cost. The block model is likely welded to the RZ Project entity schema. Assume the storage layer is not portable and plan to rebuild it, not move it.
• Unknown PHP support range. An archived Symfony 2/3 bundle plausibly predates PHP 8.1+ and will emit deprecations or fail on current runtimes. Check composer.json before assuming anything runs.
• Retired block types leave orphans. No migration tooling for block instances whose type was removed. Before removing a type in your own system, plan a backfill/cleanup — the bundle does not.
• Debugging tip for the original: when a block does not appear, debug:container for registered block types and the rz_block.* service ids first. This tells you whether the problem is registration, dispatch, or templating — three completely different fixes that look identical in the browser.
• Extension points worth preserving in a reimplementation: the block-type registry (add content shapes without core edits), the manager write path (centralize persistence + events), the renderer-per-type contract (typed failure), and the zone discriminator (grouping without a heavy entity model). Everything else — Doctrine, compiler passes, Sonata admin wiring — is Symfony-shaped and does not translate.
• One-week spike is enough. Small codebase, well-understood domain. Budget a spike to produce a spec and a build-vs-buy recommendation; do not budget an integration.