Creating Custom Packages with MODX 3 + GPM

MODX 3 brings a lot of changes with how packages are loaded. We finally have FIG standard compliant name spacing and autoloading, bringing with it a new way to package your extras. While updating the classic application GPM, or Git Package Management, theboxer (a.k.a. John) added a new feature to create a package.

At the time of this writing, there is a pending pull request to close a few issues. However, it works very easily to get started with a new package.

In this article, I am going to walk through the basic steps to generate a new "boilerplate" package for MODX 3 using GPM in MODX Cloud.

Prerequisites

The obvious prerequisite is you will need to have a site in MODX Cloud for all of these instructions to work. You can do this elsewhere, but you will need to adapt the instructions for your own use case.

Once you have a MODX Cloud instance with MODX 3, start by:

1. SSH into your site.

2. Generate an RSA Key

ssh-keygen -t rsa

3. Install composer on your instance

cd ~/www/
curl http://modx.co/scripts/install.sh | sh
source ~/.profile

4. Create a new folder where your packages will live.

cd ~/www/
mkdir pkgs
cd pkgs/

5. Install GPM on in your package's directory

git clone https://github.com/theboxer/Git-Package-Management.git gpm
cd gpm/core/components/gpm
composer install
cd ~/www/pkgs/gpm/bin/
chmod +x ./gpm
echo "export PATH=$HOME/www/pkgs/gpm/bin:$PATH" >> ~/.profile
source ~/.profile
gpm gpm:install --corePath=/www/core/

Note: If you have trouble with the first git clone command not being able to recognize the SSL from GitHub, you may need to temporarily disable SSL Verification.

git config --global http.sslVerify false
git clone https://github.com/theboxer/Git-Package-Management.git gpm
git config --global http.sslVerify true

Fix System Settings

Now that you have got GPM installed and setup, you will likely need to go into the MODX manager and adjust a few system settings. To start, go into the system settings and change the namespace to gpm, then check the gpm.packages_base_url and gpm.assets_url settings to ensure they are pointed to the appropriate /pkgs/ directory. Your settings should look something like this:

The next setting you will need to adjust is the upload_files setting. It isn't a requirement, but will make life easier to develop. Search the system settings for upload_files and append that with both php and yaml extensions. This will allow you to more easily edit your files and configuration in the package you are working on.

Create a Package

Now is the moment of truth, we are going to go back into our SSH session and create a package. For this example, I am going to use the name "basepackage" which you can find the final results of at matdave/basepackage. To create this, we will use the built-in GPM command `package:create` like so: 

cd /www/pkgs/
gpm package:create --packageVersion 0.0.1 --lowCaseName basepackage --namespace BasePackage --description "This is a base package for MODX 3" --author matdave --withComposer basepackage BasePackage
cd basepackage/core/components/basepackage/
composer install
gpm package:install basepackage

The above script goes into the package directory, creates the package, runs the composer install to generate dependencies and finally installs the package to your MODX instance. You can now review the package within the MODX manager to see that everything is working.

Connect to GitHub

Now that you've got your package set up, you can connect it to GitHub to begin development. First, we'll need our site's SSH key that we created earlier. Run the following command and copy the output.

cat ~/.ssh/id_rsa.pub

Now log in to GitHub.com and create a new repository. You will likely want to name the repository the same as what you named your package.

Once the repository is created, go into Settings -> Deploy Keys and create a new deployment key in the repository. From here, you will paste the contents of id_rsa.pub, which you copied earlier, into the Key field. Next give the deployment key a logical Title, ensure to check Allow write access and click Add Key. Now go back to the main Code tab of the repository, and click on the green <>Code button. Make sure to select Local > SSH and then click the copy button. 

Go back into your SSH session and run the following commands:

cd /www/pkgs/basepackage/
curl https://raw.githubusercontent.com/matdave/basepackage/main/.gitignore > .gitignore
git init
git branch -M main
git add .
git remote add origin <Your GitHub SSH URL>
git commit -m "Initial commit"
git push -u origin main

Your package is now connected to your repository. For further updates, you will just need to pull down changes from your repo and update the package using either the GPM manager page or CLI, like so:

git pull
gpm basepackage:update