PHPico Web Server - Manual back to main
Table of Contents: Installation of the Test Suite The server server(address, port, function [, options...] ) user_func(URI, connection) Global variables The server options init_func(TRUE) exit_func(FALSE, connections) time_func(time) server('check') server('get_open_connections') server('get_opts') server('get_requirements') server('log', type, [clientip,] message) server('shutdown') server('write', connection, header, data)
Installation of the Test Suite
How to install the Test Suite. Download the latest release. (DL@SF) Unpack the achieve. Modify the server-settings, if you want. (In run_me.php) Start run_me.php. (Linuxish: "php runme.php") The server is now running, check it out at http://127.0.0.1:8112/. (If started local, at the default port) As you can see it's really simple. The manual below gives you a litte deeper look into the server. And at least there are the sources.
The server
The function server is a multi use function. The default usage is to be a server, but with special parameters the function returns, for example, the server configuration. I've chosen this multi use function cause: There's only one function. No GLOBALS are used at all (only some will be set 'for you'). There is no chance to manipulate the server variables and options (not that I'm not trust you, it's just secure) Here is the more or less detailed listing on all server functions.
server(address, port, function [, options...] )
This is the server itself.
address	The ip address to listen on. 0.0.0.0 listens on all ip's bound to the computer. (e.g. 127.0.0.1 and 192.168.1.132)
port	The port to listen on. 80 is the default port for a web-server, since this port is usually already used, I've chosen 8112. But you can choose everything. (Note: ports below 1024 are usually reserved)
function	This is the name of the function to be called each time someone requests something. Below is a detailed listing on the parameters and the return values.
options	The other options are optional. All of the default server options (described below) can be overwritten here. There are two ways of submitting the options: server(address, port, function, array('option1' => parameter1, 'option2' => parameter2, ...)) server(address, port, function, 'option1', parameter1, 'option2', parameter2, ...)
return	The return is either FALSE if the server is already running or something went wrong during the initalisation. Or TRUE if the server had worked.
user_func(URI, connection)
This is the function you have to write and pass the name to the server(...) call. The function is called each time a request is passed to the server. You have just to echo out the contents of the page, like usually.
URI	This is the requested URI. This means everything behind http://server:port, for example: /manual.html. (see there is a slash at the beginning)
connection	This is the number of the connection to be served. In case you return 'keepconnection' you have to store this number for further use. See below.
return	Usually you have to return an array of headers. All headers you normally will pass to header(...) you have to return here. And there are some special parameters: the string 'shutdown' will shutdown the server, the string 'keepconnection' will don't answer the connection now and keeps it. You have to answer the question later with server('write', ...), everything already echoed will be lost. Or you may return NULL, which is identically to an empty array. (If the function do not return at all or just "return" it returns NULL. The first element of the array has a special meaning: it can carry the HTTP response. If not set HTTP/1.0 200 OK will be set for you. (Example: HTTP/1.0 404 File Not Found) There will be some headers added automatically, if not set: Content-Length: Since always the request must be returned at once, the length is known and will be set. Content-Type: The type will be only set to text/html, but only when the size is greater than zero. The server tries to determine whether the page is dynamic or not. If the header Last-Modified is not set then the content will be threaten as dynamic. This can be overwritten with 'cache' or 'donotcache' in the returning array. In case of a dynamic content all neccessary headers for not being cached will be set.
Global variables
Some global variables will be set for you, each time the user_func(...) get's called. magic_quotes_gpc don't exists for this server! Nothing will be quoted! Look at "show all variables" in the Test Suite. The array $_ENV will be emptied, except you prevent this by a server option. The global variables HTTP_POST_VARS, HTTP_GET_VARS, HTTP_ENV_VARS, HTTP_SERVER_VARS, HTTP_COOKIE_VARS, HTTP_POST_FILES, PHP_SELF, argv and argc will be always unset. Since register_globals should not be used anymore, that should not be a problem.)
$_GET	All GET requests, as usually. (But set by the server instead of PHP)
$_POST	All POST requests, as usually. (But set by the server instead of PHP)
$_COOKIE	All COOKIES, as usually. (But set by the server instead of PHP)
$_REQUEST	$_GET, $_POST and $_COOKIE in one variable (gpc order), as usually. (But set by the server instead of PHP)
$_FILES	The submitted files. Different from PHP! $_FILES is an array of arrays with the following fields:
	name	The name of the submitted file (if there is one)
	type	The mime-type of the submitted file (if there is one)
	size	The size of the submitted file
	data	The contents of the submitted file
