📄 index.xtp
字号:
<document> <header> <title>Quercus: Background PHP tasks using BAM</title> <description> <p>This tutorial will introduce using Broker Agent Messaging (BAM) to run background tasks written in PHP.</p> </description> <type>tutorial</type> <tutorial-startpage>frontend.php</tutorial-startpage> </header> <body> <summary/><s1 title="Files in this tutorial"><deftable><tr><td><viewfile-link file="WEB-INF/resin-web.xml"/> </td><td>web.xml configuration</td></tr><tr><td><viewfile-link file="frontend.php"/> </td><td>The frontend PHP interface</td></tr><tr><td><viewfile-link file="backend.php"/> </td><td>The background PHP task</td></tr></deftable></s1><s1 title="Introduction"><p>In the past, PHP developers who wanted to run tasks in the backgroundwere limited to cron jobs or using the <code>system()</code> function tolaunch the tasks manually.</p><p>This tutorial introduces PHP developers to using Broker Agent Messaging (BAM)to queue tasks to be handled by a background agent, also written in PHP. The application will initiate tasks to be handled in the background on a frontendscript. This script is a normal PHP web page. The tasks in this case areitems to add to an RSS feed. The background agent then takes the tasks andexecutes them to add the items to the RSS document. We are only using RSSmodification as an example. In general, this functionality might be used toexecute tasks that take a long time, but which you don't want to have theuser wait for while the page is reloading. Further examples include paymentprocessing, heavy computation, or any other slow process.</p></s1><s1 title="Implementing the application"><p>Let's go ahead and dive into the code of the application. The applicationconsists of two PHP scripts: a frontend page and a backend <em>agent</em>.We'll go over exactly what we mean by agent toward the end of the tutorial,but for now it suffices to know that it is code that will handle the tasksassigned by the frontend. Let's look at the frontend first, since that willbe most familiar to existing PHP developers.</p><s2 title="Frontend"><p>The frontend script will look very familiar to any PHP developer. It's anormal page that's executed when the user browses to it. The only differenceis that it uses some functions specific to BAM. The page consists mainly ofa form with a button and a frame containing the RSS feed. The button is asubmit button that simply calls back to the same page, POSTing a value of"add". When this value is present, the PHP code sends 5 messages to thebackground process using the <code>bam_send_message()</code> function.</p><example title="frontend.php"><html> <head> <title>Frontend</title> </head> <body> <?php if ($_POST["add"]) { bam_send_message("backend@localhost", "foo"); bam_send_message("backend@localhost", "bar"); bam_send_message("backend@localhost", "baz"); bam_send_message("backend@localhost", "bam"); bam_send_message("backend@localhost", "bop"); } ?> <form action="frontend.php" method="POST"> <input type="submit" name="add" value="Add 5 Tasks"/> </form> <iframe src="rss.xml" width="100%" height="100%"/> </body></html></example><p>There are two things to take notice of in the calls to <code>bam_send_message()</code>:</p><ul> <li>The target address: <b>backend@localhost</b>. This is the address of the backend process in the BAM system. We'll see how this is configured later. To learn more about BAM addressing in general, see the <a href="../../doc/hmtp.xtp">BAM documentation</a>.</li> <li>The messages: <b>foo</b>, <b>bar</b>, etc. Notice the order of the messages sent by the frontend script. These messages will be received by the backend script and processed in order.</li></ul></s2><s2 title="Backend"><p>The backend script will be new to most developers. It is written in PHP, buthas a slightly unusual execution pattern. Let's look at the script at the high level first.</p><example title="backend.php overview"><?phpfunction bam_message($to, $from, $value){ // process the message...}bam_dispatch();?></example><p>This backend script implements an event handler called an BAM "agent". Theseagents can listen for and send certain kinds of communications. For now, we'llfocus on messages. Messages are simple, unidirection communications that include a to address, a from address, and a value. </p><p>When a message is received by the agent, the script is executed from top tobottom. When the <code>bam_dispatch()</code> function is called, it dispatchesthe message to the event handler function, <code>bam_message()</code>. Itpasses the to and from addresses as well as the value of the message to thisfunction. Thus in this case, all of our task handling code goes into<code>bam_message()</code>.</p><p>Now let's take a look at the contents of the function:</p><example title="backend.php overview">function bam_message($to, $from, $value){ $doc = new DOMDocument(); $doc->Load("rss.xml"); $xpath = new DomXPath($doc); $items = $xpath->query("rss/channel/item"); if ($items->length == 0) { $task_number = 1; } else { // take the task number of the last task from its guid $guid = $xpath->query("rss/channel/item/guid"); $task_number = explode("#", $guid->item(0)->nodeValue)[1] + 1; } // Create the new item $new_item = $doc->createElement("item"); $new_item->appendChild($doc->createElement("title", "Task $task_number")); $new_item->appendChild($doc->createElement("link", "http://www.caucho.com/")); $new_item->appendChild($doc->createElement("description", "Task $task_number ($value)")); $new_item->appendChild($doc->createElement("pubDate", date("D, j M Y H:i:s e"))); $new_item->appendChild($doc->createElement("guid", "http://www.caucho.com/quercus-tasks#$task_number")); // Insert the new item $channel = $xpath->query("rss/channel"); $channel->item(0)->insertBefore($new_item, $items->item(0)); // trim off any items beyond 10 $num_items = $items->length; while ($num_items > 10) { $num_items--; $channel->item(0)->removeChild($items->item($num_items)); } $doc->save("rss.xml");}</example><p>This function just does some basic XML manipulations to add new items to theRSS feed. The main thing to notice is that we use the value of the messagesent to construct the description of the RSS item.</p></s2><s2 title="Configuring the backend agent">Finally to hook up the backend.php script at a BAM agent, we need to do asmall bit of configuration in the resin-web.xml:<example title="resin-web.xml"><web-app xmlns="http://caucho.com/ns/resin"> <bam-service name="backend@localhost" class="com.caucho.quercus.lib.bam.BamPhpAgent"> <init> <script>backend.php</script> </init> </bam-service></web-app></example></s2></s1><s1 title="See also"><ul><li><a href="../../doc/hmtp.xtp">BAM documentation</a></li></ul></s1></body></document>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -