Yaml Lint Laravel Package

Getting Started

First Steps

1. Installation Add the package via Composer:

   composer require --dev j13k/yaml-lint
   

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

   'providers' => [
       // ...
       J13k\YamlLint\YamlLintServiceProvider::class,
   ],
   

2. Basic Usage Run the linter directly via Artisan:

   php artisan yaml:lint path/to/file.yaml
   

   Or integrate it into your CI pipeline (e.g., GitHub Actions, GitLab CI).

3. First Use Case Validate a single YAML file (e.g., config/services.yaml):

   php artisan yaml:lint config/services.yaml
   

   Output will show syntax errors, indentation issues, or invalid keys.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline Add to phpunit.xml or .github/workflows/lint.yml:

   <php>
       <env name="YAML_LINT" value="1"/>
       <file name="config/services.yaml"/>
   </php>
   

   Or via GitHub Actions:

   - name: Lint YAML
     run: php artisan yaml:lint config/*.yaml
   

2. Pre-Commit Hook Use php artisan yaml:lint in a pre-commit script (e.g., with Laravel Pint or custom hooks):

   # .git/hooks/pre-commit
   #!/bin/bash
   php artisan yaml:lint --changed-only
   

3. Laravel Task Scheduling Schedule nightly YAML validation for critical files:

   // app/Console/Kernel.php
   protected function schedule(Schedule $schedule)
   {
       $schedule->command('yaml:lint config/*.yaml')
                ->dailyAt('23:00');
   }
   

Customization

• Exclude Files Configure exclusions in config/yaml-lint.php:

  'exclude' => [
      'vendor/**',
      'storage/logs/**',
  ],
  

• Custom Rules Extend validation via YamlLint::extend() in a service provider:

  YamlLint::extend(function ($errors, $yaml, $path) {
      if (str_contains($yaml, 'deprecated_key')) {
          $errors[] = "Key 'deprecated_key' is obsolete. Use 'new_key' instead.";
      }
  });
  

Team Collaboration

• Shared Config Store .yaml-lint.yml in the repo root for team-wide rules:

  extends: default
  rules:
    indentation: error
    line-length: disable
  

Gotchas and Tips

Common Pitfalls

1. False Positives

   • YAML comments (#) or anchors (&) may trigger false errors.
   • Fix: Whitelist known patterns in config/yaml-lint.php:

     'ignore_patterns' => [
         '/#.*/',
         '/&[a-zA-Z_]+/',
     ],
     

2. Performance

   • Linting large files (e.g., database/migrations/*.yaml) can be slow.
   • Fix: Use --parallel flag (if supported) or split files into smaller chunks.

3. Indentation Sensitivity

   • Mixing tabs/spaces may cause inconsistent errors.
   • Fix: Enforce consistent indentation in .editorconfig:

     [*.{yaml,yml}]
     indent_style = space
     indent_size = 4
     

Debugging Tips

• Verbose Output Run with -v for detailed error context:

  php artisan yaml:lint --verbose config/services.yaml
  

• Dry Run Test changes without failing the build:

  php artisan yaml:lint --dry-run
  

Extension Points

1. Custom Error Formatting Override the error renderer:

   YamlLint::setErrorRenderer(function ($errors) {
       return collect($errors)->map(function ($error) {
           return "[ERROR] Line {$error['line']}: {$error['message']}";
       })->implode(PHP_EOL);
   });
   

2. Integration with Laravel Mix Add a Webpack plugin to lint YAML during build:

   const YamlLintPlugin = require('yaml-lint-webpack-plugin');
   mix.webpackConfig({
       plugins: [
           new YamlLintPlugin({
               configFile: '.yaml-lint.yml',
           }),
       ],
   });
   

3. API Usage Use the underlying parser programmatically:

   $validator = app(YamlLint::class);
   $errors = $validator->lintString('key: value', 'inline.yaml');
   

Config Quirks

• Case Sensitivity Rules like key-names are case-sensitive in .yaml-lint.yml.
• Default Rules Override defaults explicitly to avoid surprises:

  extends: default
  rules:
    document-start: disable  # Disable if your YAML lacks `---`