$_SERVER	Something like $_SERVER on a Apache server. Here is the detailed listing:
	HTTP_*	For all headers sent in the request a variable will be set, with the prefix HTTP_, except for the following two
	CONTENT_LENGTH	This is the length of the POST data, if submitted
	CONTENT_TYPE	This is the mime-type of the POST data, if submitted
	REMOTE_ADDR	The IP address of the client
	REMOTE_PORT	The port used by the client
	SERVER_ADDR	The IP address of the server, this request is being served. (If you've submitted a IP as the address parameter to the server, this will be always the address, but if the server listens on all addresses this will be e.g. 127.0.0.1 or 192.168.1.132 depending on the used interface)
	SERVER_PORT	Always the port on which the server listens
	SERVER_NAME	The submitted option to server(...) or the SERVER_ADDR
	SERVER_ADMIN	The submitted option to server(...)
	SERVER_SIGNATURE	An apache like signature
	SERVER_SOFTWARE	The used software, which is PHPico, and the version of it, and of the used PHP
	SERVER_PROTOCOL	The HTTP version of the request
	REQUEST_METHOD	GET, POST or HEAD depending on the request method
	QUERY_STRING	Everything submitted by GET
	REQUEST_URI SCRIPT_NAME PHP_SELF	The requested page, also submitted to the user_func
	argv	An array of arguments submitted by GET
	argc	The number of submitted argument
The server options
These are the options you may pass to the server.
Option	Default	Description
listenqueue	20	How many queries should be stored. This is done by the operating system. See socket_listen for more information.
headsupport	TRUE	Should the server serve HEAD requests? Such a request is like a regular request (and also the user function will be called) but only the headers are returned.
keepenv	FALSE	Usually the variable $_ENV will be cleaned, this options suppress this.
time_interval	not set	Call a user function every X seconds. See time_func.
time_func	not set	This is the time function to be called. See time_func.
init_func	not set	This function is called just before the server starts - after initialization. See init_func.
exit_func	not set	This function is called when the server goes down. See exit_func.
max_post_kb	50	The maximum size of POST data to load (in kB)
read_blocksize	2048	The reading block size
write_blocksize	2048	The writing block size
server_name	not set	The name of the server (see SERVER_NAME)
server_admin	not set	The admin of the server (see SERVER_ADMIN)
errorlog	stderr	Where to write the error log file (Apache style)
accesslog	stdout	Where to write the access log file (Apache Common Log Format style)
read_select_timeout	2	Timeout for one select during read (in secs, how much time you have to submit one line/block of request)
read_total_timeout	5	Timeout for the whole reading of the request
write_select_timeout	1	Timeout for one select during write
write_total_timeout	2	Timeout for the whole writing
init_func(TRUE)
This is the function you have to write and pass the name in the options during the server startup. This function will be called after the successful initialization of the server just before the server starts serving requests. The first parameter is TRUE so you can write one function for init, exit and time. (one for all: don't forget to check $param === TRUE)
return	Will be ignored. Also everything you do echo will be ignored.
exit_func(FALSE, connections)
This is the function you have to write and pass the name in the options during the server startup. This function will be called just after the server had stopped serving requests. The first parameter is FALSE so you can write one function for init, exit and time. (one for all: don't forget to check $param === FALSE)
connections	This is an array with all open connections. The same as returned by server('get_open_connections').
return	Will be ignored. Also everything you do echo will be ignored.
time_func(time)
This is the function you have to write and pass the name in the options during the server startup. The function is called each few seconds. You have to specify the amount in the options. The first parameter is always a integer so you can write one function for init, exit and time. (one for all: don't forget to check is_integer($param) )
time	The UNIX timespamp of now (seconds, same as time()).
return	Will be ignored. Also everything you do echo will be ignored.
server('check')
Return the status of the server.
return	TRUE if the server is running, FALSE if the server is going down or NULL if the server is down.
server('get_open_connections')
Get all open connections.
return	An array with all open connections. You may return they with server('write', ...).
server('get_opts')
Get the server options.
return	An array with all options. See server options.
server('get_requirements')
Get the requirements to start this server.
return	Just a string.
server('log', type, [clientip,] message)
Write something to the error log file.
type	Something like 'error', 'warning' or 'notice' or whatever you want.
clientip	The IP of the client, will be added to log. Optional.
message	The message to log. Newlines will be translated to \n. (visible)
return	NULL
server('shutdown')
Shut down the server.
return	TRUE if the going down or FALSE if the server is down.
server('write', connection, header, data)
This is the server itself.
connection	The connection to return the request. Submitted to you by user_func(...) or server('get_open_connections') You can also write to the current connection using this function. This is maybe useful, if you want to know whether the data will be submitted. You can also use NULL to specify the actual connection. After doing this, everything the user_func echoes or returns will be ignored, except the return value 'shutdown'.
header	The same as the return of the user_func(...), except that the specials 'keepconnection' and 'shutdown' are not allowed.
data	The data to submit.
return	The number of written bytes, FALSE in case of an error or NULL is case of the connection is already closed.