Ux Blocks Laravel Package

Getting Started

Install and verify the version you're actually on

composer require symfinity/ux-blocks:^0.1.6

v0.1.6 is a patch release published 2026-07-05. The GitHub release body is only a pointer to CHANGELOG.md, so treat the changelog file itself as the source of truth before upgrading — read the entries for 0.1.4 through 0.1.6 rather than trusting the release title. As a patch on a 0.1.x line you should expect no breaking changes, but pre-1.0 packages are explicitly allowed to break on minor bumps, so verify rather than assume.

Where to look first, in this order

1. CHANGELOG.md at the v0.1.6 tag — the release notes here are a stub, so this is the only real record of what changed.
2. README.md — install/registration instructions.
3. config/ux-blocks.php (after publishing) — the knobs that matter day-to-day usually live here: view namespace/paths, caching, default block set.
4. src/ — for a blocks package the interesting surface is normally a service provider, a registry/manager class, and a Blade component or directive. Grep for Blade::, Component, and register to find the integration points fast.
5. resources/views/ — the shipped blocks themselves; these are your reference implementations and your override targets.

First use case

The realistic first day-one task is "render one shipped block inside an existing Blade view, then override its markup without touching vendor code." Publish assets and views first:

php artisan vendor:publish --provider="Symfinity\UxBlocks\UxBlocksServiceProvider"

(Laravel auto-discovery should register the provider; confirm with php artisan about or php artisan vendor:publish with no arguments and look for the ux-blocks tag.) Then drop a block into a template, confirm it renders, and only after that start customising. Getting the render path working before you customise saves you from debugging two things at once.

Implementation Patterns

Treat blocks as a registry, not a library of includes

The value of a blocks package is the indirection: your templates reference a name, and the package resolves that name to a view/class. Lean on that. Pass block data as an array or DTO from the controller rather than reaching into the package internals from Blade:

// Controller
return view('pages.home', [
    'blocks' => [
        ['type' => 'hero',   'data' => $heroData],
        ['type' => 'cta',    'data' => $ctaData],
    ],
]);

Then loop and render in the view. This keeps block composition data-driven, which is what makes the package worth using over plain @include.

Page-builder / CMS integration

If you're storing block definitions in the database (JSON column of {type, data} entries), validate type against the package's registered block list before rendering. An unknown type should degrade to a logged warning plus an empty render, not a 500 on a production page. Wrap the render call in a small helper of your own so every render site gets that safety net for free — and so you have one place to change when the package's API shifts under you at 0.2.0.

Overriding shipped blocks

Publish views, then customise the published copies. Prefer this over subclassing or monkey-patching: published views are a supported, documented extension point, whereas internal classes are not. Keep a short note in your repo of which published views you've modified, because vendor:publish --force during an upgrade will silently clobber them. If you need heavier customisation, register your own block under a distinct name and leave the shipped one untouched.

Testing

Blocks are view-layer, so assert on rendered output rather than mocking internals:

$this->view('components.ux-blocks.hero', ['data' => $fixture])
     ->assertSee('expected headline');

Keep one fixture per block type. That fixture set doubles as your regression check after each patch release — re-run the suite on the bump and you'll catch view-path or data-shape changes that the changelog under-documents.

Gotchas and Tips

The changelog is your only release record. Every release in this line so far has shipped a one-line "see CHANGELOG.md" body. Automate the check: diff CHANGELOG.md between your current tag and the target tag as part of the upgrade PR, not after something breaks.

Pin tightly and upgrade deliberately. ^0.1.6 allows 0.1.7+, which for a pre-1.0 package can include breaking changes under semver's 0.x rules. If you want predictability, pin 0.1.6 exactly in composer.json and bump via an explicit PR. Never let a patch release ride along inside an unrelated composer update.

Config and view caching bite in this order. After publishing config or editing views, run php artisan config:clear and php artisan view:clear. If a block renders stale markup in local dev, view cache is the first suspect; if it ignores a config change in staging, config cache is. Both are cheap to rule out and easy to forget.

Watch the published-asset surface across upgrades. Re-run vendor:publish without --force on every bump and read which files it skipped — those are the ones the package changed that you are now running stale. Any file you've customised will show up here, which is exactly the list you want.

Debugging a block that renders nothing. Work down this list: (1) is the block type registered? (2) does the resolved view path exist in resources/views/vendor/ux-blocks/ or the package's own views? (3) is the data shape what the view expects? Silent empty renders almost always mean an unregistered type or a name/path mismatch rather than a package bug. For a definitive answer, dump the registry from php artisan tinker and compare against what your template is asking for.

Extension points to prefer, in order of safety: published views → published config → your own blocks registered alongside the shipped ones → (last resort) decorating the package's manager class via the container. Anything below "published config" is unstable at 0.1.x and should be isolated behind one thin wrapper class in your app so a future minor bump only breaks one file.

Report upstream. Given how thin the release notes are, if you hit a behaviour change between 0.1.5 and 0.1.6 that isn't in the changelog, open an issue. For a 0.1.x package, the maintainer's responsiveness to that is the best available signal for whether to build on it or wrap it defensively and keep your options open.