Weave Code
Shiki Php Laravel Package
spatie/shiki-php
Use Shiki syntax highlighting from PHP. Highlight code snippets with editor-quality themes and 100+ languages, plus Antlers and Blade. Works great with Laravel via spatie/laravel-markdown and CommonMark through a companion extension.
Code highlighting with Shiki in PHP
Frequently asked questions about Shiki Php
- How do I integrate Shiki syntax highlighting into a Laravel blog using spatie/laravel-markdown?
- Install `spatie/laravel-markdown` and `spatie/shiki-php`, then configure the Markdown processor to use Shiki. The package automatically handles code blocks in Markdown files, applying themes like 'github-dark' or 'vscode-dark-plus'. No extra setup is needed beyond requiring both packages via Composer. For custom themes, place JSON files in `resources/themes/` and reference them in your Markdown processor config.
- What Laravel versions does spatie/shiki-php support, and why does it require PHP 8.0+?
- The package supports Laravel 9+ and 10+ due to its PHP 8.0+ requirement, which aligns with Laravel’s LTS support. PHP 7.4 was dropped in v2.3.2 to leverage modern features like named arguments and attributes, improving performance and maintainability. If you’re on an older Laravel version, consider alternatives like `vlucas/phpdox` or `ocramius/proxy-manager` for legacy syntax highlighting.
- Can I use spatie/shiki-php without Node.js in production? What are the alternatives?
- No, the package requires Node.js v20+ and the `shiki` npm package to function. If Node.js isn’t available (e.g., serverless or Docker containers), you’ll need to install it during deployment or use a fallback like `highlight.js` via PHP’s `highlight_string()` function. For Docker, include Node.js in your image or use a multi-stage build to vendor `node_modules/shiki`.
- How do I highlight Blade or Antlers templates with custom line styling (e.g., for tutorials)?
- Use the `highlight()` method with the `language` parameter set to `'blade'` or `'antlers'`. For line-specific styling, pass an array to `highlightLines`, `addLines`, or `deleteLines` in the options. Example: `Shiki::highlight($code, 'blade', 'github-light', ['highlightLines' => [5, 10]])`. This works for both standalone usage and Laravel Markdown integration.
- Is there a way to cache Shiki highlights to improve performance in high-traffic Laravel apps?
- The package doesn’t include built-in caching, but you can wrap `Shiki::highlight()` calls in Laravel’s cache (e.g., `Cache::remember()`) or use Redis. Cache keys should include the code, language, and theme to avoid redundant Node process spawning. For queueing, dispatch a job with the highlight payload and store the result in the database or cache before rendering.
- How do I add a custom theme or language to spatie/shiki-php? What’s the validation process?
- Custom themes require valid VSCode JSON files placed in `resources/themes/`. Use the `getAvailableThemes()` method to verify compatibility. For languages, extend Shiki’s npm package and rebuild it, then update the PHP package’s dependencies. Test customizations with `Shiki::getAvailableLanguages()` and handle errors gracefully (e.g., fallback to a default theme).
- What happens if Node.js or the shiki npm package is missing during a Laravel request?
- The package throws a `RuntimeException` if Node.js or `shiki` isn’t found. Implement a fallback mechanism, like returning plain-text code or using PHP’s `highlight_string()`, in your error handler. Example: `try { Shiki::highlight(...); } catch (Exception $e) { return highlight_string($code, true); }`. This ensures graceful degradation.
- Can I use spatie/shiki-php with league/commonmark without spatie/laravel-markdown?
- Yes, use the companion package `spatie/commonmark-shiki-highlighter`, which integrates Shiki into `league/commonmark`. Install it via Composer and register the `ShikiHighlighter` extension in your CommonMark environment. This works for static sites, APIs, or any project using CommonMark, not just Laravel.
- Are there performance concerns with large code blocks (e.g., 50KB+ files) in production?
- Historically, large code blocks could cause `proc_open()` failures, but this was fixed in v2.3.3 by streaming input via `stdin`. For extreme cases, pre-process code into smaller chunks or use a queue system to offload highlighting. Monitor Node process memory usage and consider reducing the number of concurrent highlights under high load.
- How do I deploy spatie/shiki-php in a Docker environment without Node.js installed?
- Install Node.js v20+ in your Dockerfile (e.g., `FROM node:20-alpine`) and run `npm install -g shiki` during the build phase. For production, vendor `node_modules/shiki` into your PHP container or use a multi-stage build to avoid bloating the final image. Example: `RUN npm install shiki && npm install --production && npm prune --production`.
Weaver
How can I help you explore Laravel packages today?