PHP

Several application types use or may use PHP, including Static/CGI/PHP applications, WordPress, and Drupal.

PHP on the Command Line

The PHP command-line interface, php, is installed on all WebFaction servers. Several versions of the command-line interface are available. You can specify a version of PHP by running phpXY, where XY is the major and minor version number. For example, to use the command-line interface for PHP 5.6, run php56.

The default version (the version that runs when you run the php command) and available versions vary by server:

Operating system Default php version PHP 5.2 PHP 5.3 PHP 5.4 PHP 5.5 PHP 5.6 PHP 7.0
CentOS 5 5.2 Yes Yes Yes Yes Yes  
CentOS 6 5.2 Yes Yes Yes Yes Yes Yes
CentOS 7 5.6 Yes Yes Yes Yes Yes Yes

To find the default version of PHP on your server, run php --version. To find your server’s operating system, see Finding Your Server’s Operating System.

Configuring PHP

You may configure PHP settings (also known as directives) using a file with a .ini extension located in your PHP-based application’s directory. Typically, this file is called php.ini but any and all files named with an ending .ini are scanned for PHP settings.

Note

List of php.ini directives provides a table of possible settings. Only settings listed as PHP_INI_PERDIR or PHP_INI_ALL in the Changeable column may be changed. Settings listed as PHP_INI_SYSTEM settings will not work with the following directions.

Note

If you’re using the optional FastCGI deployment method, please see Using FastCGI for additional configuration details.

To configure a PHP-based application:

  1. Create php.ini if it does not already exist.
    1. Open an SSH session to your account.
    2. Enter touch ~/webapps/application/php.ini where application is the name of the application as it appears in the control panel, and press Enter.
  2. Edit php.ini.
    1. Open ~/webapps/application/php.ini in a text editor.
    2. For each setting, add a new line containing name = value, where name is the name of the directive and value is the new value for the setting.
    3. Save and close the file.

Configuring an Upload Limit

To configure an upload limit for PHP-based applications:

  1. Create php.ini if it does not already exist.

    1. Open an SSH session to your account.
    2. Enter touch ~/webapps/application/php.ini where application is the name of the application as it appears in the control panel, and press Enter.
  2. Edit php.ini.

    1. Open ~/webapps/application/php.ini in a text editor.

    2. Add these lines to the end of the file:

      upload_max_filesize = XM
      post_max_size = XM
      

      where X is the maximum number of megabytes you want to allow to be uploaded.

    3. Save and close the file.

Configuring DOCUMENT_ROOT

The DOCUMENT_ROOT setting has two possible default values:

  • For websites with one PHP-based application, DOCUMENT_ROOT is set to /home/username/webapps/application, where username is your username and application is the name of the PHP-based application.
  • For websites with two or more PHP-based applications, DOCUMENT_ROOT is set to /home/username/webapps/_.

To change the value of DOCUMENT_ROOT:

  1. Create set_document_root.php.

    1. Open an SSH session to your account.

    2. Enter touch ~/webapps/application/set_document_root.php, where application is the name of the application as it appears in the control panel, and press Enter.

    3. Open ~/webapps/application/set_document_root.php in a text editor.

    4. Insert these lines:

      <?php
        $_SERVER['DOCUMENT_ROOT'] = '/home/username/webapps/example_application';
      ?>
      

      where the string following the equal sign is the new DOCUMENT_ROOT path.

    5. Save and close the file.

  2. Create php.ini if it does not already exist.

    1. Open an SSH session to your account.
    2. Enter touch ~/webapps/application/php.ini where application is the name of the application as it appears in the control panel, and press Enter.
  3. Edit php.ini.

    1. Open ~/webapps/application/php.ini in a text editor.
    2. Add a new line containing auto_prepend_file = "/home/username/webapps/application/set_document_root.php" where application is the name of the application as it appears in the control panel.
    3. Save and close the file.

Using FastCGI

Note

FastCGI is available on servers web120 and greater or dweb61 and greater. If you have a plan on a server that does not support FastCGI, you may request a server migration. Please see Migrating Servers for more details.

Warning

