Skip to content

contribution.md

Latest commit

 

History

History
245 lines (183 loc) · 7.15 KB

contribution.md

File metadata and controls

245 lines (183 loc) · 7.15 KB

Table of Contents

  1. Examples in action
  2. Overview of all rules
  3. Installation
  4. Configuration and Processing
  5. Best practice guide
  6. Limitations
  7. Contribution

Contributing

Want to help? Great! Join the TYPO3 Slack channel #ext-typo3-rector

Fork the project

Fork this project into your own account.

Install TYPO3 Rector

You can use TYPO3 Rector with at least PHP 7.4. Your contributed code MUST also be compatible with PHP 7.4!

Install the project using composer:

git clone git@github.com:your-account/typo3-rector.git
cd typo3-rector
composer install

Pick an issue from the list

https://github.com/sabbelasichon/typo3-rector/issues

INFO You can filter by tags where you can select, for example, only the easy ones by selecting "easy pick" or "good first issue".

Assign the issue to yourself

Assign the issue to yourself if you are a member of the project, so others can see that you are working on it. If you are not a member of the project, make a comment to let everyone know that you are working on it.

Create an own Rector Rule

Run the following command and answer all questions:

bin/generate-rule

To generate a code quality rule, use the following command:

bin/typo3-rector generate-code-quality-rule

This command will ask you some questions to provide a proper rector setup. Following this will lead to the creation of the overall rector structure necessary. It will create the skeleton for the rector rule with the class, test class, fixtures and directories to start coding — basically everything you need to start!

Useful infos:

  • Use the PHP code parser to get the AST of it here: https://getrector.com/ast. This will help you to know on which node to listen to (for example StaticCall).
  • the refactor must return a node, an array of nodes, int (when you want to remove a node) or null.
  • keep it flat! Use early returns (with null) in case your conditions for migration are not met.
  • the getNodeTypes method is used to define the use case of the function to migrate. It helps as well acting like an early return (see example below).
  • helper functions and classes are provided via rector to make it easy for you to control further processing.
  • here is a list of all php node types: https://github.com/rectorphp/php-parser-nodes-docs/blob/master/README.md
  • search for similar rules and copy the code that is helpful for you. Frequent times you only need to make a few adjustments to existing rules.

Example

In this example the methods GeneralUtility::strtoupper(...) and GeneralUtility::strtolower(...) are migrated.

  • getNodeTypes checks for the StaticCall, preventing further rector execution if not met
  • refactor first checks for the ObjectType to do an early return in case the class scanned is not TYPO3\CMS\Core\Utility\GeneralUtility
  • after that, the actual function call is checked for being one of the functions to migrate
final class GeneralUtilityToUpperAndLowerRector extends AbstractRector
{
    /**
     * @return array<class-string<Node>>
     */
    public function getNodeTypes(): array
    {
        return [StaticCall::class];
    }

    /**
     * @param StaticCall $node
     */
    public function refactor(Node $node): ?Node
    {
        if (! $this->nodeTypeResolver->isMethodStaticCallOrClassMethodObjectType(
            $node,
            new ObjectType('TYPO3\CMS\Core\Utility\GeneralUtility')
        )) {
            return null;
        }

        if (! $this->isNames($node->name, ['strtoupper', 'strtolower'])) {
            return null;
        }

        // ...
    }
}

Remove a node

This is a minimal example to demonstrate how to remove a node. In this case you need to listen to an Expression and return NodeVisitor::REMOVE_NODE.

<?php

use PhpParser\Node;
use PhpParser\Node\Stmt\Expression;
use PhpParser\NodeVisitor;
use Rector\Rector\AbstractRector;

final class RemoveNodeRector extends AbstractRector
{
    /**
     * @return array<class-string<Node>>
     */
    public function getNodeTypes(): array
    {
        return [Expression::class];
    }

    /**
     * @param Expression $node
     */
    public function refactor(Node $node): ?int
    {
        $expressionNode = $node->expr;

        // your magic

        return NodeVisitor::REMOVE_NODE;
    }
}

Return multiple Nodes

Sometimes you need to return more than a single node. A typical use case is if you want to create another method, for example. In this case you need to listen to an Expression. Do a full text search for [Expression::class] to find existing rules which can help you.

final class MyRector extends AbstractRector
{
    public function getNodeTypes(): array
    {
        return [Expression::class];
    }

    /**
     * @param Expression $node
     * @return Node[]|null
     */
    public function refactor(Node $node): ?array
    {
        $methodCall = $node->expr;

        if (! $methodCall instanceof Node\Expr\MethodCall) {
            return null;
        }

        // More checks

        // Do your magic

        $methodCall = $this->nodeFactory->createMethodCall(...);

        return [new Expression($methodCall), $node];
    }
}

Minimum PHP Version required

To run this rule only when a minimum PHP version is used, add this method with a required feature:

use Rector\ValueObject\PhpVersionFeature;
use Rector\VersionBonding\Contract\MinPhpVersionInterface;

final class MyRector extends AbstractRector implements MinPhpVersionInterface
{
    public function provideMinPhpVersion(): int
    {
        return PhpVersionFeature::ENUM;
    }
}

Check if class implements an interface

To check if a class implements an interface, first the scope needs to be fetched and then checked by using class reflection.

private function implementsInterface(ClassMethod|Class_ $node): bool
{
    $scope = ScopeFetcher::fetch($node);

    $classReflection = $scope->getClassReflection();
    if (! $classReflection instanceof ClassReflection) {
        return false;
    }

    return $classReflection->implementsInterface('Vendor\YourInterface');
}

All Tests must be green

Make sure you have a test in place for your Rector

All unit tests must pass before submitting a pull request. Additionally, the code style must be valid. Run the following commands:

composer update
composer run-script local:contribute
vendor/bin/phpunit

Overall hints for testing:

  • testing happens via fixture files (*.php.inc)
  • those files display the code before and after execution, separated by -----
  • rector keeps spaces etc. as its job is migration and not code cleaning, so keep that in mind. TCA fixture files don't need to look pretty!
  • provide custom test classes via "Source" folder, that will be tested, but will not be affected by your rector to test and prevent side effects of your rule.
  • Add stubs that reflect the original code

Submit your changes

Great, now you can submit your changes in a pull request