Blade Cli Laravel Package

Getting Started

This package bundles Laravel's Blade compiler into a standalone CLI tool so you can render .blade.php files without booting a full Laravel app. It is archived (last release Nov 2023), so treat it as a stable-but-frozen dependency — good for one-off tooling, risky as a foundation for new long-lived products.

composer require surgiie/blade-cli

First thing to do: open vendor/surgiie/blade-cli/README.md and src/ before writing any templates. Because the repo is archived, the README is your canonical reference — trust it over any blog post or snippet you find online, and confirm the binary name and flags against bin/ or composer.json's bin section.

Typical first invocation looks like a render-and-write command (verify the exact flag names from the README):

vendor/bin/blade render templates/config.blade.php --output=build/config.php

Your first real use case should be low-stakes: rendering a config file, a README, or a scaffold from a template in a CI/script context. That exercises the pipeline (path resolution, variable passing, output writing) before you commit to it for anything generated in production.

Check the version and the archive notice in composer.json / the GitHub banner, and pin the exact tag in your composer.json so a future resolution surprise doesn't change your output.

Implementation Patterns

Template + variables as a scripted generator. The sweet spot is generating textual artifacts (configs, env files, Dockerfiles, scaffolding, docs) from a .blade.php source with a small set of interpolated values. Keep templates in a dedicated templates/ dir, keep inputs in shell variables or a JSON/env file, and render into a clean build/ or dist/ directory that you can gitignore.

Wire it into scripts, not application code. This is a build-time tool, not a runtime one. Put invocations inside a Makefile, composer.json scripts, an npm script, or a GitHub Action step — somewhere the output is reproducible and the invocation is versioned with the repo:

"scripts": {
  "build:config": "blade render templates/app.blade.php --output=config/generated.php"
}

Compose templates with @include / @extends. Blade's layout inheritance works here, so factor shared headers, license blocks, and boilerplate into partials. Test that includes resolve relative to a sensible base path early — this is the most common surprise when porting templates from a Laravel app.

Prefer explicit variable injection over globals. Don't rely on Laravel helpers (config(), env(), route(), auth()) existing at render time. Pass everything the template needs in as data, either via CLI flag or a JSON/.env-style input. Templates that read only their explicit inputs are portable and testable; templates that reach for framework state will break under this tool.

Use it as a lighter alternative to Twig/Handlebars/mustache for Laravel shops. The real value proposition is "we already know Blade." If your team writes Blade daily, this removes the context switch for text templating tasks. Do a quick cost test: if the template is trivial, envsubst or sed may be simpler and has zero dependency risk.

Snapshot-test the output. Since the tool is frozen, guard against regressions in your own templates by committing expected outputs and diffing in CI (git diff --exit-code build/). This catches both intentional template changes and accidental dependency drift.

Gotchas and Tips

Archived status is the headline. No security patches, no Laravel major-version compatibility updates, no fixes for edge cases. Before adopting, check which Laravel/Illuminate Blade version it pins as a dependency — if it lags the framework you use elsewhere, you can hit compiler behavior mismatches. Consider vendoring a fork if you need to patch.

Framework helpers are not available. Anything that depends on the Laravel container (@auth, @can, @livewire, route(), asset(), config(), env()) will fail or produce wrong output. If you need those, build a small facade shim or just don't use this tool for that template.

Custom Blade directives require registration. If your templates use @money, @datetime, or your own Blade::directive() calls from a Laravel app, they won't exist here. Either the package exposes a way to register directives (check src/ for the compiler/service provider hook) or you inline the logic into the template. Don't assume parity with your app's Blade setup.

Escaping and whitespace are Blade defaults, not "text template" defaults. {{ }} HTML-escapes by default — for non-HTML output (YAML, shell scripts, SQL) you'll want {!! !!} or @verbatim, and be aware of the @php ... @endphp block behavior and any trailing-newline trimming the compiler does. Shell scripts especially can break on stray newlines.

Path resolution is relative to CWD, not the template. When passing --output=... and template paths from inside a Makefile or CI step, prefer absolute paths or $(pwd)-anchored paths. Silent no-op writes due to a wrong relative path cost more debugging time than the tool saves.

Caching is likely off or filesystem-based. If you're rendering the same template repeatedly in a loop (e.g., N config files from one template), check whether the package exposes a cached-compiled-template flag. If not, batch in one process where possible rather than shell-looping the binary.

Debugging output issues. When a render fails or produces empty output, run with verbose flags (usually -v/-vv depending on the Symfony Console setup) and inspect the compiled PHP Blade generates before it's rendered — that's where interpolation and directive errors surface. The compiled artifact is far easier to trace than a cryptic "unexpected token" from the CLI.

Extension points are limited by the archive. You can't count on upstream accepting PRs. If you need to extend behavior, fork it, or — realistically — write a ~50-line wrapper around illuminate/view's BladeCompiler yourself. For most "render a text file from a template" jobs, the wrapper is the more durable path, and it means you own the upgrade cadence against your Laravel version.