PHP¶

PHP is a popular general-purpose scripting language that is especially suited to web development.

PHP Versions¶

Opalstack supports PHP versions 8.1, 8.0, 7.4, 7.3, and 5.6.

Changing PHP Versions for Web Applications¶

The default PHP version for web applications is version 7.4.

To change the PHP version for your application:

Click on Applications in the dashboard sidebar.
Click the Edit icon (a pencil) for your application in the Application list in the lower half of the page. A form will appear.
Select the desired PHP version on the form. If no version is selected then then application is the default value.
Click the green "Update Application" button to save your changes.

Using Different PHP Versions at the Command Line¶

The default PHP version for the command line - that is, what you get when you run "php" - is version 7.3.

To run other PHP versions, the commands are:

PHP 5.6: php56
PHP 7.4: php74
PHP 8.0: php80
PHP 8.1: php81

Configuring PHP Settings for Web Applications¶

Settings for PHP applications installed via the Opalstack dashboard can be configured as follows:

Create a file named .user.ini in your application directory.

Note the leading dot . character at the beginning of the filename. This dot is required.
Edit your .user.ini file to specify your PHP settings.

Each setting should be on an individual line in the format directive = value.

You can use any PHP directives that are listed as PHP_INI_ALL or PHP_INI_PERDIR in the "Changeable" column in the official list of INI directives.
Save your .user.ini file. Your changes are effective immediately.

Example: setting the maximum file size for uploads¶

The maximum file size for uploads in our default PHP configuration is 64MB. If your PHP application needs to be able to accept larger uploads, for example 128MB, then create a .user.ini file as described above and include the following lines:

post_max_size = 128M
upload_max_filesize = 128M

Tuning PHP-FPM Settings for Performance¶

Most PHP-FPM applications installed via your Opalstack dashboard include two options for performance tuning:

FPM Max Child Threads: this is the maximum number of processes that will run to serve your site.
FPM Max Requests: this is the number of requests that each process will serve before restarting.

Our general recommendations for these settings are:

If your site is struggling due to heavy traffic, then use a higher value for FPM Max Child Threads. Note that this may result in higher memory usage due to a higher number of simultaneous requests to your site.
If your site is using too much memory due to a memory leak then use a lower value for FPM Max Requests. Note that this may result in lower performance due to the overhead of starting new processes to service more requests.

In practice, effective performance tuning may require adjustments to both of these parameters. Opalstack makes no specific recommendations as to how these parameters should be set for a particular application or level of traffic. To figure out the best settings for your site, you will need to monitor your site's performance and adjust the settings accordingly.

Installing Composer¶

Composer is a dependency manager for PHP that is used for package management in modern PHP web frameworks.

To install Composer in your home directory:

Log into a SSH session as your application's shell user.

Run the following commands to download and install Composer:

cd ~
mkdir -p ~/bin
wget -O composer-setup.php https://getcomposer.org/installer
php composer-setup.php --install-dir=$HOME/bin --filename=composer
rm composer-setup.php

Once these steps are completed you can use Composer by running composer or ~/bin/composer at the command line.

Password Protection for PHP+Apache Applications¶

If you need password protection for a PHP+Apache application that does not provide its own authentication then you can use Apache HTTP authentication as an alternative.

Note: this feature is not available for PHP-FPM+Nginx applications. It is only for PHP+Apache and the corresponding symlink app types.

To do so:

Log into a SSH session as your application's shell user.
Run the following commands to create the password file. This example will use myuser as the shell user name, myapp as the application name, and webuser as the name of the HTTP authentication user.
```
cd ~/apps/myapp
htpasswd -c .htpasswd webuser
```
Enter the password for webuser twice as prompted.
Add the following to your application's .htaccess file (if your app does not have a .htaccess file you can run touch ~/apps/myapp/.htaccess to create it):
```
<Files .*>
  Require all denied
</Files>

AuthUserFile /home/myuser/apps/myapp/.htpasswd
AuthName MyApp
AuthType Basic
Require valid-user
```

