What is a Transport Package?
A Transport Package (hereafter TP
) is a set of objects and files that can be used to “transport” data from one MODX installation to another; or even to transport third-party components in a simple, easily manageable format. In other words, TP
s can transport almost anything – from database data, files, and even scripts to run during installation.
Transport Packages also allow for versioning, as they are named using a simple format that follows PHP version number standards:
packagename-version-release.transport.zip
An example of a TP
would be myextra-1.0-rc1.transport.zip
. If you were to upload myextra-1.0-rc2.transport.zip
, MODX would interpret it as part of the same ‘package’, but a newer version. So it would behave in “update” mode.
The TP
are stored in .zip
files ending in .transport.zip
. They can be downloaded and installed anywhere MODX Revolution is installed – regardless of server configuration.
Contents of the Transport Package
MODX Revolution will automatically “unzip” your TP
. This will create a subdirectory in your core/packages
directory named after the zip file (without the transport.zip
suffix). This subdirectory will contain:
manifest.php
- Subdirectories of each Transport Container (more on this later)
It may also contain a saved.php
file if the package is an update of a previous package, which contains metadata for the installation being restored. And finally, there may be a setup-options.php
file if the package is packaged inside.
Manifest.php
The manifest file typically stores all the information needed for the package, including the location of files and information about them. If you open the manifest.php
file, you’ll see that it contains a giant PHP array being returned. There are a few keys in there that you might be interested in:
- manifest-version – this tells us what version the manifest definition is. MODX uses this to determine how to interpret the manifest and to make it easier for future versions of MODX to be backwards compatible.
- manifest-attributes – these are any custom attributes that were set on the package when it was built. The most common are ‘license’, ‘readme’ and ‘setup-options’ which MODX interprets during installation.
- manifest-vehicles is the
TP
Container metadata in array format.
What is a Transport Package Container?
Transport Containers (or Transport Package Containers) are part of the TP
. A package can contain any number of Transport Containers, and they also come in different types; Currently available:
xPDOObjectVehicle
– For transporting database dataxPDOFileVehicle
– For transporting files
In the “manifest-vehicles” array you will see these keys for each Container:
- vehicle_package – this tells us what type of package these Containers are in. Currently the only type is “transport”.
- vehicle_class – the class name of the given Container type.
- class – the class name of the DB object being transported, or
xPDOFileVehicle
if it is a file Container. - guid – a randomly generated GUID for the Container.
- native_key – If the Container is a database object, this will be its primary key by which it will be identified.
- file_name – where in the transport package folder the Container’s source file is located.
- namespace – Some packages use a
namespace
field to group Containers and other objects to make them uniquely identifiable in the installation MODX.
So now that we’ve seen what Containers are in the manifest, let’s open up a Container by looking at the file and diving in.
Inside a Transport Container
There can be a number of different files grouped inside containers, but first we’ll look at the main Transport Container file, which is listed in the manifest and often ends in .vehicle
.
Again, this looks like a big PHP array with similar keys. However, it has a few extra keys that are important. xPDOFileVehicle
and xPDOObjectVehicle
can have different keys. Let’s look at the most common ones:
- class – similar to the manifest, the class type of the Container.
- object – an array containing information about the object. For DB objects, this will likely be a JSON array representation of the DB table. For files, this will be a PHP array with the source, target, and Container name.
- vehicle_class – similar to the manifest, the class name of the Container.
- ** vehicle_package** – similar to the manifest, the type of transport of the Container.
- guid – similar to the manifest, a unique identifier of the Container.
- package – Only applicable to
xPDOObjectVehicles
, most likely this will be ‘modx’ or empty. - signature – the filename signature for this Container.
- native_key – similar to the manifest. If the Container is a database object, this will be its primary key by which it will be identified.
XPDOObjectVehicle
or Database Containers often have the following additional keys:
- preserve_keys – If true, the Container will attempt to preserve the primary key of the database record on install.
- update_object – If true, the Container WILL UPDATE the object if it was already found in the database during install. If false, it will be skipped.
- unique_key – the name of the column by which the database object can be uniquely identified – often not the primary key, as auto-incrementing fields are often inconsistent across databases.
- related_objects – a complex array of any related objects to this Container’s primary database object. Sometimes you may want to pack “related” objects to achieve the desired end result. A great example is if a packer wanted to put all of their Snippets into a Category. They would make the Container object a category, and then add related objects to it – Snippets.
- related_object_attributes – attributes for the aforementioned related objects.
- namespace – similar to a manifest; grouping value for objects in
TP
.
There are also a few optional keys that may or may not be set:
- validate – an array of arrays that contain “validators”, explained later.
- resolve – an array of arrays that contain “resolvers”, explained later.
In xPDOFileVehicles
you will also see a directory with the same name as the Container, minus the .vehicle
. If you open it, it will contain the files for the Container.
Resolvers and Validators
What are “Resolvers” and “Validators”? Think of them as scripts that run before and after installation. They are essentially PHP scripts. (In fact, if you open them, they look exactly like PHP scripts.) Their names are the same as the TC
filename, but with a .resolver
or .validator
postfix.
Validator
A validator is run before installing, updating, or uninstalling a Container. If they return false, the Container is not installed and is skipped.
They are useful for determining whether to still install, uninstall, or update a Container during a TC
installation. For example, if you want to have dependencies and not install the Container unless something else is found, a Validator would be a good place to do that.
Resolver
Resolvers are run after installing, updating, or uninstalling a Container. Each of these will be executed in turn, regardless of the results of any other Resolver.
Resolvers are useful for “cleaning up” after a Container installation, or for tweaking custom configuration options (such as setup options during installation).
Usage
Transport packages can be managed in the Package Manager. They can be added to MODX in one of the following ways:
- Upload the file manually to the
core/packages/
directory, then click the “Upload Packages” button and select the “Search for packages locally” option. - Download a package from a Transport Provider. This also allows you to download updates to a package remotely.
Once downloaded, they can be installed by right-clicking on the package in the list and selecting “Install”. Here the user will be asked to accept the license agreement if the package has one, and the prompt to read the README file if the package has one. It will then present a form with pre-installation options, which may or may not exist depending on the package. The user can then click “Install” to install the package.
Once installed, the user can uninstall the package at any time. Additionally, if the package was downloaded from a Transport Provider, the user can check for updates to the package.