Laravel Easyblade Laravel Package

Getting Started

EasyBlade is a thin directive layer over native Blade. There is no build step, no config file you must publish, and no runtime service to boot beyond the package's service provider.

1. Install:

   composer require rezaamini-ir/laravel-easyblade
   

   On Laravel 5.5+ the provider is auto-discovered. If you are on an older stack, add RezaaminiIr\EasyBlade\EasyBladeServiceProvider manually to config/app.php.

2. Publish the config (optional but recommended for discovery):

   php artisan vendor:publish --provider="RezaaminiIr\EasyBlade\EasyBladeServiceProvider"
   

   This gives you a place to toggle directives on/off per environment — useful so you don't leak helper syntax into a production view that another team will maintain without the package.

3. Look at the directive table in the README first. This is the whole API surface. The package's value is entirely in the list of blade directives it registers (@eif, @eelse, @eauth, @eguest, @ecan, @eisempty, @eroute, @easset, form/CSRF shorthands, etc.). There is no logic worth reading beyond that table and the EasyBladeServiceProvider/directive class that registers each one.

4. First use case: open one existing view and swap a verbose conditional for the readable form. The canonical win is turning:

   @if(auth()->check() && auth()->user()->isAdmin())
       ...
   @endif
   

   into the shorter directive the package exposes. Do this on one view in a throwaway branch, run the page, and confirm the directive is actually registered — if the directive isn't found, Blade leaves the literal string in output rather than throwing, which is the most common first-run confusion.

5. Verify it works: php artisan view:clear && php artisan serve, load the page, and view source. If you see @e... in the HTML, the provider wasn't discovered or the directive name is misspelled.

Implementation Patterns

Incremental adoption, not a rewrite. Treat EasyBlade as sugar for new code and for views you're already touching. Do not schedule a "convert all views" ticket — the diff noise is large and offers no behavioral benefit, and reviewers cannot diff directive semantics easily.

Wrap it in a team convention. Because the directives live in the global Blade namespace, decide as a team whether EasyBlade directives are the default or an opt-in. A practical rule: use the short forms for auth/guest/can checks and string conditions, keep native @foreach, @component, @livewire untouched.

Keep auth and authorization in one idiom. If the package provides @eauth, @eguest, and @ecan, standardize on those for all guard checks so you don't mix @auth('admin') and @eauth('admin') in the same file — mixed idioms are where maintainers get lost.

Use it on layouts and partials that are read often. Header navigation, sidebar menus, and card partials are read by every developer and benefit most from shorter conditionals. Reserve it there.

Integration with Blade components: you can call the directives inside a component's view like any other Blade expression, but do not try to use them inside a @php block or a class — they are compile-time Blade tokens, not PHP helpers. If you need the logic in PHP, use the underlying Laravel helper directly (e.g., Gate::allows(...)) and pass a boolean to the view.

Form-heavy admin screens are a strong fit if the package ships CSRF/method/route shortcuts: you get consistency across dozens of forms with less boilerplate, and reviewers can scan for @emethod('PUT') as a signal that a form is a real update versus a GET.

Migration workflow:

git checkout -b easyblade/resources-views
# edit 2–3 views
php artisan view:clear
# load each page, verify in browser
# run feature tests that assert the rendered HTML

Tests that assert on rendered HTML (assertSee, assertDontSee) are your safety net — they catch a directive that silently failed to compile.

Gotchas and Tips

Undefined directives fail silently. The number one bite: a typo in a directive name produces the literal @eif(...) text in the rendered page, not an exception. If a view looks wrong, view-source and search for @e before debugging anything else.

Clear the compiled view cache after any directive change. Blade compiles to storage/framework/views. After editing the package config or upgrading, always:

php artisan view:clear
php artisan config:clear

Stale compiled views are a common source of "it works on my machine."

IDE and editor support is missing. PHPStorm, VS Code, and Blade formatters don't know these directives. You'll get no autocomplete, no syntax highlighting, and formatters may re-indent blocks incorrectly. Mitigate by adding the directive names to a project blade.php custom-directive note or your team wiki; don't expect it to improve.

Global namespace collisions. Anyone can register a directive with the same name — another package or your own AppServiceProvider::boot(). If a directive misbehaves after a composer update, grep both vendor/ and app/ for the directive name. Prefer the package's e-prefixed names precisely because they're unlikely to collide.

Maintenance risk: last release was June 2023. Pin the version in composer.json ("rezaamini-ir/laravel-easyblade": "^1.0" — use the version you installed, not *), and be prepared to fork if an upcoming Laravel major breaks the provider registration. The API surface is small, so a fork is realistically a one-file change if needed.

Don't let it replace components. A short directive is not a substitute for x- Blade components or Livewire when you need reusable markup with its own state. EasyBlade is about readability, not composition; using it to fake components leads to copy-pasted logic.

Debugging tip: if a directive renders but behaves oddly, look at the compiled file in storage/framework/views/*.php. The compiled PHP shows exactly what the directive substituted — that's the ground truth, not the directive source.

Config quirks: if the config file exists, check whether directives are enabled per-environment. A freshly published config that defaults to "off" or "local only" in production is a classic post-deploy surprise. Diff the published config against the package default before shipping.

Extension points: the natural extension is to register your own directives in AppServiceProvider::boot() using Blade::directive('yourname', fn ($expr) => "...") — use EasyBlade's directive implementation as a reference for the escaping/echo pattern, then keep your app-specific directives out of vendor/.