Testing and Deploying a PHP App in Ubuntu

If you've been learning PHP in an online classroom like Codecademy you may find yourself surprised when setting up your workstation for PHP development.

Unlike HTML or JavaScript code which will run automatically in your browser, PHP code -- even if it works perfectly well in your online IDE -- will not work on localhost unless you are running it from a server.

Without a server to render your PHP code, your may find your browser prompting you to download the PHP file you're trying to open, or just displaying the PHP code without rendering it. In technical terms, while JavaScript is a client-side scripting language, PHP is a server-side language.

Hence, to get your PHP code working in localhost, you will need to run it with a server. One popular solution is to use a prepackaged stack like XAMPP which will contain Apache (the server), MariaDB (a popular MySQL database), and PHP. Such prepackaged stacks will save you a lot of installation time.

However, if your OS is a Linux distribution like Ubuntu, you can take the opportunity to set up a classic LAMP stack (Linux, Apache, MySQL, PHP). Setting this up will however require extra configuration in addition to installing the software.

MySQL

Let's start with the database installation. I recommend MariaDB as it offers an optimized installation of MySQL. These commands will install MariaDB and set up the database's security options according to your preferences:

sudo apt update
sudo apt install mariadb-server
sudo mysql_secure_installation

Apache

Next, you need to install the Apache server:

sudo apt install apache2

Now that you have an Apache server running on your machine, you will need to configure Ubuntu's firewall. You can run sudo ufw app list to see the available firewall profiles and sudo ufw app info "Profile Name" to get information on a particular profile:

If you like a particular profile, say in this case, Apache Full, you can activate it with the command sudo ufw allow in "Apache Full"

You can now open http://localhost/ in your browser to see your Apache server running:

However, additional configuration is still needed for Apache to render your PHP code. By default, Apache will open files saved in the /var/www directory. However, this directory is protected and you will need to sudo to write into it. Hence it won't be good practice to keep your code here.

A better solution will be to activate Apache's User Directory feature, which will allow you to run your PHP code from a new public_html directory in your home folder. The following command will activate the User Directory feature:

sudo a2enmod userdir

Next, you will need create the User Directory (~/public_html) and set the correct directory permissions:

mkdir $HOME/public_html
chmod +x $HOME
chmod 755 $HOME/public_html

You will then need to enable PHP scripting in the User Directory (by default Ubuntu disables this). To do this, first:

cd /etc/apache2/mods-enabled/

When you are in the /etc/apache2/mods-enabled/ directory, use the command ls to look for the PHP configuration file. It will be named php[version_number].conf:

In this example, the version number is 7.4 and you will need to edit php7.4.conf to activate PHP scripting in the User Directory:

sudo nano php7.4.conf

Look for the following lines:

<IfModule mod_userdir.c>
   <Directory /home/*/public_html>
       php_admin_flag engine Off
   </Directory>
</IfModule>

Add an # at the start of each line to deactivate Ubuntu's disabling of PHP scripting in the User Directory:

# <IfModule mod_userdir.c>
#    <Directory /home/*/public_html>
#        php_admin_flag engine Off
#    </Directory>
# </IfModule>

The file should now look like this:

Press Control-O to save the file and then Control-X to exit the text editor.

In that same directory, you will also need to edit another Apache configuration file:

sudo nano /etc/apache2/mods-enabled/dir.conf

Look for this line:

DirectoryIndex index.html index.cgi index.pl index.php index.xhtml index.htm

In this line, cut and paste index.php so that it comes before index.html:

DirectoryIndex index.php index.html index.cgi index.pl index.xhtml index.htm

Save the file and exit. You will now need to restart Apache to active the new settings:

sudo systemctl restart apache2

PHP

The final part of the LAMP stack is of course PHP:

sudo apt install php libapache2-mod-php php-mysql

This command will install PHP as well as the packages needed for PHP to access Apache as well as MariaDB.

You should now be able to run your PHP code in your new LAMP stack. To test this, write and save a PHP file in your public_html directory. Here's a very simple -- but useful! -- PHP script you can use:

<?php
    phpinfo();

Save this in your public_html directory. I have named mine test.php but you can name it anything you want; just make sure the filename has the .php suffix.

Open your browser and go the following address (replace username with your Ubuntu username and filename with the name you gave your test file):

http://localhost/~username/filename.php

In my case, the URL is http://localhost/~alvin/test.php. My LAMP stack has successfully rendered the PHP script in the browser:

Deploying to Production

Given these complicated steps just to render a PHP script in localhost, you might imagine that deploying a PHP app would be similarly complicated, and you would be right!

Apps written in PHP will not run on platforms like Netlify which are designed to host static apps. While you can host and run your PHP app on Heroku, it has to be deployed with a composer.json companion file otherwise the deployment will fail. To generate a composer.json file, you will need to use install and use Composer. Please refer to its documentation for instructions on how to do this.

The purpose of composer.json is to keep track of the dependencies of your PHP app, but even if your app has no such dependencies, you will still need to generate a composer.json file if you want to deploy your app to Heroku. My Magic 8-Ball PHP app, which is hosted on Heroku, has one such dependency-free composer.json file:

But it's important to keep the goal in mind. Once you get past the hurdle of creating a composer.json file, you will have a shiny new PHP app for your portfolio!