monkeyscloud / monkeyslegion-template
MLView – the MonkeysLegion template engine with components, slots, and caching
Installs: 189
Dependents: 2
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
pkg:composer/monkeyscloud/monkeyslegion-template
Requires
- php: ^8.4
This package is auto-updated.
Last update: 2025-10-06 16:09:13 UTC
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
andinclude
s 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 inresources/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