Twigcs Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (if still accessible):

   composer require allocine/twigcs
   

   Note: Since the package is archived, verify compatibility with your Twig/Laravel version.

2. Basic Usage Integrate TwigCS into your Laravel project by extending your existing Twig environment:

   // In a service provider (e.g., AppServiceProvider)
   $twig = $this->app['view.factory'];
   $twig->getCompiler()->addExtension(new \Allocine\TwigCS\TwigCS());
   

3. First Use Case Use TwigCS to validate a template file (e.g., resources/views/email.blade.php):

   php artisan twigcs:check resources/views/email.blade.php
   

   Outputs errors/warnings in a structured format.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Add TwigCS to your build process (e.g., GitHub Actions, GitLab CI):

   # Example GitHub Actions step
   - name: Run TwigCS
     run: php artisan twigcs:check resources/views/
   

2. Pre-Commit Hooks Use husky or pre-commit to run TwigCS before commits:

   # .husky/pre-commit
   php artisan twigcs:check resources/views/
   

3. Laravel Mix/Webpack Integrate TwigCS with frontend tooling by running checks during npm run dev/build:

   // webpack.mix.js
   mix.scripts([...], 'public/js/app.js')
     .then(() => {
       require('child_process').execSync('php artisan twigcs:check resources/views/');
     });
   

Common Patterns

• Template Inheritance Validation Ensure all extends directives reference valid base templates:

  {# resources/views/child.blade.php #}
  @extends('layouts.app') {# TwigCS will flag if 'layouts.app' doesn't exist #}
  

• Variable Usage Checks Detect unused variables or undefined variables in templates:

  {# TwigCS will warn if `$user` is not passed to the template #}
  <p>Hello, {{ $user->name }}!</p>
  

Gotchas and Tips

Pitfalls

1. False Positives

   • TwigCS may flag dynamic template names (e.g., @extends($layout)) as invalid. Exclude such cases via config:

     // config/twigcs.php (if available)
     'ignore_dynamic_extends' => true,
     

   • Workaround: Use @php blocks for dynamic includes if needed.

2. Blade vs. Twig Confusion

   • The package targets Twig syntax, not Blade. Mixed syntax (e.g., @if in Twig templates) may cause errors.
   • Tip: Stick to Twig syntax ({% if %}) or use Blade directives consistently.

3. Performance Overhead

   • Running TwigCS on large template directories can be slow. Cache results or run selectively:

     php artisan twigcs:check resources/views/partials --cache
     

Debugging

• Verbose Output Enable debug mode for detailed errors:

  php artisan twigcs:check --verbose resources/views/
  

• Custom Rules Extend TwigCS by creating a custom rule (if the package supports it):

  // app/Rules/NoHardcodedUrls.php
  use Allocine\TwigCS\Rule\AbstractRule;
  
  class NoHardcodedUrls extends AbstractRule {
      public function check(Node $node) {
          // Custom logic to detect hardcoded URLs
      }
  }
  

  Note: Check the package’s Rule namespace for extension points.

Configuration Quirks

• Excluded Directories Configure exclusions in config/twigcs.php (if available):

  'exclude' => [
      'resources/views/vendor/*',
      'resources/views/archived/*',
  ],
  

• Custom Template Paths Override default paths (e.g., for custom view locations):

  php artisan twigcs:check /path/to/custom/views --paths=/path/to/another
  

Extension Points

1. Custom Error Formatting Override the error formatter to integrate with Laravel’s notification system:

   // app/Providers/TwigCSServiceProvider.php
   $twigcs = new \Allocine\TwigCS\TwigCS();
   $twigcs->setErrorFormatter(new CustomErrorFormatter());
   

2. Integration with Laravel Debugbar Display TwigCS results in the Debugbar panel:

   // app/Providers/AppServiceProvider.php
   Debugbar::extend('twigcs', function() {
       return new TwigCSCollector();
   });