From NAS-Tweaks

PHP is a server-side scripting language that is widely used for developing dynamic web sites. PHP allows custom software to run on the server (in our case the NAS) hosting the web site.

PHP scripts are typically embedded in HTML pages. When a browser requests such a HTML page, the scripts are executed by the PHP add-in module of the HTTP server (here: lighttpd). Usually the PHP code inserts some additional HTML content into the version of the HTML page that gets sent to the browser. The browser ("client") itself thus doesn't see the scripts which were executed on the server.

In this tutorial we assume that the lighttpd HTTP server is already installed on the NAS (see tutorial on installing lighttpd). On bigger systems, PHP is sometimes used in combination with an Apache server (instead of the leaner lighttpd) and an SQL database. This widely-used bundle of software tools is sometimes known as LAMP: Linux, Apache, MySQL, PHP. The installation of MySQL on the NAS is covered in another tutorial.

Contents 1 PHP uses 2 Setting up PHP 2.1 Installation 2.2 Configuring PHP 2.3 Configuring Lighttpd 2.4 Activation 3 Testing PHP 4 Using PHP 5 Optional: Using shared extensions 5.1 Available modules 5.2 Editing php.ini 5.3 Demo of calendar extension 6 Notes 6.1 PHP and HTML 6.2 Short open tag 6.3 File extensions and default file names 6.4 Stateless 6.5 Learning the PHP language 6.6 Dealing with PHP errors

PHP uses

With regular HTML pages, your web server can only provide static content: all users see the same set of pages and the pages don't change until someone (e.g. manually) updates the stored HTML pages. A server-side scripting language like PHP helps if you need to add dynamic content, such as a visitor counter (see example code below) or maybe news-of-the-day. Public domain as well as proprietary PHP software is available for various applications including:

• public domain
  • personal photo galleries (e.g. Gallery (Gallery 2 also requires mySQL) or Dalbum)
  • WikiPedia runs PHP-based software called MediaWiki. This site runs WikiMedia.
  • blog and forum applications like WordPress
• proprietary
  • larger online shops (see URL of this example)
  • online reference sites (Urban Dictionary)

Setting up PHP

Installation

Fonz, the creator of fun_plug, kindly provided a packaged version of php for the NAS in his repository.

PHP is not installed as part of fun_plug by default, but you should already have downloaded a copy as part of the general tutorial on how to download, install and upgrade packages. Let's make sure you still have the latest version (as Fonz upgrades his repository regularly). Note that the rsync command could take a while because it can download multiple packages depending on what is already in your /ffp/pkg/packages directory. Also note that you have to install curl additionally since php-5.2.9-1.

cd /ffp/pkg
rsync -av --delete inreto.de::dns323/fun-plug/0.5/extra-packages/All/ extra-packages
ls -al extra-packages/php*
funpkg -i /ffp/pkg/extra-packages/php-*.tgz
ls -al extra-packages/curl*
funpkg -i /ffp/pkg/extra-packages/curl-*.tgz

If you have a version of php installed that is outdated, you will need to run in upgrade mode instead (see here for help). Still make sure, you have curl installed!

funpkg -u /ffp/pkg/extra-packages/php-*.tgz

Configuring PHP

PHP is configured with a file called php.ini. You thus need to copy one of the example-files from /ffp/etc/examples/ to /ffp/etc/ while renaming it to php.ini:

cd /ffp/etc
cp examples/php.ini-recommended php.ini

Configuring Lighttpd

To use PHP with the lighttpd-webserver, you have to use another configuration file as explained in the section on config files in the tutorial.

cd /ffp/etc
cp examples/lighttpd.conf-with-php lighttpd.conf

You may have to edit this lighttpd.conf file if you peviously changed the lighttpd port number as explained here. If you don't do this, Lighttpd will run on the default port of 8080. There is not much wrong with running on such a port number, but the default port where browsers expect to find an HTTP server is 80.

Activation

Restart lighttpd to load the new configuration - including the PHP module. This can be done by rebooting the entire NAS or using

cd /ffp/start
sh lighttpd.sh restart

Testing PHP

You can test your installation of PHP by placing a file called index.php in the server.document-root directory (e.g. /mnt/HD_a2/www/pages) with the following content:

<H1>This is normal HTML</H1>
But the <U>following table</U> is generated by PHP:
<?php
phpinfo();
?>

Now go to the website on your NAS using the configured address and port: e.g. http://CH3SNAS:80. You should see a long page with configuration information for the PHP server as shown in the picture or here). This output is generated by the function call "phpinfo()".

Using PHP

Let us now go back to a somewhat less intimidating and possibly even boring example: the standard "Hello World" in PHP. Copy and paste the following text to a file named helloworld.php and store it in the server.document-root directory:

<?php
echo "Hello World";
?>

