Skip to content

Commit

Permalink
[DOCS] Improve best practice docs and add version matrix
Browse files Browse the repository at this point in the history
  • Loading branch information
helsner committed Aug 6, 2024
1 parent 103db71 commit e6ae691
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 4 deletions.
7 changes: 7 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,13 @@ and when you want to execute the migrations run:
vendor/bin/rector process
```

Version matrix:

| | v1 | v2 |
|--------------------|---------------------------------------|----------------|
| **typo3 versions** | 7 - 12 (not all rules) | 10 - 13 |
| **file support** | all files (typoscript, flexform, ...) | only PHP files |

## Contributing

Please see [CONTRIBUTING](docs/contribution.md) for details.
Expand Down
32 changes: 28 additions & 4 deletions docs/best_practice_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,14 @@

# Best practice guide


Version matrix:

| | v1 | v2 |
|--------------------|---------------------------------------|----------------|
| **typo3 versions** | 7 - 12 (not all rules) | 10 - 13 |
| **file support** | all files (typoscript, flexform, ...) | only PHP files |

## What to use for

You can use TYPO3 Rector in various ways:
Expand All @@ -21,7 +29,8 @@ You can use TYPO3 Rector in various ways:

### TLDR;

- apply older or current version rulesets first (if you're going from v8 to v10, apply v7/v8 sets first)
- apply older or current version rulesets first (if you're going from v10 to v12, apply v7/v8/v9/v10 sets first)
- if possible start with version 2 of typo3-rector because it has the bugfixes and all rules from version 10 to 13 of TYPO3
- add ClassAliasMap in case you're upgrading two versions to provide old classes to migrate (see [ClassAliasMap](#classaliasmap))
- apply rulesets stepwise by version; first TCA only, then full set or combined
- apply rulesets stepwise to your packages or multiple packages at once
Expand Down Expand Up @@ -93,7 +102,7 @@ Those need to be provided via `extra` section inside `composer.json` of the proj
Provide the ClassAliasMap files of all necessary extensions for all necessary versions.

---
**Be aware!**
### Limitations
There are limitations to the TCA detection.

TYPO3 Rector can only detect TCA if the TCA is valid, which means there is a 'ctrl' and a 'columns' key:
Expand All @@ -105,8 +114,23 @@ return [
];
```

**INFO**
TCA in `Configuration/Override/` is also migrated if necessary.
So to migrate your TCA in `Configuration/Override/` it is required to add those keys.

Also we can only migrate, when the type of the TCA column is known. For overrides this means you have to add it, e.g. when you extend the doktype items.

```php
$pages = [
'columns' => [
'doktype' => [
'items' => [
['foo', 'foo']
],
],
],
];
```

add `'type' => 'select` to migrate with rector

---

Expand Down

0 comments on commit e6ae691

Please sign in to comment.