FastCGI deployments do not use php.ini configuration files. If you’re switching an existing PHP application to FastCGI and that application has a php.ini file, please rename the file to .user.ini.

You can use FastCGI as an alternative deployment method for PHP scripts. Although it consumes your account’s memory, it has better performance characteristics for some applications. To enable FastCGI:

  1. Open $HOME/webapps/application/.htaccess in a text editor, where application is the name of the PHP-based application.

  2. Insert the following lines:

    <FilesMatch \.php$>
        SetHandler <handler>
    </FilesMatch>
    

    where <handler> is the FastCGI handler you want to use. Acceptable values are:

    • php54-fcgi
    • php55-fcgi
    • php56-fcgi
    • php70-fcgi

    Additionally, you can run up to six FastCGI processes by appending an integer 2-6. For example, to use FastCGI with PHP 5.4 and 3 processes, enter php54-fcgi3 in place of <handler>.

  3. Save and close the file.

Subsequent requests will use FastCGI with the PHP interpreter and the number of processes you selected.

Installing a Custom PHP Package

While WebFaction provides installers for some of the most popular PHP web applications, we cannot provide installers for all. Many packages use a familiar installation process, however. For most PHP-based packages, follow this procedure:

  1. Create a website with a new Static/CGI/PHP application.

  2. Download the software package and review its README and installation files. Review other documentation, like the software’s website, as needed.

  3. If applicable, create a database for your application. Make a note of the database name, username, and password.

  4. Upload the package to the Static/CGI/PHP application, ~/webapps/app, where app is the name of the application as it appears on the control panel.

  5. Start the package’s installation process. Typically, the application will have a specific URL for you to open. For example, MediaWiki uses domain_path/config/index.php, where domain_path is the domain and URL path, to start the installation process. See your software package’s documentation for details. Follow the on-screen instructions.

    Some packages may not provide a web-based install procedure. For such applications, review and follow the provided documentation.

    Note

    Many packages include a step to delete installation files. If it applies, don’t skip this step! Failing to do so may allow others to gain control of your application and data.

Installing and Using PEAR Packages

PEAR, or the PHP Extension and Application Repository, is a collection of commonly-used PHP packages. You can use the PEAR package manager to install such packages in your home directory.

Installing the PEAR Package Manager

Before you can use PEAR to install packages, you must create a PEAR installation in your home directory:

  1. Open an SSH session to your account.

  2. Create a directory for PEAR. Enter mkdir $HOME/pear and press Enter.

  3. Create a PEAR configuration file. Enter pearXY config-create $HOME $HOME/.pearrc, where XY is the major and minor version of PHP you want to use, and press Enter.

    For example, to use PHP 5.6, enter pear56 config-create $HOME $HOME/.pearrc and press Enter.

  4. Install PEAR. Enter pearXY install -o PEAR and press Enter.

Installing PEAR Packages

  1. Open an SSH session to your account.

  2. Add the PEAR installation directory to your PATH. Enter export PATH=$HOME/pear:$PATH and press Enter.

  3. Install a package. Enter pear install package, where package is the name of a PEAR package, and press Enter.

    See also

    For a complete list available packages, see the PEAR List Packages page.

Using PEAR Packages

Before you can require or include an installed PEAR package in a PHP script, you must add the ~/pear/php directory to your include_path.

To add add the ~/pear/php directory to the include_path for a single script, include this line before any require or include statements:

set_include_path(get_include_path() . PATH_SEPARATOR . '/home/<username>/pear/php');

where <username> is your username.

Alternatively, you can set the include_path to .:/home/username/pear/php, where username is your username, in a PHP configuration file.

Serving HTML Files as PHP Scripts

By default, WebFaction Static/CGI/PHP and PHP-based applications treat files ending in .html as plain HTML to serve those pages as quickly as possible. You can override that default, but the process varies from server to server.

For servers Web120 and higher, edit or create a .htaccess file in the directory you want to serve HTML files as PHP scripts to contain this line:

AddHandler php56-cgi .html

For servers Web119 and lower, edit or create a .htaccess file in the directory you want to serve HTML files as PHP scripts to contain these lines:

