docs(building-sites/extras): fact-check pass, en/ru sync by Ibochkarev · Pull Request #678 · modxorg/Docs

Ibochkarev · 2026-10-21T04:53:53Z

Fact-check pass of the section building-sites/extras against the code of the MODX 3.x branch (a7096dbe1).

The section was written for MODX 2: half of the interface it names does not exist any more. 39 discrepancies were found — 7 PHANTOM, 11 STALE, 3 ORPHAN, 15 UNDOCUMENTED, 3 UNVERIFIABLE. All of them are closed.

Fixed

"Add New Package" does not exist. In 3.x the Download Extras button is a split button whose menu holds Select a Provider, Search Locally for Packages and Upload a package.
"Scan Local" is Search Locally for Packages.
"Revert" is not a button of a package. To go back to a previous version, pick the mode Restore in the window of the uninstall (preexisting_mode = 2), or delete the version in the card of the package.
"Add New Provider" is the button Create.
The right-click menu of a package is gone — the context menu of the grid is disabled (disableContextMenuAction: true). The actions are the buttons of the row: Install, Uninstall, Reinstall, Update, Check For Updates, Remove, View Details.
"Next" in the window of the provider is Save and go to Package Browser.
A provider is not a JSON file. It is an XML-REST service: the answers are parsed with simplexml_load_string, the request carries Accept: application/xml, and the provider is checked on save with GET <service_url>/verify.
The URL of the official provider is https://rest.modx.com/extras/, and it ships with MODX 3.x — not with 2.0.0.
Only cURL is checked in the manager, not the PHP sockets; the requests to the providers go through the PSR-18 client.
Remove does more than deleting the archive: it uninstalls the package, then deletes the record, the unpacked directory core/packages/<signature>/ and the archive. Uninstall rolls the elements back and leaves the archive, the directory and the record in place.
Packages are downloaded one at a time in 3.x.
The licence is shown on a tab of the pre-install panel and confirmed with Continue, not with an Agree control.

Added

The full reference: the actions of a row and when they show, the card of a package with its uploaded versions, the dependencies and the setting abort_install_on_unsatisfied_dependency, the upload of an archive, Purge Old Packages, the permissions (workspaces, packages, providers, file_upload), the events OnPackageInstall / OnPackageUninstall / OnPackageRemove, the settings and the table of the processors.

Screenshots

Five screenshots of the MODX 2 panel are gone from the repository — they showed the grid of the providers, the wizard of the provider, the wizard of the download, the setup options and the uninstall. The frames that replace them are named in .temp/docs-review/media-todo.md; they need a test stand of MODX 3. The four screenshots of the Package Management page that are of MODX 3 stay, and two of them are now in the text.

Defects of the core

Reported in modxcms/revolution:

#17098 — modTransportManager::getProviders() filters on a column disabled that the table transport_providers does not have (the flag is active), so the query fails with Unknown column 'disabled'.
#17099 — modTransportManager::scanForUpdates() and scanForPackages() call scanForUpdates() and scanForPackages() on the provider, and modTransportProvider has no such methods.
#17100 — the option default_provider is read by the page of Package Management, but it is not registered as a system setting, so it cannot be set in the manager.

Locales

The Russian pages follow the English ones: the same headings, the same tables with the same number of rows, the same wording. The link to the section of the dependencies carried the anchor #зависимости, which the site cannot resolve — it transliterates the Cyrillic — so it is #zavisimosti now.

Checks

markdownlint-cli@0.18 (the version used by CI): 0 issues
Every link and every anchor of the six pages resolves, checked with the slugifier of the site
No markers FACT?, EXAMPLE? or MEDIA are left in the files

Mark-H · 2026-10-23T00:11:54Z

+A provider is a base URL of a REST service. MODX appends a fixed route to it and reads the answer as XML:

