Upgrading from Materia 7.0.1 or older to Materia 8.0.0

Materia 8.0.0 brings a major simplification for configuring new servers. This guide should help anyone running an older copy of Materia upgrade to the new version.

Why Change

FuelPHP, the framework that Materia is built on, has a powerful and somewhat complex configuration system. It's great for developers, but it quickly became clear that it's painful for server admins that are just trying to get it running. After helping several schools install Materia, we decided to make some changes.

How is Configuration Changing

Our priority was to simplify and consolidate all of the common configuration options into a single place. We've adopted the use of environment variables for all common configuration options.

This should simplify and still offer the flexibility on where and how those options are defined.

It's worth noting, that while we've simplified configuration for most options, the original method of configuration is technically still in place. We are still relying on FuelPHP's configuration framework under the hood, it's just that those configuration files are getting their settings from environment variables instead.

Before You Upgrade

BACK UP YOUR ENTIRE INSTALL. Do it now.

Pay particular attention to any customizations you made, especially the FuelPHP config files in:

• fuel/app/config/
• fuel/app/config/production/ (assuming you're running with FUEL_ENV=production)
• fuel/app/modules/lti/config/
• fuel/app/modules/lti/config/production/(assuming you're running with FUEL_ENV=production)

These are the files that contain all of your customized configuration, and there can be quite a few. Your goal when upgrading will be to transfer customizations in these files into your new environment variables. Keep a copy of these handy and make sure you have a backup.

Where to Set Environment Variables

Using environment variables allows you do define these configuration options in a whole bunch of different ways:

• .env.local in the root directory of Materia (readme) easiest option
• NGINX fastcgi_param FUEL_ENV production; or include (docs)
• Apache SetEnv FUEL_ENV production (docs)
• PHPFPM env[FUEL_ENV] = production (docs pay attention to clear_env)
• global system environment variables
• docker environment variables

The Easiest Option: Dot ENV

In the root directory of Materia there are 2 config files that are automatically loaded: .env and .env.local. The preferred approach is to copy .env into .env.local for customization. This will make upgrading easier. .env is updated with Materia but .env.local isn't tracked by git so your changes won't be overwritten. Once you finish customizing your .env.local, it's probably a good idea to clear any unmodified variables from it. This has two benefits: your customized options are more visible, and changes to Materia in new releases won't be unintentionally overridden.

Follow the main Materia Readme for understanding each configuration option.

A Quick Example

Here's /fuel/app/config/development/config.php prior to version 8:

<?php

return [
	'profiling'  => false,

	/**
	 * Logging Threshold.  Can be set to any of the following:
	 *
	 * Fuel::L_NONE
	 * Fuel::L_ERROR
	 * Fuel::L_WARNING
	 * Fuel::L_DEBUG
	 * Fuel::L_INFO
	 * Fuel::L_ALL
	 */
	'log_threshold' => Fuel::L_ALL,
];

In version 8 and later, config/<env>/config.php files aren't used in most cases. The changes to the core configuration files allow us to use environment variables.

Here is /fuel/app/config/config.php in version 8

	/**
	 * Logging Threshold.  Can be set to any of the following:
	 *
	 * Fuel::L_NONE
	 * Fuel::L_ERROR
	 * Fuel::L_WARNING
	 * Fuel::L_DEBUG
	 * Fuel::L_INFO
	 * Fuel::L_ALL
	 */
	'log_threshold'    => $_ENV['FUEL_LOG_THRESHOLD'] ?? Fuel::L_WARNING,

Notice that config.log_threshold will now load its value from the environment variable FUEL_LOG_THRESHOLD, and fall back to Fuel::L_WARNING. You can see now how we implemented environment variables within the existing FuelPHP config files. Advanced users can still completely customize the config files, but that should be unnecessary in most use cases.

To customize FUEL_LOG_THRESHOLD in version 8, it is preferred to set it in /.env.local. For instance, we'll change it back to L_ALL below:

# LOGGING ===================

#config.log_threshold
# Threshold for for which types of logs get written
# [0|99|100|200|300|400]
# (default:300)
# L_NONE=0, L_ALL=99, L_DEBUG=100, L_INFO=200, L_WARNING=300, L_ERROR=400
FUEL_LOG_THRESHOLD=99

#config.log_handler
# Optionally set the log handler to stdout (like when you're using docker)
# [STDOUT|DEFAULT]
#LOG_HANDLER=DEFAULT

Take note that we've documented the original FuelPHP config param names in the Readme, so you'll be able to easily look up log_threshold to find the new environment variable name.

That's the whole process; just continue to copy your old settings to .env.local, cross referencing the Readme for mapping the configuration names to the new env vars.

On Security

Take note that PHP's phpinfo() page displays environment variables in plain text. Take care to not expose a phpinfo page to the public as this will contain critical secrets.