diff --git a/docs/release_notes/cohesivo_v6.0_deprecations.md b/docs/release_notes/cohesivo_v6.0_deprecations.md new file mode 100644 index 0000000000..6e507e547c --- /dev/null +++ b/docs/release_notes/cohesivo_v6.0_deprecations.md @@ -0,0 +1,38 @@ +--- +description: Adapt your project for the Cohesivo v6.0 release. +month_change: true +--- + + + +# Cohesivo v6.0 renames, deprecations and removals + +## Cohesivo v6.0 + +!!! note "Cohesivo v6.0 isn't released yet" + + This page is published ahead of the Cohesivo v6.0 release to give you time to prepare your code for the upcoming changes. + + As the work on Cohesivo 6.0 is in progress, this page **isn't exhaustive and will evolve with time**. + +As announced during Ibexa Summit 2026, [Ibexa DXP will be renamed to Cohesivo](https://www.ibexa.co/blog/redefining-the-dxp-from-execution-to-orchestration) to support the new [orchestration platform approach](https://www.ibexa.co/blog/the-orchestration-era). + +To learn more about the new brand, visit the [Cohesivo official site](https://cohesivo.com). + +This page lists backwards compatibility breaks introduced in Cohesivo v6.0. + +## PHP API changes + +### ibexa/http-cache + +| Deprecated since | Entity | Change | +| --- |---------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| N/A | `\Ibexa\HttpCache\ResponseTagger\Delegator\DispatcherTagger` | With `kernel.debug` enabled, [`DispatcherTagger`](content_aware_cache.md#dispatchertagger) will throw an exception when you pass an unsupported value instead of silently ignoring it. | +| v5.0.7 | `\Ibexa\Contracts\HttpCache\ResponseTagger\ResponseTagger::supports` | Method added to the interface. All implementations must specify [the value they support for tagging](content_aware_cache.md#delegator-and-value-taggers). | + +### ibexa/messenger + +| Deprecated since | Entity | Change | +| --- |------------------------------------------------------------------------------------|-----------------------------------------------------------| +| v5.0.9 | [`\Ibexa\Contracts\Messenger\Stamp\SudoStamp`](background_tasks.md#sudostamp) | No longer attached automatically to every dispatched message. For messages that should be processed without taking permissions into account, always attach the SudoStamp manually. | +| v5.0.9 | `\Ibexa\Bundle\Messenger\Stamp\DeduplicateStamp` | Replaced with [`\Symfony\Component\Messenger\Stamp\DeduplicateStamp`]([[= symfony_doc =]]/messenger.html#message-deduplication). Covered by [[[= product_name_base =]] Rector](/resources/rector.md) refactoring rules. | diff --git a/docs/resources/rector.md b/docs/resources/rector.md new file mode 100644 index 0000000000..6d362baa69 --- /dev/null +++ b/docs/resources/rector.md @@ -0,0 +1,336 @@ +--- +description: Use [[=product_name_base=]] Rector, an optional package based on Rector, to remove PHP and JavaScript code deprecations. +month_change: true +--- + +# [[= product_name_base =]] Rector + +[[= product_name_base =]] Rector is an optional package based on [Rector](https://getrector.com/) that comes with additional rule sets for working with [[= product_name =]] code. +Use it to get rid of PHP and JavaScript code deprecations and prepare your project for the next major release. + +## Installation + +Add the Composer dependency: + +``` bash +composer require --dev ibexa/rector +``` + +## Refactor PHP code + +### Configuration + +Adjust the generated `rector.php` file by: + +- making it match your project's directory structure +- selecting the [[= product_name_base =]] rule set that matches your current version, for example [`IbexaSetList::IBEXA_50`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Rector-Sets-IbexaSetList.html#enumcase_IBEXA_50) +- adding project-specific rules: + - [PHP rules by using `withPhpSets`](https://getrector.com/documentation/set-lists#content-php-sets) + - [Symfony, Twig, or Doctrine rules by using `withComposerBased`](https://getrector.com/documentation/composer-based-sets) + +It's recommended to activate one rule set at a time and preview the output before applying it. + +An example configuration looks as follows: + +``` php +use Ibexa\Contracts\Rector\Sets\IbexaSetList; +use Rector\Config\RectorConfig; + +return RectorConfig::configure() + ->withPaths( + [ + __DIR__ . '/src', + ] + ) + ->withSets( + [ + IbexaSetList::IBEXA_50->value, + ] + ) + ->withPhpSets(php83: true) + ->withComposerBased(symfony: true) +; +``` + +For more information, see [Rector documentation](https://getrector.com/documentation). + +### Usage + +Run Rector in dry-run mode to preview the changes it would make: + +``` bash +vendor/bin/rector --dry-run +``` + +Once you're satisfied with the proposed changes, apply them by running: + +``` bash +vendor/bin/rector +``` + +## Refactor JavaScript code + +[[= product_name_base =]] Rector also comes with transform module to help you maintain your JavaScript code. + +### Configuration + +To adjust the default configuration, plugins, or rules, modify the `rector.config.js` file present in your project or bundle directory: + +``` js +module.exports = { + config: { + paths: [{ + input: 'src/bundle/Resources/public', + output: 'src/bundle/Resources/public', + }], + prettierConfigPath: './prettier.js', + } + plugins: (plugins) => { + // modify enabled plugins + + return plugins; + }, + pluginsConfig: (config) => { + // modify plugins config + + return config; + } +}; +``` + +### Configuration options + +#### `paths` + +Array of objects with input and output directories for transformed files, relative to your project or bundle root. +Directory structure is not modified during the transformation. + +#### `prettierConfigPath` + +[Prettier](https://prettier.io/) is run at the end of the transformation. +You can provide the path to your own configuration file, otherwise [the default file](https://github.com/ibexa/eslint-config-ibexa/blob/main/prettier.mjs) is used. + +#### `plugins` + +Use it to modify enabled plugins. +To learn more about plugins, see [the list of plugins](#list-of-plugins). + +#### `pluginsConfig` + +Use this setting to modify the plugins configuration, as in the example below: + +``` json +{ + "ibexa-rename-string-values": { + "ez-form-error": "ibexa-form-error", + "ez-selection-settings": { + "to": "ibexa-selection-settings", + "exactMatch": true + }, + "(^|\\s)\\.ez-": { + "to": ".ibexa-", + "regexp": true + }, + "ibexa-field-edit--ez([A-Za-z0-9]+)": { + "to": "ibexa-field-edit--ibexa$1", + "regexp": true + } + } +} +``` + +The plugin configuration is an object with plugin names as keys, for example `ibexa-rename-string-values`. +Inside a single plugin configuration, the property names are values that should be replaced. +They can be specified explicitly (`ezform-error`) or by using regexp (`(^|\\s)\\.ez-`). + +#### Shorthand expression + +You can use a shorthand form to specify the configuration: + +- `"ez-form-error": "ibexa-form-error"` - changes all `ez-form-error` occurrences to `ibexa-form-error` + +#### Complete plugin configuration + +When not using the shorthand configuration, the following options are available: + +- `"to": "ibexa-selection-settings"` - specifies the new value +- `"regexp": true/false` - uses regexp to find the matching values. Use capture groups to reuse parts of the original value in the new value +- `"exactMatch": true` - replaces matching values only when the whole value is matched. Using the example configuration, `ez-selection-settings__field` would not be replaced as it doesn't match `ez-selection-settings` exactly + +#### Shared configuration + +You can create a shared configuration for all plugins by using the `shared` keyword, as in the example below: + +``` json +{ + "shared": { + "ez": { + "to": "ibexa", + "exactMatch": true, + } + } +} +``` + +Values specifies in the `shared` configuration can be overwritten by using configuration for specific plugins. + +### List of plugins + +#### Rename eZ global variables + +Identifier: `ibexa-rename-ez-global` + +This plugin changes all `eZ` variables to `ibexa`. + +Configuration: none + +#### Rename variables + +This plugin allows to rename any variable. + +Identifier: `ibexa-rename-variables` + +##### Configuration example + +``` json +{ + "^Ez(.*?)Validator$": { + "to": "Ibexa$1Validator", + "regexp": true + }, + "^EZ_": { + "to": "IBEXA_", + "regexp": true + } +} +``` + +##### Example output + +| Before | After | +|---|---| +| `class EzBooleanValidator extends eZ.BaseFieldValidator` | `class IbexaBooleanValidator extends ibexa.BaseFieldValidator` | +| `const EZ_INPUT_SELECTOR = 'ezselection-settings__input';` | `const IBEXA_INPUT_SELECTOR = 'ezselection-settings__input';` | + +#### Rename string values + +This plugin changes any string value except translations. +You can use it to transform selectors and other values. + +Identifier: `ibexa-rename-string-values` + +##### Configuration example + +``` json +{ + "(^|\\s)\\.ez-": { + "to": ".ibexa-", + "regexp": true + }, + "ibexa-field-edit--ez([A-Za-z0-9]+)": { + "to": "ibexa-field-edit--ibexa$1", + "regexp": true + }, + "ezselection-settings": "ibexaselection-settings" +} +``` + +##### Example output + +| Before | After | +|---|---| +| `const SELECTOR_FIELD = '.ez-field-edit--ezboolean';` | `const SELECTOR_FIELD = '.ibexa-field-edit--ezboolean'` | +| `const SELECTOR_FIELD = '.ibexa-field-edit--ezboolean';` | `const SELECTOR_FIELD = '.ibexa-field-edit--ibexaboolean';` | + +#### Rename translation IDs + +This plugin allows to change translation IDs. +Extract translations after running this transformation. + +Identifier: `ibexa-rename-trans-id` + +##### Configuration example + +``` json +{ + "^ez": { + "to": "ibexa", + "regexp": true + } +} +``` + +##### Example output + +| Before | After | +|---|---| +|`'ez_boolean.limitation.pick.ez_error'` | `'ibexa_boolean.limitation.pick.ez_error'` | + +#### Rename translation strings + +This plugin changes values in translations. +Extract translations after running this transformation. + +Identifier: `ibexa-rename-in-translations` + +##### Configuration example + +``` json +{ + "to": "ibexa-not-$1--show-modal", + "regexp": true, + "selectors-only": true +} +``` + +If the `selectors-only` property is set to `true`, this plugin changes only strings inside HTML tags. +Set to `false` or remove property to change text values as well. + +##### Example output + +| `selectors-only` value | Before | After | +|---|---|---| +| true | `/*@Desc("

