Blaze

https://github.com/livewire/blaze
Admin
Blaze is a Laravel package that optimizes Blade component rendering by compiling templates into...
Tokens:98,995
Snippets:778
Trust Score:9.2
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Direct Memo API usage

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/memoizer.md

Example of using Memo::key, has, put, get, forget, and flushState directly for custom caching wrappers.

```php
use Livewire\Blaze\Memoizer\Memo;

// Direct API use (e.g. custom caching wrappers):
$key = Memo::key('icon', ['name' => 'check']);
if (! Memo::has($key)) {
    Memo::put($key, $html);
}
echo Memo::get($key);

Memo::forget($key);
Memo::flushState();
```

--------------------------------

### compileForUnblaze() Usage Example

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/blaze.md

Example of calling compileForUnblaze() via the 'blaze' container to compile an icon component.

```php
$compiled = app('blaze')->compileForUnblaze('<x-icon :name="$name" />');
```

--------------------------------

### Factory usage example

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/runtime.md

Shows how the factory is called inside a compiled component function.

```php
$attributes = BlazeAttributeBag::make($__data, $__bound, $__keys);
// Wrapper emits exactly this line inside every compiled component function.
```

--------------------------------

### Install Blaze via Composer

Source: https://github.com/livewire/blaze/blob/main/README.md

Install the Blaze package using Composer. Requires Laravel and PHP compatible with the package.

```bash
composer require livewire/blaze:^1.0
```

--------------------------------

### Install and publish Blaze package

Source: https://github.com/livewire/blaze/blob/main/_autodocs/configuration.md

Run these commands to require the package, publish its configuration, and clear the view cache after any configuration change.

```bash
composer require livewire/blaze:^1.0
php artisan vendor:publish --tag=blaze
php artisan view:clear   # required after any configuration change
```

--------------------------------

### compile() Usage Example

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/blaze.md

Example of calling compile() via the 'blaze' container to compile a Blade component with a file path.

```php
$compiled = app('blaze')->compile('<x-button type="submit">Send</x-button>', resource_path('views/page.blade.php'));
```

--------------------------------

### Enable different optimization strategies per folder

Source: https://github.com/livewire/blaze/blob/main/README.md

Pass strategy arguments like memo: true or fold: true to ->in() to enable different strategies for different directories. The example enables memoization for icons and folding for cards.

```php
Blaze::optimize()
    ->in(resource_path('views/components/icons'), memo: true)
    ->in(resource_path('views/components/cards'), fold: true);
```

--------------------------------

### Usage of shouldFold()

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/config.md

Example of checking if a file is eligible for folding using the config singleton.

```php
$config = app('blaze.config');

if ($config->shouldFold($path)) {
    // file is eligible for folding
}
```

--------------------------------

### Usage example for isDisabled and optimize

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/blaze.md

Shows how to conditionally render with standard Blade when Blaze is disabled, and how to configure optimization for a specific directory with compile disabled.

```php
if (Blaze::isDisabled()) {
    // Render with standard Blade
}

Blaze::optimize()->in(resource_path('views/components/legacy'), compile: false);
```

--------------------------------

### Using Directives to query @blaze, @props, and @aware

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/support.md

Example usage of the Directives class: checks for @blaze, retrieves 'fold' and 'safe' parameters, and gets props variable names.

```php
$directives = new Directives(file_get_contents($path));

if ($directives->has('blaze')) {
    $fold = $directives->blaze('fold');      // bool|null
    $safe = $directives->blaze('safe');      // array|null
    $props = $directives->props();            // ['type', 'label']
}
```

--------------------------------

### Usage inside compiled component

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/runtime.md

Example of creating a bag and using merge() and class() methods.

```php
// Inside a compiled component:
$attributes = BlazeAttributeBag::make($data, $bound, $keys);

echo $attributes->merge(['type' => $type]);
echo $attributes->class(['bg-red-500' => $active, 'btn', 'text-sm']);
```

--------------------------------

### AttributeParser parse() usage example

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/support.md

Shows how to call parse() with a sample attribute string and the resulting array structure, including dynamic and valueless attributes.

```php
$attrs = $attributeParser->parse('type="submit" :id="$id" data-foo');

// => ['type' => Attribute(...), 'id' => Attribute(dynamic: true), 'dataFoo' => Attribute(valueless: true)]
```

--------------------------------

### UseExtractor::extract usage example

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/compiler.md

Example of calling extract with a callback that collects use statements into an imports string. The callback receives each statement and appends it with a newline.

```php
$compiled = $useExtractor->extract($compiled, function ($statement) use (&$imports) {
    $imports .= $statement . "\n";
});
```

--------------------------------

### Optimize multiple directories with Blaze::optimize()

Source: https://github.com/livewire/blaze/blob/main/README.md

Chain multiple ->in() calls to optimize several directories at once. The example optimizes the 'button' and 'modal' subdirectories.

```php
Blaze::optimize()
    ->in(resource_path('views/components/button'))
    ->in(resource_path('views/components/modal'));
```

--------------------------------

### Usage of in() with chaining

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/config.md

Example of registering multiple paths with different optimization flags using Blaze::optimize()->in().

```php
Blaze::optimize()
    ->in(resource_path('views/components'))
    ->in(resource_path('views/components/legacy'), compile: false)
    ->in(resource_path('views/components/icons'), memo: true)
    ->in(resource_path('views/components/cards'), fold: true);
```

--------------------------------

### DirectiveCompiler usage example

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/compiler.md

