2017-10-30 13:33:09 +00:00
|
|
|
# Rector - Reconstruct your Legacy Code to Modern Codebase
|
2017-07-15 17:20:20 +00:00
|
|
|
|
2017-09-21 10:40:27 +00:00
|
|
|
[![Build Status](https://img.shields.io/travis/RectorPHP/Rector/master.svg?style=flat-square)](https://travis-ci.org/RectorPHP/Rector)
|
|
|
|
[![Coverage Status](https://img.shields.io/coveralls/RectorPHP/Rector/master.svg?style=flat-square)](https://coveralls.io/github/RectorPHP/Rector?branch=master)
|
2017-07-15 17:20:20 +00:00
|
|
|
|
2017-10-30 15:08:28 +00:00
|
|
|
Rector **upgrades your application** for you, with focus on open-source projects:
|
2017-07-15 17:20:20 +00:00
|
|
|
|
2017-10-30 15:00:28 +00:00
|
|
|
<p align="center">
|
2017-10-30 15:02:34 +00:00
|
|
|
<a href="/src/config/level/symfony"><img src="/docs/symfony.png"></a>
|
2017-10-30 15:00:28 +00:00
|
|
|
<img src="/docs/space.png">
|
2017-10-30 15:02:34 +00:00
|
|
|
<a href="/src/config/level/nette"><img src="/docs/nette.png" height="50"></a>
|
2017-10-30 15:00:28 +00:00
|
|
|
<img src="/docs/space.png">
|
2017-10-30 15:02:34 +00:00
|
|
|
<a href="/src/config/level/phpunit"><img src="/docs/phpunit.jpg"></a>
|
2017-10-30 15:00:28 +00:00
|
|
|
<img src="/docs/space.png">
|
2017-10-30 15:02:34 +00:00
|
|
|
<a href="/src/config/level/roave"><img src="/docs/roave.png"></a>
|
2017-10-30 15:00:28 +00:00
|
|
|
</p>
|
2017-08-20 15:40:19 +00:00
|
|
|
|
2017-10-30 15:08:28 +00:00
|
|
|
<br>
|
2017-07-15 17:20:20 +00:00
|
|
|
|
|
|
|
## Install
|
|
|
|
|
2017-10-30 23:08:32 +00:00
|
|
|
Add to your `composer.json`:
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"require-dev": {
|
|
|
|
"rector/rector": "@dev",
|
|
|
|
"nikic/php-parser": "dev-master#5900d78 as v3.1.1"
|
|
|
|
}
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
And download packages:
|
|
|
|
|
2017-07-15 17:20:20 +00:00
|
|
|
```bash
|
2017-10-30 23:08:32 +00:00
|
|
|
composer update
|
2017-07-15 17:20:20 +00:00
|
|
|
```
|
|
|
|
|
2017-10-30 13:33:09 +00:00
|
|
|
## How To Reconstruct your Code?
|
|
|
|
|
|
|
|
### A. Prepared Sets
|
|
|
|
|
2017-10-30 14:44:00 +00:00
|
|
|
Fetaured open-source projects have **prepared sets**. You'll find them in [`/src/config/level`](/src/config/level).
|
2017-10-30 13:33:09 +00:00
|
|
|
|
|
|
|
E.g. Do you need to upgrade to Nette 2.4?
|
2017-09-23 21:51:04 +00:00
|
|
|
|
2017-10-30 13:33:09 +00:00
|
|
|
1. Run rector on your `/src` directory
|
2017-09-23 21:51:04 +00:00
|
|
|
|
2017-10-30 13:33:09 +00:00
|
|
|
```bash
|
|
|
|
vendor/bin/rector process src --config vendor/bin/rector/src/config/level/nette/nette24.yml
|
2017-09-23 21:51:04 +00:00
|
|
|
```
|
2017-10-30 13:33:09 +00:00
|
|
|
|
|
|
|
Too long? Try `--level` shortcut:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
vendor/bin/rector process src --level nette24
|
2017-09-23 21:51:04 +00:00
|
|
|
```
|
|
|
|
|
2017-10-30 13:33:09 +00:00
|
|
|
2. Check the Git
|
2017-09-23 21:51:04 +00:00
|
|
|
|
|
|
|
```
|
2017-10-30 13:33:09 +00:00
|
|
|
git diff
|
2017-09-23 21:51:04 +00:00
|
|
|
```
|
|
|
|
|
2017-10-30 13:33:09 +00:00
|
|
|
|
|
|
|
### B. Custom Sets
|
2017-09-27 21:58:14 +00:00
|
|
|
|
|
|
|
1. Create `rector.yml` with desired Rectors
|
|
|
|
|
|
|
|
```yml
|
|
|
|
rectors:
|
2017-09-28 14:21:20 +00:00
|
|
|
- Rector\Rector\Contrib\Nette\Application\InjectPropertyRector
|
2017-09-27 21:58:14 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
2. Run rector on your `/src` directory
|
2017-07-15 17:20:20 +00:00
|
|
|
|
|
|
|
```bash
|
2017-09-27 21:58:14 +00:00
|
|
|
vendor/bin/rector process src
|
|
|
|
```
|
|
|
|
|
|
|
|
3. Check the Git
|
|
|
|
|
|
|
|
```
|
|
|
|
git diff
|
2017-07-15 17:20:20 +00:00
|
|
|
```
|
|
|
|
|
2017-08-21 10:12:51 +00:00
|
|
|
|
2017-11-02 17:21:25 +00:00
|
|
|
### Simple setup with Dynamic Rectors
|
2017-10-07 08:58:54 +00:00
|
|
|
|
|
|
|
You don't have to always write PHP code. Many projects change only classes or method names, so it would be too much work for a simple task.
|
|
|
|
|
|
|
|
Instead you can use prepared **Dynamic Rectors** directly in `*.yml` config:
|
|
|
|
|
|
|
|
You can:
|
|
|
|
|
|
|
|
- **replace class name**
|
|
|
|
|
|
|
|
```yml
|
|
|
|
# phpunit60.yml
|
|
|
|
rectors:
|
|
|
|
Rector\Rector\Dynamic\ClassReplacerRector:
|
|
|
|
# old class: new class
|
|
|
|
'PHPUnit_Framework_TestCase': 'PHPUnit\Framework\TestCase'
|
|
|
|
```
|
|
|
|
|
2017-10-07 20:34:30 +00:00
|
|
|
- **replace part of namespace**
|
|
|
|
|
|
|
|
```yml
|
|
|
|
# better-reflection20.yml
|
|
|
|
rectors:
|
|
|
|
Rector\Rector\Dynamic\NamespaceReplacerRector:
|
2017-11-01 16:41:13 +00:00
|
|
|
# old namespace: new namespace
|
2017-10-07 20:34:30 +00:00
|
|
|
'BetterReflection': 'Roave\BetterReflection'
|
|
|
|
```
|
|
|
|
|
2017-10-16 20:06:59 +00:00
|
|
|
- **change method name**
|
2017-10-07 08:58:54 +00:00
|
|
|
|
|
|
|
```yml
|
|
|
|
rectors:
|
|
|
|
Rector\Rector\Dynamic\MethodNameReplacerRector:
|
2017-11-01 16:41:13 +00:00
|
|
|
# class
|
2017-10-07 08:58:54 +00:00
|
|
|
'Nette\Utils\Html':
|
2017-11-01 16:41:13 +00:00
|
|
|
# old method: new method
|
2017-10-07 08:58:54 +00:00
|
|
|
'add': 'addHtml'
|
2017-10-30 13:33:09 +00:00
|
|
|
|
2017-10-20 16:04:52 +00:00
|
|
|
# or in case of static methods calls
|
2017-10-30 13:33:09 +00:00
|
|
|
|
2017-11-01 16:41:13 +00:00
|
|
|
# class
|
2017-10-20 16:04:52 +00:00
|
|
|
'Nette\Bridges\FormsLatte\FormMacros':
|
2017-11-01 16:41:13 +00:00
|
|
|
# old method: [new class, new method]
|
2017-10-20 16:04:52 +00:00
|
|
|
'renderFormBegin': ['Nette\Bridges\FormsLatte\Runtime', 'renderFormBegin']
|
2017-10-07 08:58:54 +00:00
|
|
|
```
|
|
|
|
|
2017-10-21 22:04:15 +00:00
|
|
|
- **change property name**
|
|
|
|
|
|
|
|
```yml
|
|
|
|
rectors:
|
|
|
|
Rector\Rector\Dynamic\PropertyNameReplacerRector:
|
|
|
|
# class:
|
|
|
|
# old property: new property
|
|
|
|
'PhpParser\Node\Param':
|
|
|
|
'name': 'var'
|
|
|
|
```
|
|
|
|
|
2017-10-20 18:35:04 +00:00
|
|
|
- **change class constant name**
|
|
|
|
|
|
|
|
```yml
|
|
|
|
rectors:
|
|
|
|
Rector\Rector\Dynamic\ClassConstantReplacerRector:
|
2017-11-01 16:41:13 +00:00
|
|
|
# class
|
2017-10-20 18:35:04 +00:00
|
|
|
'Symfony\Component\Form\FormEvents':
|
2017-11-01 16:41:13 +00:00
|
|
|
# old constant: new constant
|
2017-10-20 18:35:04 +00:00
|
|
|
'PRE_BIND': 'PRE_SUBMIT'
|
|
|
|
'BIND': 'SUBMIT'
|
|
|
|
'POST_BIND': 'POST_SUBMIT'
|
|
|
|
```
|
|
|
|
|
2017-10-22 14:51:13 +00:00
|
|
|
- **change parameters typehint according to parent type**
|
2017-10-21 16:30:45 +00:00
|
|
|
|
|
|
|
```yml
|
|
|
|
rectors:
|
|
|
|
Rector\Rector\Dynamic\ParentTypehintedArgumentRector:
|
2017-11-01 16:41:13 +00:00
|
|
|
# class
|
2017-10-21 16:30:45 +00:00
|
|
|
'PhpParser\Parser':
|
2017-11-01 16:41:13 +00:00
|
|
|
# method
|
2017-10-21 16:30:45 +00:00
|
|
|
'parse':
|
2017-11-01 16:41:13 +00:00
|
|
|
# parameter: typehint
|
2017-10-21 16:30:45 +00:00
|
|
|
'code': 'string'
|
|
|
|
```
|
|
|
|
|
2017-11-01 16:42:08 +00:00
|
|
|
- **change argument value**
|
2017-11-01 12:07:59 +00:00
|
|
|
|
|
|
|
```yml
|
2017-11-01 16:41:13 +00:00
|
|
|
rectors:
|
|
|
|
Rector\Rector\Dynamic\ArgumentReplacerRector:
|
|
|
|
# class
|
|
|
|
'Symfony\Component\DependencyInjection\ContainerBuilder':
|
|
|
|
# method
|
|
|
|
'compile':
|
|
|
|
# argument position
|
|
|
|
0:
|
|
|
|
# added default value
|
|
|
|
~: false
|
2017-11-01 17:42:47 +00:00
|
|
|
# or remove completely
|
|
|
|
~: ~
|
|
|
|
# or replace by new value
|
|
|
|
'Symfony\Component\DependencyInjection\ContainerBuilder\ContainerBuilder::SCOPE_PROTOTYPE': false
|
2017-11-01 12:07:59 +00:00
|
|
|
```
|
2017-10-30 13:33:09 +00:00
|
|
|
|
2017-10-16 20:06:59 +00:00
|
|
|
- or **replace underscore naming `_` with namespaces `\`**
|
|
|
|
|
|
|
|
```yml
|
|
|
|
rectors:
|
|
|
|
Rector\Roector\Dynamic\PseudoNamespaceToNamespaceRector:
|
|
|
|
# old namespace prefix
|
|
|
|
- 'PHPUnit_'
|
|
|
|
```
|
2017-10-07 08:58:54 +00:00
|
|
|
|
|
|
|
|
2017-11-02 17:21:25 +00:00
|
|
|
### 6 Steps to Add New Rector
|
|
|
|
|
|
|
|
In case you need a transformation that you didn't find in Dynamic Rectors, you can create your own:
|
|
|
|
|
|
|
|
1. Just extend `Rector\Rector\AbstractRector` class. It will prepare **2 methods**:
|
|
|
|
|
|
|
|
```php
|
|
|
|
public function isCandidate(Node $node): bool
|
|
|
|
{
|
|
|
|
}
|
|
|
|
|
|
|
|
public function refactor(Node $node): ?Node
|
|
|
|
{
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
2. Put it under `namespace Rector\Contrib\<set>;` namespace
|
|
|
|
|
|
|
|
```php
|
|
|
|
<?php declare(strict_types=1);
|
|
|
|
|
|
|
|
namespace Rector\Contrib\Symfony;
|
|
|
|
|
|
|
|
use Rector\Rector\AbstractRector;
|
|
|
|
|
|
|
|
final class MyRector extends AbstractRector
|
|
|
|
{
|
|
|
|
// ...
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
3. Add a Test Case
|
|
|
|
|
|
|
|
4. Add to specific level, e.g. [`/src/config/level/nette/nette24.yml`](/src/config/level/nette/nette24.yml)
|
|
|
|
|
|
|
|
5. Submit PR
|
|
|
|
|
|
|
|
6. :+1:
|
|
|
|
|
|
|
|
|
2017-11-02 17:31:57 +00:00
|
|
|
|
|
|
|
### Coding Standards are Outsourced
|
|
|
|
|
|
|
|
|
|
|
|
This package has no intention in formating your code, as it **coding standard tools handle this much better**.
|
|
|
|
|
|
|
|
We prefer [EasyCodingStandard](https://github.com/Symplify/EasyCodingStandard):
|
|
|
|
|
|
|
|
|
|
|
|
```php
|
|
|
|
# check
|
|
|
|
vendor/bin/ecs check --config vendor/rector/rector/ecs-after-rector.neon
|
|
|
|
# fix
|
|
|
|
vendor/bin/ecs check --config vendor/rector/rector/ecs-after-rector.neon --fix
|
|
|
|
```
|
|
|
|
|
|
|
|
but you can use any other with [this setup](/ecs-after-rector.neon).
|
|
|
|
|
|
|
|
|
|
|
|
|
2017-10-15 09:07:53 +00:00
|
|
|
### Advanced Operations
|
|
|
|
|
|
|
|
- [Service Name to Type Provider](/docs/ServiceNameToTypeProvider.md)
|
|
|
|
|
|
|
|
|
2017-07-15 17:20:20 +00:00
|
|
|
### How to Contribute
|
|
|
|
|
|
|
|
Just follow 3 rules:
|
|
|
|
|
|
|
|
- **1 feature per pull-request**
|
2017-08-21 10:12:51 +00:00
|
|
|
- **New feature needs tests**
|
2017-07-15 17:20:20 +00:00
|
|
|
- Tests, coding standard and PHPStan **checks must pass**
|
|
|
|
|
|
|
|
```bash
|
|
|
|
composer all
|
|
|
|
```
|
|
|
|
|
2017-08-21 10:12:51 +00:00
|
|
|
Don you need to fix coding standards? Run:
|
2017-07-15 17:20:20 +00:00
|
|
|
|
|
|
|
```bash
|
2017-08-21 10:12:51 +00:00
|
|
|
composer fix-cs
|
2017-07-15 17:20:20 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
We would be happy to merge your feature then.
|
2017-10-30 13:33:09 +00:00
|
|
|
|
|
|
|
|
2017-11-01 01:21:22 +00:00
|
|
|
### How to use on PHP < 7.1 on Incompatible Composer Dependencies
|
2017-10-30 13:33:09 +00:00
|
|
|
|
|
|
|
You must have separated environment with PHP 7.1 (for example in Docker container). When you have it then run following command:
|
|
|
|
|
|
|
|
```
|
|
|
|
composer create-project rector/rector path-to-rector
|
|
|
|
```
|
|
|
|
|
|
|
|
When do you have it then you can run all commands like
|
|
|
|
|
|
|
|
```
|
|
|
|
path-to-rector/bin/rector process /var/www/old-project --config path-to-rector/src/config/level/nette/nette24.yml
|
|
|
|
# or for short
|
|
|
|
path-to-rector/bin/rector process /var/www/old-project --level nette24
|
|
|
|
```
|