Laravel Laravel Package

Getting Started

Torchlight is a hosted syntax highlighter: your app sends raw code blocks to the Torchlight API, gets back richly highlighted HTML (themes, line numbers, diff markers, focus/highlight lines), and caches the result locally. The Laravel package wires that API into Blade and league/commonmark, so you keep writing normal <pre><code> blocks or fenced code fences and let Torchlight upgrade them.

Minimum setup:

1. Install the package:

   composer require torchlight/laravel
   

2. Get a token from torchlight.dev and add it to .env:

   TORCHLIGHT_TOKEN=your-token-here
   

3. Publish the config:

   php artisan vendor:publish --tag=torchlight-config
   

   This writes config/torchlight.php (theme, cache driver/store, defaults, withBackgrounds, multi-theme map).
4. Render your first block in Blade:

   @torchlight
   ```php
   Route::get('/', fn () => view('welcome'));
   

   @endtorchlight

   Everything between the directives is sent as-is — including the language hint on the fence line.
   
   

First places to look:

• config/torchlight.php — theme (e.g. material-theme-palenight), cache store, and the defaults block that controls line numbers and background.
• The rendered HTML in DevTools — data-line attributes, torchlight classes, and inline styles are what your CSS targets.
• If you're rendering Markdown, jump straight to the CommonMark extension (see below) rather than using the Blade directive.

First real use case: a docs/blog page where code fences in Markdown need to look polished. Add the Torchlight CommonMark extension to your converter and fenced blocks in your Markdown are highlighted with zero changes to content authoring.

Implementation Patterns

Blade directive for inline code snippets. The @torchlight … @endtorchlight pair wraps a normal Markdown fence. Use it for marketing pages, lesson content, and copy-paste snippets. Keep the language hint on the fence line (```php) so Torchlight knows how to parse.

CommonMark extension for blog/docs pipelines. If your content comes from Markdown (files, database, a CMS), register the extension on your Environment:

use League\CommonMark\Environment\Environment;
use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;
use League\CommonMark\MarkdownConverter;
use Torchlight\Commonmark\V2\TorchlightExtension;

$environment = (new Environment([
    'torchlight' => [
        'withBackgrounds' => true,
    ],
]))->addExtension(new CommonMarkCoreExtension())
  ->addExtension(new TorchlightExtension());

$html = (new MarkdownConverter($environment))->convert($markdown);

This is the pattern most apps settle on: author in Markdown, render through CommonMark with Torchlight attached, cache the final HTML.

Multi-theme for dark/light mode. Configure themes in config/torchlight.php so one block renders both variants with CSS media queries, instead of shipping two cached copies:

'themes' => [
    'light' => 'github-light',
    'dark'  => 'material-theme-palenight',
],

Then your front-end CSS toggles between .torchlight-light / .torchlight-dark wrappers.

Per-block options via the fence comment. Torchlight reads a JSON comment adjacent to the fence. This is how authors opt into line numbers, highlighted lines, diffs, and focus without touching PHP:

// torchlight! {"lineNumbers": true, "highlightLines": [2, 3]}

Wire this into your editor tooling/docs style guide instead of baking presentation into Blade partials.

Cache aggressively, in a shared store. The package caches each highlighted block keyed by code + options + theme. In production, point the cache at Redis/database rather than the default file store so multiple app servers share hits:

'cache' => [
    'driver' => 'redis',
    'store'  => 'default',
    'ttl'    => null, // keep forever; invalidate by changing code
],

Pre-render for static sites and CI. For Jigsaw, Astro-style static hosting, or php artisan build commands, render all Markdown (with Torchlight) during the build step, ship the resulting HTML, and never call the API at request time. Your token only needs to exist in the build environment.

Custom rendering wrapper. When you need to control the surrounding markup (copy buttons, file-name headers), use Torchlight::highlight($code, 'php', $options) in a Blade component or service, and inject the copy-button markup yourself. Don't edit cached HTML after the fact.

Gotchas and Tips

• Missing token fails hard. If TORCHLIGHT_TOKEN is unset, rendering throws rather than degrading. Guard local/dev environments: set a real token, or skip highlighting in tests by mocking the client. Never commit the token; it bills your account.
• Cache misses are network calls. A cold cache on first deploy means one HTTP request per unique block. On a large docs site this is slow and can hit rate limits. Warm the cache during deploy (render once in CI) or use php artisan torchlight:warm style pre-rendering in your build script.
• Cache key sensitivity. Any change to the code, fence language, or the inline {"torchlight":…} options produces a new key. Renaming a theme invalidates everything — plan a cache-flush step when bumping themes.
• Fence comments leak if you strip them. Torchlight removes the // torchlight! {...} comment from the output only when it recognizes the format. Whitespace or a wrong JSON key silently leaves the comment inside the highlighted code. Validate options and check rendered output after upgrading.
• withBackgrounds and themes interact. Background colors are emitted as inline styles; if you want your own CSS background, set withBackgrounds => false and style the wrapper — otherwise you'll fight specificity.
• Blade directive indentation matters. Code between @torchlight and @endtorchlight is emitted verbatim. Indenting it inside another Blade block indents the code in the output. Keep the directives flush-left, or use a Markdown source instead.
• CommonMark version pinning. The extension namespace encodes the CommonMark major (V2). Upgrading league/commonmark across majors requires updating the extension class; read the package's changelog before bumping. Mixing versions produces a silent "no highlighting" result rather than an error.
• Testing. Torchlight makes outbound HTTP calls during rendering. In tests, either fake the Torchlight client, pre-populate the cache, or assert on the pre-highlighted HTML. Don't let feature tests hit the real API — you'll get flaky, rate-limited builds.
• Extension points. The config's defaults array is the cleanest place to enforce project-wide presentation (line numbers on/off, default theme). Use it before writing per-block overrides, and reserve inline torchlight! comments for genuine exceptions like a single highlighted line.
• Not offline-friendly out of the box. If you need air-gapped builds, ship a pre-warmed cache as a build artifact; Torchlight is a hosted service, so plan the cache lifecycle as part of your deploy, not as an afterthought.