Laravel on Heroku - Using a Buildpack locally to mimic your Heroku environment (Nginx)

(This is part of a series of posts on Laravel on Heroku. Check back soon for more.)

  1. Installing a Laravel app on Heroku
  2. Laravel on Heroku - Using a MySQL database
  3. Laravel on Heroku - Using a PostgreSQL database
  4. Laravel on Heroku - Using a Buildpack locally to mimic your Heroku environment (Nginx)

So by this point you've got your app and running, and deployed to Heroku. You probably even have a ClearDB MySQL database connected to it on Heroku.

But your local environment and database are not particularly in sync with your production environment. Thankfully, Heroku provides the ability to run their "buildpacks" locally to ensure a local environment that's in sync with your remote environment.

Note: I wrote a blog post to get this running on a local Apache install, but the number of steps and configuration issues it required was out of reach for a simple tutorial. The folks at Heroku have shared that they're in the middle of making changes to the Apache configuration for the buildpack, so I expect it'll get easier soon. For now, let's roll with Nginx.

Open up your app's composer.json and add the following to the end of it (or just add the buildpack to your require-dev section, if you already have one):

  "require-dev": {
    "heroku/heroku-buildpack-php": "dev-master"

Run composer update, and you'll now have the Heroku PHP Buildpack installed locally. Now, create a file in your project root directory named .env and place the following code into it:


This file is a configuration file for the Buildpack, setting an environment var named CLEARDB_DATABASE_URL and setting its value to mysql://root:123abc@ This version we created is just for local testing, so add it to your .gitignore.

Note that you'll need to update the username (root), password (123abc), and database name (my_laravel_heroku_database_name) for your local environment. Heroku's local buildpack won't be serving MySQL for you, so you'll need MySQL running.

NOTE: If you don't have a command-line mysql accessible and working, Mac/Homebrew users can brew install mysql and then follow the directions to have launchd start mysql at login. I believe the default username is root and the default password is blank.

Finally, run foreman start (unfamiliar with Foreman? Check out my blog post introducing Procfiles) to get everything up and running.

Note: If you get the following response: This program requires PHP 5.5.11 or newer; check your 'php' command., it means your local version of PHP is not up to date with what Heroku is expecting. Run php -v on the command line to find what version you're running. Hopefully you're on a Mac using Homebrew, because if you are it's a relatively painless fix: run brew update, then brew install --with-fpm php55 and then `brew install php55-mcrypt'. Follow the instructions that are output after you run the installer and you should have PHP 5.5 up and running shortly.

You'll now have a CLEARDB_DATABASE_URL env var available for use in your local database.php just like we did in the production database.php (but note we've added a bit to the code to allow for null passwords locally). The benefit of using the .env file like is this it that we can use the same database.php on dev and prod, and just rely on the .env file to change up the database credentials:

$url = parse_url(getenv("CLEARDB_DATABASE_URL"));

$host = $url["host"];
$username = $url["user"];
$password = array_key_exists('pass', $url) ? $url["pass"] : '';
$database = substr($url["path"], 1);

return array(
    'mysql' => array(
        'driver'    => 'mysql',
        'host'      => $host,
        'database'  => $database,
        'username'  => $username,
        'password'  => $password,
        'charset'   => 'utf8',
        'collation' => 'utf8_unicode_ci',
        'prefix'    => '',

With that, you have a development-ready local environment that mimicks the Heroku PHP buildpack. Just visit localhost:5000 in your browser and you're good to go!

Comments? I'm @stauffermatt on Twitter

Tags: laravel | heroku | nginx

Matt Stauffer headshot

Hi, I'm Matt Stauffer.

I'm partner & technical director at Tighten Co.

You can find me on Twitter at @stauffermatt

Like what you're reading?

I wrote an entire 400+ page book for O'Reilly: Laravel: Up and Running.

You can pre-order the ebook or print book today.