README

MLView is the built‑in, lightweight template engine for MonkeysLegion, designed to help you write clean, component‑driven views with minimal boilerplate.

🌟 Key Features

Escaped output: {{ $var }} → safe, HTML‑escaped data
Raw output: {!! $html !!} → unescaped HTML (use responsibly)
Components: <x-card title="...">...</x-card> → reusable view fragments
Slots: @slot('header')…@endslot → named content areas inside components
Layout inheritance: @extends('parent'), @section('name')…@endsection, @yield('name')
Caching & Hot‑Reload: compiled PHP cached in var/cache/views; auto‑recompiles modified templates

📂 Directory Structure

my-app/
├─ resources/views/
│  ├─ home.ml.php              # Top‑level view
│  ├─ posts/
│  │  └─ show.ml.php           # Nested view under posts/
│  └─ components/
│     ├─ layout.ml.php         # Layout component for <x-layout>
│     └─ alert.ml.php          # Alert component
└─ var/
   └─ cache/views/             # Generated PHP cache files

Dot‑notation when rendering:

home → resources/views/home.ml.php
posts.show → resources/views/posts/show.ml.php

2 · Hello, World

Hello, {{ $name }}!

use MonkeysLegion\Template\MLView;

$view = new MLView(base_path('resources/views'));

echo $view->render('hello', ['name' => 'Alice']);

The first call parses → compiles → caches the template; subsequent renders are just an include.

3 · Component Syntax

Welcome, {{ $user->name }}

Your last login was {{ $user->lastLogin->diffForHumans() }}.

↔ PHP class App\View\Components\Component.

x-slot:name fills the component's $this->slot('name').

{{ … }} escapes htmlspecialchars(); {!! … !!} prints raw.

6 · Blade-style Helpers

Helper	Description
@if / @elseif / @endif	Control blocks
@foreach / @endforeach	Loops (auto-escapes inside {{ }})
@include('partial')	Inlines another template
@csrf	Outputs <input type="hidden" …> token (when the CSRF package is installed)

(All helpers compile down to raw PHP inside the cached file—no runtime cost.)

🛠️ Component Best Practices

Simple Component Creation

Components should be straightforward with minimal PHP boilerplate:

<div class="alert alert-<?= $type ?>">
  <?php if (isset($slots['header'])): ?>
    <div class="alert-header"><?= $slots['header']() ?></div>
  <?php endif; ?>
  <div class="alert-body"><?= $slotContent ?></div>
</div>

Check slots: Always use isset($slots['name']) before accessing slots
Access slot content: Use $slots['header']() for named slots or $slotContent for default content
Component attributes: All attributes passed to your component are available as PHP variables

Advanced Component Rendering

Behind the scenes, MLView uses a component rendering pipeline:

Slots are processed recursively to handle nested components
Component attributes are extracted into the local scope
The main content is captured in $slotContent
Component output is inserted into the parent template

This approach allows for reusable components that maintain proper scoping while keeping them simple.

@extends('layouts.app')

@section('title')
  {{ \$title }}
@endsection

@section('header')
  <h1>Welcome!</h1>
@endsection

@section('content')
  <p>Home page content…</p>
@endsection

@extends('layouts.app') indicates the parent template
@section('…')…@endsection blocks define content
@yield('…') in the parent is replaced by each section

⚙️ Rendering Pipeline

Loader: resolves raw .ml.php + cache path
Parser: transforms <x-*>, @slot, @section, @yield, {{ }}, {!! !!} into an AST
Compiler: generates pure PHP code from the AST
Cache: writes to var/cache/views/<name>.php and includes it

🔄 Caching & Hot‑Reload

Location: var/cache/views
Auto‑invalidate: template timestamp checked on each render
Manual clear: php vendor/bin/ml cache:clear

🔧 Extensibility

Custom directives: add regex callbacks in Compiler
AST extensions: enhance Parser for new syntax
Alternative loaders: swap Loader for custom sources (DB, remote)

Debugging

Dump data: @dump(\$variable) inside templates to var_dump

Happy templating with MLView! 🚀

MLView Component System

The MLView template engine supports a component system to build reusable UI elements.

Component Usage

Use components in your templates with <x-name> tags:

<!-- Using a component with a default slot -->
<x-alert type="warning">
    This is a warning message!
</x-alert>

<!-- Using a component with named slots -->
<x-card>
    @slot('header')
        Card Title
    @endslot
    
    This is the main content (default slot)
    
    @slot('footer')
        <button>Action</button>
    @endslot
</x-card>

Creating Components

Components should use PHP syntax for optimal compatibility:

<!-- resources/views/components/alert.ml.php -->
@param(['type' => 'info', 'dismissible' => false])

<div class="alert alert-<?= $type ?> <?= $dismissible ? 'alert-dismissible' : '' ?>">
    <?php if (isset($slots['header'])): ?>
        <div class="alert-header"><?= $slots['header']() ?></div>
    <?php endif; ?>
    
    <div class="alert-body"><?= $slotContent ?></div>
    
    <?php if ($dismissible): ?>
        <button type="button" class="btn-close" data-bs-dismiss="alert"></button>
    <?php endif; ?>
</div>

Component Parameters

Components can define default parameters using the @param directive:

@param(['name' => 'default value', 'another' => true, 'count' => 5])

These parameters:

Must be defined at the top of the component file
Will be available as PHP variables inside the component
Can be overridden by passing attributes to the component

When using the component:

<!-- Uses default 'info' type -->
<x-alert>This is an info message</x-alert>

<!-- Overrides the default type with 'danger' -->
<x-alert type="danger">This is a danger alert!</x-alert>

<!-- Sets dismissible to true -->
<x-alert type="warning" dismissible="true">This is dismissible</x-alert>

The parameters system allows component authors to define sensible defaults while giving component users the flexibility to customize as needed.

Slot Handling

Define slots using Blade-style @slot directives:

<x-card>
    @slot('header')
        Card Title
    @endslot
    
    Default content
</x-card>

Component Data

Inside a component:

$slotContent contains the default (unnamed) slot content
$slots['name']() calls and renders named slots
All attributes from the component tag are available as variables

Template Inclusion

@include directive

The @include directive lets you include one template from another:

<!-- Include a partial template -->
@include('partials.header')

<!-- Include with variables -->
@include('partials.alert', ['type' => 'warning', 'message' => 'Danger ahead!'])

Templates included with @include should be placed in the standard views directory structure and are referenced using dot notation:

@include('header') → resources/views/header.ml.php
@include('partials.header') → resources/views/partials/header.ml.php

Component vs @include

Components (<x-name>) are placed in resources/views/components/name.ml.php
Included templates (@include) can be placed anywhere in the views directory
Components support slots and have a dedicated lifecycle
Included templates are simply merged into the parent template

monkeyscloud / monkeyslegion-template

Maintainers

Details