Third-party libraries with Composer

From Totara 13 to 19 many third-party libraries were distributed via the libraries/required directory. From Totara 20 this directory is no longer included automatically. Instead third party libraries must be installed ahead of the site install/upgrade using composer.

Totara will automatically download a copy of composer during the CLI install or upgrade process and run the correct commands to resolve the missing third-party libraries, which will be found in the vendor directory. However this is not ideal for all scenarios (for example - if at time of installation there is no access to the open internet) and some sites may want to download the libraries ahead of time.

Note: The browser based install/upgrade script will not automatically handle library installations. You must resolve those manually on the command line ahead of time.

Totara composer file structure

If you wish to install your own libraries or plugins in Totara, run the composer require command from the root directory and make sure only the root composer JSON and lock files are updated.

Default Behaviour: Totara automatically installs the library files

For this step to work, the user running the install script must have write access to both the current and vendor directories. If Totara does not have write access, an error will be printed ahead of time. If you allow this step to run, we strongly recommend temporarily allowing write access to the root + vendor directories to your user, and then removing write access afterwards.

By default Totara will download a copy of composer.phar and install it in the root directory.

Defining your own composer instance

To prevent Totara automatically downloading a composer instance, you may instead configure one yourself and tell Totara of the location in the TOTARA_COMPOSER constant.

// Inside your config.php
define('TOTARA_COMPOSER', '/path/to/composer');

If defined, Totara will skip the step where it downloads composer directly, and move on straight to the library installation.

Optional: Manually handle the library files

You may not want Totara to download composer or run the composer install command automatically, and prefer to take care of it yourself ahead of time.

If that’s the case, make sure you run composer install --no-dev -o in the dirroot directory (not the server directory) before running Totara’s install or upgrade commands.

Ideally the flow looks like this for upgrades:

1. Follow the normal documented steps so far.

2. Enable maintenance mode.

3. Checkout the new code.

4. Run the composer install --no-dev -o command manually.

5. Carry on with the regular upgrade steps.

6. When it’s time to run the install or upgrade command, pass the --no-composer flag to tell Totara to skip that step.

For an install, you’d instead do the following:

1. Checkout the code.

2. Run the composer install --no-dev -o command manually.

3. Carry on with the regular installation steps but passing in --no-composer when it’s time to run the install.

Prevent Totara install/upgrade from running composer commands

Any of these will do, pick what’s best for your situation. If you use any of these then you must run the composer install command as defined above before any install or upgrade, otherwise the results will be undefined.

1. Define a environment variable visible to PHP called TOTARA_SKIP_COMPOSER

2. Define a constant in your config.php file define('TOTARA_SKIP_COMPOSER', true);

3. Pass the --no-composer flag through to the install or upgrade script.

Handling conflicts on upgrades

If you are installing your own libraries into the root directory, then your vendor, composer.json and composer.lock files will conflict. Handling these ahead of time is critical to ensure a safe upgrade.

1. Make a note of your customisations - what libraries/plugins did you install?

2. Undo any customisations. Reset the composer.json and composer.lock files back to what Totara distributed with the new version.

3. Run the standard composer install --no-dev -o command.

4. Now re-run the composer require vendor/package commands to add your plugins back in.

Note: You will need to check your customisations support the newer version of Totara. With major releases, the core libraries and server requirements may increase and third-party libraries or plugins might need upgrading.

Installing Totara when you have no direct internet access

Sometimes you may be running Totara on a server that is not directly connected access to the erht. In this case (20.0.0 or higher) you wish to install you must pre-install the library files on a server with internet access before transferring them to the server.

1. On a server with internet access, download the Totara version (20.0.0 or higher) you wish to install

2. Download a copy of composer from Composer

3. Make sure you’re running the same PHP version your Totara server will be running

4. Run the composer install command in Totara’s root directory composer install --no-dev -o or perhaps php composer.phar install --no-dev -o

5. Copy the whole project including the vendor directory to the new server

6. When running the install, make sure you set the --no-composer flag or one of the other options outlined in the “Prevent Totara install/upgrade from running composer commands” section.