Application Environment

Configuration

Keep secrets and environment choices out of your code.

Leaf reads environment values so local, staging, and production apps can share the same code while using different credentials, modes, and service endpoints.

APP_ENV=production

DB_DATABASE=leaf

$database = _env('DB_DATABASE');

You can think of your application's environment as a set of configurations that define how your application behaves in different situations. For example, you may run a local database when developing your app, but will want your app to connect to a remote database when it's in production.

Common environments include development, testing, and production. Leaf already has some pre-programmed behaviours for these environments, but you can also create your own custom environments. One way to do this is to use environment variables.

Environment Variables

Environment variables are variables that are set in your application's current environment instead of being hardcoded in your code. This allows you to change your application's behaviour without changing your code which is pretty cool and useful for things like setting up different credentials for development and production.

Loading Environment Variables

Leaf MVC

If you use Leaf MVC, this step is already done for you, so you can go ahead and use _env() to access any environment variable you need.

To use environment variables in your Leaf application, you need to load them from your .env file into PHP's $_ENV and $_SERVER globals. You can then access these variables using the _env() helper function that Leaf provides. Here are some popular environment loaders:

• vlucas/phpdotenv
• symfony/dotenv

Using Environment Variables

Leaf comes with a pretty handy helper function _env() that you can use to access your environment variables. The _env() function takes in a key and a default value. If the key is found, the value is returned, otherwise the default value is returned.

$secretKeyFromEnv = _env('SECRET_KEY', 'mySecretIfNotFound');

Application Modes

As mentioned earlier, Leaf has some pre-programmed behaviours for common environments like development, testing, and production. Leaf uses the development environment by default if no environment is set, but you can also set the environment your app should run in manually using the mode setting in your application settings.

app()->config([
  'mode' => 'production'
]);

You can also set the application mode using the APP_ENV environment variable. If Leaf detects that the APP_ENV environment variable is set, it will automatically set the application mode to the value of the APP_ENV variable.

Debug behavior in Leaf 5

Leaf 5 treats debug mode as environment-aware unless you explicitly configure it. In development, detailed debug output stays available so you can understand errors quickly. In production, Leaf turns detailed debug output off by default so stack traces, file paths, request details, and other internals are not shown to users.

APP_ENV=production

You can still override this manually when you need to:

app()->config([
  'debug' => false
]);

For production issues, prefer logging over turning debug output back on. Debug screens are useful while building, but they can expose sensitive application details when a public app breaks.

Using Application Modes

You can also tell Leaf to run a specific script when the application mode matches a given mode. This is done using the script() method. The script() method accepts two arguments: the mode and a callable.

app()->script('production', function() {
  // Run this script when the application mode is production
});