Laravel Carve

Carve markup for Laravel, built on markup-carve/carve-php.

• Named render profiles: one for user comments, one for trusted docs, each with its own safe mode, feature preset and extensions.
• Rendered results with the HTML, a table of contents and parsed frontmatter.
• Blade: @carve, @carveText and an <x-carve> component.
• .crv views: view('docs.intro') renders resources/views/docs/intro.crv, with {{ include.crv }} support.
• Eloquent cast that stores source and reads back rendered HTML.
• Validation rule for presets, parse warnings, lint findings and length.
• Str macros: Str::carve(), str($body)->carveText()->limit(160).
• Import from Markdown and HTML, and lint for Markdown habits.
• Artisan: carve:render, carve:convert, carve:lint.
• Cache keyed by profile configuration, so profiles never share HTML.

Requirements

• PHP 8.2+
• Laravel 11, 12 or 13

Installation

composer require jeffersongoncalves/laravel-carve

Publish the config (optional):

php artisan vendor:publish --tag="carve-config"

To read YAML frontmatter with RenderedCarve::meta(), also install symfony/yaml. JSON frontmatter works without it.

Quick start

use JeffersonGoncalves\Carve\Facades\Carve;

Carve::toHtml('Some *bold* and /italic/ text');
// <p>Some <strong>bold</strong> and <em>italic</em> text</p>

Carve::toHtml($comment->body, 'comment'); // render with a named profile
Carve::toText($post->body);               // plain text, for excerpts and meta tags
Carve::toMarkdown($post->body);
Carve::toAnsi($post->body);               // for the terminal
Carve::parse($post->body);                // carve-php AST Document

Profiles

Every entry of carve.profiles becomes its own converter. The published config ships three:

'profiles' => [
    'default' => [
        'safe_mode' => true,
        'preset' => null,
        'extensions' => ['autolink'],
    ],

    // User generated content: comments, chat, reviews.
    'comment' => [
        'safe_mode' => 'strict',
        'preset' => 'comment',
        'extensions' => ['autolink', ['type' => 'external_links', 'nofollow' => true]],
    ],

    // Trusted content written by your team: docs, pages, posts.
    'trusted' => [
        'safe_mode' => false,
        'extensions' => ['autolink', 'admonition', 'details', 'heading_permalinks', 'tabs'],
    ],
],

carve.default (or CARVE_PROFILE) picks the profile used when none is given.

Extensions

Enable an extension by name, or pass an array with its options in snake_case. Options map to the carve-php extension's constructor arguments, so every option carve-php supports is available:

'extensions' => [
    'autolink',
    'spoiler',
    'mermaid',
    ['type' => 'table_of_contents', 'position' => 'top', 'min_level' => 2],
    ['type' => 'heading_permalinks', 'symbol' => '#', 'position' => 'after'],
    ['type' => 'external_links', 'target' => '_blank', 'internal_hosts' => ['example.com']],
    ['type' => 'wikilinks', 'url_template' => '/wiki/{page}'],
    ['type' => 'fenced_render', 'language' => 'chart'],
    App\Carve\MyExtension::class,
],

Available names: admonition, ascii_heading_ids, autolink, citations, code_callouts, code_group, color_swatch, default_attributes, details, external_links, fenced_render, frontmatter, glossary, heading_level_shift, heading_numbers, heading_permalinks, heading_reference, img_fence, index, inline_footnotes, list_table, lowercase_heading_ids, math_block, mentions, plus_bullet, semantic_span, smart_quotes, spoiler, tab_normalize, table_of_contents, tabs, toc_placement, wikilinks, plus the mermaid and plantuml shorthands for fenced_render.

An unknown name or option throws an InvalidArgumentException naming the extension.

Customizing a profile in code

Anything config cannot hold, such as closures and render listeners, goes through extend(), usually in a service provider:

use MarkupCarve\Carve\CarveConverter;

Carve::extend('default', function (CarveConverter $converter) {
    $converter->on('render.link', function ($event) {
        $event->getNode()->setAttribute('data-turbo', 'false');
    });
});

Carve::profile('default')->carve(); // the underlying carve-php converter

Rendered results

Carve::render() returns a RenderedCarve holding the HTML, the headings and the frontmatter collected while rendering:

$page = Carve::render(<<<'CARVE'
---yaml
title: Getting started
tags: [intro, setup]
---

# Getting started

## Install
CARVE);

$page->html;              // the frontmatter block is not part of the output
$page->toc();             // [['level' => 1, 'text' => 'Getting started', 'html' => '...', 'id' => 'Getting-started'], ...]
$page->meta();            // ['title' => 'Getting started', 'tags' => ['intro', 'setup']]
$page->meta('tags.0');    // 'intro'
$page->source;            // the original markup