Example of using DirectiveCompiler to compile custom directives. It chains directive registrations for 'props' and 'aware' and then compiles a template.

```php
$out = DirectiveCompiler::make()
    ->directive('props', $propsCompiler->compile(...))
    ->directive('aware', $awareCompiler->compile(...))
    ->compile($compiled);
```

--------------------------------

### Blaze::optimize() with fold and memo options

Source: https://github.com/livewire/blaze/blob/main/UPGRADING.md

Configure optimization strategies in a service provider using Blaze::optimize(). The example shows enabling fold for one directory and memo for another.

```php
Blaze::optimize()
    ->in(resource_path('views/components'))
    ->in(resource_path('views/components/ui'), fold: true)
    ->in(resource_path('views/components/icons'), memo: true);
```

--------------------------------

### GET /_blaze/traces

Source: https://github.com/livewire/blaze/blob/main/_autodocs/endpoints.md

Fetches a list of profiler traces. The response is JSON.

```APIDOC
## GET /_blaze/traces

### Description
Fetches a list of profiler traces. The response is JSON.

### Method
GET

### Endpoint
/_blaze/traces

### Response
#### Success Response (200)
Returns a JSON array of trace objects. Each trace object contains fields such as `url`, `mode`, `timestamp`, `renderTime`, `entries`, `components`, and `debugBar`.

#### Response Example
```json
[
  {
    "url": "/dashboard",
    "mode": "blaze",
    "timestamp": "2024-01-01T12:00:00+00:00",
    "renderTime": 3.21,
    "entries": [],
    "components": [],
    "debugBar": {}
  }
]
```
```

--------------------------------

### BladeService usage example (internal pipeline)

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/blade-service.md

Shows how to resolve a component name to a path, preprocess an attribute string as Laravel's tag compiler would, and compile an attribute into a PHP array entry. The compileAttribute method returns a string like "'id' => Str::random(), 'class' => 'btn'".

```php
// Resolve a component and read its directives:
$path = $bladeService->componentNameToPath('x-button');

// Preprocess an attribute string as Laravel's tag compiler would:
$processed = $bladeService->preprocessAttributeString(':id="Str::random()" class="btn"');

// Compile an attribute into a PHP array entry:
$entry = $bladeService->compileAttribute($attribute);
// => "'id' => Str::random(), 'class' => 'btn'"
```

--------------------------------

### Enable Blaze for entire directories in AppServiceProvider

Source: https://github.com/livewire/blaze/blob/main/README.md

Call Blaze::optimize()->in() in the boot method of AppServiceProvider to enable Blaze for all components in the specified directory. The example includes the use statement and a comment.

```php
use Livewire\Blaze\Blaze;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Blaze::optimize()->in(resource_path('views/components'));

    // ...
}
```

--------------------------------

### Default slot pass-through example

Source: https://github.com/livewire/blaze/blob/main/resources/boost/skills/blaze-optimize/references/folding-safety.md

Shows a default slot with dynamic content, which is safe for folding because slots are replaced with placeholders and restored afterwards.

```blade
<x-button>{{ $dynamicLabel }}</x-button>
```

--------------------------------

### Blade usage example

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/memoizer.md

Blade component usage that triggers memoization when @blaze(memo: true) is set.

```blade
<x-icon :name="$status->icon" />
```

--------------------------------

### GET /_blaze/traces

Source: https://github.com/livewire/blaze/blob/main/_autodocs/endpoints.md

Lists recent traces (newest first, up to 20) with summary metadata. No request parameters.

```APIDOC
## GET /_blaze/traces

### Description
Lists recent traces (newest first, up to 20) with summary metadata. No request parameters.

### Method
GET

### Endpoint
/_blaze/traces

### Response
#### Success Response (200)
- **id** (string) - ULID filename without extension (usable as `?id=` on `/ _blaze/trace`)
- **url** (?string) - Request path
- **mode** (?string) - `'blaze'` or `'blade'`
- **timestamp** (?string) - ISO-8601 timestamp
- **renderTime** (?float) - Render time in ms

#### Response Example
```json
[
  { "id": "01J9F8K2XQ1234567890ABCDEF", "url": "/dashboard", "mode": "blaze", "timestamp": "2024-01-01T12:00:00+00:00", "renderTime": 3.21 },
  { "id": "01J9F8K0YY...", "url": "/login", "mode": "blade", "timestamp": "2024-01-01T11:59:00+00:00", "renderTime": 14.5 }
]
```
```

--------------------------------

### Static prop example for folding safety

Source: https://github.com/livewire/blaze/blob/main/resources/boost/skills/blaze-optimize/references/folding-safety.md

Shows a static prop passed as a literal string, which is safe to fold. This is the simplest case for props analysis.

```blade
<x-button color="red">Submit</x-button>
```

--------------------------------

### Exclude a subdirectory with compile: false

Source: https://github.com/livewire/blaze/blob/main/README.md

Use the compile: false parameter to exclude a subdirectory from optimization. The example optimizes the main components directory but excludes the 'legacy' subdirectory.

```php
Blaze::optimize()
    ->in(resource_path('views/components'))
    ->in(resource_path('views/components/legacy'), compile: false);
```

--------------------------------

### @blaze directive parameter examples

Source: https://github.com/livewire/blaze/blob/main/_autodocs/configuration.md

Shows the @blaze directive with various parameter combinations: default, compile: true, fold with safe/unsafe arrays, and memo: true. Note that compile: false cannot be combined with memo: true or fold: true and throws \InvalidArgumentException.

