A Comprehensive Tutorial for Deploying Laravel 4 on Heroku [DATED]

Posted by Adam Engebretson on September 26, 2013

Learning to use Heroku can be a burden, especially when there is no explicit documentation for PHP users. The fact that Heroku supports PHP at all is a little-known fact to most people. I've formulated this tutorial to give Laravel users hope and guidance!

Note: This guide is old, and no longer appropriate for deploying to Heroku. Check out Matt Stauffer's more recent blog post: http://mattstauffer.co/blog/laravel-on-heroku-using-a-mysql-database

The Build Pack

I found this buildpack on GitHub, and was amazed at how easily I was able to get it to work. The buildpack can be found at https://github.com/winglian/heroku-buildpack-php. Thanks winglian!

This buildpack has everything that Laravel needs to operate, namely Composer and mcrypt. The great part is that the compile script in this buildpack automatically downloads and executes composer install for you.

The Laravel Repo

To get this thing working, the first step is to install Laravel by using composer create-project laravel/laravel. If you prefer to download the tarball or use git clone, you're welcome to as well. Once you have Laravel cloned, you'll need to make some changes to the composer.json file.

If you do not use composer create-project laravel/laravel to install Laravel, make sure to execute php artisan key:generate before you commit your changes!

When Heroku is building your app, it executes the compile script (and composer install) in a temporary build directory. Therefore, running php artisan optimize, as deemed by composer.json, will not work; the build will fail and your app will not deploy on Heroku. Through some debugging, however, I was able to discover that the environment variable _ points to $BUILD_DIR/bin/php while composer is executing. Fortunately, the _ environment variable will be set to your local php when you execute php composer.phar install on your local machine. Thus, you can update the "scripts" attribute in composer.json to the following.

"scripts": {
    "post-install-cmd": [
        "$_ artisan optimize"
    ],
    "pre-update-cmd": [
        "$_ artisan clear-compiled"
    ],
    "post-update-cmd": [
        "$_ artisan optimize"
    ],
    "post-create-project-cmd": [
        "$_ artisan key:generate"
    ]
},

Now, let's throw this all into a git repository.

$ git init
$ git commit -am 'Initial Laravel Install'

The Heroku App

Assuming you have the Heroku Toolbelt installed, you can simply execute the following command:

$ heroku create laravel --buildpack https://github.com/winglian/heroku-buildpack-php

Make sure to use a unique app name! "laravel" is already taken. ;)

Once the heroku remote has been added, execute:

$ git push heroku master

to push your changes to Heroku.

Allow the build to complete, including the installation of composer dependencies, and "You have arrived."

Best Practice

Best practice suggests that you never execute composer update in production, and therefore it is recommended that you include a composer.lock into your repository. The buildpack above executes php composer.phar install --prefer-dist.

Troubleshooting

When I tried to proof-read this tutorial and follow the steps from the beginning, I encountered this error after running git push:

Fatal error: Class 'Composer\Script\EventDispatcher' not found in phar:///tmp/build_8a13f5b0-a567-46f6-a41c-dc463d08ba6a/bin/composer/src/Composer/Factory.php on line 250

Not exactly sure what's causing this error, but executing git push again worked just fine. Any insight? Share in the comments.