Phpqatools Laravel Package

Getting Started

Minimal Steps for Laravel Integration

1. Install the Package: Add to composer.json under require-dev:

   "covex-nn/phpqatools": "~2.0"
   

   Run:

   composer install
   

2. Copy Configuration Files: Copy the provided XML configs from the package to your project root:

   cp vendor/covex-nn/phpqatools/phpcs.xml .
   cp vendor/covex-nn/phpqatools/phpunit.xml .
   cp vendor/covex-nn/phpqatools/phpmd.xml .
   

3. Create Ant Build Files: Create build.xml (minimal template):

   <?xml version="1.0" encoding="utf-8"?>
   <project name="YourProject" default="init">
       <target name="init">
           <echo message="Build initialized"/>
       </target>
   </project>
   

   Create build-dev.xml (importing QA tools):

   <?xml version="1.0" encoding="utf-8"?>
   <project name="YourProject-QA" default="init">
       <import file="build.xml"/>
       <import file="vendor/covex-nn/phpqatools/build.xml"/>
   </project>
   

4. Run QA Tools via Ant: Execute the CI build:

   ant -f build-dev.xml CI-build
   

   Skip tools by setting properties (e.g., CI.no-phpcs=1).

5. Laravel-Specific Workaround: Since Ant isn’t Laravel-native, create a Composer script in composer.json to proxy Ant calls:

   "scripts": {
       "qa:run": "ant -f build-dev.xml CI-build",
       "qa:phpunit": "ant -f build-dev.xml -D CI.no-phpunit=0 -D CI.no-others=1"
   }
   

   Run with:

   composer qa:run
   

Implementation Patterns

Workflows for Laravel Developers

1. CI/CD Integration:

   • GitHub Actions Example:

     - name: Run QA Tools
       run: composer qa:run
     

   • GitLab CI Example:

     test:qa:
       script:
         - composer qa:run
       rules:
         - if: '$CI_COMMIT_BRANCH == "main"'
     

2. Task Automation:

   • Artisan Command Wrapper (for Laravel 8+): Create a custom command to execute QA tools:

     php artisan make:command QaRun
     

     Update app/Console/Commands/QaRun.php:

     public function handle()
     {
         $this->call('vendor:publish', ['--provider' => 'Covex\\PhpQaTools\\ServiceProvider']);
         Artisan::call('vendor:qa-run'); // Hypothetical; requires package extension
     }
     

     Note: The package lacks Laravel integration—this requires forking or custom scripting.

3. Partial Adoption:

   • Use only PHP_CodeSniffer for static analysis:

     composer require --dev squizlabs/php_codesniffer
     vendor/bin/phpcs --standard=PSR12 src/
     

   • Replace PHPUnit v4 with Laravel’s default:

     composer require --dev phpunit/phpunit "^9.5"
     

4. Configuration Customization:

   • Extend phpcs.xml to include Laravel-specific rules:

     <rule ref="PSR12">
         <exclude name="PSR12.Files.SideEffectsStatement.Missing"/>
     </rule>
     

   • Override PHPUnit bootstrap in phpunit.xml:

     <php>
         <server name="APP_ENV" value="testing"/>
         <env name="DB_CONNECTION" value="sqlite"/>
     </php>
     

Gotchas and Tips

Pitfalls

1. Phar Execution Issues:

   • Symlink Problems: Phar files may fail if open_basedir restricts paths. Fix with:

     docker-php-ext-install phar
     

   • Read-Only Phar: Enable Phar execution in php.ini:

     phar.readonly = Off
     

2. Tool Version Conflicts:

   • PHPUnit v4 vs. Laravel 8+: Tests will fail due to incompatible assertions (e.g., assertContains syntax). Solution: Use phpunit/phpunit:^9.5 instead.
   • PHP_CodeSniffer v2: Lacks PSR-12 support. Solution: Upgrade to squizlabs/php_codesniffer:^3.7.

3. Ant Dependency:

   • Ant Not Installed: Requires Java. Solution: Use a Composer script or Makefile as a fallback:

     qa:
         @php vendor/bin/phpunit
         @php vendor/bin/phpcs --standard=PSR12 src/
     

4. Configuration Overrides:

   • XML Configs Ignored: Tools may use hardcoded paths in Phar files. Solution: Set include_path in php.ini or use absolute paths in configs.

5. Performance Overhead:

   • Phar Bootstrapping: Adds ~2–5 seconds per tool run. Solution: Cache results or run tools in parallel (e.g., php-parallel-lint).

Debugging Tips

1. Log Tool Output: Redirect Ant output to a file:

   ant -f build-dev.xml CI-build > qa.log 2>&1
   

   Parse logs for errors like:

   [phpcs] Warning: The file ... was encoded with encoding "UTF-8" but contains BOM.
   

2. Isolate Tool Failures: Run tools individually:

   vendor/bin/phpunit --version  # Check PHPUnit v4
   vendor/bin/phpcs --version    # Check PHP_CodeSniffer v2
   

3. Fork and Modernize: Fork the repo to update dependencies:

   git clone https://github.com/covex-nn/phpqatools.git
   composer require phpunit/phpunit "^9.5"
   composer require squizlabs/php_codesniffer "^3.7"
   

Extension Points

1. Custom Ant Tasks: Extend build.xml to add Laravel-specific tasks:

   <target name="migrate:fresh">
       <exec executable="php" output="migrate.log">
           <arg value="artisan"/>
           <arg value="migrate:fresh"/>
       </exec>
   </target>
   

2. Composer Script Hooks: Add pre-commit checks:

   "scripts": {
       "pre-commit": "composer qa:phpcs",
       "qa:phpcs": "vendor/bin/phpcs --standard=PSR12 src/"
   }
   

3. Laravel Service Provider: Hypothetical: Register QA tools as Laravel services (requires package modification):

   // config/app.php
   'providers' => [
       Covex\PhpQaTools\ServiceProvider::class,
   ],
   

   Note: The package lacks this feature—forking is required.

Laravel-Specific Quirks

1. Database Testing: PHPUnit v4 may fail with Laravel’s database transactions. Solution: Use Laravel’s refreshDatabase() in tests.

2. Artisan Command Conflicts: Tools like phpmd may clash with Laravel’s php binary. Solution: Use full paths:

   /usr/local/bin/php vendor/bin/phpmd src/ text phpmd.xml
   

3. Docker Compatibility: Ensure Dockerfile includes:

   RUN docker-php-ext-install phar
   WORKDIR /var/www
   COPY vendor/ /var/www/vendor/