Cube Common Develop Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev cubetools/cube-common-develop
   

   Ensure your project uses PHP 7.2+ and Symfony 4.3+ (due to compatibility updates in WebTestBase).

2. First Use Case:

   • Pre-commit Hooks: Run check-commit-cube.sh to validate commits for:
     • XLIFF file ordering
     • Twig template usage (e.g., avoiding .format())
     • Email address formatting
     • Controller action structure
   • Test Base Classes: Extend SmoketestPageLoadingBase for Selenium-like tests:

     use CubeTools\CommonDevelop\Test\SmoketestPageLoadingBase;
     
     class MyTest extends SmoketestPageLoadingBase {
         protected function setUp(): void {
             $this->loadPage('/dashboard');
         }
     }
     

3. Key Files:

   • vendor/bin/check-commit-cube: CLI tool for commit validation.
   • src/Test/SmoketestPageLoadingBase.php: Base for integration tests.

Implementation Patterns

1. Test Automation

• Smoke Tests: Use SmoketestPageLoadingBase for UI tests with built-in failure tracebacks:

  $this->assertPageLoaded()
       ->assertElementPresent('css', '.dashboard-header');
  

• Route Validation: Extend SymfonyLoadableTest to verify all routes are accessible:

  $this->assertRouteLoaded('/admin', 200);
  

2. Code Quality Checks

• Pre-commit Hooks: Integrate check-commit-cube.sh into Git hooks (e.g., .git/hooks/pre-commit):

  #!/bin/bash
  vendor/bin/check-commit-cube --since HEAD~1
  

  • Flags violations like binary files or Twig anti-patterns.

• Twig Template Validation: Use the check-twig-templates.sh script (beta) to enforce:

  • No .format() filters.
  • Consistent template naming.

3. Service Container

• Tagged Iterators: Configure service.yaml to support tagged services:

  services:
    App\Service\MyService:
      tags: ['my.tag']
  

  Access via:

  $container->get('my.tag')->getIterator();
  

4. CI/CD Integration

• GitHub Actions: Add a step to run checks on PRs:

  - name: Run CUBE Checks
    run: vendor/bin/check-commit-cube --since ${{ github.event.pull_request.base.sha }}
  

Gotchas and Tips

Pitfalls

1. Symfony 4.3+ Requirement:

   • Older versions may break WebTestBase compatibility. Update Symfony if tests fail:

     composer require symfony/*:^4.3
     

2. XLIFF File Handling:

   • check-commit-cube may fail if .xliff files are out of order. Use the reorder-xliff.sh script:

     vendor/bin/reorder-xliff.sh src/Resources/translations/
     

3. Pre-commit Hooks:

   • Ensure check-commit-cube.sh has executable permissions:

     chmod +x vendor/bin/check-commit-cube
     

4. PHPUnit 7+:

   • If using PHPUnit 7+, ensure phpunit.xml config matches:

     <phpunit bootstrap="vendor/autoload.php">
       <extensions>
         <extension class="CubeTools\CommonDevelop\Test\PHPUnit\Extensions\SmoketestExtension"/>
       </extensions>
     </phpunit>
     

Debugging Tips

• Test Failures:

  • Enable verbose output in SmoketestPageLoadingBase by setting:

    $this->setVerbose(true);
    

  • Check failureMessage for tracebacks.

• Service Container Issues:

  • Validate service.yaml tags with:

    vendor/bin/check-commit-cube --container
    

Extension Points

1. Custom Checks:

   • Extend check-commit-cube.sh by adding new rules in src/Check/Rule/.
   • Example: Add a rule for custom Twig filters.

2. Test Extensions:

   • Override SmoketestPageLoadingBase methods (e.g., assertPageLoaded()) for project-specific assertions.

3. PHPStan Integration:

   • Update phpstan.neon to include CubeTools’ rules:

     includes:
       - vendor/cubetools/cube-common-develop/phpstan.neon