Lint Pack Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require ajgon/lint-pack:1.2.*@dev
   

   Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 2/3):

   Ajgon\LintPackBundle\LintPackBundle::class => ['all' => true],
   

2. Basic Configuration: Add minimal config to config/packages/lint_pack.yaml (Symfony 4+) or app/config/config.yml (Symfony 2/3):

   lint_pack:
       phpcs:
           locations:
               - "%kernel.project_dir%/src"
   

3. First Use Case: Run a linter via console:

   php bin/console lint:phpcs
   

Where to Look First

• Documentation: Focus on the README.md for linter-specific configurations.
• Commands: List available linters with php bin/console lint.
• Default Locations: Linters default to scanning %kernel.root_dir% and %kernel.root_dir%/../src. Override via locations.

Implementation Patterns

Common Workflows

1. Integrate into CI/CD: Add linting to your pipeline (e.g., GitHub Actions, GitLab CI):

   # Example GitHub Actions step
   - name: Run PHPCS
     run: php bin/console lint:phpcs --format=json > phpcs-results.json
   

2. Customize Linter Output: Use --format flags (e.g., --format=json) for machine-readable output. Parse results in PHP:

   $output = shell_exec('php bin/console lint:phpcs --format=json');
   $results = json_decode($output, true);
   

3. Combine Linters: Run multiple linters sequentially in a script:

   #!/bin/bash
   php bin/console lint:phpcs && php bin/console lint:phpmd
   

4. Dynamic Configuration: Load configurations from environment variables or services:

   # config/packages/lint_pack.yaml
   lint_pack:
       phpcs:
           standard: "%env(CODE_STANDARD)%"
   

5. Pre-Commit Hooks: Use tools like Husky to run linters before commits:

   # .husky/pre-commit
   #!/bin/sh
   php bin/console lint:phpcs --dry-run || exit 1
   

Integration Tips

• Symfony Flex: If using Symfony 4+, leverage config/packages for modular configurations.
• Docker: Mount linter binaries (e.g., csslint) into your container if not globally installed.
• Parallelization: Use tools like GNU Parallel to run linters concurrently:

  parallel --jobs 4 php bin/console lint:{} ::: phpcs phpmd phpcpd jshint
  

• Custom Linters: Extend the bundle by creating a new command (see src/Command/ in the bundle).

Gotchas and Tips

Pitfalls

1. Binary Paths:

   • Linters like csslint or jshint may not be globally installed. Specify full paths in config:

     lint_pack:
         jshint:
             bin: "/usr/local/bin/jshint"
     

   • For PHP-based linters (e.g., phpcs), use vendor/bin/ paths:

     lint_pack:
         phpcs:
             bin: "vendor/bin/phpcs"
     

2. Ignores vs. Ignore Files:

   • The ignores config (regex patterns) and jshintignore/phpcs.ignore files serve different purposes. Avoid mixing them unless intentional.
   • Example: jshintignore disables the ignores config entirely.

3. Performance:

   • Linting large codebases can be slow. Use --extensions to limit file types:

     lint_pack:
         phpcs:
             extensions: ["php", "inc"]
     

   • Exclude vendor directories explicitly:

     lint_pack:
         phpcs:
             ignores:
                 - "vendor/"
     

4. Symfony 4+ Compatibility:

   • The bundle is designed for Symfony 2/3. For Symfony 4+, ensure config/packages/ is used instead of app/config/.
   • Autowiring may not work out-of-the-box; stick to manual service registration if needed.

5. Twig Linter:

   • The twigviews linter is basic (regex-based). For advanced Twig linting, consider twig-lint.

Debugging

1. Dry Runs: Use --dry-run to test configurations without executing linters:

   php bin/console lint:phpcs --dry-run
   

2. Verbose Output: Enable debug mode for detailed logs:

   php bin/console lint:phpcs -vvv
   

3. Check Binary Availability: Validate linter binaries are accessible:

   which phpcs jshint csslint || echo "Binaries not found"
   

4. Configuration Validation: Test config snippets in isolation:

   # config/packages/test_lint_pack.yaml
   lint_pack:
       phpcs:
           locations: ["%kernel.project_dir%/src"]
           standard: "PSR12"
   

   Then run:

   php bin/console lint:phpcs --env=test
   

Extension Points

1. Custom Commands: Extend the bundle by creating a new command in src/Command/:

   namespace App\Command;
   use Ajgon\LintPackBundle\Command\AbstractLintCommand;
   
   class CustomLintCommand extends AbstractLintCommand {
       protected function configure() {
           $this->setName('lint:custom');
       }
       protected function execute(InputInterface $input, OutputInterface $output) {
           // Custom logic
       }
   }
   

2. Event Listeners: Hook into linter execution via Symfony events (e.g., console.command):

   // src/EventListener/LintListener.php
   public function onLintCommand(ConsoleCommandEvent $event) {
       if (strpos($event->getCommand()->getName(), 'lint:') === 0) {
           // Pre/post-processing
       }
   }
   

3. Override Templates: Customize output formats by overriding the bundle’s Twig templates (located in Resources/views/).

4. Add New Linters: Implement a new linter by extending AbstractLintCommand and registering it as a service:

   services:
       App\Command\NewLintCommand:
           tags: ['console.command']