```blade
@blaze

@blaze(compile: true)

@blaze(fold: true, safe: ['title'], unsafe: ['attributes'])

@blaze(memo: true)
```

--------------------------------

### boot() method signature

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/service-provider.md

Public method signature for the service provider's boot() method. Called after all providers are registered.

```php
public function boot(): void
```

--------------------------------

### Blaze trace JSON response

Source: https://github.com/livewire/blaze/blob/main/_autodocs/endpoints.md

Example JSON response from GET /_blaze/trace. Shows the trace object structure with fields like url, mode, timestamp, renderTime, entries, components, and debugBar. The debugBar object contains the full debug-bar dataset.

```json
{
  "url": "/dashboard",
  "mode": "blaze",
  "timestamp": "2024-01-01T12:00:00+00:00",
  "renderTime": 3.21,
  "entries": [
    { "name": "dashboard", "start": 0.1, "depth": 0, "children": 2, "strategy": "view", "file": "resources/views/dashboard.blade.php", "end": 3.2, "duration": 3.1, "selfTime": 1.2 }
  ],
  "components": [
    { "name": "x-icon", "count": 12, "totalTime": 0.9, "selfTime": 0.5 }
  ],
  "debugBar": {
    "blazeEnabled": true,
    "totalTime": 3.21,
    "totalComponents": 13,
    "bladeComponentCount": 0,
    "bladeComponents": [],
    "components": [],
    "timerView": "dashboard",
    "strategies": { "compiled": 12, "view": 1 }
  }
}
```

--------------------------------

### add()

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/config.md

Registers optimization settings for a path. Like in(), but the strategy booleans are nullable.

```APIDOC
## add()

### Description
Registers optimization settings for a path. Like `in()`, but the strategy booleans are nullable. Writes `$this->compile[$path] = $compile`, `$this->memo[$path] = $memo`, `$this->fold[$path] = $fold`.

### Method
add

### Signature
`public function add(string $path, ?bool $compile = true, ?bool $memo = false, ?bool $fold = false): self`

### Parameters
- **$path** (string) - Required - Directory or file path
- **$compile** (bool|null) - Optional - Default: `true` - Compile flag
- **$memo** (bool|null) - Optional - Default: `false` - Memo flag
- **$fold** (bool|null) - Optional - Default: `false` - Fold flag

### Returns
- **self**
```

--------------------------------

### blaze:trace:show command usage

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/commands.md

Shows how to run the show command with a trace ID and optionally limit the number of components.

```bash
php artisan blaze:trace:show 01J9F8K2XQ1234567890ABCDEF
php artisan blaze:trace:show 01J9F8K2XQ1234567890ABCDEF --limit=5
```

--------------------------------

### Enable Blaze at runtime in a service provider boot method

Source: https://github.com/livewire/blaze/blob/main/_autodocs/configuration.md

Use this snippet in a service provider's boot method to enable Blaze compilation at runtime, optionally enabling debug mode and throwing exceptions. The optimize method returns a Config instance for fluent path configuration.

```php
use Livewire\Blaze\Blaze;

public function boot(): void
{
    Blaze::enable();
    // Blaze::debug();
    // Blaze::throw();

    Blaze::optimize()
        ->in(resource_path('views/components'), fold: true);
}
```

--------------------------------

### Enable Blaze compilation in AppServiceProvider::boot()

Source: https://github.com/livewire/blaze/blob/main/resources/boost/skills/blaze-optimize/SKILL.md

Add this to AppServiceProvider::boot() to enable Blaze optimization for the default components directory.

```php
use Livewire\Blaze\Blaze;

public function boot(): void
{
    Blaze::optimize()->in(resource_path('views/components'));
}
```

--------------------------------

### Blade directives usage example

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/service-provider.md

Example of using @blaze, @unblaze, and @endunblaze directives in a Blade template. @blaze takes options for folding and safe/unsafe attributes. @unblaze scopes variables for the enclosed block.

```blade
@blaze(fold: true, safe: ['title'], unsafe: ['attributes'])

@unblaze(scope: ['name' => $name])
    <input value="{{ old($scope['name']) }}">
@endunblaze
```

--------------------------------

### blaze:trace:list command usage

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/commands.md

Shows how to run the list command with and without the --limit option.

```bash
php artisan blaze:trace:list
php artisan blaze:trace:list --limit=10
```

--------------------------------

### optimize()

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/blaze.md

Returns the Config instance for fluent configuration, such as specifying directories to compile.

```APIDOC
## optimize()

### Description
Returns the `Config` instance for fluent configuration, such as specifying directories to compile.

### Method
`optimize()`

### Return Type
`Config`

### Example
```php
Blaze::optimize()->in(resource_path('views/components/legacy'), compile: false);
```
```

--------------------------------

### GET /_blaze/profiler

Source: https://github.com/livewire/blaze/blob/main/_autodocs/endpoints.md

Returns the profiler HTML page for viewing traces in the browser.

```APIDOC
## GET /_blaze/profiler

### Description
Returns the profiler HTML page for viewing traces in the browser.

### Method
GET

### Endpoint
/_blaze/profiler

### Response
#### Success Response (200)
Returns an HTML page (the profiler UI).

#### Response Example
```html
<!DOCTYPE html>
<html>
<head><title>Blaze Profiler</title></head>
<body>Profiler UI</body>
</html>
```
```

--------------------------------

### Apply memoization via service provider

Source: https://github.com/livewire/blaze/blob/main/resources/boost/skills/blaze-optimize/references/advanced-optimization.md

Preferred for entire directories like 'icons/'. Optimizes all components in the given paths, with memoization enabled for the icons directory.

