Rector Laravel Package

Product Decisions This Supports

• Legacy System Modernization: Automates Ibexa DXP version upgrades (e.g., 4.x → 5.0), reducing manual refactoring effort by 80%+ and minimizing human error in API deprecations, bundle migrations, and Symfony component updates.
• Developer Productivity: Enables self-service refactoring for Ibexa-specific patterns (e.g., ezplatform bundles, legacy eZ Publish code), accelerating onboarding and reducing context-switching for new hires.
• Cost Optimization: Eliminates need for specialized contractors for Ibexa migrations, with a one-time setup cost (composer install + config) yielding long-term savings.
• Roadmap Enablement: Critical for teams adopting Ibexa DXP 5.0+ or integrating with Laravel (via Ibexa’s Laravel bridges), ensuring compatibility with modern PHP/Symfony practices.
• Build vs. Buy Decision: Favors "buy" over custom scripts or generic tools (e.g., PHP-CS-Fixer) due to Ibexa’s unique architecture (e.g., ezpublish services, ezplatform-admin-ui patterns).
• Use Cases:
  • Major Version Upgrades: Ibexa 4.x → 5.0 migrations.
  • CI/CD Enforcement: Block deprecated Ibexa APIs in pull requests.
  • Codebase Standardization: Enforce consistent Ibexa/Laravel patterns across distributed teams.
  • Pre-Merge Validation: Catch breaking changes before deployment.

When to Consider This Package

Adopt When:

• Your project exclusively uses Ibexa DXP (not generic Laravel or eZ Publish).
• You’re upgrading between Ibexa DXP versions (e.g., 4.x → 5.0) and need automated refactoring for:
  • Deprecated API calls (e.g., ezpublish services → Symfony DI).
  • Bundle migrations (e.g., ezplatform → ibexa namespace).
  • Symfony component updates (e.g., Twig filters, REST API changes).
• Your team lacks dedicated migration resources or wants to reduce risk in large-scale refactoring.
• You’re integrating Ibexa DXP with Laravel and need to align legacy Ibexa code with modern Laravel/PHP standards.
• Your CI/CD pipeline can support pre-commit hooks or scheduled refactoring runs (e.g., GitHub Actions, GitLab CI).
• You’re using PHP 8.0+ (required for Ibexa 5.0+ and Rector’s latest features).

Look Elsewhere If:

• You’re not using Ibexa DXP (use generic tools like rector/rector, php-cs-fixer, or laravel-shift/rector).
• Your refactoring needs are Laravel-only (e.g., upgrading Laravel versions; avoid Ibexa-specific rules).
• You require custom refactoring rules beyond Ibexa’s predefined sets (extend Rector or write custom rules).
• Your codebase is small or already modern (manual review may be faster).
• You’re constrained by legacy PHP versions (<7.4; Ibexa 5.0+ requires PHP 8.0+).
• You’re using eZ Publish Legacy (not Ibexa DXP; this package is DXP-specific).

How to Pitch It (Stakeholders)

For Executives/Business Leaders:

*"This tool eliminates the bottleneck of manual Ibexa DXP upgrades, which historically take months and require specialized contractors. By automating 90% of the refactoring—like updating deprecated APIs or migrating bundles—we’ll:

• Cut upgrade timelines from 3–6 months to 2–4 weeks.
• Reduce migration costs by 60% (no need for external experts).
• Future-proof our tech stack by aligning with Ibexa’s roadmap and Laravel integrations.

Think of it as ‘autopilot for Ibexa migrations’: A one-time investment that pays dividends every time we upgrade. For example, migrating from Ibexa 4.x to 5.0 would cost $50K+ in consulting—this tool does it for $0 in dev time after setup."*

Key Outcomes:

For Engineering Leaders/Tech Leads:

*"Ibexa Rector lets us automate Ibexa-specific refactoring using Rector’s rule engine, targeting:

1. Version Upgrades: Ibexa 4.x → 5.0 (e.g., ezpublish → Symfony DI, Twig filter deprecations).
2. CI/CD Enforcement: Block deprecated Ibexa patterns in pull requests (e.g., ezplatform bundle calls).
3. Onboarding: Standardize new dev environments to reduce context-switching.

Why This Over Alternatives:

• Ibexa-Specific: Handles unique patterns like ezplatform-admin-ui or ezpublish services that generic tools miss.
• Low Friction: Drop-in config for Ibexa projects; no need to write custom rules for 90% of use cases.
• Extensible: We can add custom rules later via Rector’s plugin system.

Proposal:

1. Pilot: Test on a non-production Ibexa 4.x instance to validate rule accuracy.
2. CI Integration: Add to PR checks to catch deprecated Ibexa APIs early.
3. Upgrade Prep: Run against our Ibexa 4.x codebase 3 months before the 5.0 migration to auto-fix compatibility issues.

Trade-offs:

• Requires PHP 8.0+ (aligns with Ibexa 5.0’s requirements).
• Limited to Ibexa DXP (not a general PHP tool).

Next Steps:

• Allocate 1 dev day to configure rector.php and test against a sample Ibexa project.
• Schedule a dry run for our Ibexa 4.x → 5.0 migration timeline."*

For Developers:

*"This is like artisan migrate but for your Ibexa code. Instead of manually updating every:

• ezpublish service call → Symfony DI container,
• ezplatform bundle reference → ibexa namespace,
• Deprecated Twig filter → new syntax,

Just run:

composer require --dev ibexa/rector
./vendor/bin/rector process src/ --dry-run

How to Use It:

1. Configure rector.php:

   return RectorConfig::configure()
       ->withPaths([__DIR__.'/src', __DIR__.'/tests'])
       ->withSets([IbexaSetList::IBEXA_50]); // Target Ibexa 5.0
   

2. Test First:

   ./vendor/bin/rector process src/ --dry-run  # Preview changes
   

3. Apply Changes:

   ./vendor/bin/rector process src/           # Auto-fix
   

Pro Tips:

• Use --parallel for faster runs on large codebases.
• Combine with phpstan for static analysis post-refactor.
• Add to your composer.json scripts:

  "scripts": {
    "rector": "rector process src/"
  }
  

Works Great With:

• Ibexa DXP 4.x/5.0 projects.
• Custom ezplatform bundles.
• Laravel + Ibexa integrations (e.g., ibexa/laravel-bridge)."*

For DevOps/Platform Teams:

*"This tool integrates seamlessly into CI/CD pipelines to enforce Ibexa code standards. Here’s how to deploy it:

1. GitHub Actions Example:

   - name: Run Ibexa Rector
     run: vendor/bin/rector process src/ --level=strict
   

2. GitLab CI:

   rector:
     stage: test
     script:
       - composer require --dev ibexa/rector
       - ./vendor/bin/rector process src/ --dry-run
   

3. Pre-Merge Checks:
   • Fail PRs if Ibexa Rector finds deprecated patterns.
   • Log changes to a RECTOR_CHANGES.md file for review.

Why This Matters:

• Reduces Merge Conflicts: Catches Ibexa-specific breaking changes early.
• Standardizes Codebase: Ensures all branches comply with Ibexa 5.0+ standards.
• Low Overhead: Runs in <5 minutes for most Ibexa projects.

Next Steps:

• Add to our php-cs-fixer workflow as a parallel step