Previous: Starting Web Applications Manually, Up: Working With Web Applications


5.1.8 Working With MicroServer Applications

In this section we will see how to turn a PHP website into a compiled web application that includes an embedded web server, allowing you to distribute the web application as a stand alone program.

Coding for the MicroServer

The MicroServer defines two new PHP symbols:

The MicroServer runs on port 8000 by default. This value can be changed at compile time, using the --port command line options. It can also be changed at runtime, using the -p option.

TIP: You should offer a way for your client to end the MicroServer application by calling re_mhttpd_stop when they are ready to quit. For example:

     if ($_GET['quit'] == 1)
         re_mhttpd_stop();
     
     echo '<a href="'.$_SERVER['PHP_SELF'].'?quit=1">Click Here To Exit</a>';

If the user does not quit the application, the MicroServer will continue to reside in memory.

Index Pages

If your project contains a file named “index.php” in any of the directories of your source tree, then that file will be served if the client requests the directory in which is resides.

For example, if your source tree contains:

     /index.php
     /home.php
     /foo/index.php
     /foo/about.php

and the client requests http://localhost:8000/ or http://localhost:8000/foo/ then the MicroServer will automatically serve /index.php or /foo/index.php respectively.

Automatic Startup Page

If you need to run code when the application starts (for example, to launch a web browser automatically pointing to the MicroServer location) you can do this by including in your project a specially named PHP file: mhttpd_startup.inc

If this file exists it will be executed once when the application starts.

Here is an example mhttpd_startup.inc file that automatically launches a web browser on Windows:

     <?
     
     // This text runs on start and shows up in the command window
     echo "Sample MicroServer App Started at: http://localhost:".RE_MHTTPD_PORT."/\n";
     
     // launch a browser using the windows ShellExecute function
     win_shellexecute("open", 'http://localhost:'.RE_MHTTPD_PORT.'/', '', '', SW_RESTORE);
     
     ?>

Compiling Overview

To compile your website into a web application, call the compiler pcc with the --microserver switch, the name of the application, and a list of all the PHP source files. You can also specify the default port the MicroServer should use.

     pcc --microserver myapp --port 8080 index.php include/foo.inc include/mhttpd_startup.inc

Note: All files on the commandline will be compiled, but only files with a .php extension will be served as web pages. This prevents web clients from accessing or running code that is only intended to be accessed internally with include and not served directly.

Roadsend PHP will create a binary object file (.o) for each source file in the web application. If you change a source file and wish to rebuild, Roadsend PHP will only recompile those files that have changed. You can force a full rebuild with the --force-rebuild option.

The two important files necessary for deployment are the executable file (myapp on Unix, myapp.exe on Windows) and the library file (libmyapp_u.so on Unix, libmyapp_u.dll on Windows).

Serving Static Files

Static files (such as images, static HTML, javascript, etc.) are not compiled into MicroServer applications. They must exist in the web root directory that the MicroServer application is run from.

The embedded MicroServer will serve the static files that exist in its root directory. This allows you your web application to serve the normal array of static items that comprise a full web application.

When you deploy your application, you should include the static files as part of your package.

MicroServer Binary Commandline Arguments

The binary file created during a MicroServer build will automatically accept a few command line arguments:

        -h,--help This help message
        -d LEVEL  Debug level
        -l LOG    Log all requests to the specfied file
        -p PORT   Server port number

You may use these options at runtime to change how the MicroServer operates.

Deploying

When you are ready to deploy your MicroServer application, you should include the following files in your package:

The layout of your distribution may look like this:

     /
       myapp.exe
       libmyapp_u.dll
       static/
         info.html
         about.html
       images/
         logo.gif
         icon1.gif
       styles/
         theme.css

If you have dynamically linked your MicroServer application (the default), then you may also have to include the runtime libraries in your package. You can use the Linux command “ldd myapp” to get a list of dependent libraries. On Window, you can use the Deploy functionality of the IDE to identify and include dependent libraries.

If you have compiled the MicroServer application with the --static option, you do not need the supporting libraries.