```php
Blaze::optimize()
    ->in(resource_path('views/components'))
    ->in(resource_path('views/components/icons'), memo: true);
```

--------------------------------

### DebuggerStore constructor

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/debugger.md

Constructor sets the trace storage path to storage_path('blaze/traces').

```php
public function __construct()   // path = storage_path('blaze/traces')
```

--------------------------------

### GET /_blaze/trace

Source: https://github.com/livewire/blaze/blob/main/_autodocs/endpoints.md

Fetches a single profiler trace by id, or the most recent one when no id is provided.

```APIDOC
## GET /_blaze/trace

### Description
Fetches a single profiler trace by id, or the most recent one when no id is provided.

### Method
GET

### Endpoint
/_blaze/trace

### Parameters
#### Query Parameters
- **id** (string) - Optional - Trace ID (ULID filename without `.json`). When absent, the latest trace is returned.

### Response
#### Success Response (200)
- **url** (string) - Request path that produced the trace (e.g. `/dashboard`)
- **mode** (string) - `'blaze'` or `'blade'` (whether Blaze was enabled for the request)
- **timestamp** (string) - ISO-8601 timestamp
- **renderTime** (float) - View render time in ms
- **entries** (array) - Trace entries: `{ name, start, depth, children, strategy, file?, end, duration, selfTime }`
- **components** (array) - Per-component aggregates sorted by self time: `{ name, count, totalTime, selfTime }`
- **debugBar** (object) - The full debug-bar dataset (see `Debugger::getDebugBarData()` shape)

#### Response Example
```json
{
  "url": "/dashboard",
  "mode": "blaze",
  "timestamp": "2024-01-01T12:00:00+00:00",
  "renderTime": 3.21,
  "entries": [
    { "name": "dashboard", "start": 0.1, "depth": 0, "children": 2, "strategy": "view", "file": "resources/views/dashboard.blade.php", "end": 3.2, "duration": 3.1, "selfTime": 1.2 }
  ],
  "components": [
    { "name": "x-icon", "count": 12, "totalTime": 0.9, "selfTime": 0.5 }
  ],
  "debugBar": {
    "blazeEnabled": true,
    "totalTime": 3.21,
    "totalComponents": 13,
    "bladeComponentCount": 0,
    "bladeComponents": [],
    "components": [],
    "timerView": "dashboard",
    "strategies": { "compiled": 12, "view": 1 }
  }
}
```
```

--------------------------------

### Show trace details

Source: https://github.com/livewire/blaze/blob/main/resources/boost/skills/blaze-optimize/references/advanced-optimization.md

Shows the slowest components for a specific page and how many times they were rendered.

```bash
php artisan blaze:trace:show [id]
```

--------------------------------

### compile() method signature

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/compiler.md

Entry point for AST post-processing. Accepts any Node and returns it unchanged if it's not a ComponentNode.

```php
public function compile(Node $node): Node
```

--------------------------------

### Typical Blaze Facade Usage

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/blaze.md

Shows common runtime calls: enable() for global compilation, debug() for debug bar and profiler, throw() to throw on incompatible components, and optimize() to configure per-directory strategies with compile and memo flags.

```php
use Livewire\Blaze\Blaze;

// Enable compilation globally at runtime
Blaze::enable();

// Enable debug bar + profiler
Blaze::debug();

// Throw instead of silently skipping folding on incompatible components
Blaze::throw();

// Configure per-directory strategies
Blaze::optimize()
    ->in(resource_path('views/components'), compile: true)
    ->in(resource_path('views/components/icons'), memo: true);
```

--------------------------------

### GET /_blaze/profiler

Source: https://github.com/livewire/blaze/blob/main/_autodocs/endpoints.md

Serves the standalone flame-chart profiler page (static asset `src/Debugger/profiler.html`, ~2,535 lines of HTML/CSS/JS).

```APIDOC
## GET /_blaze/profiler

### Description
Serves the standalone flame-chart profiler page (static asset `src/Debugger/profiler.html`, ~2,535 lines of HTML/CSS/JS).

### Method
GET

### Endpoint
/_blaze/profiler

### Response
#### Success Response (200)
- **body** (text/html) - The full HTML document. The bundled JavaScript fetches `/ _blaze/trace` to load the trace for the last visited URL and renders a flame chart. The profiler button in the debug bar links here with `target="_blank"`.

#### Response Example
```html
<!DOCTYPE html>
<html>
...
</html>
```
```

--------------------------------

### earliestPreCompilationHook method

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/blade-service.md

Registers a callback as the earliest Blade pre-compilation step via BladeCompiler::prepareStringsForCompilationUsing(), deferred with app()->booted(...). The callback receives ($input, $this->compiler->getPath()).

```php
public function earliestPreCompilationHook(callable $callback): void
```

--------------------------------

### blaze:trace:clear command usage

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/commands.md

Shows how to run the clear command.

```bash
php artisan blaze:trace:clear
```

--------------------------------

### Misc method signatures

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/runtime.md

Declares setApplication and flushState methods for swapping the application instance and clearing stacks.

```php
public function setApplication(Application $app): void
public function flushState(): void
```

--------------------------------

### Including the Blaze component with x-button

Source: https://github.com/livewire/blaze/blob/main/README.md

Blade syntax to include the component, passing attributes and slot content. This is the usage example that Blaze compiles into a direct function call.

```blade
<x-button type="submit">Send</x-button>
```

--------------------------------

### Keyboard shortcuts and resize handling

Source: https://github.com/livewire/blaze/blob/main/src/Debugger/profiler.html

Handles keyboard events for zooming (+, -), focusing search (/), and refreshing (R). Also includes debounced resize handling to re-render.

```javascript
Math.min(totalDuration, viewDuration * 1.3); viewStart = Math.max(0, center - newDuration / 2); viewEnd = Math.min(totalDuration, center + newDuration / 2); scheduleRender(); return; } // /: focus search if (ev.key === '/') { ev.preventDefault(); document.getElementById('search-input').focus(); return; } // R: refresh if (ev.key === 'r' && !ev.ctrlKey && !ev.metaKey) { ev.preventDefault(); fetchTracesList(); return; } }); // ─── Resize handling ──────────────────────────────────────────────── let resizeTimer; window.addEventListener('resize', function() { clearTimeout(resizeTimer); resizeTimer = setTimeout(render, 50); }); // ─── Init ─────────────────────────────────────────────────────────── fetchTracesList();
```

--------------------------------

### Blade component with @blaze directive

Source: https://github.com/livewire/blaze/blob/main/README.md

Example of a Blade component using the @blaze directive, with props and attribute merging. This is the source template that Blaze compiles into an optimized PHP function.

```blade
@blaze 

@props(['type' => 'button'])

<button {{ $attributes->merge(['type' => $type]) }}>
    {{ $slot }}
</button>
```

--------------------------------

### Blade compilation interception hook

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/service-provider.md

Installs the Blaze pipeline as the earliest Blade string-compilation step. Laravel exception views bypass Blaze; when disabled, only debug instrumentation is applied.

```php
$blade->earliestPreCompilationHook(function ($input, $path) use ($blade, $blaze) {
    if ($blade->containsLaravelExceptionView($input)) {
        return $input;
    }

    if ($blaze->isDisabled()) {
        if ($blaze->isDebugging()) {
            return $blaze->compileForDebug($input, $path);
        }

        return $input;
    }

    return $blaze->collectAndAppendFrontMatter($input, function ($input) use ($path, $blaze) {
        return $blaze->compile($input, $path);
    });
});
```

--------------------------------

### render method

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/blade-renderer.md

Renders a component in isolation for folding. Takes a ComponentNode and a file path, and returns the folded HTML with placeholders intact.

```php
public function render(ComponentNode $component, string $path): string
```

--------------------------------

### Strategy query method signatures

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/config.md

Public methods to check if a file should be compiled, memoized, or folded.

```php
public function shouldCompile(string $file): bool
public function shouldMemoize(string $file): bool
public function shouldFold(string $file): bool
```

--------------------------------

### Using `unsafe` for slots to force folding abort

Source: https://github.com/livewire/blaze/blob/main/README.md

Marks the `slot` as unsafe, forcing folding to abort when the component receives a slot. The example shows a component that checks for actual slot content.

```blade
@blaze(fold: true, unsafe: ['slot'])

@if ($slot->hasActualContent())
    <span>No results</span>
@else
    <div>{{ $slot }}</div>
@endif
```

```blade
<x-items>
    @if(isPro())
        ...
    @endif
</x-items>
```

--------------------------------

### TraceShowCommand signature and handle method

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/commands.md

Defines the 'blaze:trace:show' command with a required id argument and optional --limit option (default 30). The handle method displays trace details.

```php
protected $signature = 'blaze:trace:show
                        {id : The trace ID to inspect}
                        {--limit=30 : Number of slowest components to display}';

protected $description = 'Display details of a recorded Blaze profiler trace';

public function handle(DebuggerStore $store): int
```

--------------------------------

### Enable Blaze with @blaze directive in a Blade component

Source: https://github.com/livewire/blaze/blob/main/README.md

Add @blaze at the top of an anonymous component to enable Blaze for that template. The example shows a simple button component using $attributes and $slot.

```blade
@blaze

<button {{ $attributes }}>
    {{ $slot }}
</button>
```

--------------------------------

### TraceListCommand signature and handle method

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/commands.md

Defines the 'blaze:trace:list' command with an optional --limit option (default 30). The handle method lists traces and returns SUCCESS.

```php
protected $signature = 'blaze:trace:list
                        {--limit=30 : Maximum number of traces to display}';

protected $description = 'List recorded Blaze profiler traces';

public function handle(DebuggerStore $store): int
```

--------------------------------

### Specify optimization strategies with @blaze arguments

Source: https://github.com/livewire/blaze/blob/main/README.md

Pass arguments to @blaze to enable memoization or folding strategies. The example shows two separate directives: @blaze(memo: true) and @blaze(fold: true).

```blade
@blaze(memo: true)

@blaze(fold: true)
```

--------------------------------

### Marking attributes as unsafe for attribute bag analysis

Source: https://github.com/livewire/blaze/blob/main/resources/boost/skills/blaze-optimize/references/folding-safety.md

Use this when the component reads attributes not defined in `@props` via `$attributes->get()` and uses the value in logic. Mark `attributes` as unsafe to abort folding.

```blade
@blaze(fold: true, unsafe: ['attributes'])

@php
$active = $attributes->get('href') === url()->current();
@endphp

<a {{ $attributes->merge(['data-active' => $active]) }}>
    {{ $slot }}
</a>
```

--------------------------------

### Folder constructor

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/folder.md

Constructor for the Folder class, injecting Config, BladeService, BladeRenderer, and BlazeManager dependencies.

```php
public function __construct(
    protected Config $config,
    protected BladeService $blade,
    protected BladeRenderer $renderer,
    protected BlazeManager $manager,
)
```

