Laravel: New Environment Encryption Commands

Oct, 11 2022#vapor #releases

Laravel v9.32.0 brought the release of two new Artisan commands: env:encrypt and env:decrypt.

These commands make it possible to securely store an encrypted copy of your application's environment file in source control, making it a living part of your application.

Doing so presents several benefits, such as:

Artisan "env:encrypt" Command

First, let's explore the env:encrypt command. This command reads an environment file and encrypts the contents. Then, the encrypted contents are written to a new environment suffixed with .encrypted.

By default, the env:encrypt command will look for a .env file at the root of your application and encrypt it with a long, randomly generated key. For example, executing the following command will result in an encrypted file named .env.encrypted.

php artisan env:encrypt

The command's output displays the encryption key that was used to encrypt the file, which you should store in a secure password manager, as you will need it to decrypt the file.


Of course, the command also offers several options to give you control over the key and cipher to use and the environment you wish to encrypt. To explore these options, execute the php artisan help env:encrypt command.

Artisan "env:decrypt" Command

The env:decrypt command decrypts the encrypted environment file and writes it back to its typical location. The decryption key must be provided to the command via the --key option:

php artisan env:decrypt --key="3UVsEgGVK36XN82KKeyLFMhvosbZN1aF"

It's also possible to provide the key by defining an LARAVEL_ENV_ENCRYPTION_KEY environment variable on your server or build environment. If this environment variable is defined, the env:decrypt command will use its value as the decryption key.

To learn more about these commands and the other options they offer, you may consult the Laravel documentation.

Integration With Laravel Vapor

Laravel Vapor is a serverless PHP platform that runs on AWS Lambda. One of the limitations of Lambda is the restriction on the number of environment variables which can be associated with a given function - a hard limit of 4 KB.

Vapor offers a secondary method of adding environment variables for projects that outgrow this limit: secrets. Under the hood, secrets leverage AWS Systems Manager Parameter Store. When the Vapor runtime boots, the secrets are pulled in via the Parameter Store API and injected into the environment.

Although secrets offer a great way to add additional environment variables, they incur additional AWS billing charges. The limitations on environment variables and secrets make Vapor a prime candidate for environment encryption.

Today, we're excited to announce built-in support!

To start using encrypted environment variables with Laravel Vapor, you must first ensure you are running a version of Laravel >= v9.32.0 and Vapor Core >= v2.24.0.

Next, ensure your project contains an encrypted environment file generated by the .env.encrypted command. If you plan to deploy to production, create a file named .env.production at your project root and add all your production environment variables to this file. Make sure this file is not included in source control. Next, run the following command:

php artisan env:encrypt --env=production

The command output will display the key used to encrypt the file. You should store this key in a secure password manager.

After running the env:encrypt command, you will find an encrypted equivalent of your production environment file named .env.production.encrypted at the root of your project.

Finally, you need to provide Vapor with the key to decrypt the file when the runtime boots. Log in to the Vapor UI and navigate to your project's production environment. Click on the menu option on the top right-hand side of the screen and select "Edit Environment Variables". In the subsequent modal, add the key LARAVEL_ENV_ENCRYPTION_KEY and set the value to the encryption key displayed by the env:encrypt command:


You're ready to go! During your next deployment, Vapor will look for the presence of an encrypted environment file and attempt to decrypt it with the key set in the environment before loading the decrypted variables into the runtime.

You may find more information about this new feature in the Vapor documentation.

We hope you like this new addition to Vapor which is available to use right away!

If you are new to Vapor, register now and get started for free with our sandbox plan.

By Joe Dixon

Software Developer at Laravel.

Find me on Twitter, GitHub or my blog.

Follow the RSS Feed.