128 Chapter 5 Implementing with PHP: Standalone Scripts if($i++ == 10) { break; } } print “\n\n”; } ?> The script works by reading in a logfile on STDIN and matching each line against $regex to extract individual fields.The script then computes summary statistics, counting the number of requests per unique IP address and per unique Web server user agent. Because combined-format logfiles are large, you can output a . to stderr every 1,000 lines to reflect the parsing progress. If the output of the script is redirected to a file, the end report will appear in the file, but the .’s will only appear on the user’s screen. Parsing Command-Line Arguments When you are running a PHP script on the command line, you obviously can’t pass arguments via $_GET and $_POST variables (the CLI has no concept of these Web proto- cols). Instead, you pass in arguments on the command line. Command-line arguments can be read in raw from the $argv autoglobal. The following script: #!/usr/bin/env php <?php print_r($argv); ?> when run as this: > ./dump_argv.php foo bar barbara gives the following output: Array ( [0] => dump_argv.php [1] => foo [2] => bar [3] => barbara ) Notice that $argv[0] is the name of the running script. Taking configuration directly from $argv can be frustrating because it requires you to put your options in a specific order.A more robust option than parsing options by hand is to use PEAR’s Console_Getopt package. Console_Getopt provides an easy interface to use to break up command-line options into an easy-to-manage array. In addition to Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. 129 Parsing Command-Line Arguments simple parsing, Console_Getopt handles both long and short options and provides basic validation to ensure that the options passed are in the correct format. Console_Getopt works by being given format strings for the arguments you expect. Two forms of options can be passed: short options and long options. Short options are single-letter options with optional data.The format specifier for the short options is a string of allowed tokens. Option letters can be followed with a single : to indicate that the option requires a parameter or with a double :: to indicate that the parameter is optional. Long options are an array of full-word options (for example, help).The option strings can be followed by a single = to indicate that the option takes a parameter or by a double == if the parameter is optional. For example, for a script to accept the -h and help flags with no options, and for the file option with a mandatory parameter, you would use the following code: require_once “Console/Getopt.php”; $shortoptions = “h”; $longoptons = array( “file=”, “help”); $con = new Console_Getopt; $args = Console_Getopt::readPHPArgv(); $ret = $con->getopt($args, $shortoptions, $longoptions); The return value of getopt() is an array containing a two-dimensional array.The first inner array contains the short option arguments, and the second contains the long option arguments. Console_Getopt::readPHPARGV() is a cross-configuration way of bringing in $argv (for instance, if you have register_argc_argv set to off in your php.ini file). I find the normal output of getopt() to be a bit obtuse. I prefer to have my options presented as a single associative array of key/value pairs, with the option symbol as the key and the option value as the array value.The following block of code uses Console_Getopt to achieve this effect: function getOptions($default_opt, $shortoptions, $longoptions) { require_once “Console/Getopt.php”; $con = new Console_Getopt; $args = Console_Getopt::readPHPArgv(); $ret = $con->getopt($args, $shortoptions, $longoptions); $opts = array(); foreach($ret[0] as $arr) { $rhs = ($arr[1] !== null)?$arr[1]:true; if(array_key_exists($arr[0], $opts)) { if(is_array($opts[$arr[0]])) { $opts[$arr[0]][] = $rhs; } Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. 130 Chapter 5 Implementing with PHP: Standalone Scripts else { $opts[$arr[0]] = array($opts[$arr[0]], $rhs); } } else { $opts[$arr[0]] = $rhs; } } if(is_array($default_opt)) { foreach ($default_opt as $k => $v) { if(!array_key_exists($k, $opts)) { $opts[$k] = $v; } } } return $opts; } If an argument flag is passed multiple times, the value for that flag will be an array of all the values set, and if a flag is passed without an argument, it is assigned the Boolean value true. Note that this function also accepts a default parameter list that will be used if no other options match. Using this function, you can recast the help example as follows: $shortoptions = “h”; $longoptions = array(“file=”, “help”); $ret = getOptions(null, $shortoptions, $longoptions); If this is run with the parameters -h file=error.log, $ret will have the following structure: Array ( [h] => 1 [ file] => error.log ) Creating and Managing Child Processes PHP has no native support for threads, which makes it difficult for developers coming from thread-oriented languages such as Java to write programs that must accomplish multiple tasks simultaneously. All is not lost, though: PHP supports traditional Unix mul- titasking by allowing a process to spawn child processes via pcntl_fork() (a wrapper around the Unix system call fork()).To enable this function (and all the pcntl_* func- tions), you must build PHP with the enable-pcntl flag. Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. 131 Creating and Managing Child Processes When you call pcntl_fork() in a script, a new process is created, and it continues executing the script from the point of the pcntl_fork() call.The original process also continues execution from that point forward.This means that you then have two copies of the script running—the parent (the original process) and the child (the newly created process). pcntl_fork() actually returns twice—once in the parent and once in the child. In the parent, the return value is the process ID (PID) of the newly created child, and in the child, the return value is 0.This is how you distinguish the parent from the child. The following simple script creates a child process: #!/usr/bin/env php <?php if($pid = pcntl_fork()) { $my_pid = getmypid(); print “My pid is $my_pid. pcntl_fork() return $pid, this is the parent\n”; } else { $my_pid = getmypid(); print “My pid is $my_pid. pcntl_fork() returned 0, this is the child\n”; } ?> Running this script outputs the following: > ./4.php My pid is 4286. pcntl_fork() return 4287, this is the parent My pid is 4287. pcntl_fork() returned 0, this is the child Note that the return value of pcntl_fork() does indeed match the PID of the child process. Also, if you run this script multiple times, you will see that sometimes the parent prints first and other times the child prints first. Because they are separate processes, they are both scheduled on the processor in the order in which the operating system sees fit, not based on the parent–child relationship. Closing Shared Resources When you fork a process in the Unix environment, the parent and child processes both have access to any file resources that are open at the time fork() was called. As conven- ient as this might sound for sharing resources between processes, in general it is not what you want. Because there are no flow-control mechanisms preventing simultaneous access to these resources, resulting I/O will often be interleaved. For file I/O, this will usually result in lines being jumbled together. For complex socket I/O such as with database connections, it will often simply crash the process completely. Because this corruption happens only when the resources are accessed, simply being strict about when and where they are accessed is sufficient to protect yourself; however, Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. 132 Chapter 5 Implementing with PHP: Standalone Scripts it is much safer and cleaner to simply close any resources you will not be using immedi- ately after a fork. Sharing Variables Remember: Forked processes are not threads.The processes created with pcntl_fork() are individual processes, and changes to variables in one process after the fork are not reflected in the others. If you need to have variables shared between processes, you can either use the shared memory extensions to hold variables or use the “tie” trick from Chapter 2,“Object-Oriented Programming Through Design Patterns.” Cleaning Up After Children In the Unix environment, a defunct process is one that has exited but whose status has not been collected by its parent process (this is also called reaping the child process). A responsible parent process always reaps its children. PHP provides two ways of handing child exits: n pcntl_wait($status, $options)—pcntl_wait() instructs the calling process to suspend execution until any of its children terminates.The PID of the exiting child process is returned, and $status is set to the return status of the function. n pcntl_waitpid($pid, $status, $options)—pcntl_waitpid() is similar to pcntl_wait(), but it only waits on a particular process specified by $pid. $status contains the same information as it does for pcntl_wait(). For both functions, $options is an optional bit field that can consist of the following two parameters: n WNOHANG—Do not wait if the process information is not immediately available. n WUNTRACED—Return information about children that stopped due to a SIGTTIN, SIGTTOU, SIGSTP,orSIGSTOP signal. (These signals are normally not caught by waitpid().) Here is a sample process that starts up a set number of child processes and waits for them to exit: #!/usr/bin/env php <?php define(‘PROCESS_COUNT’, ‘5’); $children = array(); for($i = 0; $i < PROCESS_COUNT; $i++) { if(($pid = pcntl_fork()) == 0) { exit(child_main()); } else { Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. 133 Creating and Managing Child Processes $children[] = $pid; } } foreach($children as $pid) { $pid = pcntl_wait($status); if(pcntl_wifexited($status)) { $code = pcntl_wexitstatus($status); print “pid $pid returned exit code: $code\n”; } else { print “$pid was unnaturally terminated\n”; } } function child_main() { $my_pid = getmypid(); print “Starting child pid: $my_pid\n”; sleep(10); return 1; ?> One aspect of this example worth noting is that the code to be run by the child process is all located in the function child_main(). In this example it only executes sleep(10), but you could change that to more complex logic. Also, when a child process terminates and the call to pcntl_wait() returns, you can test the status with pcntl_wifexited() to see whether the child terminated because it called exit() or because it died an unnatural death. If the termination was due to the script exiting, you can extract the actual code passed to exit() by calling pcntl_wexitstatus($status). Exit status codes are signed 8-bit numbers, so valid val- ues are between –127 and 127. Here is the output of the script if it runs uninterrupted: > ./5.php Starting child pid 4451 Starting child pid 4452 Starting child pid 4453 Starting child pid 4454 Starting child pid 4455 pid 4453 returned exit code: 1 pid 4452 returned exit code: 1 pid 4451 returned exit code: 1 pid 4454 returned exit code: 1 pid 4455 returned exit code: 1 Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. 134 Chapter 5 Implementing with PHP: Standalone Scripts If instead of letting the script terminate normally, you manually kill one of the children, you get output like this: > ./5.php Starting child pid 4459 Starting child pid 4460 Starting child pid 4461 Starting child pid 4462 Starting child pid 4463 4462 was unnaturally terminated pid 4463 returned exit code: 1 pid 4461 returned exit code: 1 pid 4460 returned exit code: 1 pid 4459 returned exit code: 1 Signals Signals send simple instructions to processes.When you use the shell command kill to terminate a process on your system, you are in fact simply sending an interrupt signal ( SIGINT). Most signals have a default behavior (for example, the default behavior for SIGINT is to terminate the process), but except for a few exceptions, these signals can be caught and handled in custom ways inside a process. Some of the most common signals are listed next (the complete list is in the signal(3) man page): Signal Name Description Default Behavior SIGCHLD Child termination Ignore SIGINT Interrupt request Terminate process SIGKILL Kill program Terminate process SIGHUP Terminal hangup Terminate process SIGUSR1 User defined Terminate process SIGUSR2 User defined Terminate process SIGALRM Alarm timeout Terminate process To register your own signal handler, you simply define a function like this: function sig_usr1($signal) { print “SIGUSR1 Caught.\n”; } and then register it with this: declare(ticks=1); pcntl_signal(SIGUSR1, “sig_usr1”); Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. 135 Creating and Managing Child Processes Because signals occur at the process level and not inside the PHP virtual machine itself, the engine needs to be instructed to check for signals and run the pcntl callbacks.To allow this to happen, you need to set the execution directive ticks. ticks instructs the engine to run certain callbacks every N statements in the executor.The signal callback is essentially a no-op, so setting declare(ticks=1) instructs the engine to look for signals on every statement executed. The following sections describe the two most useful signal handlers for multiprocess scripts—SIGCHLD and SIGALRM—as well as other common signals. SIGCHLD SIGCHLD is a common signal handler that you set in applications where you fork a num- ber of children. In the examples in the preceding section, the parent has to loop on pcntl_wait() or pcntl_waitpid() to ensure that all children are collected on. Signals provide a way for the child process termination event to notify the parent process that children need to be collected.That way, the parent process can execute its own logic instead of just spinning while waiting to collect children. To implement this sort of setup, you first need to define a callback to handle SIGCHLD events. Here is a simple example that removes the PID from the global $children array and prints some debugging information on what it is doing: function sig_child($signal) { global $children; pcntl_signal(SIGCHLD, “sig_child”); fputs(STDERR, “Caught SIGCHLD\n”); while(($pid = pcntl_wait($status, WNOHANG)) > 0) { $children = array_diff($children, array($pid)); fputs(STDERR, “Collected pid $pid\n”); } } The SIGCHLD signal does not give any information on which child process has terminat- ed, so you need to call pcntl_wait() internally to find the terminated processes. In fact, because multiple processes may terminate while the signal handler is being called, you must loop on pcntl_wait() until no terminated processes are remaining, to guarantee that they are all collected. Because the option WNOHANG is used, this call will not block in the parent process. Most modern signal facilities restore a signal handler after it is called, but for portabil- ity to older systems, you should always reinstate the signal handler manually inside the call. When you add a SIGCHLD handler to the earlier example, it looks like this: #!/usr/bin/env php <?php Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. 136 Chapter 5 Implementing with PHP: Standalone Scripts declare(ticks=1); pcntl_signal(SIGCHLD, “sig_child”); define(‘PROCESS_COUNT’, ‘5’); $children = array(); for($i = 0; $i < PROCESS_COUNT; $i++) { if(($pid = pcntl_fork()) == 0) { exit(child_main()); } else { $children[] = $pid; } } while($children) { sleep(10); // or perform parent logic } pcntl_alarm(0); function child_main() { sleep(rand(0, 10)); // or perform child logic return 1; } function sig_child($signal) { global $children; pcntl_signal(SIGCHLD, “sig_child”); fputs(STDERR, “Caught SIGCHLD\n”); while(($pid = pcntl_wait($status, WNOHANG)) > 0) { $children = array_diff($children, array($pid)); if(!pcntl_wifexited($status)) { fputs(STDERR, “Collected killed pid $pid\n”); } else { fputs(STDERR, “Collected exited pid $pid\n”); } } } ?> Running this yields the following output: > ./8.php Caught SIGCHLD Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. 137 Creating and Managing Child Processes Collected exited pid 5000 Caught SIGCHLD Collected exited pid 5003 Caught SIGCHLD Collected exited pid 5001 Caught SIGCHLD Collected exited pid 5002 Caught SIGCHLD Collected exited pid 5004 SIGALRM Another useful signal is SIGALRM, the alarm signal. Alarms allow you to bail out of tasks if they are taking too long to complete.To use an alarm, you define a signal handler, regis- ter it, and then call pcntl_alarm() to set the timeout.When the specified timeout is reached, a SIGALRM signal is sent to the process. Here is a signal handler that loops through all the PIDs remaining in $children and sends them a SIGINT signal (the same as the Unix shell command kill): function sig_alarm($signal) { global $children; fputs(STDERR, “Caught SIGALRM\n”); foreach ($children as $pid) { posix_kill($pid, SIGINT); } } Note the use of posix_kill(). posix_kill() signals the specified process with the given signal. You also need to register the sig_alarm() SIGALRM handler (alongside the SIGCHLD handler) and change the main block as follows: declare(ticks=1); pcntl_signal(SIGCHLD, “sig_child”); pcntl_signal(SIGALRM, “sig_alarm”); define(‘PROCESS_COUNT’, ‘5’); $children = array(); pcntl_alarm(5); for($i = 0; $i < PROCESS_COUNT; $i++) { if(($pid = pcntl_fork()) == 0) { exit(child_main()); } else { Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. [...]... TestHarness to autoload all the test cases in EmailAddress.phpt and Text/Word.phpt: < ?php require_once “TestHarness .php ; require_once “PHPUnit/TextUI/TestRunner .php ; $suite = new TestHarness(); $suite->register(“EmailAddress.phpt”); $suite->register(“Text/Word.phpt”); PHPUnit_TextUI_TestRunner::run($suite); ?> This makes it easy to automatically run all the PHPUnit_Framework_TestCase objects for a project... to add the class to the suite Here’s how you do it: < ?php require_once require_once require_once require_once “EmailAddress.phpt”; “Text/Word.phpt”; “PHPUnit/Framework/TestSuite .php ; “PHPUnit/TextUI/TestRunner .php ; $suite = new PHPUnit_Framework_TestSuite(); $suite->addTestSuite(‘EmailAddressTestCase’); $suite->addTestSuite(‘Text/WordTestCase’); PHPUnit_TextUI_TestRunner::run($suite); ?> Alternatively,... interactive terminal-based applications with PHP and the ncurses extension in Volume 1, Issue 12 php| architect is available online at http://www.phparch.com Although there is not space to cover it here, PHP- GTK is an interesting project aimed at writing GUI desktop applications in PHP, using the GTK graphics toolkit Information on PHP- GTK is available at http://gtk .php. net A good open-source resource monitoring... chapter, we will use PEAR’s PHPUnit PHPUnit, like most of the free unit testing frameworks, is based closely on JUnit, Erich Gamma and Kent Beck’s excellent unit testing suite for Java Installing PHPUnit is just a matter of running the following (which most likely needs root access): # pear install phpunit Alternatively, you can download PHPUnit from http://pear .php. net/PHPUnit Writing Your First Unit... chapter:You can wrap a PHPUnit_Framework_TestSuite creation and run a check to see whether the test code is being executed directly.That way, you can easily run the particular tests in that file (by executing directly) or include them in a larger testing harness EmailAddress.phpt looks like this: < ?php require_once “EmailAddress.inc”; require_once ‘PHPUnit/Framework/TestSuite .php ; require_once ‘PHPUnit/TextUI/TestRunner .php ;... instantiate a PHPUnit_Framework_ TestSuite object and the test case to it: require_omce “PHPUnit/Framework/TestSuite”; $suite = new PHPUnit_Framework_TestSuite(); $suite->addTest(new EmailAddressTest(‘testLocalPart’)); After you have done this, you run the test: require_once “PHPUnit/TextUI/TestRunner”; PHPUnit_TextUI_TestRunner::run($suite); You get the following results, which you can print: PHPUnit 1.0.0-dev... your test code directly into the code base To the bottom of EmailAddress.inc you can add this block: if(realpath($_SERVER[ PHP_ SELF’]) == _ _FILE_ _) { require_once “PHPUnit/Framework/TestSuite .php ; require_once “PHPUnit/TextUI/TestRunner .php ; class EmailAddressTestCase extends PHPUnit_Framework_TestCase{ public function _ _construct($name) { parent::_ _construct($name); } public function testLocalPart()... $this->assertTrue($email->domain == ‘omniti.com’); } } if(realpath($_SERVER [PHP_ SELF]) == _ _FILE_ _) { $suite = new PHPUnit_Framework_TestSuite(‘EmailAddressTestCase’); PHPUnit_TextUI_TestRunner::run($suite); } ?> In addition to being able to include tests as part of a larger harness, you can execute EmailAddress.phpt directly, to run just its own tests: PHPUnit 1.0.0-dev by Sebastian Bergmann Time: 0.0028760433197... $this->assertEquals($email->domain, ‘omniti.com’); } } $suite = new PHPUnit_Framework_TestSuite(‘EmailAddressTestCase’); PHPUnit_TextUI_TestRunner::run($suite); } What is happening here? The top of this block checks to see whether you are executing this file directly or as an include $_SERVER[ PHP_ SELF’] is an automatic variable that gives the name of the script being executed realpath($_SERVER [PHP_ SELF]) returns the canonical absolute... one that is relative to the current directory, such as foo .php or /scripts/foo .php In both of these examples, you need to know the current directory to be able to find the files An absolute path is one that is relative to the root directory For example, /home/george/scripts/ foo .php is an absolute path, as is /home/george//src/ /scripts/./foo .php (Both, in fact, point to the same file.) Writing Inline . script: #!/usr/bin/env php < ?php print_r($argv); ?> when run as this: > ./dump_argv .php foo bar barbara gives the following output: Array ( [0] => dump_argv .php [1]. this: #!/usr/bin/env php < ?php Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. 136 Chapter 5 Implementing with PHP: Standalone