Please note that these documents apply to OpenShift Online v2 only (accounts created before August 1st, 2016).
If you are using one of the OpenShift 3 products, please refer to documents available at

Getting Started with PHP

It’s easy to get up and running with PHP on OpenShift.

Step 1: Create a PHP Application

This tutorial walks through the creation of an application titled myphpapp under the domain mydomain. Before going through the rest of the tutorial, be sure to have created an OpenShift account and installed the RHC command line tools.

Once that is completed, open a terminal on a local machine and change into the directory where you would like the OpenShift application source code to be located. At the command prompt, enter the following command to create a PHP application:

$ rhc app create myphpapp php-5.4


$ rhc app create myphpapp php-5.3

The output will look something like this:

Application Options
Domain:     mydomain
Cartridges: php-5.4
Gear Size:  default
Scaling:    no

Creating application 'myphpapp' ... done

Waiting for your DNS name to be available ... done

Cloning into 'myphpapp'...
Warning: Permanently added the RSA host key for IP address '' to the list of known hosts.

Your application 'myphpapp' is now available.

  URL: (1)
  SSH to:
  Git remote: ssh://
  Cloned to:  /home/me/git_demo/myphpapp (2)

Run 'rhc show-app myphpapp' for more details about your app.
1 Public URL of application
2 Location of local Git repository

The application will now be running and accessible at the URL (1) listed in the output. A local Git repository for your application was also created in the directory listed under Cloned to (2).

Step 2: Make the First Change

A developer on OpenShift can make code changes on a local machine, check those changes in locally, and then git push those changes to OpenShift. One of the primary advantages of the Git version control system is that it does not require a continuous online presence in order to run. A developer can easily check in (commit, in Git terminology) and revert changes locally before deciding to upload those changes to OpenShift.

Using the Git Repository

To make the first change, edit index.php in the myphpapp directory. Go to the file in the terminal and edit with a command line editor such as Vim or Emacs. Alternatively, edit the file using any text editor or IDE. Strip out everything between the two <body> tags and change the content to look like this:

        <h1>Hello world!</h1>

Now that you have made this incredibly complicated code change, the new code must be deployed to the server. You can accomplish this task using Git.

  1. To add the change to the Git repository’s index and stage it for the next commit, use the command git add:

    $ git add --all .
  2. Next commit the staged changes to the Git repository, with a log message to explain the changes:

    $ git commit -m "Your commit message"
  3. Finally, push these changes to the remote OpenShift application.

    $ git push

The output of the push command will first show the git push, and then the build process and deployment of the code on OpenShift. When the build is finished, go back to the application’s URL ( and you should see a page that simply says "Hello World".

This is the basic process to follow when developing an application: git add, git commit, and finally git push.

If you are curious about Git or would like to learn more, the Pro Git book is a great resource.

Step 3: Managing Dependencies

Your PHP application code may rely on third-party libraries that you wish to include in your build. To add dependencies using the PHP Extension and Application Repository (PEAR), add the names of the libraries in .openshift/pear.txt. For example, the contents of your pear.txt file could be the following:


Use Git to add, commit, and push your changes to pear.txt to OpenShift.

To use an alternative dependency manager, such as Composer, add any commands you would like to be executed at build time on OpenShift into an action hook script at .openshift/action_hooks/build.

Setting Your Document Root

The DocumentRoot is chosen by the cartridge control script logic depending on conditions in the following order:

IF php/ dir exists THEN DocumentRoot=php/
ELSE IF public/ dir exists THEN DocumentRoot=public/
ELSE IF public_html/ dir exists THEN DocumentRoot=public_html/
ELSE IF web/ dir exists THEN DocumentRoot=web/
ELSE IF www/ dir exists THEN DocumentRoot=www/
ELSE DocumentRoot=/

As I’m sure you’ve guessed, this makes the new OpenShift app directory structure compatible with all major upstream PHP projects, including Drupal, WordPress, Joomla, Zend Framework Skeleton Apps and many others.

Enabling 'Development' Mode

When you develop your PHP application on OpenShift, you can also enable the 'development' environment by setting the APPLICATION_ENV environment variable, using the rhc client, like:

$ rhc env set APPLICATION_ENV=development

Then, restart your application:

$ rhc app restart

If you do so, OpenShift will run your application under 'development' mode. In development mode, your application will:

Using the development environment can help you debug problems in your application in the same way as you do when developing on your local machine. However, we strongly advise you not to run your application in this mode in production.

Other Tips

To find out how OpenShift selects the Apache document root for your PHP application code, see the Repository Layout section. A list of directories automatically added to the include_path is also included in the Repository Layout guide.

Hot Deploy and Other Markers

By default, when a git push occurs as outlined above, OpenShift starts and stops the Apache server to deploy the new build. However, it is possible to deploy code without restarting the server. See Hot Deployment for more information on how a marker file in the Git repository can be used to turn on this build style.

More PHP marker files are listed in the Markers section.

Adding a Database to an Application

Find out how to add a database to your application by going to the Adding a Database guide.

You should only use environment variables to specify the connection parameters for your database. Using hard coded names, ports, or credentials limits the resusability of your app and can potentially break your app during OpenShift maintenance.

Next Steps

The best next step is to create an application using OpenShift.

Look at the Application Gallery and Developer Spotlight to see what other developers have created on OpenShift.

Browse the QuickStarts and community cartridges to see other exciting technologies you can use in your applications.

Finally, if at any point you have questions or issues, please visit the Help Center for a full list of options.