Then go to the website on your NAS using the configured address and port and add /helloworld.php (the address may look like this: http://CH3SNAS/helloworld.php).

The following example shows a more complete web page (adapted from the lighttpd tutorial). It adds 3 features:

• visitors are greeted using their IP address (using the $_SERVER['REMOTE_ADDR'])
• any viewing of the web page triggers updates to a file (counter.txt) stored on the NAS
• the web site uses counter.txt to show how often the page has been viewed

This requires three fragments of PHP code, each enclosed between <?php and ?> tokens:

<?php
$fname = "counter.txt";             // The file where the number of hits gets stored
if(!file_exists($fname)) {          // If file doesn't exist..
    $countfile=fopen($fname,"a");   // .. create it
    $counter=0;                     // .. and initialize hit counter to zero
}
else {
    $countfile=fopen($fname,"r+");  // Open for read and write
    $counter=fgets($countfile,100); // Load number of hits by reading first 100 bytes
    rewind($countfile);             // Reset the file pointer to overwrite old counter value
}
$counter++;                         // Increment counter by one
fputs($countfile,$counter);         // Write the new value to the file
fclose($countfile);                 // Close the File
?>

<html>
    <head>
        <title>Hello PHP World!</title>
        <style type="text/css">
        <!--
                        h1 {text-align:center; font-family:Arial, Helvetica, Sans-Serif;}
                        h2 {text-align:center;}
                        p  {text-indent:20px;}
        -->
        </style>
    </head>
    
    <body bgcolor = "#ffffcc" text = "#0000ff">
        <h1>Welcome, <?php echo $_SERVER['REMOTE_ADDR']; ?>, <BR>to the PHP world</h1>
        <h2>This page was viewed <?php echo $counter; ?> times</h2>
        <p><A HREF="page1.html">Link to page1</A></p>
        <p><A HREF="page2.html">Link to page2</A></p>
        <p><A HREF="http://nas-tweaks.net/CH3SNAS:Tutorials/lighttpd">external link</A></p>
    </body>
</html>

The first and by far the longest PHP section looks to see if a file name counter.txt exists in the server.document-root directory. If it doesn't exist, it creates it and decides there have been zero hits so far ($counter=0). Note that variables in PHP do not need to be declared and start with a $ and that no clear distinctions are made between numeric and string variables: conversions are done on demand.

If the file already exists, the first 100 bytes (should be enough for a decent number) are copied into $counter. Then $counter is incremented, written to the counter.txt file and the file is closed.

The remaining HTML code is similar to the code in the lighttpd tutorial. In the level one header (H1), a string is generated by a PHP echo command which prints the IP address of the remote client. In the level two header the value of $counter that was previously computed is used.

Optional: Using shared extensions

PHP allows the use of additional modules, so called "shared extensions". E.g. there is calendar for calendar-related functions. The modules are stored in /ffp/lib/php/extensions/no-debug-non-zts-20060613/.

Available modules

You can list the available modules using:

ls -al /ffp/lib/php/extensions/no-debug-non-zts-20060613/*.so

As of version php-5.2.6-3 the following modules are available:

Module	Description	Requires installation of ffp package
calendar	functions related to days/months/years and Unix timestamps	-
ctype	character type checking	-
ftp	File Transfer Protocol	-
gd	image processing	libjpeg, libpng
mbstring	manipulation of non-ASCII strings (e.g. unicode)	-
mysql	MySQL database access	mysql
pdo	PHP data objects	-
pdo_mysql	PDO interface to the MySQL database	mysql
pdo_sqlite	PDO interface to the SQLlite database	-
sqlite	SQLlite database access	-
tokenizer	access to PHP tokens found by the lexical analyzer	-
zlib	.gz file compression	-

Editing php.ini

If you want to add one or more modules, you need to edit the file /ffp/etc/php.ini. Open php.ini and find:

;;;;;;;;;;;;;;;;;;;;;;
; Dynamic Extensions ;
;;;;;;;;;;;;;;;;;;;;;;

And add below the extension you want. E.g. to enable the calendar extension, you add:

; Linux extensions
extension=calendar.so
;extension=ctype.so
;extension=ftp.so
;extension=gd.so
;extension=mbstring.so
;extension=mysql.so
;extension=pdo.so
;extension=pdo_mysql.so
;extension=pdo_sqlite.so
;extension=sqlite.so
;extension=tokenizer.so
;extension=zlib.so

Afterwards you have to restart lighttpd to load the changes.

Demo of calendar extension

To see whether or not calendar was indeed loaded, you could run the PHPinfo.php script shown above. Or run a script calendar.php containing:

<?php
for ($year=2000;$year<2011;$year++) {
    $days = cal_days_in_month(CAL_GREGORIAN,2,$year);
    echo "February in $year has $days days <BR>";
}
?>

Notes

PHP and HTML

A page with PHP code is generally stored on disk as HTML code with one or more fragments of embedded PHP. When the HTTP sends delivers the actual page to the browser ("client") the PHP sections have been interpreted and removed. In general they have been replaced by additional HTML code (see the counter example above). The receiving client thus does not see the PHP code and cannot even directly know whether PHP has been used to generate the served page.

Short open tag

If you want to use "<?" instead of "<?php" to mark the start of PHP code fragments, you need to change change the value of "short_open_tag" (line 131) in /ffp/etc/php.ini file to On:

short_open_tag = On

This is a matter of taste and convenience. When you distribute PHP code for use in other servers, you need to keep in mind that they may be set to short_open_tag = Off.

File extensions and default file names

HTML pages containing PHP code should have a .php extension. This tells the lighttpd server to pass the code via the PHP preprocessor before sending it across the network.

When you access the lighttpd server without providing a specific file name, it successively checks for files in the server.document-root directory(typically /mnt/HD_a2/www/pages/) named

• index.php
• index.html
• index.htm
• default.htm

This is defined in a parameter called index-file.names in the lighttpd.conf file. As the list suggests, if you have both an index.php file and an index.html file in the same directory, the index.php file has precedence. If you explicitly ask for index.html, however, you will get that file instead of index.php.

Stateless

Note that after a page has been processed, when a new request for the same page is made by the same or another client, all computation starts from scratch: PHP is "stateless" in the sense that variables such as $counter are all lost after the page request has been completed. So the only way to track state in a PHP server is to store information in a file (as in counter.txt above), to store information in a database (another tutorial), or to assume the client maintains any relevant information between one page request and the next one.

Learning the PHP language

There are numerous books (printed and online) on PHP. See for example php.net.

Dealing with PHP errors

PHP syntax errors messages are appended to the Lighttpd error.log file. So if you are experimenting with- or developing PHP code, it can help to keep an eye on that file.