From d918f6356b2b7faef489cea8e28b70a8a3dac08d Mon Sep 17 00:00:00 2001 From: Ivan Bochkarev Date: Thu, 3 Sep 2026 11:44:38 +0600 Subject: [PATCH] =?UTF-8?q?docs:=20add=20Extra=202.x=E2=86=923.x=20compati?= =?UTF-8?q?bility=20checklist=20(#301)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Author-facing page under upgrading-to-3.0 with Collection-style examples and links to class names, processors, xPDO, and menus. --- .../upgrading-to-3.0/breaking-changes.md | 1 + en/getting-started/upgrading-to-3.0/extras.md | 84 ++++++++++++++++++ en/getting-started/upgrading-to-3.0/index.md | 1 + .../upgrading-to-3.0/breaking-changes.md | 1 + ru/getting-started/upgrading-to-3.0/extras.md | 85 +++++++++++++++++++ ru/getting-started/upgrading-to-3.0/index.md | 1 + 6 files changed, 173 insertions(+) create mode 100644 en/getting-started/upgrading-to-3.0/extras.md create mode 100644 ru/getting-started/upgrading-to-3.0/extras.md diff --git a/en/getting-started/upgrading-to-3.0/breaking-changes.md b/en/getting-started/upgrading-to-3.0/breaking-changes.md index f89d9f359..deb8ba565 100644 --- a/en/getting-started/upgrading-to-3.0/breaking-changes.md +++ b/en/getting-started/upgrading-to-3.0/breaking-changes.md @@ -15,6 +15,7 @@ The biggest breaking changes can be summarised as follows: - [It's no longer possible to use a custom core folder/path](getting-started/upgrading-to-3.0/core-folder) - [sqlsrv support has been removed](getting-started/upgrading-to-3.0/sqlsrv) - [A large number of (previously unnamespaced) classes have been renamed and moved](getting-started/upgrading-to-3.0/class-names), including processors and model classes. +- [Checklist for Extra authors updating 2.x packages](getting-started/upgrading-to-3.0/extras) - [xPDO 3 ships via Composer with PSR-4 models; migrate custom packages](getting-started/upgrading-to-3.0/xpdo) - [All processors have been renamed, including base processors](getting-started/upgrading-to-3.0/processors) - [modAction and related functionality has been removed](getting-started/upgrading-to-3.0/actions) diff --git a/en/getting-started/upgrading-to-3.0/extras.md b/en/getting-started/upgrading-to-3.0/extras.md new file mode 100644 index 000000000..66d4653d8 --- /dev/null +++ b/en/getting-started/upgrading-to-3.0/extras.md @@ -0,0 +1,84 @@ +--- +title: "Updating Extras for 3.0" +description: "Checklist for Extra authors: namespaces, processors, xPDO models, menus, and CRC changes from MODX 2.x to 3.x." +sortorder: 2 +--- + +Site owners use [Upgrading from 2.x to 3.0](getting-started/upgrading-to-3.0). This page is for authors who build or maintain transport packages. + +Compatible packages: [SiteDash extras list](https://sitedash.app/extras). Linked pages below cover each topic in depth. The [Collection](https://github.com/modxcms/Collections) notes from [theboxer](https://github.com/theboxer) (summary on [modx.pro](https://modx.pro/development/19429)) are a worked example of an Extra that extends `modResource`. + +## Support scope + +| Goal | Approach | +| --- | --- | +| MODX 3 only | Namespaced classes, PSR-4 models, `bootstrap.php`. Drop `require_once` of old core paths. | +| One package for 2.x and 3.x | Branch on version (`$modx->version['version'] >= 3`), class-name prefixes or dynamic parent classes. More work. Overview: [Modernizing Extras cheat sheet](https://modx.com/blog/modernizing-extras-conversion-cheat-sheet). | + +Global aliases (`modResource`, `modObjectCreateProcessor`, and similar) still load by default in 3.0-3.2 through `load_deprecated_global_class_aliases`. Automatic loading is scheduled to stop in **3.3**, so move to namespaced code before then. See [Changed class names](getting-started/upgrading-to-3.0/class-names). + +## Checklist + +1. PHP: match the floor for the MODX line you support ([requirements](getting-started/upgrading-to-3.0/requirements)). +2. Class names: in `extends`, type hints, and `instanceof`, replace short core names with `MODX\Revolution\…` / `xPDO\…`. Tables: [Changed class names](getting-started/upgrading-to-3.0/class-names). +3. Processors: extend the new processor namespaces. Remove flat-file processors. Drop `require_once` of `core/model/modx/modprocessor.class.php` and `…/processors/resource/*.class.php` (those paths are gone). Details: [Processors](getting-started/upgrading-to-3.0/processors). +4. xPDO models: set schema `package` to a PHP namespace, `version="3.0"`, regenerate `metadata.mysql.php`, call `addPackage` with a namespace prefix, register PSR-4. Guide: [xPDO 3](getting-started/upgrading-to-3.0/xpdo). +5. `bootstrap.php`: optional file at the Extra core root (namespace path). Register autoload, `addPackage`, and DI services. See [Namespaces](extending-modx/namespaces) and [DI container](extending-modx/di-container). +6. Menus / CMP: no `modAction`. Menu `action` is a controller name in the namespace (`/manager/?namespace=myextra&a=home`). See [modAction and related](getting-started/upgrading-to-3.0/actions). +7. Manager JS: `MODx.config.manager_language` → `MODx.config.cultureKey` ([Manager language](getting-started/upgrading-to-3.0/manager-language)). +8. HTTP client: `modRestClient` is gone. Use the [HTTP service](extending-modx/services/http). +9. Build / install: test install and upgrade on MODX 3. Prefer current scaffolds ([ModExtra3](https://github.com/modx-pro/ModExtra3) for 3.x). Package markdown attributes are parsed in 3.0 ([build script](extending-modx/transport-packages/build-script)). + +## Example: Extra that extends `modResource` (Collections) + +If a custom resource must show up in `$modx->getDescendants(\MODX\Revolution\modResource::class)`, the schema `extends` value must be the namespaced core class. + +### Schema + +Before: + +```php + + + +``` + +After: + +```php + + + +``` + +Rebuild the model so `metadata.mysql.php` picks up the change. + +### PHP class and processors + +Delete obsolete includes such as: + +```php +require_once MODX_CORE_PATH . 'model/modx/modprocessor.class.php'; +require_once MODX_CORE_PATH . 'model/modx/processors/resource/create.class.php'; +require_once MODX_CORE_PATH . 'model/modx/processors/resource/update.class.php'; +``` + +Extend the namespaced types instead: + +| 2.x | 3.x | +| --- | --- | +| `modResource` | `MODX\Revolution\modResource` | +| `modResourceCreateProcessor` | `MODX\Revolution\Processors\Resource\Create` | +| `modResourceUpdateProcessor` | `MODX\Revolution\Processors\Resource\Update` | + +Apply the same mapping to any custom `{ClassKey}CreateProcessor` / `{ClassKey}UpdateProcessor`. See [Processors](getting-started/upgrading-to-3.0/processors) and [Custom resource classes](building-sites/resources/custom-resources). + +## Related pages + +- [Breaking changes](getting-started/upgrading-to-3.0/breaking-changes) +- [Changed class names](getting-started/upgrading-to-3.0/class-names) +- [Processors](getting-started/upgrading-to-3.0/processors) +- [xPDO 3](getting-started/upgrading-to-3.0/xpdo) +- [modAction and related](getting-started/upgrading-to-3.0/actions) +- [Namespaces](extending-modx/namespaces) +- [Modernizing Extras (MODX blog series)](https://modx.com/blog/modernizing-extras-conversion-cheat-sheet) diff --git a/en/getting-started/upgrading-to-3.0/index.md b/en/getting-started/upgrading-to-3.0/index.md index e2c8479ce..ccb470799 100644 --- a/en/getting-started/upgrading-to-3.0/index.md +++ b/en/getting-started/upgrading-to-3.0/index.md @@ -22,6 +22,7 @@ After upgrading the core and upgrading your extras, you may encounter some break - ⚠️ Important: [MODX 3.0 required PHP 7.2; current 3.x (3.2+) requires PHP 8.1+](getting-started/upgrading-to-3.0/requirements) - ⚠️ Important: [sqlsrv support has been removed](getting-started/upgrading-to-3.0/sqlsrv) - [A list of breaking changes can be found here](getting-started/upgrading-to-3.0/breaking-changes), most notably [many core classes have been moved and renamed](getting-started/upgrading-to-3.0/class-names) +- [Updating Extras for 3.0](getting-started/upgrading-to-3.0/extras) - [xPDO 3, Composer, and migrating custom models](getting-started/upgrading-to-3.0/xpdo) - [The manager language is now dynamic](getting-started/upgrading-to-3.0/manager-language) - [Various system settings have been removed or changed](getting-started/upgrading-to-3.0/system-settings) diff --git a/ru/getting-started/upgrading-to-3.0/breaking-changes.md b/ru/getting-started/upgrading-to-3.0/breaking-changes.md index 71d08b806..b97dc79d9 100644 --- a/ru/getting-started/upgrading-to-3.0/breaking-changes.md +++ b/ru/getting-started/upgrading-to-3.0/breaking-changes.md @@ -15,6 +15,7 @@ translation: "getting-started/upgrading-to-3.0/breaking-changes" - [Больше нельзя использовать свой каталог или путь к core](getting-started/upgrading-to-3.0/core-folder) - [Поддержка sqlsrv удалена](getting-started/upgrading-to-3.0/sqlsrv) - [Большое число (ранее без namespace) классов переименовано и перенесено](getting-started/upgrading-to-3.0/class-names), включая процессоры и классы моделей. +- [Чеклист для авторов Extras при обновлении пакетов 2.x](getting-started/upgrading-to-3.0/extras) - [xPDO 3 через Composer и PSR-4; миграция кастомных пакетов](getting-started/upgrading-to-3.0/xpdo) - [Все процессоры переименованы, включая базовые](getting-started/upgrading-to-3.0/processors) - [modAction и связанный функционал удалены](getting-started/upgrading-to-3.0/actions) diff --git a/ru/getting-started/upgrading-to-3.0/extras.md b/ru/getting-started/upgrading-to-3.0/extras.md new file mode 100644 index 000000000..5784505f0 --- /dev/null +++ b/ru/getting-started/upgrading-to-3.0/extras.md @@ -0,0 +1,85 @@ +--- +title: "Обновление дополнений для 3.0" +description: "Чеклист для авторов Extras: пространства имён, процессоры, модели xPDO, меню и CRC при переходе с MODX 2.x на 3.x." +translation: "getting-started/upgrading-to-3.0/extras" +sortorder: 2 +--- + +Владельцы сайтов идут по [Обновлению с 2.x до 3.0](getting-started/upgrading-to-3.0). Эта страница для авторов, которые собирают и сопровождают transport-пакеты. + +Список совместимых пакетов: [SiteDash](https://sitedash.app/extras). Подробности по каждому пункту на связанных страницах ниже. Заметки [theboxer](https://github.com/theboxer) по [Collection](https://github.com/modxcms/Collections) (сводка на [modx.pro](https://modx.pro/development/19429)) показывают Extra, который расширяет `modResource`. + +## Объём поддержки + +| Цель | Подход | +| --- | --- | +| Только MODX 3 | Классы с namespace, модели PSR-4, `bootstrap.php`. Убрать `require_once` старых путей ядра. | +| Один пакет на 2.x и 3.x | Ветвление по версии (`$modx->version['version'] >= 3`), префиксы имён классов или динамические родительские классы. Больше работы. Обзор: [Modernizing Extras cheat sheet](https://modx.com/blog/modernizing-extras-conversion-cheat-sheet). | + +Глобальные алиасы (`modResource`, `modObjectCreateProcessor` и похожие) в 3.0-3.2 по умолчанию ещё подключаются через `load_deprecated_global_class_aliases`. Автоподключение планируют убрать в **3.3**, поэтому к этому моменту код лучше перевести на namespace. См. [Изменённые имена классов](getting-started/upgrading-to-3.0/class-names). + +## Чеклист + +1. PHP: ориентируйтесь на минимум той линейки MODX, которую поддерживаете ([требования](getting-started/upgrading-to-3.0/requirements)). +2. Имена классов: в `extends`, type hint и `instanceof` вместо коротких имён ядра используйте `MODX\Revolution\…` / `xPDO\…`. Таблицы: [Изменённые имена классов](getting-started/upgrading-to-3.0/class-names). +3. Процессоры: наследуйтесь от новых namespace процессоров. Flat-file процессоры уберите. Удалите `require_once` на `core/model/modx/modprocessor.class.php` и `…/processors/resource/*.class.php` (эти пути исчезли). Подробнее: [Процессоры](getting-started/upgrading-to-3.0/processors). +4. Модели xPDO: в схеме `package` это PHP-namespace, `version="3.0"`, пересоберите `metadata.mysql.php`, вызовите `addPackage` с префиксом namespace, зарегистрируйте PSR-4. Гайд: [xPDO 3](getting-started/upgrading-to-3.0/xpdo). +5. `bootstrap.php`: необязательный файл в корне Extra (путь namespace). Autoload, `addPackage`, сервисы DI. См. [Пространства имён](extending-modx/namespaces) и [DI-контейнер](extending-modx/di-container). +6. Меню / CMP: без `modAction`. В меню `action` это имя контроллера в namespace (`/manager/?namespace=myextra&a=home`). См. [modAction и связанные](getting-started/upgrading-to-3.0/actions). +7. JS менеджера: `MODx.config.manager_language` → `MODx.config.cultureKey` ([Язык менеджера](getting-started/upgrading-to-3.0/manager-language)). +8. HTTP-клиент: `modRestClient` удалён. Используйте [HTTP-сервис](extending-modx/services/http). +9. Сборка / установка: проверьте install и upgrade на MODX 3. Для 3.x удобнее актуальная заготовка ([ModExtra3](https://github.com/modx-pro/ModExtra3)). В 3.0 Markdown в атрибутах пакета разбирается ([скрипт сборки](extending-modx/transport-packages/build-script)). + +## Пример: Extra расширяет `modResource` (Collections) + +Если кастомный ресурс должен попадать в `$modx->getDescendants(\MODX\Revolution\modResource::class)`, в схеме у `extends` нужно полное имя класса ядра. + +### Схема + +Было: + +```php + + + +``` + +После: + +```php + + + +``` + +Пересоберите модель, чтобы обновился `metadata.mysql.php`. + +### PHP-класс и процессоры + +Уберите устаревшие подключения, например: + +```php +require_once MODX_CORE_PATH . 'model/modx/modprocessor.class.php'; +require_once MODX_CORE_PATH . 'model/modx/processors/resource/create.class.php'; +require_once MODX_CORE_PATH . 'model/modx/processors/resource/update.class.php'; +``` + +Наследуйтесь от типов с namespace: + +| 2.x | 3.x | +| --- | --- | +| `modResource` | `MODX\Revolution\modResource` | +| `modResourceCreateProcessor` | `MODX\Revolution\Processors\Resource\Create` | +| `modResourceUpdateProcessor` | `MODX\Revolution\Processors\Resource\Update` | + +То же для любых `{ClassKey}CreateProcessor` / `{ClassKey}UpdateProcessor`. См. [Процессоры](getting-started/upgrading-to-3.0/processors) и [пользовательские классы ресурсов](building-sites/resources/custom-resources). + +## Связанные страницы + +- [Критические изменения](getting-started/upgrading-to-3.0/breaking-changes) +- [Изменённые имена классов](getting-started/upgrading-to-3.0/class-names) +- [Процессоры](getting-started/upgrading-to-3.0/processors) +- [xPDO 3](getting-started/upgrading-to-3.0/xpdo) +- [modAction и связанные](getting-started/upgrading-to-3.0/actions) +- [Пространства имён](extending-modx/namespaces) +- [Modernizing Extras (серия в блоге MODX)](https://modx.com/blog/modernizing-extras-conversion-cheat-sheet) diff --git a/ru/getting-started/upgrading-to-3.0/index.md b/ru/getting-started/upgrading-to-3.0/index.md index eb84df1c1..7d4d777ad 100644 --- a/ru/getting-started/upgrading-to-3.0/index.md +++ b/ru/getting-started/upgrading-to-3.0/index.md @@ -21,6 +21,7 @@ translation: "getting-started/upgrading-to-3.0" - ⚠️ Важно: [MODX 3.0 требовал PHP 7.2, текущие 3.x (3.2+) требуют PHP 8.1+](getting-started/upgrading-to-3.0/requirements) - ⚠️ Важно: [поддержка sqlsrv удалена](getting-started/upgrading-to-3.0/sqlsrv) - [Список критических изменений](getting-started/upgrading-to-3.0/breaking-changes), в частности [многие классы ядра перенесены и переименованы](getting-started/upgrading-to-3.0/class-names) +- [Обновление дополнений для 3.0](getting-started/upgrading-to-3.0/extras) - [xPDO 3, Composer и миграция кастомных моделей](getting-started/upgrading-to-3.0/xpdo) - [Язык менеджера теперь динамический](getting-started/upgrading-to-3.0/manager-language) - [Различные системные настройки удалены или изменены](getting-started/upgrading-to-3.0/system-settings)