--------------------------------

### Blaze::optimize()

Source: https://github.com/livewire/blaze/blob/main/_autodocs/configuration.md

Returns the Config instance for fluent path configuration.

```APIDOC
## Blaze::optimize()

### Description
Returns the `Config` instance for fluent path configuration.

### Method
`Blaze::optimize()`

### Parameters
None

### Return Value
- `Config` instance

### Example
```php
use Livewire\Blaze\Blaze;

Blaze::optimize()
    ->in(resource_path('views/components'), fold: true);
```
```

--------------------------------

### Static prop usage and folded output

Source: https://github.com/livewire/blaze/blob/main/README.md

Shows how the button component is used with a static prop and the resulting static HTML after folding. The component is rendered once and subsequent requests serve the static HTML.

```blade
<x-button color="red">Submit</x-button>
```

```blade
<button class="bg-red-500 hover:bg-red-400">
    Submit
</button>
```

--------------------------------

### in() method signature

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/config.md

Alias for add() that registers optimization settings for a path. Returns self for chaining.

```php
public function in(string $path, bool $compile = true, bool $memo = false, bool $fold = false): self
```

--------------------------------

### DebuggerMiddleware::register() method signature

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/debugger.md

Static method that registers three routes and pushes the middleware onto the HTTP kernel.

```php
public static function register(): void
```

--------------------------------

### fold() method signature

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/folder.md

Public method that performs the placeholder-substitution rendering and returns a string of static HTML with runtime expressions restored.

```php
public function fold(): string
```

--------------------------------

### Blaze::optimize()

Source: https://github.com/livewire/blaze/blob/main/README.md

Configures directories for Blaze compilation. Allows enabling/disabling compilation, compile-time folding, and runtime memoization per directory.

```APIDOC
## Blaze::optimize()

### Description
Configures directories for Blaze compilation. Allows enabling/disabling compilation, compile-time folding, and runtime memoization per directory.

### Usage
```php
Blaze::optimize()
    ->in(resource_path('views/components'))
    ->in(resource_path('views/components/ui'), fold: true)
    ->in(resource_path('views/components/icons'), memo: true)
    ->in(resource_path('views/components/legacy'), compile: false);
```

### Options
| Option | Default | Description |
|--------|---------|-------------|
| `compile` | `true` | Enable Blaze compilation. Set `false` to exclude. |
| `fold` | `false` | Enable compile-time folding |
| `memo` | `false` | Enable runtime memoization |
```

--------------------------------

### Benchmark: Rendering 25,000 anonymous components with and without Blaze

Source: https://github.com/livewire/blaze/blob/main/README.md

ASCII bar chart showing the performance improvement: without Blaze takes 500ms, with Blaze takes 13ms.

```text
Rendering 25,000 anonymous components:

Without Blaze  ████████████████████████████████████████  500ms
With Blaze     █                                          13ms
```

--------------------------------

### Config class properties

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/config.md

Defines the protected arrays for fold, memo, and compile settings, keyed by path.

```php
class Config
{
    protected $fold = [];

    protected $memo = [];

    protected $compile = [];
}
```

--------------------------------

### Blaze methods: enable, debug, throw

Source: https://github.com/livewire/blaze/blob/main/README.md

Lists the Blaze methods for enabling compilation, enabling debug mode, and throwing exceptions during folding.

```php
Blaze::enable();    // Enable Blaze compilation
Blaze::debug();     // Enable debug mode
Blaze::throw();     // Throw exceptions encountered during folding
```

--------------------------------

### Blaze fold-dependency flow diagram

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/front-matter-events.md

ASCII diagram showing the flow from Folder::fold() dispatching ComponentFolded, through BlazeManager collection, to FrontMatter compilation and stale dependency checks on subsequent requests.

```text
Folder::fold()  →  Event::dispatch(ComponentFolded)
                         └─ BlazeManager listener → $foldedEvents[]

BlazeManager::compile() → collectAndAppendFrontMatter($input, $compileClosure)
    → FrontMatter::compileFromEvents($events) → prepends `<?php # [BlazeFolded]:... ?>`

Next request, view composes:
    BlazeManager::viewContainsExpiredFrontMatter($view)
        → FrontMatter::containsExpiredFoldedDependencies($compiledPath)
        → recompile if stale
```

--------------------------------

### DebuggerMiddleware::handle() method signature

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/debugger.md

Handles HTTP requests, skips injection under certain conditions, and injects the debug bar on status 200.

```php
public function handle(Request $request, Closure $next): SymfonyResponse
```

--------------------------------

### Apply memoization via directive

Source: https://github.com/livewire/blaze/blob/main/resources/boost/skills/blaze-optimize/references/advanced-optimization.md

Use on individual components to enable memoization.

```blade
@blaze(memo: true)
```

--------------------------------

### Blaze::enable()

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/blaze.md

Enables the Blaze library through the static facade, delegating to the manager's enable method.

```APIDOC
## Blaze::enable()

### Description
Enables the Blaze library. This is a static facade call that delegates to the manager's `enable()` method.

### Method
Static method call

### Endpoint
`Blaze::enable()`

### Parameters
None

### Response
No return value specified.
```

--------------------------------

### Publishable config file config/blaze.php

Source: https://github.com/livewire/blaze/blob/main/_autodocs/configuration.md

Publish with 'php artisan vendor:publish --tag=blaze'. The file defines 'enabled' and 'debug' keys, each reading from environment variables with defaults. Merged into the 'blaze' config key by BlazeServiceProvider::registerConfig().

```php
<?php

