Block Bundle Laravel Package

Getting Started

Framework reality check first. The Bundle suffix and DependencyInjection/ + Resources/config/ layout are Symfony conventions. There is no extra.laravel block and no service provider to auto-discover, so composer require alone will not wire it into a Laravel app. Two realistic paths:

1. Symfony host — install and enable it as a real bundle (steps below).
2. Laravel host — treat it as a plain Composer library: instantiate the block manager yourself and skip everything that assumes a Symfony kernel. Confirm from the source that the manager class does not type-hint ContainerInterface, EventDispatcherInterface, etc. If it does, this is effectively a fork job.

Install (both cases). Register the Bitbucket repo explicitly and pin to a commit — the repo publishes no tags, so dev-master will silently drift:

{
    "repositories": [
        { "type": "vcs", "url": "https://bitbucket.org/eactive/integrated-block-bundle.git" }
    ],
    "require": {
        "integrated/block-bundle": "dev-master#<sha>"
    }
}

For private access, put a Bitbucket app password in COMPOSER_AUTH or use the SSH URL. In CI, confirm the token is scoped to read this repo — a rotated-too-narrow token breaks installs with a confusing "not found" rather than "unauthorized."

Enable (Symfony only).

// config/bundles.php
Integrated\BlockBundle\IntegratedBlockBundle::class => ['all' => true],

Then dump the real config tree rather than guessing YAML keys — Configuration.php is the source of truth:

bin/console config:dump-reference integrated_block
bin/console debug:container --parameters | grep -i block

Where to look first, in this order:

1. README.md — installation snippet, any Twig helper example.
2. composer.json — type, require (PHP/Symfony constraints decide whether it even installs on your stack), autoload.
3. DependencyInjection/Configuration.php — the actual config keys.
4. Resources/config/services.* — service IDs and any public: true aliases you can inject.
5. Entity/ or Model/ — the persisted block shape.
6. Twig/ — the extension class. Read the method signature; do not assume the function is called integrated_block().

First use case. Render a named block inside a layout so editors can change copy without a deploy:

{# templates/base.html.twig #}
<footer>
    {{ integrated_block('footer_legal') }}
</footer>

Insert the block record (fixture, admin form, or a console command if the bundle ships one), clear cache, confirm HTML output. That round-trip — key → repository lookup → template render → HTML — is the whole mental model; everything else is a variation.

Implementation Patterns

Wrap the manager in your own provider. With zero dependents and no upstream release cadence, keep the blast radius to a single class so a fork or replacement only touches one file:

final class ContentBlockProvider
{
    public function __construct(private BlockManagerInterface $blocks) {}

    public function html(string $key): string
    {
        try {
            return $this->blocks->render($key) ?? '';
        } catch (\Throwable $e) {
            report($e);
            return '';
        }
    }
}

The null-object fallback matters: a missing block should render empty, not throw a 500 on the footer of every page.

Per-block-type templates. Blocks normally carry a type that maps to a template. Override the bundle's templates at the app level (Symfony's templates/bundles/IntegratedBlockBundle/... convention) rather than editing vendor code — an override directory survives a composer update / fork refresh; an in-place edit does not.

Custom block types via the documented extension point. Most implementations of this pattern expose an abstract base class or a tagged service for block types. Check Resources/config/services.* for a tag (e.g. integrated_block.type) before inventing your own registry:

# config/services.yaml
App\Block\PromoBannerBlock:
    tags: ['integrated_block.type']   # verify the exact tag name

If no tag exists, that is a signal the extension surface is thinner than the README implies — plan accordingly.

Seed blocks as data, not code. Block content lives in the database, so treat it like content: fixtures for local dev, and a versioned seed/import for staging and production so a fresh environment is not empty. Do not hand-create rows in prod.

Cache deliberately, invalidate on save. Rendering is a DB hit per block; a footer with six blocks is six queries on every request. Cache the rendered HTML keyed by block key + updated timestamp. Wire invalidation into whatever save path you control (an event listener on the block entity's postUpdate, or a manual clear in the admin controller) — the bundle is unlikely to do this for you.

Feature-flag the integration. Put block rendering behind a flag so a broken upgrade degrades one region of the page, not the whole site.

Gotchas and Tips

No semver tags — pin to a SHA. dev-master is the trap. Every CI run can pull different code. Once the spike proves useful, fork into an internal namespace and reference that; Bitbucket availability (SSO changes, token rotation, archival) should not be on your deploy critical path.

License is unverified. Read it before a single line lands in the repo. "Internal or abandoned" is the likely story given zero stars and zero dependents — which also means you cannot expect BC guarantees or security fixes.

schema:update will hurt you. If the bundle ships Doctrine entities, always generate and review a migration; never let doctrine:schema:update touch a real database. Block tables accrete content, and an unreviewed schema diff on populated block rows is an expensive afternoon.

Watch for N+1 on block resolution. Block systems commonly lazy-load per block. Benchmark a page with realistic block counts, and log queries (doctrine.dbal.logging locally, or Telescope/Clockwork if you have bridged it into a Laravel app). One query per block per request adds up fast on high-traffic layouts.

Missing-block behaviour is usually an exception, not null. Test the empty case explicitly before shipping — a deleted block key should not blank the page.

Twig function signature is not documented. Read Twig/*Extension.php. Args may be (string $key), (string $key, array $params), or an object. Guessing produces a Too few arguments error that points at your template, not the bundle.

Config keys may not match the README. Older bundles drift. config:dump-reference beats documentation every time. Similarly, service IDs may be private in newer Symfony — inject by type-hint via autowiring rather than $container->get('integrated_block.manager').

Cache clearing is required after config or template changes (bin/console cache:clear). If output looks stale, clear cache before debugging the bundle.

If you fork, set up CI and a changelog on day one. There is no upstream to lean on. Budget recurring time for framework-major upgrades and transitive dependency updates, and name an owner — an orphaned fork behind a load-bearing feature is the worst outcome of this whole evaluation.

The cheap exit is early. If the spike cannot establish a license, an owner, and a working render in the sandbox within a day or two, stop and price the in-house alternative: a blocks table (key, type, content, updated_at) plus a Twig/Blade helper is a few hours of work and zero long-term dependency risk.