Laravel Tachyon Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dotninth/laravel-tachyon
   

   Publish the config file:

   php artisan vendor:publish --provider="Dotninth\Tachyon\TachyonServiceProvider"
   

2. First Use Case: Enable Tachyon globally in config/tachyon.php:

   'enabled' => env('TACHYON_ENABLED', true),
   

   Add to your .env:

   TACHYON_ENABLED=true
   

3. Verify Integration: Run a test request and inspect the response headers for X-Tachyon-Optimized: true.

Where to Look First

• Config File: config/tachyon.php (optimization rules, exclusions, and middleware settings).
• Middleware: app/Http/Middleware/TachyonMiddleware.php (customize logic if needed).
• Blade Directives: @tachyon and @tachyonoff for granular control in views.

Implementation Patterns

Core Workflows

1. Global Optimization: Enable middleware in app/Http/Kernel.php:

   protected $middleware = [
       \Dotninth\Tachyon\Http\Middleware\TachyonMiddleware::class,
   ];
   

2. Conditional Optimization: Use Blade directives to exclude specific sections:

   @tachyonoff
       <!-- Unoptimized content (e.g., dynamic ads, user-generated HTML) -->
   @endtachyonoff
   

3. Dynamic Rules: Configure rules in config/tachyon.php:

   'rules' => [
       'remove_comments' => true,
       'collapse_whitespace' => true,
       'shorten_doctype' => true,
       'remove_processing_instructions' => true,
       'remove_cdata_sections' => true,
       'remove_xml_prolog' => true,
   ],
   

4. Livewire Integration: Exclude Livewire components from optimization by wrapping them:

   @tachyonoff
       <livewire:component />
   @endtachyonoff
   

   Or configure Livewire-specific exclusions in config/tachyon.php:

   'excluded_routes' => [
       'livewire/*',
   ],
   

5. API vs. Web Routes: Disable Tachyon for API routes in config/tachyon.php:

   'excluded_routes' => [
       'api/*',
   ],
   

Integration Tips

• Caching: Leverage Laravel’s cache to avoid reprocessing identical HTML (Tachyon supports this out of the box).
• Testing: Use php artisan tachyon:test to validate optimizations on a specific route.
• Debugging: Enable debug mode in config to log optimization steps:

  'debug' => env('TACHYON_DEBUG', false),
  

• Custom Rules: Extend the optimizer by creating a custom rule class and registering it in the config:

  'custom_rules' => [
      \App\Rules\CustomHtmlRule::class,
  ],
  

Gotchas and Tips

Pitfalls

1. Over-Optimization:

   • Issue: Aggressive minification (e.g., removing whitespace) may break layouts relying on CSS/JS dependencies.
   • Fix: Test thoroughly with tools like HTML Validator and disable rules incrementally if issues arise.

2. Livewire/Alpine Conflicts:

   • Issue: Optimizing dynamic content (e.g., Livewire wire:model bindings) can corrupt functionality.
   • Fix: Explicitly wrap dynamic components in @tachyonoff or exclude their routes.

3. Caching Headaches:

   • Issue: Optimized HTML may not update until cache is cleared.
   • Fix: Use php artisan cache:clear or configure cache tags for granular control.

4. Middleware Order:

   • Issue: Tachyon must run after Blade compilation but before response sending.
   • Fix: Ensure TachyonMiddleware is placed correctly in app/Http/Kernel.php:

     // Correct order (example):
     \App\Http\Middleware\TrimStrings::class,
     \Dotninth\Tachyon\Http\Middleware\TachyonMiddleware::class,
     \Illuminate\Foundation\Http\Middleware\VerifyCsrfToken::class,
     

Debugging

1. Enable Debug Logs: Set 'debug' => true in config/tachyon.php and check storage/logs/laravel.log for optimization steps.

2. Compare Outputs: Use browser dev tools to compare optimized vs. unoptimized HTML (disable Tachyon temporarily with @tachyonoff around suspect sections).

3. Route Exclusions: If a route isn’t optimizing, verify it’s not in excluded_routes or blocked by middleware priority.

Extension Points

1. Custom Rules: Implement Dotninth\Tachyon\Contracts\HtmlRule to add bespoke optimizations:

   namespace App\Rules;
   
   use Dotninth\Tachyon\Contracts\HtmlRule;
   
   class CustomHtmlRule implements HtmlRule {
       public function process(string $html): string {
           // Custom logic (e.g., replace placeholders)
           return str_replace('{{placeholder}}', 'value', $html);
       }
   }
   

   Register in config/tachyon.php:

   'custom_rules' => [
       \App\Rules\CustomHtmlRule::class,
   ],
   

2. Event Listeners: Listen for tachyon.optimized and tachyon.failed events to log or modify behavior:

   // In EventServiceProvider
   protected $listen = [
       'Dotninth\Tachyon\Events\HtmlOptimized' => [
          \App\Listeners\LogOptimization::class,
       ],
   ];
   

3. Conditional Middleware: Dynamically enable/disable Tachyon based on request attributes (e.g., user role):

   // In TachyonMiddleware
   public function handle($request, Closure $next) {
       if (auth()->check() && auth()->user()->is_admin) {
           return $next($request);
       }
       // Proceed with optimization
   }
   

Config Quirks

1. Environment Variables: Override settings via .env:

   TACHYON_RULE_REMOVE_COMMENTS=false
   TACHYON_DEBUG=true
   

2. Performance Impact:

   • Warning: Tachyon adds ~1-5ms per request during optimization. Benchmark with php artisan tachyon:benchmark.

3. Blade Directives:

   • Note: @tachyon and @tachyonoff must be at the root level of a Blade file (not nested in other directives like @if).