return [

    /*
    |--------------------------------------------------------------------------
    | Enable Blaze
    |--------------------------------------------------------------------------
    |
    | When set to false, Blaze will skip all compilation and optimization.
    | Templates will be rendered using standard Blade without any Blaze
    | processing. This is useful for debugging or disabling Blaze in
    | specific environments.
    |
    */

    'enabled' => env('BLAZE_ENABLED', true),

    /*
    |--------------------------------------------------------------------------
    | Debug Mode
    |--------------------------------------------------------------------------
    |
    | When enabled, Blaze will register the debugger middleware and output
    | additional diagnostic information about the compilation pipeline.
    |
    */

    'debug' => env('BLAZE_DEBUG', false),

];
```

--------------------------------

### Unblaze class with static caches

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/unblaze.md

Defines the Unblaze class with two static caches: $unblazeScopes (token to scope array) and $unblazeReplacements (token to inner content).

```php
class Unblaze
{
    static $unblazeScopes = [];
    static $unblazeReplacements = [];
}
```

--------------------------------

### in()

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/config.md

Registers optimization settings for a path. Alias for add(). Used as Blaze::optimize()->in(...).

```APIDOC
## in()

### Description
Registers optimization settings for a path. Alias for `add()`. Used as `Blaze::optimize()->in(...)`.

### Method
in

### Signature
`public function in(string $path, bool $compile = true, bool $memo = false, bool $fold = false): self`

### Parameters
- **$path** (string) - Required - Directory path (or exact file path) to register settings for
- **$compile** (bool) - Optional - Default: `true` - Enable Blaze function compilation within the path; `false` excludes it
- **$memo** (bool) - Optional - Default: `false` - Enable runtime memoization for self-closing components in the path
- **$fold** (bool) - Optional - Default: `false` - Enable compile-time folding in the path

### Returns
- **self** - for chaining

### Example
```php
Blaze::optimize()
    ->in(resource_path('views/components'))
    ->in(resource_path('views/components/legacy'), compile: false)
    ->in(resource_path('views/components/icons'), memo: true)
    ->in(resource_path('views/components/cards'), fold: true);
```
```

--------------------------------

### Debugger constructor with BladeService dependency

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/debugger.md

Constructor for the Debugger singleton, injecting the BladeService and creating the public readonly DebuggerStore property for trace storage.

```php
public function __construct(
    protected BladeService $blade,
)
```

--------------------------------

### Opt in to folding and memoization with @blaze

Source: https://github.com/livewire/blaze/blob/main/UPGRADING.md

Use @blaze(fold: true, memo: true) to explicitly enable both folding and memoization.

```php
@blaze(fold: true, memo: true)
```

--------------------------------

### Blaze query methods

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/blaze.md

Public methods to check Blaze's state: isEnabled, isDisabled, shouldThrow, isDebugging, isFolding, and optimize. Each method returns a boolean except optimize which returns the Config instance.

```php
public function isEnabled()   // $this->enabled ??= config('blaze.enabled', true);
public function isDisabled()  // ! $this->isEnabled()
public function shouldThrow() // $this->throw
public function isDebugging() // $this->debug ??= config('blaze.debug', false);
public function isFolding(): bool  // $this->folding
public function optimize(): Config // returns $this->config
```

--------------------------------

### Constructor signature

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/runtime.md

Constructor that skips the parent setAttributes() check because attributes are always plain arrays in the Blaze path.

```php
public function __construct(array $attributes = [])
```

--------------------------------

### Blaze::enable()

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/blaze.md

Enables compilation globally at runtime via the Blaze facade.

```APIDOC
## Blaze::enable()

### Description
Enables compilation globally at runtime. This is a static call proxied to the BlazeManager singleton.

### Method
Static method on the Blaze facade.

### Usage
```php
use Livewire\Blaze\Blaze;

Blaze::enable();
```

### Parameters
None.

### Returns
Void (no return value documented).
```

--------------------------------

### add() method signature

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/config.md

Like in() but with nullable strategy booleans. Writes to the internal arrays.

```php
public function add(string $path, ?bool $compile = true, ?bool $memo = false, ?bool $fold = false): self
```

--------------------------------

### __toString() signature

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/runtime.md

Renders key="value" pairs with special handling for booleans, placeholders, and escaping.

```php
public function __toString()
```

--------------------------------

### Blaze::compile($t, $path)

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/blaze.md

Compiles a template string using the static facade, delegating to the manager's compile method.

```APIDOC
## Blaze::compile($t, $path)

### Description
Compiles a template string. This is a static facade call that delegates to the manager's `compile(string $template, ?string $path = null): string` method.

### Method
Static method call

### Endpoint
`Blaze::compile($t, $path)`

### Parameters
- **$t** (string) - Required - The template string to compile.
- **$path** (?string) - Optional - The path associated with the template.

### Response
Returns the compiled string.
```

--------------------------------

### Include custom component paths with Blaze::optimize()->in()

Source: https://github.com/livewire/blaze/blob/main/resources/boost/skills/blaze-optimize/SKILL.md

Add additional component paths found in step 2 by chaining multiple in() calls.

```php
Blaze::optimize()
    ->in(resource_path('views/components'))
    ->in(resource_path('views/other-components'));