It is Htmlable, so {{ $page }} prints the HTML unescaped, and Arrayable/JsonSerializable.

Blade

@carve($post->body)
@carve($comment->body, 'comment')
@carveText($post->body) {{-- plain text, escaped --}}

<x-carve :source="$post->body" />
<x-carve :source="$comment->body" profile="comment" />

<x-carve>
    # Welcome back, {{ $user->name }}

    You have *{{ $count }}* new messages.
</x-carve>

The component slot is dedented, so it can follow your template's indentation. Values echoed with {{ }} inside the slot are Carve source: Carve markup in them is rendered, while HTML is always shown as text. Render user supplied values with a safe_mode profile.

Views

Files ending in .crv inside your view paths render as Carve:

return view('docs.intro'); // resources/views/docs/intro.crv

Set carve.views.profile to render them with a specific profile, carve.views.extension to change the extension, or carve.views.enabled to false to skip the view engine. View data is not interpolated; use the component for templates with variables.

Includes

Set carve.include_root to an absolute directory to expand {{ chapter.crv }} directives in views, Carve::renderFile() and carve:render. Includes can only read files inside that directory. With include_root null, directives stay literal text.

'include_root' => resource_path('docs'),

Carve::renderFile(resource_path('docs/book.crv'))->html;

Eloquent cast

use JeffersonGoncalves\Carve\Casts\AsCarve;

class Post extends Model
{
    protected $casts = [
        'body' => AsCarve::class,
        'excerpt' => AsCarve::class.':comment', // with a profile
    ];
}

$post->body = '# Hello *world*';  // stores the source
$post->body->html;                // rendered HTML
$post->body->source;              // stored markup
$post->body->toc();
{{ $post->body }}                 // prints the HTML in Blade

Validation

use JeffersonGoncalves\Carve\Rules\ValidCarve;

$request->validate([
    'body' => ['required', new ValidCarve],
    'comment' => ['required', ValidCarve::preset('comment')->maxLength(5000)],
    'docs' => ['required', (new ValidCarve)->strict()->lint()],
]);

• preset('comment') fails when the text uses markup the preset does not allow, instead of silently degrading it.
• strict() fails on parse warnings such as undefined references.
• lint() fails on lint findings such as Markdown's **bold**.
• maxLength(n) limits the length in characters.

Messages ship in English and Brazilian Portuguese. Publish them with php artisan vendor:publish --tag="carve-translations".

Str macros

use Illuminate\Support\Str;

Str::carve('*bold*');                             // HTML
Str::carve($comment, 'comment');
Str::carveText($post->body);                      // plain text
str($post->body)->carveText()->squish()->limit(160); // meta description

Import and lint

Carve::fromMarkdown(file_get_contents('README.md')); // CommonMark/GFM to Carve
Carve::fromHtml($html);                              // HTML to Carve (not a sanitizer)

foreach (Carve::lint('**bold**') as $warning) {
    echo "{$warning->line}:{$warning->column} {$warning->rule} {$warning->message}";
}

Artisan

php artisan carve:render docs/intro.crv                       # HTML to the console
php artisan carve:render docs/intro.crv --format=text         # text, markdown or ansi
php artisan carve:render docs/intro.crv --profile=trusted --output=public/intro.html

php artisan carve:convert README.md --output=README.crv       # from .md / .html (or --from=)

php artisan carve:lint resources/docs                         # exits 1 on findings

Cache

'cache' => [
    'enabled' => env('CARVE_CACHE', false),
    'store' => env('CARVE_CACHE_STORE'), // null = default store
    'ttl' => null,                       // seconds, null = until evicted
    'prefix' => 'carve',
],

Entries are keyed by the profile's configuration, the carve-php version and a hash of the source, so changing a profile or upgrading carve-php never serves stale HTML. extend() customizers are not part of the key: change prefix when one changes the output of a cached profile. File renders with includes are not cached, since an included file can change on its own.

Security

• The default profile escapes raw HTML and blocks javascript:, data: and similar URLs. Use 'strict' or a comment/minimal preset for user generated content.
• Output of @carve, <x-carve> and the cast is echoed unescaped because it is HTML. Only use a profile with safe_mode => false for content you trust.
• symbols values are inserted as raw HTML. Never fill them from user input.
• fromHtml() is not a sanitizer. Render its result with a safe profile when the HTML is untrusted.

Testing

composer test
composer analyse
composer format

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Jefferson Gonçalves
• markup-carve/carve-php for the Carve engine
• All Contributors

License

The MIT License (MIT). Please see License File for more information.