Basic Blocks Laravel Package

Getting Started

Pin the version before you install. There is exactly one release note in evidence (v1.6.0), so nothing documents supported php, laravel/framework, or bagisto/* constraints. Install explicitly rather than floating:

composer require bagistoplus/basic-blocks:1.6.0

Then open the package's own composer.json and check the constraints against your storefront before merging to a shared branch. This takes two minutes and is the difference between a clean install and a broken CI matrix.

Read the service provider before the README. The package description ("simple, framework-friendly API", "simple block registration") describes intent, not mechanics. Open src/Providers/*ServiceProvider.php and answer three questions up front:

1. Does it auto-discover and register block types, or is there an explicit registration step?
2. What is publishable — config, resources/views, database/migrations — and under which tags?
3. Is there a block registry (a config array or a container singleton you extend), or is each block a standalone class?

The answer to (3) determines your entire extension strategy later.

Publish selectively, by tag:

php artisan vendor:publish --tag=basic-blocks-config
php artisan vendor:publish --tag=basic-blocks-views

If those tags don't exist, read the provider for the real tag names. Do not fall back to --provider and publish everything blindly — you will dump views into your theme that you then have to track as overrides forever, and you'll silently clobber them on the next publish.

Look here first, in this order:

• resources/views/ — the block partials. This is the render path and the surface every theme override touches. Read the category banner partial line by line before anything else.
• The category banner block class — specifically how it resolves its category. That one method answers the FK/polymorphic/pivot question and determines whether multi-store is even viable.
• database/migrations/ — if present, read them. You need the exact columns (store_id, locale, position, is_active) before you design anything around them.

First use case (do this, not a demo page): wire the category banner onto one non-production category, confirm it renders, then disable the block and confirm the existing category image falls back cleanly. The fallback is the acceptance criterion, not the happy path — because the fallback is what keeps your other 4,000 categories working during rollout.

Implementation Patterns

Always render through a fallback. The block is a replacement layer, not a source of truth:

@php($banner = $category->bannerBlock ?? null)

@if ($banner)
    @include('basic-blocks::blocks.category-banner', ['block' => $banner])
@elseif ($category->image)
    <img src="{{ asset($category->image) }}" alt="{{ $category->name }}">
@endif

Wrap whatever the package gives you. Untouched categories must keep working through the entire rollout — this is the cheapest insurance you'll buy on this dependency.

Compose, don't duplicate. The package's whole value proposition is that blocks are data. The moment you copy a block partial into your theme to "just change the wrapper," you've re-created the hard-coded-template problem with extra steps and broken the upgrade path. Override by extending or including the namespaced view, or register a new block type that reuses the field schema.

Register your custom blocks alongside, not instead. Anything commerce-specific the library doesn't ship yet — product-listing hero, per-category promo strip, seasonal countdown — belongs in a small internal package that depends on this one. That keeps your customisations upgradeable and makes "block library plus a thin internal layer" a real architecture instead of a slide.

Cache the resolution; invalidate on save. Blocks are cheap queries but they land on your highest-traffic category pages:

// Observer on whatever model backs the block
public function saved($block)
{
    Cache::forget("category:{$block->category_id}:blocks");
}

If the package doesn't ship an observer, write one. The "swap a banner without a deploy" selling point is only real if save → render is immediate.

Treat multi-store as unverified until proven. Before you enable editors on a marketplace or multi-channel storefront, check whether the block record carries store_id. If it doesn't, a banner authored for one channel silently appears on all of them — that's a content bug that takes a week to diagnose, not a feature gap.

Keep a one-file override inventory. List every published view path in your theme's README. v1.6.0 shipped two blocks in a single release, which is a decent signal that more are coming; that list becomes your upgrade checklist.

Write the three-case regression test now. With no visible test suite in the package, you own this:

public function test_category_page_with_block() { /* renders block partial */ }
public function test_category_page_without_block() { /* falls back to image */ }
public function test_category_page_with_disabled_block() { /* falls back, no partial */ }

Thirty minutes of work that converts an unpinned third-party risk into a managed one. Run it before and after every upgrade.

Gotchas and Tips

Verify the association before you extend it. Whether a block binds to a category via FK, polymorphic relation, or pivot changes everything downstream — whether one banner can serve multiple categories, and whether deleting a category orphans block rows. Read the migration; never infer from the class name.

View namespacing is the highest-friction item in the package. Confirm the provider uses loadViewsFrom with a namespace (basic-blocks::) rather than publishing views straight into your theme path. If it publishes by default, every vendor:publish risks dropping your overrides — prefer the namespaced include and override at a higher-priority path in your own theme.

Cache invalidation is the failure mode that kills adoption. If you can't demonstrate that saving a banner updates the category page within a few seconds, merchandising loses trust on day two and goes back to filing tickets. Test this before the pilot, not after the first complaint.

Watch for storefront-unscoped queries. Packages aimed primarily at the admin/editor surface sometimes resolve blocks without applying channel scope. Grep the resolution method for where('store_id', ...) or equivalent; if it's missing, add a local scope rather than patching the vendor file.

Extension points, ranked by safety:

1. Register your own block types — safest, no coupling to internals.
2. Override published views — safe with an inventory.
3. Extend the block registry class — fragile across minor versions.
4. Patch the vendor file — never. You will rediscover it mid-upgrade at the worst possible moment.

Debugging tip: dump the resolved block, not the view. When a banner doesn't appear, the failure is almost always in resolution (wrong category, wrong store, relation not loaded) rather than in Blade. dd($category->bannerBlock) before you touch the template.

Scope discipline. This is a block library, not a page builder. It does not give you scheduling, editorial approval, localisation governance, or asset management. The moment a stakeholder asks for any of those, say so explicitly and estimate them separately — the fastest way to make this dependency go stale is to load it with expectations it was never designed to carry.

Release cadence is your real risk metric. Two additive blocks in one release is a healthy signal, but it's one data point. Before each upgrade cycle, check commit activity, issue response time, and whether the prior notes flagged BC breaks. Zero dependents and negligible stars mean you should decide now whether you're willing to become the de facto maintainer of your own fork — because with a package in the critical path of high-traffic pages, that's a real possibility, not a hypothetical.