```

--------------------------------

### Wrapper constructor

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/compiler.md

Defines the constructor for the Wrapper class, which takes a BladeService and BlazeManager instance and builds PropsCompiler, AwareCompiler, and UseExtractor instances.

```php
public function __construct(
    protected BladeService $blade,
    protected BlazeManager $manager,
)
```

--------------------------------

### Enabling debug mode via service provider

Source: https://github.com/livewire/blaze/blob/main/README.md

Enable Blaze debug mode from your service provider by calling Blaze::debug() in the boot method.

```php
use Livewire\Blaze\Blaze;

public function boot(): void
{
    Blaze::debug();

    // ...
}
```

--------------------------------

### Data and slot stack method signatures

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/runtime.md

Declares the methods for managing data and slot stacks used by @aware and delegate forwarding.

```php
public function currentComponentData(): array
public function mergedComponentSlots(): array
public function unescapeAttributes($data): array
public function pushData(array $data): void
public function pushSlots(array $slots): void
public function popData(): void
public function getConsumableData(string $key, mixed $default = null): mixed
```

--------------------------------

### Call site for the foldable component

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/folder.md

Shows how the component is used with a color prop and slot content. This call site is passed to Foldable::fold(), which pre-renders the component and replaces the slot with a runtime expression.

```blade
<x-button color="red"><b>Send</b></x-button>
```

--------------------------------

### Raw-block lifecycle methods

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/blade-service.md

Methods for storing and restoring verbatim and PHP blocks via reflection into BladeCompiler. preStoreUncompiledBlocks runs storeVerbatimBlocks then storePhpBlocks. storeVerbatimBlocks uses LaravelRegex::VERBATIM_BLOCK and the compiler's private storeRawBlock. storePhpBlocks uses LaravelRegex::PHP_BLOCK. restoreRawBlocks and restorePhpBlocks restore placeholders via private methods.

```php
public function preStoreUncompiledBlocks(string $input): string
public function storeVerbatimBlocks(string $input): string
public function storePhpBlocks(string $input): string
public function restoreRawBlocks(string $input): string
public function restorePhpBlocks(string $input): string
```

--------------------------------

### Front matter comment line format

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/front-matter-events.md

Each event emits one comment line containing PHP so it survives template caching but renders nothing. The format includes the component name, path, and filemtime.

```php
<?php # [BlazeFolded]:{<name>}:{<path>}:{<filemtime>} ?>
```

--------------------------------

### Constructor with BladeCompiler and Factory

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/blade-service.md

Constructor signature for BladeService. Requires the app Blade compiler and view factory. Builds an internal ComponentTagCompiler from the compiler's class aliases, namespaces, and the compiler itself.

```php
public function __construct(
    public BladeCompiler $compiler,
    protected Factory $view,
)
```

--------------------------------

### Folder::checkProblematicPatterns() method signature

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/folder.md

Protected method that scans for incompatible patterns and throws exceptions.

```php
protected function checkProblematicPatterns(ComponentSource $source): void
```

--------------------------------

### Sidebar sizing and data fetching functions

Source: https://github.com/livewire/blaze/blob/main/src/Debugger/profiler.html

These functions manage the sidebar height based on the main area and flame graph dimensions, fetch the traces list from the server, populate the select dropdown, and load a specific trace by ID.

```javascript
function sizeSidebarToFit() { const mainEl = document.getElementById('main-area'); const mainH = mainEl.clientHeight; if (mainH <= 0) return; const flameContentH = (maxDepth + 1) * ROW_FULL + 20; const flameFixed = 36 + 24 + 5; // minimap + time axis + resize handle const flamePadding = 32; const flameNeeded = flameFixed + flameContentH + flamePadding; const sidebarH = Math.max(200, mainH - flameNeeded); $sidebar.style.height = sidebarH + 'px'; }
```

```javascript
async function fetchTracesList() { try { const resp = await fetch('/_blaze/traces'); tracesList = await resp.json(); populateSelect(); if (tracesList.length) { await loadTrace(tracesList[0].id); } } catch (e) { console.error('Failed to fetch traces list:', e); } }
```

```javascript
function populateSelect() { const $select = document.getElementById('hdr-select'); $select.innerHTML = ''; if (!tracesList.length) { $select.innerHTML = '<option value="">No traces</option>'; return; } for (const t of tracesList) { const opt = document.createElement('option'); opt.value = t.id; const time = t.timestamp ? new Date(t.timestamp).toLocaleTimeString() : ''; const render = t.renderTime != null ? fmtMs(t.renderTime) : ''; const mode = (t.mode || '').toUpperCase(); const url = t.url || '/'; opt.textContent = url + ' — ' + render + ' — ' + time; $select.appendChild(opt); } }
```

```javascript
async function loadTrace(id) { try { const url = id ? '/_blaze/trace?id=' + encodeURIComponent(id) : '/_blaze/trace'; const resp = await fetch(url); data = await resp.json(); entries = data.entries || []; processData(); sizeSidebarToFit(); render(); } catch (e) { console.error('Failed to fetch trace:', e); } }
```

```javascript
document.getElementById('hdr-select').addEventListener('change', function() { if (this.value) loadTrace(this.value); });
```

--------------------------------

### Enable Blaze debugging in AppServiceProvider

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/debugger.md

Call Blaze::debug() in the boot method of AppServiceProvider to enable profiling. This is required to record traces for the profiler page.

```php
// app/Providers/AppServiceProvider.php
public function boot(): void
{
    Blaze::debug();
}
```

--------------------------------

### registerDebuggerMiddleware() method signature

Source: https://github.com/livewire/blaze/blob/main/_autodocs/api-reference/service-provider.md

Protected method signature for registering the debugger middleware.

```php
protected function registerDebuggerMiddleware(): void
```
Tokens:
Raw