Shiki Php Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Leverages Shiki.js: Integrates with the industry-standard Shiki syntax highlighter (used by VS Code, GitHub, etc.), ensuring high-quality, maintainable, and extensible syntax highlighting.
  • Laravel-Native: Designed with Laravel in mind (via spatie/laravel-markdown), reducing friction for Laravel-based projects. Supports Blade and Antlers out of the box, which are critical for Laravel templating.
  • Theming Flexibility: Supports 100+ built-in themes (including GitHub’s) and custom VS Code themes, enabling consistent branding across applications.
  • Line-Specific Styling: Allows highlighting, adding, deleting, or focusing lines—useful for diff views, tutorials, or collaborative editing features.
  • Performance Optimized: Handles large code blocks efficiently (via stdin input in v2.3.3) and includes speed improvements (e.g., v1.0.2).

• Cons:

  • Node.js Dependency: Requires Node.js (≥20) and shiki as an npm package, adding complexity to PHP-only deployments (e.g., serverless, Docker containers without Node).
  • External Process Overhead: Relies on proc_open() to invoke Node.js, which introduces latency (~50–200ms per highlight call) and potential failure modes (e.g., Node not found, permission issues).
  • No Caching Layer: Repeated calls for identical code blocks will reprocess them, unlike client-side solutions (e.g., Shiki.js in the browser).

Integration Feasibility

• Laravel Ecosystem:
  • Seamless integration with spatie/laravel-markdown for Markdown-based applications (e.g., documentation, blogs).
  • Compatible with spatie/commonmark-shiki-highlighter for CommonMark parsers.
  • Blade templates can directly embed highlighted code via @highlight directives or custom components.
• Vanilla PHP:
  • Works in non-Laravel PHP projects (since v2.1.0), but requires manual setup (e.g., Node.js path configuration).
• Frontend Frameworks:
  • Output is HTML/CSS, so it can be rendered in any frontend (React, Vue, etc.) or embedded in emails (via Laravel’s Mailable classes).

Technical Risk

• Node.js Dependency Risks:
  • Version Mismatches: Node.js ≥20 is required; older environments (e.g., shared hosting) may not support this.
  • Path Configuration: NVM users or custom Node installations may need symlinks (e.g., /usr/local/bin/node), adding DevOps overhead.
  • Security: Node.js processes run with PHP’s permissions; misconfigurations could expose the system (e.g., if shiki has vulnerabilities).
• Performance:
  • Highlighting large files (e.g., 10KB+) may hit proc_open() limits (mitigated in v2.3.3 but still a risk for edge cases).
  • No built-in caching; repeated highlights (e.g., in loops) will reprocess identically.
• Failure Modes:
  • If Node.js fails to execute, the package throws exceptions (e.g., RuntimeException). Graceful fallbacks (e.g., plain-text output) are not built-in.
  • Custom themes require valid JSON paths; invalid paths will break highlighting.

Key Questions

1. Deployment Constraints:
   • Can Node.js ≥20 be installed/configured in the target environment (e.g., serverless, Docker, shared hosting)?
   • Are there restrictions on proc_open() or external process execution?
2. Performance Requirements:
   • How often will highlighting occur? (e.g., per-request vs. pre-rendered content).
   • Are there large code blocks (e.g., >10KB) that could hit proc_open() limits?
3. Theming/Customization:
   • Will custom themes be used? If so, how will paths be managed (e.g., asset storage, versioning)?
4. Fallback Strategy:
   • Should there be a fallback (e.g., plain-text or client-side highlighting) if Node.js fails?
5. Caching:
   • Is there a need to cache highlighted output (e.g., Redis) for repeated requests?
6. Testing:
   • How will Node.js availability be tested in CI/CD (e.g., Docker containers, local dev)?

Integration Approach

Stack Fit

• Best Fit:
  • Laravel Applications: Ideal for projects using spatie/laravel-markdown, Blade templates, or CommonMark (via spatie/commonmark-shiki-highlighter).
  • Documentation/DevPortals: Perfect for rendering code snippets in Markdown (e.g., Laravel Nova, Forge docs).
  • Educational Tools: Useful for tutorials with line-specific annotations (e.g., "highlighted" or "deleted" lines).
• Partial Fit:
  • Vanilla PHP: Works but requires manual Node.js setup and lacks Laravel’s integration helpers.
  • Headless APIs: Possible but inefficient (Node.js overhead per request).
• Poor Fit:
  • Browser-Based Apps: Client-side Shiki.js would be more performant.
  • High-Performance Systems: Latency from proc_open() may be prohibitive (e.g., real-time IDE plugins).

Migration Path

1. Assess Node.js Compatibility:

   • Verify Node.js ≥20 is available in all environments (dev, staging, prod).
   • For Docker, include Node.js in the image:

     FROM php:8.2-cli
     RUN apt-get update && apt-get install -y nodejs npm
     RUN npm install -g shiki@latest
     

   • For NVM users, document symlink creation (e.g., /usr/local/bin/node → ~/.nvm/versions/node/v20.x/bin/node).

2. Install Dependencies:

   • Composer:

     composer require spatie/shiki-php
     

   • Node.js:

     npm install shiki
     

   • For Laravel, install spatie/laravel-markdown if using Markdown:

     composer require spatie/laravel-markdown
     

3. Configuration:

   • Laravel: Publish config (if any) and bind the Shiki service in AppServiceProvider:

     $app->singleton(\Spatie\ShikiPhp\Shiki::class, fn() => new \Spatie\ShikiPhp\Shiki());
     

   • Vanilla PHP: Ensure Node.js path is detectable (default paths are /usr/local/bin/node or /opt/homebrew/bin/node).

4. Implementation:

   • Blade Templates: Create a helper or directive:

     // app/Helpers/CodeHelper.php
     function highlightCode($code, $language = 'php', $theme = 'github-light') {
         return \Spatie\ShikiPhp\Shiki::highlight($code, $language, $theme);
     }
     

     {!! highlightCode('<?php echo "Hello"; ?>') !!}
     

   • Markdown: Use spatie/laravel-markdown with Shiki extension:

     use Spatie\Markdown\MarkdownRenderer;
     $renderer = new MarkdownRenderer();
     $renderer->useShikiHighlighter();
     echo $renderer->toHtml('# Title with `code`');
     

   • CommonMark: Integrate spatie/commonmark-shiki-highlighter.

5. Testing:

   • Mock Node.js failures in tests:

     $shiki = Mockery::mock(\Spatie\ShikiPhp\Shiki::class)->shouldReceive('highlight')->andThrow(new \RuntimeException('Node failed'))->getMock();
     

   • Test edge cases:
     • Large code blocks (>10KB).
     • Custom themes (invalid paths).
     • Unsupported languages.

Compatibility

• Laravel:
  • ✅ Full compatibility with Laravel 8+ (PHP 8.0+).
  • ✅ Works with spatie/laravel-markdown and spatie/commonmark-shiki-highlighter.
• PHP Versions:
  • ✅ PHP 8.0+ (PHP 7.4 dropped in v2.3.2).
• Node.js:
  • ✅ Node.js ≥20 required (hard dependency).
• Frontend:
  • ✅ Output is HTML/CSS; works with any frontend (React, Vue, etc.).
  • ⚠️ Ensure CSS classes (e.g., .shiki) are not overridden by global styles.

Sequencing

1. Phase 1: Setup (1–2 days):
   • Install Node.js and shiki in all environments.
   • Configure Node.js paths (if using NVM/custom installs).
   • Add Composer dependencies.
2. Phase 2: Integration (2–3 days):
   • Implement highlighting in Blade/Markdown/