Weave Code
Contao Rector Laravel Package
contao/contao-rector
Automate Contao upgrades with Rector. This package provides ready-made Rector rules and configuration to refactor Contao projects for newer versions, helping you modernize code, remove deprecations, and apply consistent changes safely across your codebase.
Rector rules for Contao
Frequently asked questions about Contao Rector
- Can I use contao/contao-rector to upgrade a Laravel app that integrates with Contao CMS?
- Yes, but only for Contao-specific code. The package targets Contao’s legacy patterns (e.g., tl_* tables, DCA structures, or hooks). Run it on Contao modules/plugins within your Laravel app, excluding pure Laravel logic. Test thoroughly, as refactored Contao code may affect Laravel integrations.
- What Laravel versions or PHP versions does this package support?
- This package doesn’t directly support Laravel—it’s for Contao CMS (PHP 7.4+). However, if your Laravel app uses Contao’s backend (e.g., Contao 5.x with PHP 8.1+), you can run the rules on Contao-specific files. Ensure your Laravel app’s PHP version matches Contao’s requirements (e.g., PHP 8.0+ for Rector).
- How do I install and run contao-rector in a Laravel project with Contao modules?
- Install via Composer: `composer require contao/contao-rector --dev`. Run Rector on Contao-specific directories (e.g., `vendor/bin/rector process src/Modules --set ContaoLevelSetList::UP_TO_CONTAO_50`). Exclude Laravel files using `--exclude-paths` to avoid conflicts. Start with `--dry-run` to preview changes.
- Will this break my custom Contao hooks or third-party extensions?
- Potentially. The package refactors Contao’s core patterns, which may affect custom hooks or extensions relying on legacy syntax. Test in a staging environment first. Use Contao’s Behat for integration testing, and manually review hook implementations. Exclude problematic files with `--exclude` if needed.
- Can I use contao-rector to migrate from Contao 4.9 to 5.0 in a Laravel app?
- Yes, but focus on Contao-specific code. Use the `ContaoLevelSetList::UP_TO_CONTAO_50` set, which includes PHP 8.1+ and Symfony 6.x updates. Run it on Contao modules/plugins, not Laravel core files. Validate with PHPUnit and Contao’s Behat tests, as Contao 5.0 may introduce breaking changes.
- How do I integrate this into Laravel’s CI/CD pipeline?
- Add Rector as a GitHub Actions step or pre-commit hook. Example: `rector process --set ContaoSetList::CONTAO_50 --parallel --dry-run`. For CI, use `--level-set` to target specific Contao versions. Cache dependencies to speed up builds. Run tests post-refactor to catch regressions.
- Are there alternatives for Laravel developers who need Contao compatibility?
- If you’re not using Contao CMS, this package isn’t a fit. For Laravel-specific refactoring, use `rector/rector` with Laravel rules (e.g., `laravel-artisan-rector`). For Contao-Laravel hybrids, manually isolate Contao code or use `contao/behat` for testing. No direct Laravel-compatible Contao refactoring tools exist yet.
- How do I handle template files (e.g., .tpl, .html5) with contao-rector?
- Exclude template files by default—they use Contao’s {$var} syntax, which Rector may break. Add `--exclude-paths=*/*.tpl,*/*.html5` to your command. Manually review templates post-refactor, as they often rely on legacy Contao patterns. Use Contao’s frontend preview tools to validate output.
- What if Rector changes break my Contao backend or frontend?
- Start with `--dry-run` to preview changes. For backend issues, test with Contao’s Behat or manual QA. Frontend breaks often stem from template or asset paths. Use `ContaoSetList::FQCN` first to fix namespace issues, then enable version-specific sets. Roll back incrementally if problems arise.
- Does this package support Contao 4.4 or older versions?
- No, the package targets Contao 4.9+ and 5.0+. For older versions, you’d need custom Rector rules or manual upgrades. Check the `ContaoLevelSetList` for supported ranges. If your project is on Contao 4.4, consider upgrading to 4.9 first, then use this package for further modernization.
Weaver
How can I help you explore Laravel packages today?