-MODX recommends not downloading Transport Packages from providers you cannot verify or do not trust. We recommend the modx.com Official Provider at: [https://rest.modx.com/extras/](https://rest.modx.com/extras/)
+| Route | What it returns |


Do we need the routes in the docs? Kinda technical, but also incomplete for anything looking to build their own (which would require tons more detail).

Removed the route list. A provider is the address packages are downloaded from. For modx.com that address is https://rest.modx.com/extras/, and it goes in Service URL.

Mark-H · 2026-10-23T00:12:23Z

+| `description` | free text |

-Once you have a provider, you can connect to it by going up to the Packages grid, clicking "Add New Provider", and then select the "Select a Provider" option. This will bring up a dropdown of Provider options: ![](selprovider.png)
+MODX checks the provider when it is saved: it asks the service `verify` and expects an answer that confirms the provider. A provider that does not answer is not saved.


too technical, just say that it is verified on creation

The page now says MODX checks the provider when you save. If the service does not confirm the address, the record is not saved.

Mark-H · 2026-10-23T00:12:48Z

+MODX checks the provider when it is saved: it asks the service `verify` and expects an answer that confirms the provider. A provider that does not answer is not saved.

-Once you've selected your provider, click Next, and the download tree will be populated with the contents of that Provider's payload (ie, data). This will show you a tree of Package Versions you can download:
+Every request to the provider carries:


too technical. it may be worth adding a section that explains what information is shared with providers though.

Added a short list of what each request sends: the Username and API Key from the window, an installation identifier, the database type, the MODX version, the host, the PHP version, and the manager language. The page uses those window labels.

Mark-H · 2026-10-23T00:13:51Z

+## cURL Is Missing

-Most issues can be resolved by making sure you have cURL installed, and that the core/packages/ directory is writable by PHP.
+MODX asks the providers over HTTP with the PSR-18 client, which needs the extension cURL. The manager checks it when the page opens. Without cURL a notice is shown above the page, and the button **Download Extras** is replaced by the search of the local directory.


too technical, what user cares about it being PSR-18

these "fact-check" PRs are very obviously translating code to docs but aren't asking what users care about. it's not a route or PSR standard, it's the functionality in most cases.

The PSR-18 name is gone. Without the cURL extension, a warning appears above the page and Download Extras is replaced by Search Locally for Packages.

Mark-H · 2026-10-23T00:14:39Z

+Some servers have a broken build of ZipArchive, and the unpack fails with an error from `extractTo` or `archiveTo`. The message comes from PHP, not from MODX.

-### Access Denied Error
+Set the system setting `archive_with` to **Yes** (the value `1`). MODX then unpacks the archives with PCLZip, which is shipped with MODX and needs no extension of PHP.


too technical again imo. good to explain archive_with but what does a pclzip mean to a typical user?

The library and PHP function names are gone. If an archive does not unpack, set archive_with to Yes. MODX unpacks the archive without the PHP Zip extension.

Mark-H · 2026-10-23T00:17:48Z

+| **Uninstall** | the package is installed; the button rolls its elements back |
+| **Reinstall** | the package is installed; the button runs the installation again over it |
+| **Update** | the setting `auto_check_pkg_updates` is on and the provider has a newer version |
+| **Check For Updates** | the package came from a provider and the setting `auto_check_pkg_updates` is off, so MODX does not know of a newer version yet |


this is wrong, it is also shown when it hasn't previously found an update and lets the user do a manual check

The row shows Check For Updates for any package from a provider when Update is not on that row. That covers a package where no newer version has been found yet, so you can run the check yourself. Update appears when the list loads, auto_check_pkg_updates is on, and the provider has a newer version. If the check returns no versions, the window stays closed and the manager says the package is already up to date.

Mark-H · 2026-10-23T00:18:57Z

+
+A package that came from a provider can be checked for a newer version: the **Check For Updates** button of the row opens a window with the versions the provider offers, and a newer version is installed from there.
+
+With the setting `auto_check_pkg_updates` turned on, MODX asks the provider for the newest version itself. The button of the row is then **Update** when a newer version is there, and **Check For Updates** otherwise.


With the setting auto_check_pkg_updates turned on, MODX asks the provider for updates when loading the list automatically.

Rewrote that sentence. When the list loads and auto_check_pkg_updates is on, MODX asks the provider for a newer version. The row shows Update when one exists. Otherwise a package from a provider shows Check For Updates.

Mark-H · 2026-10-23T00:20:18Z

+The **Remove** button of the row deletes the package from the installation. The window **Delete Package** asks whether the package has to be uninstalled first — the option **Force Package Removal** deletes it either way.

-## Step-by-step
+The removal drops the archive `core/packages/<signature>.transport.zip`, the unpacked directory `core/packages/<signature>/` and the record of the database. The elements of the package are left where they are.


can't say I've tried this recently, but surely the Remove option uninstalls the package (removing its elements) before removing the records?

Remove uninstalls the package first, so the elements are removed. It then deletes the archive, the unpacked directory, and the package record. Force Package Removal deletes the record even when the uninstall failed.

Mark-H · 2026-10-23T00:21:11Z

+The requirements are listed on the tab **Dependencies** of the pre-install panel, and the button **Install all dependencies to continue** installs them.

-The Official Provider of modx.com has a URL of: <http://rest.modx.com/extras/> and comes packaged in with MODX Revolution 2.0.0.
+With the setting `abort_install_on_unsatisfied_dependency` — on by default — the installation is stopped until the dependencies are satisfied.


too technical, this is a detail for package devs I think

Removed that setting from this page. During install, the Dependencies tab keeps the continue buttons inactive until the missing packages are installed from the rows. Their label is Install all dependencies to continue. How a package declares dependencies stays on the transport packages page.

Mark-H · 2026-10-23T00:22:51Z

+The option `default_provider` names the provider that is preselected. The page reads it, but it is not registered as a system setting — see [modxcms/revolution#17100](https://github.com/modxcms/revolution/issues/17100).

-### Uninstalling Packages
+## Processors


what's the use for this type of reference for the typical user?

Removed the processor list from the package management page.

… the RU locale Three markers of the editorial pass are resolved against the code: - the actions of a row. **Uninstall** rolls the elements of an installed package back, **Reinstall** runs the installation again over it — both call the same handlers, but they do different things. **Update** shows when the setting `auto_check_pkg_updates` is on and the provider has a newer version; **Check For Updates** shows when the package came from a provider and the setting is off, so MODX does not know of a newer version yet (`Processors/Workspace/Packages/GetList.php`, the method `checkForUpdates()`); - `OnPackageInstall` carries the `package` and the `action`: `install` for the first installation, `upgrade` when a newer version is installed over an older one (`Processors/Workspace/Packages/Install.php`). The setting `abort_install_on_unsatisfied_dependency` is added to the table of the settings. The Russian pages follow the English ones: the same headings, the same tables and the same wording. The link to the section of the dependencies carried the anchor `#зависимости`, which the site cannot resolve — it transliterates the Cyrillic — so it is `#zavisimosti` now.

The review on modxorg#678 asked for the buttons and checks on the package manager, without routes, processor tables, or library names.

Ibochkarev requested a review from Mark-H October 21, 2026 04:55

Mark-H reviewed Oct 23, 2026

View reviewed changes

OpenCode and others added 2 commits October 23, 2026 10:16

docs(building-sites/extras): editorial pass on the section

bdaaa81

Ibochkarev force-pushed the docs/extras branch from 9115b97 to 97683d5 Compare October 23, 2026 04:17

docs(building-sites/extras): describe the actions a site builder sees

41d38bb

The review on modxorg#678 asked for the buttons and checks on the package manager, without routes, processor tables, or library names.

Ibochkarev requested a review from Mark-H October 23, 2026 05:10


		A package that came from a provider can be checked for a newer version: the Check For Updates button of the row opens a window with the versions the provider offers, and a newer version is installed from there.

		With the setting `auto_check_pkg_updates` turned on, MODX asks the provider for the newest version itself. The button of the row is then Update when a newer version is there, and Check For Updates otherwise.

Conversation

Ibochkarev commented Oct 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Fixed

Added

Screenshots

Defects of the core

Locales

Checks

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Ibochkarev commented Oct 21, 2026 •

edited

Loading