Rector

Rector is the kind of tool that starts to make sense when a project has too many mechanical changes to handle by hand. Updating one class manually is fine. Ten classes are still fine. But once you are dealing with hundreds of files, a PHP upgrade, a framework upgrade, or years of mixed coding patterns, manual work becomes slow, tiring, and surprisingly easy to get wrong.

What I like about Rector is that it is not just another formatter. It works with the AST and performs targeted refactoring steps. Used well, it can shorten the path to a more modern codebase. Not because it decides the architecture for you, but because it takes over the repetitive part of the work that humans are not especially good at doing consistently.

Where Rector makes sense

I would most often reach for Rector during PHP, Symfony, or Laravel upgrades, when cleaning up older code, or when gradually adopting newer language features. If a project has been growing for years, there are usually many places where the code can be made more consistent: types can be added, deprecated patterns can be removed, and older constructs can be moved toward current practice.

The key word is gradually. Rector is not something I would run on a large project and merge without reading the result. A healthier workflow is to split changes into small steps, run it in dry-run mode, read the diff, and keep tests close. In that setup, Rector does not take control away from the developer. It removes a large amount of mechanical work.

Refactoring you can review

The difficult part of refactoring is trust. If a tool changes hundreds of lines, I need to understand why it made those changes and whether they are safe. Rector has an advantage here because it is rule based. You can decide which sets of rules belong in the project, which ones should wait, and which ones are not appropriate at all.

In practice, that makes it possible to move in layers. Start with simple, low-risk changes. Add stricter rules later. Leave larger structural refactors for a separate pass. With tests, static analysis, and code review around it, Rector becomes a fairly safe assistant. Without those guardrails, it can still produce a lot of nice-looking changes that nobody fully trusts.

Why I would put it in CI

Rector does not have to be a tool you run only during a big cleanup. It can also be useful in CI, at least in dry-run mode. If the team agrees on a set of rules, the pipeline can quickly show that newly added code is drifting away from the chosen direction. That is usually better than repeating the same comments in code review.

I would still be careful with automatic rewriting without review. Some rules are safe enough for that, others deserve a human look. But even dry-run mode has value. It reminds the team that the codebase should keep moving forward, and that some maintenance can be systematic instead of depending on someone remembering to clean things up later.

What to watch out for

Rector is not a cure for bad architecture. It will not fix the domain model, redraw module boundaries, or decide which technical choices were wrong. What it can do is make the project easier to move. In an older codebase, that is often exactly the first step: remove mechanical debt before trying to solve larger design problems.

The best results come when Rector is part of a wider development process. Run the rules, read the diff, run tests, check static analysis, and only then merge. In that mode, Rector is not magic automation. It is more like a very fast colleague for repetitive refactoring, with the developer still setting the boundaries.