Show message

for ez-not-error--show-modal")*/` | `/*@Desc("

Show message

for ez-not-error--show-modal")*/` | +| false | `/*@Desc("

Show message

for ez-not-error--show-modal")*/` | `/*@Desc("

Show message

for ibexa-not-error--show-modal")*/` | + +#### Rename icons names used in getIconPath method + +This plugin allows you to rename any icon name that is passed as an argument to the `getIconPath` method. + +Identifier: `ibexa-rename-icons` + +##### Configuration example + +In this plugin, the `exactMatch` default value is set to `true` when using the shorthand expression. + +``` json +{ + "browse": "folder-browse", + "content-": { + "to": "file-", + "exactMatch": false + } +} +``` + +##### Example output + +| Before | After | +|---|---| +| `getIconPath('browse')` | `getIconPath('folder-browse')` | + +### Usage + +To install the dependencies, execute the following command: + +``` bash +yarn --cwd ./vendor/ibexa/rector/js install +``` + +Then, run the transform: + +``` bash +yarn --cwd ./vendor/ibexa/rector/js transform +``` + +The `--cwd` argument must point to the directory where the transform module is installed, by default `./vendor/ibexa/rector/js`. diff --git a/docs/resources/resources.md b/docs/resources/resources.md index c93d0b86de..5ca74e3dbd 100644 --- a/docs/resources/resources.md +++ b/docs/resources/resources.md @@ -10,5 +10,6 @@ See additional information about [[= product_name =]] development process, helpf [[= cards([ "resources/release_process_and_roadmap", "resources/phpstorm_plugin", + "resources/rector", "resources/contributing/report_and_follow_issues", ], columns=3) =]] diff --git a/mkdocs.yml b/mkdocs.yml index 9a9d01ad3f..d65d12462e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -946,6 +946,7 @@ nav: - Resources: resources/resources.md - Release process and roadmap: resources/release_process_and_roadmap.md - Ibexa DXP PhpStorm plugin: resources/phpstorm_plugin.md + - Ibexa DXP Rector: resources/rector.md - New in documentation: resources/new_in_doc.md - Contributing: - Report and follow issues: resources/contributing/report_and_follow_issues.md @@ -955,6 +956,7 @@ nav: - Product guides: product_guides/product_guides.md - Release notes: - Release notes: release_notes/release_notes.md + - Cohesivo v6.0 deprecations and BC breaks: release_notes/cohesivo_v6.0_deprecations.md - Ibexa DXP v5.0 LTS: release_notes/ibexa_dxp_v5.0.md - Ibexa DXP v5.0 deprecations and BC breaks: release_notes/ibexa_dxp_v5.0_deprecations.md - Ibexa DXP v4.6 LTS: release_notes/ibexa_dxp_v4.6.md