GoRevo transfers an Evolution site to Revolution
In a few easy steps, GoRevo will transfer a MODX Evolution site to a MODX Revolution site. The following objects will be transferred:
- Manager Users
- Web Users
- Template Variables
- Resource Groups
- Selected System Settings
- Custom Snippets
- Custom Plugins
- Selected files and/or directories
All relationships between the objects will be preserved. Users will belong to the same User Groups, Resources will have the correct Templates, Template Variables will be connected to the same Templates and will retain their values for individual Resources, and Elements will remain in their categories. Manager users will be able to log into the Revolution Manager using their Evolution credentials.
In addition, tags in Resources and Elements will be translated to their Revolution format.
Ditto tags will be converted to getResources or pdoResources (your
phx:userinfo tags will be converted to their Revolution equivalents. GoRevo will also attempt to convert Breadcrumbs, WebLogin, and WebLoginPE to work in Revolution. Optionally, other snippets can be renamed.
Installing GoRevo in Revolution
This has to happen first, since the Evolution files are contained in the Revolution transport package. Be sure the Revolution install is empty except for the Home page.
Copy the gorevo.transport.zip file to the
directory of your Revolution install. Go to Package Management (Extras -> Installer on the Top Menu of the latest version). Click on the down-arrow of the "Download Extras" button and select the "Search Locally for Packages" option on the drop-down menu. Click on the "Yes" button.
GoRevo should appear in the grid. Click on its "Install" button and follow the installation steps.
Installing GoRevo in Evolution
There are about ten files that need to be copied to your Evolution site.
They can be found in the
assets/components/gorevo/ directory. They need to be placed in a
gorevo directory in the MODX root of the Evolution site. There are two ways to move them. The most reliable way is to just download the single file:
gorevo-evo-files.zip (once you've installed GoRevo on the Revolution site, you can find that file under the assets/components/gorevo/ directory), and upload it to the MODX root of your Evolution site. Unzip it in that directory either in cPanel or by shell command. The result should look like this:
(MODX Root Directory) gorevo .htaccess flxziparchive.class.php gorevo.css gorevo.js gorevo-form.html gorevo-logo.png gorevo-results.html gorevo-export.class.php gorevoexport.snippet.php index.php
If you have trouble with this method, you can always either move the
files to where they belong, or use the second method, which is to create the
gorevo directory in the MODX root and copy the files to it individually (you don't need to transfer the .zip file). Don't forget the
index.php file and the
Once the files are in place, you're done installing GoRevo and it's time to move the site.
Important Reminder: For the GoRevo import to work correctly, your Revolution site needs to be an empty, fresh install. There should be nothing there but the admin user, the home page (which will be removed) and the few pieces of GoRevo.
Click on the "Buy Now" link below to see the licensing options for GoRevo.
Just the Basics
We'll look at the finer points of using GoRevo below, but here are the basic steps for moving a site. This section assumes that you have installed GoRevo for both sites as described above. Be sure that you are logged out of the Revolution site. The configuration settings for GoRevo are at the top of the
gorevo/index.php file on the Evo site. For most sites, you won't need to change them. The only thing you're likely to want to edit are additional custom snippets of your own you want to rename. Everything else can be controlled in the form.
- Put this URL in your browser's address bar:
YourEvoSite.com/gorevo/(replacing YourEvoSite.com with the actual site URL)
- On the form that comes up, select the objects you want to move and any additional options, then click on the "Submit" button. Unless your site is huge, the export will take less than ten seconds. If you forgot something, just do it again. All the files will be overwritten.
- Find the
evo.zipfile that's created in the
/gorevo/directory of the Evolution site. Be sure the file is called "evo.zip". Download that file, and upload it to the
/gorevo/directory of the Revolution site (just under the MODX root directory).
- It's optional, but strongly recommended, that at this point you "Export" the empty Revolution site to SQL in PhpMyAdmin. That will be handy if you make a mistake, decide to use different options, or the import times out. Do it *after* you've installed the GoRevo package and *before* you import the Evolution site. Be sure to select the "Drop Table if Exists" option before exporting so you'll get a clean copy if you need to restore the site. To restore, just select the database and "Import" the SQL file in PhpMyAdmin.
- If your site is very large, skip this step. If your site is not too large, you can just point your browser to YourRevoSite.com/gorevo/. It should be safe to do this with sites having less than 1,500 users and less than 200 resources. For very large sites (or if the server is overloaded), PHP may time out (30 seconds is the default). Be patient — importing is slow, but if you don't see the 'Finished' message after five minutes, import the empty-site SQL backup you created earlier and use the method described in the paragraph below.
If the import times out, you need to clear out the crud in the site before trying again. If you don't you'll get lots of error messages about colliding objects. Import the empty-site SQL file you created earlier in PhpMyAdmin (just select the MODX database and "Import" the file). Once you've done that, close PhpMyAdmin. If you don't have a backup, you'll have to wipe out the site and empty the database tables, then start over with a fresh install of MODX and GoRevo.
Once you're back to a fresh install, execute the file:
gorevo/index.php. You can do it directly with a shell command or with a one-time cron job. The command will be
php path/to/modx/root/gorevo/index.php. On a localhost install, you may be able to execute the file in a code editor like PhpStorm. Doing it this way will avoid the PHP time limit and you should see "Finished" when the process is done.
At this point, you should have a semi-working Revolution site. If the front end of your site is a mess, it often means that you've put your CSS and/or image files outside the
assets/ directory and forgotten to specify the directory for transfer.
After importing the Evolution site, the user files and
evo.zip file under the
gorevo directory in both sites contain the usernames and password hashes of all your users in plain text (but not the actual passwords). The files are protected by
.htaccess files, but you'll still want to delete them as soon as you have a successful import. Delete the gorevo/ directory manually in the Evolution install, and uninstall the GoRevo package in the Revolution Package Manager.
It's not a bad idea to double-check to make sure (in the Revolution site) that the
gorevo directory under the MODX root, the
core/components/gorevo directory, and the
assets/components/gorevo directories have been removed and that (in the Evolution site) the entire
/gorevo/ directory is gone.
The Finer Points
Evolution and Revolution are different animals, so it's literally impossible to do a straight conversion from one to the other. This section covers the details of how GoRevo handles the differences.
Here is the form you'll see when doing the export from Evolution:
Depending on the server settings, when you run the Evo export, you may see an error message telling your that
mysql_connect is deprecated. This warning comes from the MODX database API code, not GoRevo. Since it's just a warning, it won't effect the operation of GoRevo.
Evolution has two kinds of users, Manager Users and Web Users. Revolution just has Users. Worse yet, in Evolution the IDs of the two kinds of users both start at 1. That means that a Web User can have the same ID as a different Manager User and a user who is both a Manger User and a Web User will have two separate User Profiles and may have two different IDs. There's no perfect way to handle this.
If a Web User is also a Manager User (with the same username), GoRevo puts the user in any User Groups they belong to, but does not transfer the second User Profile or the second User ID (if different).
If a Web User who is not a Manager User has an ID already in use by a Manager User (with a different username), a new ID is created for the Web User. The formula is oldID + maxId + 10 (where maxId is the highest ID in use by any user in the Evo site). This will happen to very few users — often none. GoRevoExport will report the changed IDs in the output. For those users (if any), the user-related fields of Resources will not be correct (
deletedby). Since more than one user can have the same ID, there's no way to correct them. This will only happen for web users with low IDs who are not Manager Users, have colliding IDs, and have created, edited, published, or deleted resources in the front end of the site. The odds are good that nobody meets all those criteria.
Evolution has no concept of active users. In GoRevo, all users who are not marked as
blocked will be transferred as active.
The original admin user (ID = 1) of the Evolution site is not transferred to Revolution on the assumption that the user already exists as the admin who created the Revolution site. Important: That user will not be able to log in to the Revolution site with their Evolution credentials. The credentials used during Setup for Revolution will always work for the admin Super User.
Manager users are *not* automatically placed in the Administrator group unless they belong to a User Group with that name in Evolution. It's recommended that you *not* put them in the Administrator group, since leaving them out makes it easier to control their permissions and allows more flexibility when customizing the Manager.
User roles mean something very different in the two versions. There's no point in transferring them, because Revolution can't make any sense of Evolution roles. Instead, GoRevo creates two new roles, (ManagerUserRole, and WebUserRole) for use in the permissions system.
Running the Import
Whether or not you can just point your browser to yourRevoSite.com/gorevo/index.php will work or not depends on the size of your site and the speed of your server. It's a lot slower to create objects than to just read them. The import process can take a while and most hosts use the default PHP time limit of 30 seconds. As mentioned above, if you see a timeout error message or if you don't see the 'Finished' message after a minute or two, you can import the SQL backup of the empty site and run the import from the command line, or as a cron job.
If you don't have shell access, but do have access to cPanel (or the equivalent), you can run the import with a one-time cron job. It's very easy to do this in cPanel. Be sure you're logged out of the Revolution site first.
In the Cron Job section of cPanel, select the current year, month, and day, then select an hour, and minute that's about 20 minutes from now. Use the command listed above in the "Just the Basics" section. Give the script plenty of time to run before trying to log in or view the site. For a very large site, it could take quite a while. GoRevo tries its best to be memory efficient, but it's possible that you could run out of memory if your Evolution site is very large. In that case, it may help to do several transfers, using a separate transfer for just the Resources and another for just the Users.
All User Groups from the Evolution site will exist and will contain the same members on the Revolution site. In addition, All Manager Users will be placed in a new group called 'ManagerUsers', and all Web Users will be placed in a group called 'WebUsers'.
There's no reasonable way to transfer the Evolution permissions structure to Revolution. GoRevo does it's best to create a system that will work for you right away. You may need to modify it, but if you do, you'll have a head start.
For Manager Users, GoRevo a new Access Policy called 'ManagerUserPolicy'. It's based on the Administrator Policy Template. It contains all possible Manager permissions, but only 24 of the 170+ possible permissions are enabled. It gives your manager users the ability to perform basic operations in the Manager, such as creating, editing, and deleting, resources (but not publishing them or creating resource at the root of the tree). If your Manager Users need more rights, or you want to take away rights they don't need, this is all you need to do:
- Hover over the gear icon at the upper right of the Manager
- Select "Access Control Lists"
- Go to the "Access Policies" tab
- Right-click on the ManagerUserPolicy row and select "Update Policy"
- Check or uncheck permissions in the list
- Click on the "Save" button at the upper right
Before any permission changes will take effect, you need flush all sessions (aka, "Logout all Users") from the Manager's top menu. In later versions of Revolution, this is are under the "Manage" menu. In earlier versions, it may be under the Security menu.
The rights of Web Users can be changed by editing the WebUserPolicy, but it's seldom necessary to do so since they have no rights to the Manager. They can log on in the front end and see resources you have hidden from other users. You need to protect the resources in order to hide them, but they will be in their original Resource Groups, so you just need to create a Resource Group ACL entry to hide them. Web Users also have most of the rights necessary to use NewsPublisher to create documents in the front end of the site. See the permissions section at Bob's Guides (especially the links at the end) for more information.
GoRevo attempts to transfer about 30 System Settings that make sense in both Evolution and Revolution. It translates the keys and values when necessary. In many cases, it converts the field names since they are different in Revolution.
Evolution has no SMTP prefix setting, so if you need that, you'll have to set it manually in Revolution.
Snippets and Plugins
Snippets and plugins that are installed by default in Evolution, generally won't run in Revolution, so GoRevo doesn't transfer them, though the tags for them will still be there. You'll need to download the Revolution equivalents for them. You'll also want to delete any chunks that belong to them first because the Revolution chunks may be different (though you should leave your own custom Tpl chunks alone).
GoRevo will attempt to convert Ditto, Breadcrumbs, WebLogin, WebLoginPE, and PHX tags to work in Revolution. Wayfinder tags will generally work as is. Here is a list of Revolution packages that contain the snippets you'll need for them:
|Evolution Snippet||Revolution package|
|Ditto||getResources or pdoTools (for pdoResources)|
|Ditto (with paginate)||getPage|
|Wayfinder||Wayfinder or pdoTools (for pdoMenu)|
|UltimateParent||UltimateParent or pdoTools (for pdoField)|
|getResourceField||getResourceField or pdoTools (for pdoField)|
|PHX||No package Needed|
GoRevo will translate Ditto tags to either getResources or pdoResources, and other than the snippets listed above, it will leave other tags alone (including Wayfinder) unless you specify them in the configuration section of the
index.php file. Wayfinder tags will usually work correctly, but getResources and pdoResources tags may need some minor adjustments. GoRevo does its best to modify their properties, but some small changes may still be necessary.
If you convert Ditto to pdoResources and your tag contains the
&includeTVs property, the Evolution property is a "Yes/No" property. The Revolution one for pdoResources is a list of TVs to include. GoRevo will add all TVs attached to the current template to that property. After the conversion, you can delete any TVs you don't want in the list (easier than adding the ones you do need). This will only work if the Ditto tag is in a template or the content field of a resource. If the tag is in a TV or a chunk, GoRevo can't tell which template to get the TVs from.
Another difference with pdoResources involves date fields and date TVs. getResources will return a formatted date, which needs to be converted to a timestamp with
:strtotime. pdoResources returns a timestamp, so the
:strtotime is not necessary.
Ditto tags with
&paginate are converted to the equivalent getPage tags wrapping either pdoResources or getResources. You'll need to download and install the getPage package, and you may need to update the Tpl chunks and/or placeholder tags for them.
The usual replacement for eForm is FormIt, but the they are different enough that GoRevo can't do the conversion for you (and you may choose to roll your own form code rather than use FormIt). If you use eForm for a very simple contact form, SPForm is a good alternative.
If you have a snippet that lets users update their User Profiles, the UpdateProfile snippet in the Login package is a good replacement. You'll usually need to create a new form, but the documentation for UpdateProfile is very good.
If you have custom plugins and snippets, you can specify them in the GoRevo form, or in the config section of the
index.php file and they'll be transferred, but be aware that the code may need to be modified to run in Revolution. To prevent debilitating crashes, all plugins you transfer will be set as disabled.
If you have specified snippets to be renamed, GoRevo will rename them when they are found in snippet tags anywhere, though their properties and their code will sometimes have to be adjusted manually in order to work in Revolution.
Snippets (including Ditto) will not be renamed if they are called in code with
runSnippet(), but this will be a very rare occurrence. You'll know it has happened if a snippet you specified for renaming shows up in the Snippets Used list (unless you have misspelled its name, in which case it won't be renamed at all).
If you choose to transfer chunks (recommended), the odds are that you will get more chunks than you want — the Tpl chunks of various Evolution extras, for example. You'll probably want to delete them before installing any Revolution Extras. The chunks will be in their original categories, which should make this easier. If you're absolutely sure that a chunk won't be used, you can delete it from the Evolution site before doing the export.
The EvoLogin Plugin
Evolution has a number of password hashing options that Revolution knows nothing about. Evolution also has no
hash_class field and the hashing method may or may not be specified in prefix on the password. To allow the Evo users to log in, the EvoLogin plugin installed with the Revolution version of GoRevo is connected to the
OnWebAuthentication System Events. It checks the hash itself and bypasses the MODX login check. If the updateHashClass property of the plugin is set (which it is by default), the plugin also converts the hashing method to PBKDF2, which is the Revolution default.
There is no point in installing the additional MODX extra, PBKDF2convert. It only works with users for whom the hashing method is MD5 and the EvoLogin plugin will handle them as well as users with all the other Evolution hashing methods.
Important: After running the import, you can log in to the Revolution site as the original admin (created when you ran setup), but you can't log in with the credentials of the original Evolution user (ID = 1). GoRevo assumes that these are the same person and doesn't touch that person's record during the import.
Once all users have logged in at least once, you can disable or remove the EvoLogin Plugin (though you don't need to). Before doing this, look at the
modx_users table in the database with PhpMyAdmin to make sure that the
hash_class field contains PBKDF2 for all users. Users with another setting won't be able to log in once the plugin is removed. You can also just disable the plugin by right-clicking on it in the Elements tree.
Templates and Template Variables
Templates should transfer with no trouble and GoRevo will connect them to the appropriate Resources and TVs.
Template Variables are transferred "as is" and will be connected to the appropriate Templates. The values for each resource should also be intact. There may be some differences between the formats of some of the more complex TVs (e.g. image TVs) that will have to be adjusted, but by and large, TVs are the same in Evolution and Revolution, so most of them should work fine. GoRevo will convert dropdown TVs to listbox TVs.
Revolution uses output modifiers rather than phx, but regular phx tags should work fine, since the format for tags with output modifiers is the same as the phx format in Evolution. GoRevo will convert the tags to the equivalent placeholders in Revolution.
phx:if tags, the process is more complex. GoRevo will try to convert them to use the
If snippet (which you'll have to install before they will work). For typical
phx:if tags, this will work fine, since the available aliases cover almost all possibilities, but some minor modifications may be necessary.
GoRevo can't convert complex
phx:if tags containing
:or terms, so they are left alone. They'll be easy to spot, since they will still start with
phx:if. If you have any of these complex tags, you'll have to convert them manually.
Directories and Their Files
You can supply a list of directories to include in the transfer, either by specifying them in the form (in HTML mode) or by editing the
index.php file. Paths from the MODX root are allowed (e.g., images/sidebar/current). If you have placed files you'll need (e.g. images, CSS, or JS files) outside the
assets/ directory, you'll want to specify them for transfer in the GoRevo form when you export the Evo site.
If you specify the
assets directory, by default the following directories will be *excluded* from the transfer: snippets, plugins, modules, cache, backup, docs, site, export, import, and components. You can override this behavior either by editing the
$excludeAssetsDirs variable in the
index.php file or by simply specifying the ones you want in the list of directories to include.
If, for example, you'd like to include just the
assets/components/somecomponent directory but not other directories under
assets/components, just add
assets/components/somecomponent to the list of directories to include and leave the
components entry in the
excludeAssetsDirs variable in the
You can also exclude specific files in the
assets directory by editing the
$excludeAssetsFiles variable in the
If your assets directory is very large, it may cause the export or the import to time out. You may want to exclude it from the process and transfer it on your own. If you are running
index.php from the command line (or if your server thinks you are in CLI mode) the assets directory may be transferred anyway. If so, edit line 55 of the gorevo/index.php file like this:
$includeDirs = '';
GoRevo will report the names of all snippets called via tags on the new site, so you'll know what snippets need to be downloaded or replaced in the Revolution site. All snippet tags in Resources, Chunks, Templates, and Template Variable values will be detected. Snippets called in code with
$modx->runSnippet() in snippets, plugins, and
@EVAL TVs will also be detected. Remember that these are *not* the snippets transferred by GoRevo — they are the snippets the Revolution site needs to fully function. It's not a bad idea to print the list.
You may get some false positives if there are snippet tags in HTML comments or in code examples.
The snippet names are collected after any renaming has occurred.
In addition to displaying the results, GoRevo will also write them to the file gorevo/gorevo.log so they can be viewed later and will be available when GoRevo is run as a cron job. A log will be created during the export and also during the import.
If you use the YAMS multi-language extra in Evolution, you can use this snippet to convert all the YAMS TVs to migxMultiLang TVs and (optionally) delete the YAMS TVs. Run the snippet as your last step after doing the transfer and installing both MIGX and MigxMultiLang. In other words:
- Run the Evo export
- Run the Revo import
- Install MIGX and MigxMultiLang in Package Manager
- Clear the Site Cache
- Create a resource with the
- Run the Yams2Mml snippet by viewing the resource
If you include the this property in the Yams2Mml snippet tag, you can control whether GoRevo deletes the YAMS TVs as it creates the new mml TVs:
&delete_yams_tvs=`1`. It's recommended that you run the snippet once with the option off, then if there are no errors, run it again with the option on to remove the YAMS TVs.
You can also run the Yams2Mml snippet from the command line, but be sure to install the MIGX and MigxMultiLang extras first. If running from the command line, set the
$deleteOldTvProperty property value at the top of the snippet file. If you have many language entries and have memory troulbe, there is also a commented out line around line 120 of the snippet that uses
getIterator() instead of
getCollection(). Uncomment that line and comment out the
getCollection() line just above it.
GoRevo needs to be able to write to the
/gorevo/ directory. Make sure the directory permissions and ownership allow this.
If your Evolution users have trouble logging in, Check the EvoLogin plugin. Make sure it is not disabled. On the System Events tab, make sure it is attached to OnManagerAuthentication and OnWebAuthentication.
Another possible issue with logging in is permissions. In order to log into the Manager, users need to be in a User Group that has a Context Access ACL entry for the
mgr context. In order to see resources in the
web section of the tree the user group also need a Resource Group Access ACL entry for the
web context. GoRevo attempts to create these permissions for the ManagerUsers User Group, but if you have removed that user group or modified its membership or permissions, users may have issues logging in to the Manager.
Similarly, users need permission to log on in the front end. They need a Context Access ACL entry for the
web context, which is the default front-end context. GoRevo creates that ACL entry for the WebUsers User Group, but if you have removed that user group or modified its membership or permissions, users may have issues logging in to the front end of the site.
First, a word about the pdoTools extra. The pdoTools package replaces a number of standard MODX snippets with much faster alternatives. These are specified as commented-out options in the configuration section of of the
index.php file in the Evolution
gorevo directory. To use them, just delete the
// in front of each option you want.
In most cases the properties are the same for the pdoTools alternative, so all you need to do is replace the snippet name, but some minor changes might be necessary. The pdoTools package is not documented in English nearly as well as the snippets it replaces, so in some cases, you may need to ask for help in the MODX Forums.
After transferring the site, your first step should be to log into the Revolution Manager (using the same credentials you used when installing Revolution) and clear the site cache. Delete any chunks that you know are not going to be used — for example, chunks for Evolution snippets you didn't use and default chunks that you have replaced with custom chunks of your own.
Next, install any snippets you will need in Revolution's Package Manager. Unlike Evolution, in Revolution, no snippets or plugins are installed by default. See the "Snippets Used" report and the suggested replacements in the table above. Go to Package Manager from the Top Menu and click on the "Download Extras" button. Put the name of the snippet you want in the search box and click on the "Go" button. When the package appears, click on the "Download" button.
Here are some packages you may want:
- getResources (or pdoTools, which includes pdoResources, pdoMenu, pdoUsers, pdoCrumb, and a number of other components)
- getPage (for Ditto tags with
- Login (which includes Login, Profile, UpdateProfile ForgotPassword,ResetPassword, ChangePassword, Register, ConfirmRegister, ActiveUsers and isLoggedIn)
- Ace (a code editor)
- FormIt (for eForm)
- SPForm (a simple contact form)
- NewsPublisher (front-end resource creation and editing)
- pThumb (for creating thumbnails)
- Articles (for a blog)
- Personalize (for showing different content to logged-in users)
- MIGX (for custom TVs that allow adding multiple items into one TV-value
- Peoples (for listing user and user group information)
- Batcher (for performing batch operations on Resources)
- EZfaq (for creating FAQ pages)
- SiteAtoZ (for creating an alphabetical listing of the site's pages)
- MxCalendar (for creating calendars or event management
- Subscribe (for registering users and their preferences)
- Notify (for sending emails to selected users)
- StageCoach (for scheduling future updates to resources)
When you have downloaded all the packages you want (you can always come back later for more), click on the "Back to Package Manager" button. In the Package Manager grid, click on the install button for each extra and follow the steps to install it. Then, think about how long it would have taken to install all those packages in Evolution and celebrate your decision to switch. ;)
Click on the "Buy Now" link below to see the licensing options for GoRevo.
If you have the book and would like to download the code, you can find it here.
If you have the book and would like to see the updates and corrections page, you can find it here.
MODX: The Official Guide is 772 pages long and goes far beyond this web site in explaining beginning and advanced MODX techniques. It includes detailed information on:
- Installing MODX
- How MODX Works
- Working with MODX resources and Elements
- Using Git with MODX
- Using common MODX add-on components like SPForm, Login, getResources, and FormIt
- MODX security Permissions
- Customizing the MODX Manager
- Using Form Customization
- Creating Transport Packages
- MODX and xPDO object methods
- MODX System Events
- Using PHP with MODX
Go here for more information about the book.
Thank you for visiting BobsGuides.com
— Bob Ray