<IfModule !php5_module>
    RewriteEngine on
    RewriteBase /
    RewriteCond %{REQUEST_URI} \.html$
    RewriteRule (.*) http://127.0.0.1:2480/$1 [P]
</IfModule>
AddHandler php5-script html

Alternatively, to serve files ending in .php as if they were .html files, edit or create a .htaccess file in the directory you want to serve the PHP files with the .html extension to contain these lines:

<IfModule !php5_module>
    RewriteCond %{REQUEST_URI} \.html$
    RewriteRule (.*) http://127.0.0.1:2480/$1 [P]
</IfModule>

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_URI} \.html$
RewriteRule (.*).html $1.php

Sending Mail from a PHP Script

To send mail from a PHP script, use the built-in mail() function to send an email. For example, this script sends a test message:

<?php
$to = 'example@example.com';
$subject = 'Test Message';
$message = 'Hello, World!';
$headers = "From: example@example.com\r\n";
mail($to, $subject, $message, $headers);
?>

Alternatively, the script may connect to and send mail from an SMTP server. There are several packages available which simplify this method of sending mail:

For example, this PHP script uses the PEAR Mail package to send an email:

<?php
require_once "Mail.php";

$from_addr = "Me <my_email_address@somedomain.example>";
$to = "Team <team@somedomain.example>";
$subject =  "Hello!";
$body = "Dear Team, here is my message text.";

$headers = array ("From" => $from_addr,
                  "To" => $to,
                  "Subject" => $subject);
$smtp = Mail::factory("smtp", array ('host' => "smtp.webfaction.com",
                                     'auth' => true,
                                     'username' => "my_mailbox_name",
                                     'password' => "password1"));

$mail = $smtp->send($to, $headers, $body);
?>

For this script to work, the values for from_addr, my_mailbox_name, and password1 would be changed to an outgoing address, a valid WebFaction mailbox name, and a valid mailbox password, respectively.

Serving an Application from a Subdirectory

Some PHP frameworks call for serving a site from a subdirectory. See Serving a Static/CGI/PHP application from a Subdirectory to learn about using a Symbolic link application to serve a subdirectory.

Setting PHP’s Default Time Zone

To set the default time zone for a PHP applications’ date and time functions, modify the application’s PHP settings such that date.timezone is your preferred time zone. For example, to set the default to the United States Eastern time zone, add date.timezone = America/New_York to your php.ini. For valid time zones, see the official PHP documentation’s List of Supported Timezones.

Troubleshooting

Error: 500 Internal Server Error

See also

For additional troubleshooting recommendations, please see the general CGI 500 Internal Server Error documentation.

Error: Premature end of script headers: php54.cgi

A 500 Internal Server Error in the browser and an error like this in the $HOME/logs/frontend/error_website_php.log file:

[Thu Mar 22 18:38:49 2012] [error] [client 123.456.78.9 ] Premature end of script headers: php54.cgi

may be a failed attempt to use the apache_request_headers function.

There are two common solutions to this problem:

  1. Disable the apache_request_headers function. Many software packages gracefully work around the disabled function. To disable the function, modify the application’s php.ini file to contain:

    disable_functions = "apache_request_headers"
    

    See Configuring PHP for detailed instructions about creating and modifying php.ini.

  2. For servers web120 and greater or dweb61 and greater, switch to the FastCGI PHP deployment method. See Using FastCGI for detailed instructions on how to enable FastCGI.

Strange Characters in Output

Strange hexadecimal characters may appear prepended to expected output with software which forces the HTTP/1.1 header.

To resolve this issue, add these directives to the application’s .htaccess file to force the correct headers:

SetEnv force-response-1.0 1
SetEnv downgrade-1.0 1

Alternatively, you may modify the software to use the correct headers. For example, this problem can be solved for Drupal by modifying the drupal_set_header function in includes/common.inc. Add this line to the end of the function definition:

$header = str_replace('HTTP/1.1', $_SERVER["SERVER_PROTOCOL"], $header);

The line replaces the HTTP/1.1 header with the correct header based on PHP’s server and execution environment information.