Lesserphp Laravel Package

Getting Started

Minimal Setup

1. Installation Update Composer to require PHP 7.2+ and install the package:

   composer require marcusschwarz/lesserphp --update-with-dependencies
   

   Register the service provider in config/app.php (if not auto-discovered):

   'providers' => [
       // ...
       MarcusSchwarz\LesserPhp\LesserPhpServiceProvider::class,
   ],
   

2. Basic Compilation Use the facade for LESS-to-CSS conversion (PHP 8+ compatible):

   use MarcusSchwarz\LesserPhp\Facades\LesserPhp;
   
   $css = LesserPhp::compile('body { color: #fff; }');
   

3. First Use Case: Dynamic Styling Compile LESS files with PHP 8 type safety:

   $userTheme = User::find($id)->theme;
   $compiledCss = LesserPhp::compileFile(storage_path("themes/{$userTheme}.less"));
   

Implementation Patterns

Workflows

1. PHP 8+ Optimizations Leverage PHP 8 features for cleaner integration:

   // Type-hinted compiler options
   $compiler = new \MarcusSchwarz\LesserPhp\Compiler();
   $compiler->setOptions(['paths' => [base_path('resources/less')], 'strictMath' => true]);
   

2. Asset Pipeline Integration Extend Laravel Mix with PHP 8-compatible Webpack config:

   // webpack.mix.js
   mix.less('resources/less/app.less', 'public/css', {
       less: {
           paths: [path.resolve(__dirname, 'resources/less')],
           strictMath: true // PHP 8+ feature
       }
   });
   

3. Caching with PHP 8 Attributes Use PHP 8 attributes for cache key generation:

   #[Cacheable]
   public function getCompiledTheme(string $theme): string {
       return cache()->remember("less:{$theme}", now()->addHours(1), fn() =>
           LesserPhp::compileFile(storage_path("themes/{$theme}.less"))
       );
   }
   

Integration Tips

• Blade Directives with PHP 8 Update Blade directives to support typed expressions:

  // AppServiceProvider.php
  Blade::directive('less', function (string $expression) {
      return "<?php echo \\MarcusSchwarz\\LesserPhp\\Facades\\LesserPhp::compile($expression); ?>";
  });
  

  Usage remains identical but now benefits from PHP 8's stricter type checking.

• Dynamic Imports with PHP 8 Match Use PHP 8's match expression for cleaner conditional imports:

  $lessImports = match(auth()->user()->role) {
      'admin' => '@import "admin.less";',
      'user' => '@import "user.less";',
      default => '',
  };
  $compiled = LesserPhp::compile($lessImports, $userLessContent);
  

Gotchas and Tips

Pitfalls

1. PHP Version Requirement

   • Breaking Change: Minimum PHP version is now 7.2 (dropped PHP 5.x support).
   • Fix: Update your server environment or use a container (e.g., Docker with php:7.4-apache).

2. Performance with PHP 8

   • PHP 8's JIT compiler may improve compilation speed, but test under load.
   • Tip: Use strictMath: true in options for consistent results across PHP versions.

3. Path Resolution Quirks

   • PHP 8's stricter type system may expose path resolution issues.
   • Fix: Always use absolute paths or configure paths explicitly:

     LesserPhp::setOptions([
         'paths' => [base_path('resources/less')],
         'strictMath' => true,
     ]);
     

4. Deprecated Features

   • Some LESS features (e.g., ~"variables") may behave differently in PHP 8.
   • Tip: Test with @import "strict-math.less"; to catch issues early.

Debugging

• PHP 8 Error Handling Use PHP 8's try-catch with specific exceptions:

  try {
      $css = LesserPhp::compile($less);
  } catch (\MarcusSchwarz\LesserPhp\Exception\ParseError $e) {
      report($e); // Laravel's error reporting
      $css = file_get_contents(storage_path('fallback.css'));
  }
  

• Enable Strict Mode Configure the compiler for stricter parsing:

  LesserPhp::setOptions(['strictImports' => true, 'strictMath' => true]);
  

Extension Points

1. PHP 8 Callable Syntax Register LESS functions with PHP 8's modern syntax:

   LesserPhp::addFunction('darken', static fn (array $args): string => {
       return 'rgba(0, 0, 0, 0.1)';
   });
   

2. Pre/Post-Processing with PHP 8 Use arrow functions for concise preprocessing:

   $compiler = new \MarcusSchwarz\LesserPhp\Compiler();
   $compiler->setPreProcessor(fn (string $less) => str_replace('$var', 'red', $less));
   $css = $compiler->compile($less);
   

3. Fallback with PHP 8 Attributes Implement fallback logic with attributes:

   #[FallbackCss(path: 'fallback.css')]
   public function compileWithFallback(string $less): string {
       try {
           return LesserPhp::compile($less);
       } catch (\Exception) {
           return file_get_contents(storage_path('fallback.css'));
       }
   }