Artisan Ui Laravel Package

Getting Started

April UI is a Laravel UI toolkit: the two fixes in v1.3.6 confirm it ships (a) an asset-registration layer that injects script/style tags into rendered views, and (b) a table builder with server-side sorting driven by the request. Start there.

1. Install and publish

   composer require yungifez/april-ui
   php artisan vendor:publish --tag=april-ui-config
   php artisan vendor:publish --tag=april-ui-assets
   

   Laravel package discovery registers the service provider; only add it manually if you have discovery disabled.

2. First places to look

   • config/april-ui.php — asset groups, table defaults, sort parameter names.
   • The Blade layout/directive that emits April UI's asset tags (the thing changed in #68).
   • The table builder class used in your controllers/Livewire components (the thing changed in #69).

3. First use case — a sortable listing Render a table through the builder, mark a column sortable(), and let the request drive the sort:

   return AprilTable::make(User::query())
       ->column('name')->sortable()
       ->column('created_at')->sortable()
       ->defaultSort('created_at', 'desc');
   

   Click the column header; the query string should carry the sort key/direction and the builder should apply it. That is the single workflow most of this package's day-to-day value flows through.

Implementation Patterns

Asset registration per request Since v1.3.6 the tag list is evaluated on each request rather than baked into the compiled Blade view. Use that:

// AppServiceProvider::boot()
AprilUI::assets()->register('charts', resource_path('js/charts.js'));

This now works even when views are cached (php artisan view:cache), which is the normal production state. Prefer registering in a service provider or a dedicated AssetServiceProvider over doing it inside controllers, so the ordering is deterministic.

Conditional bundles

if (request()->routeIs('reports.*')) {
    AprilUI::assets()->register('reports', ...);
}

Per-request evaluation means environment- or route-specific bundles no longer require a view-cache clear between deploys.

Table sorting workflow

• Define columns once; mark only the ones users may sort.
• Set a default sort for the unfiltered view.
• Keep the sort parameter whitelisted (column name + asc|desc) — never forward raw query input into orderBy.
• For paginated tables, always append the current sort to pagination links so page 2 keeps the same ordering.

Livewire / SPA-ish flows Because assets are rebuilt per request, components that mount later (modals, tabs, lazy-loaded widgets) can register their own assets without stale tags. If you render fragments via AJAX, ensure the fragment response includes the asset tags — the per-request behaviour is what makes this correct.

Deterministic defaults Where you need a guaranteed order independent of user interaction (e.g. exports, API responses reusing the builder), call the ordering explicitly on the underlying query rather than relying on the builder's default, which user sort can now override.

Gotchas and Tips

Sort precedence changed in 1.3.6 (#69). The user-selected sort is now applied before the builder's own orderBy, so the chosen sort wins. Two consequences:

• If you previously set a default order and assumed it would override a user's sort, results will differ after upgrading. Audit any builder where you added ->orderBy() after the builder's sort to "force" an order.
• If you need a hard ordering (e.g. pinned records first), do it in a way that survives this — e.g. a computed rank column the user cannot sort, or re-apply the constraint after the builder resolves the query.
• Add a stable tiebreaker (usually the primary key) when sorting by non-unique columns, otherwise pagination can duplicate or skip rows between pages.

Asset tags are no longer frozen at compile time (#68). Upgrade benefits:

• No more php artisan view:clear after changing which assets are registered.
• view:cache in CI/deploy no longer produces stale asset URLs. Costs and caveats:
• The tag list is recomputed per request; keep registration logic cheap and side-effect free. Don't hit the filesystem or DB inside an asset callback if you can resolve it once in a config/provider.
• Guard against double registration — registering the same handle in both a provider and a middleware will now emit duplicate tags on every request instead of being masked by the compiled view.
• If you were relying on the old compile-time snapshot to "freeze" assets for a long-running process, verify behaviour under Octane; per-request evaluation should be fine, but confirm no request-scoped state leaks between workers.

Debugging the table sort

• Dump the final SQL (->toSql() / DB::listen) to confirm which orderBy won. This is the fastest way to diagnose a post-upgrade ordering change.
• Check the configured sort parameter name before assuming the UI is broken — a mismatched query key silently falls back to the default sort.
• Validate direction case-insensitively; reject anything that isn't asc/desc.

Debugging assets

• If tags are missing, confirm the layout actually calls the April UI asset directive and that the provider runs after your registration.
• If tags are duplicated, you have two registration paths for one handle.
• If URLs look stale, check config/april-ui.php for a cached manifest/version key; the per-request fix covers view compilation, not your own cached config values.

Extension points Prefer the package's registration and builder APIs over overriding published views: view overrides are exactly the layer whose compile-time caching caused the original bug, and they will not receive the per-request asset behaviour automatically. Keep overrides thin — a wrapper component around the table builder or a small service provider for assets ages better than a forked Blade file.