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:

CLEARDB_DATABASE_URL=mysql://root:123abc@127.0.0.1/my_laravel_heroku_database_name

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@127.0.0.1/my_laravel_heroku_database_name. 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!