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.
The MicroServer defines two new PHP symbols:
RE_MHTTPD_PORT
- a constant defining the current port that the MicroServer is running on
re_mhttpd_stop()
- a function that, when called, stops execution of the MicroServer and exits the application
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.
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.
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); ?>
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).
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.
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.
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.