Getting started with Laravel and PHP on Heroku

Recently, Heroku added official beta support for deploying PHP applications on their system. I'm going to discuss how to create a new Laravel project and push it to Heroku as well as how to migrate any of your existing projects.

The benefits of using Heroku

Easy Administration

The best part by far about Heroku is that you no longer have to be a server administrator to your clients. We've all had problems in the past where you get a phone call from a client at 7:00am informing you their site is down. You frantically try everything possible to fix it while waiting on hold for technical support for 3 hours only for them to tell you it's a problem on their end and there is nothing you can do but wait for it to come back.

Sure, this isn't true with all providers, but the fact remains that you are the one responsible and you have to figure it out if it breaks.

With Heroku, because you simply host an app on their service, you don't need to worry about all the extra server details and there is a lot less things that can go wrong. If your app deploys without any errors then it's likely you will never experience a problem. I've never had any service disruption with them and when I had a minor technical issue with an add-on they were able to point me in the right direction quickly.


Another great feature of Heroku is the scalability. Heroku lets you start running and testing apps for free. If you ever get big enough that the free plan is too slow you can always scale up your app without having to change any code, migrate databases, or do anything exceedingly technical. You just have to drag a few sliders in the admin panel or run a couple commands in the terminal.


Heroku also comes with a plethora of add-ons you can take advantage of with a single click or command. This makes it easy to set up any type of database you need without a cumbersome configuration.

Note that currently not all add-ons play nice with PHP, but with the announcement of native PHP support I'm sure Heroku has some plans for that.

Deploying with Heroku

Heroku did have unofficial support for PHP before this announcement but you had to use custom buildpacks, however, we are not going to be using them. If you were previously using a buildpack and are trying to convert your app you may run into some issues. You can remove the old buildpack with heroku config:unset BUILDPACK_URL.


Make sure you have Git, Composer, and Heroku Toolbelt installed.

1. Create (or open) your Laravel app

There are many ways to do this available on the Laravel website so we won't go into too much detail. If you already have a Laravel project open you can skip ahead, otherwise create a new project with:

composer create-project laravel/laravel --prefer-dist  

2. Preparing the environment

Heroku runs applications from the root directory by default, but since Laravel uses the public directory we need to tell Heroku to use that folder instead. To do this we need to make a file named Procfile in the project root. All this file needs to contain is:

web: vendor/bin/heroku-php-apache2 public  

We might also run into some problems with composer because Laravel doesn't add composer.lock to git by default. If you get the following error when pushing to Heroku you need to make sure you remove composer.lock from your .gitignore so it can be pushed correctly.

!     ERROR:        Your composer.json specifies dependencies, but no composer.lock
      was found, please check it into your repository along with composer.json!

!     Push rejected, failed to compile PHP app

3. Preparing a database

There are a couple ways to prepare a database. You can login to the Heroku website and create an add-on for whatever type of database you'd like (Postgres, MySQL, Mongo, etc.), or you can run the command from your terminal.

In this tutorial we will be creating a Postgres database from the terminal.

heroku addons:add heroku-postgresql:dev  

Once you've done that you'll need to get the database info. You can access it from the Heroku website (under the databases tab) or from the command line by pulling it out of the DATABASE_URL in your Heroku config.

heroku config

=== your-app-name Config Vars
DATABASE_URL: postgres://username:password@host:port/database_name  

Grab your username, password, host, port, and database_name and put them in your app/config/database.php.

'pgsql' => array(  
            'driver'   => 'pgsql',
            'host'     => 'host',
            'database' => 'database_name',
            'username' => 'username',
            'password' => 'password',
            'charset'  => 'utf8',
            'prefix'   => '',
            'schema'   => 'public',

You can now set up your database migrations and seeds. Have a look at the extensive documentation on the Laravel website to help you if you are unfamiliar. Once you are ready move on to the next step.

4. Push to git

We're now ready to add and push all our changes to git. Note that you do not need to push to Github or Bitbucket you just need a local repository.

git add -A  
git commit -m "initial commit"  
git push  

5. Push to Heroku

If you haven't already made a project with Heroku you'll need to do that first. It can be done either on their website or from the command line with:

heroku create  

If you instead have an existing project you'll need to add the URL to your git remote so you can push the changes.

heroku git:remote -a your-app-name  

Then you can simply tell git to push to heroku.

git push heroku master  

Alternatively, if you are working from a branch and want to push the branch instead of master, you can do something like this:

git push heroku yourbranch:master  

After successfully running this command a bunch of text will start flying through your terminal as it starts downloading and installing all the packages. If you get any errors make sure you followed step 2 properly and, if you made changes, don't forget to add them to git.

5. Running Artisan commands on Heroku

We should now have our app successfully installed on Heroku, but there's still more to do! On our local machines we have the ability to use artisan for lots of useful tasks. To use artisan on Heroku it's a little bit different but still really simple. You just need to remember to prefix your commands with heroku run.

So, for example, to migrate the database we need to run:

heroku run php artisan migrate  

That's it!

Your Laravel app should now be online and ready to go!

If you have any questions please leave them in the comments.

Thanks for reading.

comments powered by Disqus