Block Laravel Package

Getting Started

litecms/block is a LiteCMS-specific content-block package, so the entry point assumes you already have a LiteCMS/Lavalite application running. If you're on plain Laravel, stop here — a blocks table plus a Blade component will be cheaper than pulling in the whole CMS core.

Install and orient:

composer require litecms/block
php artisan vendor:publish --provider="Litecms\Block\BlockServiceProvider"
php artisan migrate

Prefer explicit publish tags (--tag=block-config, --tag=block-migrations) over a blanket publish so you don't clobber sibling LiteCMS package config.

Read these three files first (in this order):

1. vendor/litecms/block/src/BlockServiceProvider.php — find the binding, the facade, any Blade directives (directive(), view namespace, and the published config/migration tags.
2. vendor/litecms/block/config/block.php — table name, cache TTL, block types, regions, route prefix, middleware.
3. vendor/litecms/block/database/migrations/ — the actual schema (slug, name, content, type, status, region, order are the usual suspects).

First use case — create a block in the admin panel (or seed one) and render it in a Blade view. Most LiteCMS content packages expose either a directive or a facade; check the provider before guessing:

{{-- if the provider registers a directive --}}
@block('homepage-hero')

{{-- if it exposes a facade --}}
{!! \Litecms\Block\Facades\Block::render('homepage-hero') !!}

Grep the provider for directive(, Blade::, Facade, or render/findBySlug on the model to confirm which one this package actually gives you. Don't assume the docs description ("helpers and directives") matches the implementation — it's a small, low-maintenance package; verify against source.

Implementation Patterns

Treat blocks as keyed content fragments and render defensively. The pattern you'll use most:

$block = \Litecms\Block\Models\Block::where('slug', 'footer-cta')
    ->where('status', 'published')
    ->first();

echo $block?->content;

Wrap this in a single helper or Blade component so the query, the status filter, and the fallback live in one place — not repeated across every template.

Centralize rendering behind your own interface. Don't let templates call Block::render() directly everywhere. A thin service (App\Support\BlockRenderer) that does lookup → cache → sanitize → fallback means you can swap the package out later without touching views. This is the single most valuable habit with an unmaintained dependency.

Cache at render time. If the package does a per-block query on every render, page assembly becomes N+1 as blocks-per-page grows. Cache keyed on slug + updated_at:

Cache::remember("block:{$slug}:{$block->updated_at}", 3600, fn() => $block->content);

Invalidate on save via a model observer, or rely on the updated_at in the key so stale entries fall out naturally.

Region/slot composition. For layout regions (header promo, sidebar, footer), iterate a region rather than hardcoding slugs:

@foreach(\Litecms\Block\Models\Block::where('region', 'footer')->orderBy('order')->where('status', 'published')->get() as $block)
    @include('blocks.'.$block->type, ['block' => $block])
@endforeach

Testing. Add tests around your usage — a block renders, a missing block falls back safely, a malformed payload doesn't throw. You're effectively writing the test suite the package doesn't ship.

Gotchas and Tips

Zero traction means you own every bug. No dependents, no issue history, no downstream code to copy. Budget ~5–10% of an engineer for dependency bumps and Laravel upgrade compatibility from day one. Fork into a path repository or private VCS and record the upstream commit SHA for provenance.

Watch the version constraints. LiteCMS-lineage packages pin tightly to framework majors. Check composer.json for illuminate/* and any litecms/core constraint against your installed versions before the spike — a mismatched Laravel major will strand you.

Namespace collisions are silent, not loud. Config and view namespaces in this ecosystem frequently collide with sibling packages (page, menu, settings). Symptoms surface as wrong-view-rendered bugs rather than errors. If a published view isn't yours, check namespace registration order.

Malformed JSON payloads can take down a page. If content is stored as JSON with thin validation, one bad editor save throws at render. Always wrap rendering in try/catch with a log-and-skip fallback — degrade the region, don't kill the page.

XSS surface is real if raw HTML is allowed. Sanitize at render ({!! !!} is the warning sign) and restrict block authoring to trusted roles. Audit what content actually holds.

Orphaned embeds on delete. A block deleted without cascading to regions/templates leaves broken renders. Verify foreign-key behavior explicitly; add a soft-delete or a "in use" guard if deletes are exposed to editors.

Asset path breakage on redeploy. If assets publish to a fixed path and vendor:publish is skipped in your deploy pipeline, styles/scripts 404 silently. Make the publish step explicit in deploy scripts.

Upgrade drift on core. A LiteCMS core upgrade that changes model or menu conventions will break this package quietly. Pin core, run upgrades in isolation against a scratch DB, and re-run your usage tests before touching staging.

Extension points are thin — plan to fork. Expect your customization surface to be: config values, model observers, and publishing/overriding views. Anything deeper (validation, caching, sanitization) will be your code, not a hook the package provides. Accept that and design your wrapper interface to absorb it.