Last updated December 02, 2024

This article describes how to take an existing PHP app and deploy it to Heroku.

Prerequisites

The best practices in this article assume that you have:

• an existing PHP app that uses Composer for dependency management.
• PHP installed
• Composer installed
• a free Heroku account
• the Heroku CLI

Overview

The details of Heroku’s PHP Support are described in the Heroku PHP Support article.

Heroku PHP Support will be applied to applications only when the application has a file named composer.json in the root directory. Even if an application has no Composer dependencies, it must include an empty composer.json in order to be recognized as a PHP application.

Manage dependencies

Heroku uses Composer for dependency management in PHP projects. If your app has any dependencies, the composer.json file should specify them. It will look something like this:

{
  "require": {
    "monolog/monolog": "^3.0",
  }
}

Your PHP app can then make use of the dependencies that Composer installed. Dependencies are usually installed to the vendor/ directory after including the autoloader generated by Composer, typically like this:

require('vendor/autoload.php');

Whenever you add or change dependencies in composer.json, you must regenerate the lock file. This lock file is important to ensure reproducible behavior for your dependencies across multiple environments. It also helps ensure dev/prod parity. To generate your composer.lock file, make sure you have Composer installed and then type:

$ composer update

After updating your dependencies and re-generating the lock file, don’t forget to add and commit the changes to your Git repository:

$ git add composer.json composer.lock
$ git commit

Whenever an app gets deployed, Heroku reads the composer.lock file and installs the appropriate production dependencies into the vendor directory by running composer install --no-dev during the build. For more information, see PHP build behavior.

Each developer on your team will run composer install to install the same dependencies as everyone else, because composer.lock has “remembered” them.

How to keep build artifacts out of Git

Prevent build artifacts from going into revision control by creating a .gitignore file. The Composer vendor directory should be included in your .gitignore file. This keeps repository sizes small, simplifies dependency updates, and allows Composer to reliably install an application’s dependencies based on composer.lock

Here’s a typical .gitignore file:

vendor/
.env

Specify runtimes and extensions

Optionally, you can specify which engine (PHP or HHVM) and version to use at runtime. For more information, see the selecting a runtime article.

Any PHP extensions that are not enabled by default can be enabled via composer.json. The extensions article has a detailed list of available extensions and instructions about how to activate them.

The Procfile

A Procfile is a text file in the root directory of your application that defines process types and explicitly declares what command should be executed to start your app. Your Procfile will look something like this:

web: heroku-php-apache2

This declares a single process type, web, and the command needed to run it. The name, web, is important here. It declares that this process type will be attached to the HTTP routing stack of Heroku, and receive web traffic when deployed.

Selecting a web server

Depending on the runtime (PHP or HHVM) and web server (Apache2 or Nginx) you would like to use to run your application, the command for the web process type in your Procfile will be different. The possible options are documented in the web servers article. For example, to use Nginx as the web server instead, the Procfile would contain:

web: heroku-php-nginx

These boot scripts (heroku-php-apache2 or heroku-php-nginx) accept different options and arguments for fine-tuning the configuration of your application. Please refer to Customizing web server and runtime settings for PHP for more information.

Configuring the document root

Optionally, you can use a document root for your application that’s not the root directory of your app. To do this, modify your Procfile to add an argument at the end of the bootscript. The argument will be the name of the directory that should be used as the document root, relative to your application’s root directory.

For example, if you have a folder named public that contains your JavaScript, CSS, images and index.php file, your Procfile would define the Apache web server with that directory used as document root as follows:

web: heroku-php-apache2 public/

Deploy your application to Heroku

After you commit your changes to git, you can deploy your app to Heroku.

$ git add .
$ git commit -m "Added a Procfile."
$ heroku login
Enter your Heroku credentials.
...
$ heroku create
Creating arcane-lowlands-8408... done, stack is cedar
http://arcane-lowlands-8408.herokuapp.com/ | git@heroku.com:arcane-lowlands-8408.git
Git remote heroku added
$ git push heroku master
...
-----> PHP app detected
...
-----> Launching... done
       http://arcane-lowlands-8408.herokuapp.com deployed to Heroku

To open the app in your browser, type heroku open.

One-off dynos

Heroku allows you to run commands in a one-off dyno by using the heroku run command. Use this for scripts and applications that only need to be executed when needed, such as maintenance tasks, loading fixtures into a database, or database migrations during application updates.

For example, you can use heroku run to do a database migration for your application using Doctrine by doing something similar to this:

$ heroku run "php app/console doctrine:migrations:migrate"
Running `php app/console doctrine:migrations:migrate` attached to terminal... up, run.4062
Migrating up to 20100416130452 from 0

  >> migrating 20100416130452

     -> CREATE TABLE users (username VARCHAR(255) NOT NULL,
        password VARCHAR(255) NOT NULL) ENGINE = InnoDB

  >> migrated

For debugging purposes, such as to examine the state of your application after a deploy, you can use heroku run bash for a full shell into a one-off dyno. But remember that this will not connect you to one of the web dynos that may be running at the same time.

$ heroku run bash
Running `bash` attached to terminal... up, run.5662
$ cat Procfile
web: heroku-php-apache2
$ exit

Logging

Heroku treats logs as streams and expects them to be written to STDOUT and STDERR and not to its ephemeral filesystem.

The most basic way of sending logging information is to write to the php://stderr stream in your code like this:

file_put_contents("php://stderr", "something happened!");

Refer to the logging documentation for more general information about logging on Heroku.

Next steps

• Read the Heroku PHP Support documentation to learn about available versions, extensions, features and behaviors.
• Learn how to customize web server and runtime settings for PHP, in particular how to set the document root for your application.
• Use a custom GitHub OAuth token for Composer.
• Explore the PHP category on Dev Center.