Makefiles Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require wyrihaximus/makefiles
   

   This package generates a Makefile in your project root, providing standardized build blocks for common Laravel development tasks.

2. First Use Case: Run make in your terminal to see available commands. Key starter commands include:

   make all          # Run all QA checks (static analysis, tests, code style)
   make test         # Run unit tests
   make cs           # Run code style checks (PHP-CS-Fixer)
   make cs-fix       # Auto-fix code style issues
   

3. Where to Look First:

   • Makefile: Auto-generated in your project root. Customize by overriding variables or adding new rules.
   • composer.json: Configure supported features (e.g., disable code-style or unit-tests) under "extra.wyrihaximus.supported-features".
   • etc/ directory: Contains config files for tools like PHPStan, PHP-CS-Fixer, and InfectionPHP (auto-generated or manually editable).

Implementation Patterns

Core Workflows

1. Docker Integration

• Pattern: Use Docker for isolated environments. The package auto-detects Docker and mounts the socket when needed (e.g., for test containers).
• Example:

  # Auto-generated Docker rule (override in your Makefile)
  DOCKER_RUN ?= docker run --rm -v $(PWD):/app -w /app $(DOCKER_OPTS)
  

• Laravel-Specific Tip: Use DOCKER_OPTS to pass Laravel-specific flags (e.g., --network=host for database access):

  DOCKER_OPTS += --network=host
  

2. QA Pipeline Customization

• Pattern: Extend or disable QA checks via composer.json:

  {
    "extra": {
      "wyrihaximus": {
        "supported-features": {
          "static-analysis": false,  // Disable PHPStan
          "unit-tests": true,
          "code-style": true
        }
      }
    }
  }
  

• Laravel Use Case: Disable static-analysis for legacy projects or enable windows support if using WSL.

3. Task Composition

• Pattern: Chain commands for complex workflows. Example: Run tests + mutation testing:

  test-with-mutations:
      $(MAKE) test
      $(MAKE) infection
  

• Laravel-Specific: Add Laravel-specific tasks like:

  migrate:
      $(DOCKER_RUN) php artisan migrate --env=testing
  

4. Configuration Management

• Pattern: Override tool configs in etc/. Example: Customize PHPStan (etc/phpstan.neon):

  includes:
      - vendor/laravel/framework/src/Rules
  

• Laravel Integration: Exclude Laravel-specific paths from static analysis:

  excludeFiles:
      - vendor/laravel/**
      - storage/**
  

5. Interactive Debugging

• Pattern: Use make shell for an interactive Docker shell with all dependencies pre-installed:

  make shell
  

• Laravel Tip: Preload Laravel environment variables:

  shell:
      $(DOCKER_RUN) bash -c "source .env && bash"
  

Integration Tips

• Artisan Commands: Proxy Laravel Artisan commands through Docker:

  artisan:
      $(DOCKER_RUN) php artisan $@
  

• Database Tasks: Use Docker for database-heavy tasks (e.g., seeding):

  db-seed:
      $(DOCKER_RUN) php artisan db:seed --class=UserTableSeeder
  

• CI/CD: Leverage make all in GitHub Actions or GitLab CI for standardized QA:

  # .github/workflows/ci.yml
  jobs:
    test:
      runs-on: ubuntu-latest
      steps:
        - run: make all
  

Gotchas and Tips

Pitfalls

1. Docker Socket Overhead:

   • Issue: Mounting the Docker socket (--privileged) can slow down builds.
   • Fix: Only enable it for tasks requiring it (e.g., test containers):

     DOCKER_OPTS ?= $(if $(filter test-container%,$(MAKECMDGOALS)),--privileged,)
     

2. Config File Conflicts:

   • Issue: Auto-generated configs (e.g., etc/phpstan.neon) may conflict with manual edits.
   • Fix: Use make cs-fix-debug to inspect conflicts before applying fixes.

3. ZTS (Zend Thread Safety) Quirks:

   • Issue: Some tools (e.g., OpenTelemetry) fail on ZTS PHP builds.
   • Fix: Disable ZTS-specific features in composer.json:

     "extra": {
       "wyrihaximus": {
         "supported-features": {
           "zts": false
         }
       }
     }
     

4. Windows Support:

   • Issue: Windows-specific paths (e.g., C:\) break Makefile rules.
   • Fix: Explicitly disable Windows support:

     "supported-features": {
       "windows": false
     }
     

5. Dependency Bloat:

   • Issue: make all installs all dev dependencies, even if unused.
   • Fix: Use composer require --dev selectively or override the on-install-or-update rule.

Debugging Tips

• Verbose Output: Add VERBOSE=1 to see raw commands:

  VERBOSE=1 make test
  

• Dry Runs: Test Docker commands locally before CI:

  make test DOCKER_OPTS="--entrypoint=sh -c 'echo $$(which php)'"
  

• Log Inspection: Check etc/qa/ logs for tool-specific errors (e.g., phpstan.log).

Extension Points

1. Custom Rules:

   • Add project-specific rules to your Makefile:

     deploy:
         $(DOCKER_RUN) php artisan deploy
     

   • Ensure they depend on on-install-or-update for dependency setup:

     deploy: on-install-or-update
     

2. Tool Overrides:

   • Replace default tools (e.g., PHPStan) by overriding paths:

     PHPSTAN_BIN ?= ./vendor/bin/custom-phpstan
     

3. Environment Variables:

   • Pass Laravel-specific env vars to Docker:

     DOCKER_ENV += APP_ENV=testing DB_CONNECTION=sqlite_test
     

4. Git Hooks:

   • Integrate with Laravel’s Git hooks by adding Makefile targets:

     pre-commit:
         $(MAKE) cs-fix
         $(MAKE) test-unit
     

Laravel-Specific Quirks

• Laravel Mix: Disable if using Vite:

  "supported-features": {
    "code-style": { "exclude": ["resources/js"] }
  }
  

• Pest Integration: Override test commands for Pest:

  test:
      $(DOCKER_RUN) ./vendor/bin/pest
  

• Forge/Sail: Use Docker socket for Sail:

  sail-up:
      docker-compose -f docker-compose.yml up -d
  sail-test:
      $(MAKE) test DOCKER_OPTS="--network=laravel"