If you need to create additional HTTP authentication users for your application, you can re-run the htpasswd command without the -c flag like so:

htpasswd .htpasswd anotheruser

PHP exec, passthru, shell_exec, and system¶

The PHP exec, passthru, shell_exec, and system functions are disabled by default on PHP apps installed via our dashboard.

If you'd like to have these function enabled for your PHP application, then please contact us to let us know the shell user and application for which you want them enabled.

Troubleshooting PHP Applications¶

Browser displays a blank page instead of rendered pages¶

View the source of the blank page as it may contain partially-rendered code and/or error messages related to the problem.
Check your application's error logs in ~/logs/appname as it may contain error messages related to the problem.
If your application has a debug mode of operation then activate it and reload the page. This may allow the application to display diagnostic information and/or error messages related to the problem.

Why is my site serving PHP source instead of my site?¶

If your PHP site is serving its source code instead of rendered HTML then please check the following:

PHP handlers in .htaccess¶

If your app is using a .htaccess file then look for something like the following in that file:

<FilesMatch .php$>
    SetHandler php72-cgi
</FilesMatch>

Delete the SetHandler line. If the FilesMatch block doesn't contain anything else, then delete the entire block.

Save the file and reload the site in your browser.

You can quickly locate .htaccess files that might need your attention with the following command:

grep -R --include=".htaccess" -iE "(Set|Add)Handler.+php" ~/apps

Wrong application type¶

Check the application type for your application in the app list.

If you chose a static app type instead of a PHP app type when you created your application then contact support to have it changed.

Installing and Using PEAR Packages¶

PEAR (the PHP Extension and Application Repository) is a framework and distribution system for reusable PHP components.

To install PEAR in your home directory:

Log into a SSH session as your application's shell user.

Execute the following commands to download and launch the PEAR installer:

cd ~
mkdir ~/tmp
wget https://pear.php.net/go-pear.phar
php go-pear.phar

You will be prompted to review the file layout for the PEAR installation:

Below is a suggested file layout for your new PEAR installation.  To
change individual locations, type the number in front of the
directory.  Type 'all' to change all of them or simply press Enter to
accept these locations.

 1. Installation base ($prefix)                   : /home/username/pear
 2. Temporary directory for processing            : /home/username/tmp/pear/install
 3. Temporary directory for downloads             : /home/username/tmp/pear/install
 4. Binaries directory                            : /home/username/pear/bin
 5. PHP code directory ($php_dir)                 : /home/username/pear/share/pear
 6. Documentation directory                       : /home/username/pear/docs
 7. Data directory                                : /home/username/pear/data
 8. User-modifiable configuration files directory : /home/username/pear/cfg
 9. Public Web Files directory                    : /home/username/pear/www
10. System manual pages directory                 : /home/username/pear/man
11. Tests directory                               : /home/username/pear/tests
12. Name of configuration file                    : /home/username/.pearrc

1-12, 'all' or Enter to continue:

Press Enter to accept the defaults.

You will be prompted to modify the system php.ini file:
```
Would you like to alter php.ini </etc/php.ini>? [Y/n] :
```
Type n at the prompt and press Enter

Once these steps are completed you can install PEAR packages by running ~/pear/bin/pear install packagename the command line, replacing packagename with the name of the PEAR package that you want to install.

Using PEAR packages in your PHP applications¶

After you've installed PEAR and have used it to install the packages that you need, you can then configure your applications to use those packages as follows:

Create a .user.ini file in your application directory. See Configuring PHP Settings for details.
Add the following line to the .user.ini file from step 1, replacing username with the name of your application's shell user:
```
include_path = .:/home/username/pear/share/pear
```

Once these steps are completed your application will be able to locate and use the PHP packages that you've installed from PEAR.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search