Plug in PHP 100 POWER SOLUTIONS- P55 doc

New_ 236 P l u g - i n P H P : 1 0 0 P o w e r S o l u t i o n s 236 P l u g - i n P H P : 1 0 0 P o w e r S o l u t i o n s O ne of the most interesting recent developments on the Web is the trend of providing Application Programming Interfaces (APIs) to web sites, with which you can integrate content from other sites into your own. Generally such APIs accept standard POST or GET requests as might be sent from an HTML form or hyperlink, and then return data in the form of XML (Extensible Markup Language), JSON (JavaScript Object Notation), or other easy-to-process formats. For example, both Google and Yahoo! provide a range of APIs for many of their web properties, such as Google Book Search and Charts or Yahoo! Search, Answers, and Stocks. There are plug-ins for all of these in this chapter. There are also plug-ins for handling Wikipedia entries, Flickr photo streams, and currency conversion from the European Central Bank. However, although these plug-ins provide the functionality to process the information supplied by those companies, it’s your responsibility to ensure you follow each service’s rules and guidelines and have sufficient permission to reuse or republish data extracted from their sites. Create Google Chart Google Charts is a great API that not too many people seem to know about yet. With it you can create a huge variety of charts to display on your web site, incorporate in your documents, and so on. However, it is quite complex and requires using a number of different command strings, which is where this plug-in comes in. Using the plug-in, you only have to supply the data to be charted and (optionally) various widths, heights, colors, and other details. The plug-in then interfaces with Google Charts and returns a ready-made image (as a GD object) containing the chart. You can then display the image straightaway or save it to disk for future use. Figure 10-1 shows a 3D pie chart created from seven items of data, representing types of cheese. FIGURE 10-1 Leverage the power of the Google Charts API with this plug-in. 7 1 C h a p t e r 1 0 : A P I s , R S S , a n d X M L 237 C h a p t e r 1 0 : A P I s , R S S , a n d X M L 237 About the Plug-in This plug-in returns a GD image containing a chart created using the supplied data. Upon failure, it returns FALSE. It requires the following arguments, all of which (except for $width, $height, and $data) may be passed as NULL or the empty string to use default values: • $title The chart’s title • $tcolor The title’s color • $tsize The title’s font size • $type The chart type to create out of: line A line chart vbar A vertical bar chart hbar A horizontal bar chart gometer A Google-O-Meter chart pie A pie chart (the default) pie3d A 3D pie chart venn A venn chart radar A radar chart • $bwidth Bar width (only applies for bar charts) • $labels The data labels, separated by | symbols • $legends The data legends, separated by | symbols • $colors The data colors, separated by commas • $bgfill The background fill color (six hex digits) • $border The border width in pixels • $bcolor The border color (six hex digits) • $width The chart width in pixels • $height The chart height in pixels • $data The chart data, separated by commas Variables, Arrays, and Functions $types Associative array containing the chart type names and Google Chart command equivalents $tail String containing the command tail to add to the Google Charts URL $url String containing the Google charts URL $image GD image containing the returned Google chart $w The width of $image in pixels $h The height of $image in pixels $image2 GD image containing the final image to return after adding any border $clr GD color object created from the $bcolor border color 238 P l u g - i n P H P : 1 0 0 P o w e r S o l u t i o n s 238 P l u g - i n P H P : 1 0 0 P o w e r S o l u t i o n s How It Works This plug-in starts by populating the $types associative array so that the chart types passed in the argument $type can be quickly converted to the types Google Charts requires. For example, a 3D pie chart is represented by a $type of pie3d, which must be translated to p3 for Google. To facilitate this, the array element $types['pie3d'] has been given the value p3 so that simply looking up the value of $types[$type] will return p3 when $type is pie3d. All the other types will also be similarly translated. So next the value of $types[$type] is tested with the isset() function to see whether it has a value. If not, then an unknown value was passed in $type, and $type is then set to pie, the default value. Next, $tail is built up using the various parameters passed to the plug-in such as the title, type, width, height, and so on. The contents of $tail will be appended to the base API URL for Google Charts to make a query string, which is sent as a GET request to the server. After the main values have been placed in $tail, if they were passed in the function call, the next five if statements add further values. For example, in the fourth of these statements, if $colors is NULL or the empty string, then no color information will be appended to $tail. Otherwise, the Google Charts command &chco= will be appended to $tail, followed by the colors supplied. Next, the tail is appended to the Google Charts API URL and the result is placed in $url, which is then passed to the imagecreatefrompng() function to call up the API which (on success) returns a chart as a PNG image. This image is then placed in the GD image object $image. Now that an image has been created, the width and height of it are placed in the variables $w and $h so that a new image can be created by passing these values to imagecreatetruecolor(). If $border has a value, it will define the width of a border to be added to the image, and the new image is made slightly larger than the original to allow for the borders. The new image is then stored in $image2, and a GD color object is created in $clr from the color in $bcolor. This color is then passed to the imagefilledrectangle() function to fill in the new image with the specified color. Finally, the original image is copied to the exact center of the new image so that, if the new image is larger, the image will now be a bordered version of the original. If no border width was specified, then the copy will simply overwrite the fill color and the new image will be identical to the original. Now that it is no-longer required, the original image object is removed from memory using the imagedestroy() function, returning the memory back to the system, and the new image is then returned by the plug-in. TIP The Google Charts API actually includes many more features than there is room to include in this plug-in. If you visit http://code.google.com/apis/chart/, you will see more options you may wish to add to the plug-in for your own use. You should be able to slot them in without too much difficulty. C h a p t e r 1 0 : A P I s , R S S , a n d X M L 239 C h a p t e r 1 0 : A P I s , R S S , a n d X M L 239 How to Use It To obtain a Google Chart using this plug-in, you should prepare all the parameters you want in it and then pass them to the plug-in, like this: $title = 'My Favorite Types of Cheese'; $tcolor = 'FF0000'; $tsize = '20'; $type = 'pie3d'; $width = '570'; $height = '230'; $bwidth = NULL; $labels = 'Stilton|Brie|Swiss|Cheddar|Edam|Colby|Gorgonzola'; $legends = $labels; $colors = 'BD0000,DE6B00,284B89,008951,9D9D9D,A5AB4B,8C70A4,FFD200'; $bgfill = 'EEEEFF'; $border = '2'; $bcolor = '444444'; $data = '14.9,18.7,7.1,47.3,6.0,3.1,2.1'; $result = PIPHP_CreateGoogleChart($title, $tcolor, $tsize, $type, $bwidth, $labels, $legends, $colors, $bgfill, $border, $bcolor, $width, $height, $data); The preceding lines of code will re-create the chart shown in Figure 10-1, which is returned in $result as a GD image object, and which you can then output to a browser by first sending the correct PNG image header, followed by the image data, like this: header('Content-type: image/png'); imagepng($result); According to the Google Charts Usage Policy at http://code.google.com/apis/chart/: “There’s no limit to the number of calls per day you can make to the Google Chart API. However , we reserve the right to block any use that we regard as abusive. If you think your service will make more than 250,000 API calls per day, please let us know.” Therefore, you may prefer to employ caching techniques by saving the chart to disk (if it hasn’t already been saved), and then serving it from there. You can save the image using one of these commands where path/filename.ext is the filename, including path and extension: imagepng($result, 'path/filename.png'); imagegif($result, 'path/filename.gif'); imagejpeg($result, 'path/filename.jpg'); Just choose the type of file you wish to save the image as, and select one of these three commands accordingly. On the other hand, if your usage will not be high enough to get your program blocked, you may wish to save on your own bandwidth and use Google’s by uncommenting the return $url; command, about two-thirds of the way into the plug-in. You will now only need code such as the following to display the chart directly from Google’s servers: echo "<img However, the border options will be ignored and you’ll therefore have to use CSS (Cascading Style Sheets) if you need borders. 240 P l u g - i n P H P : 1 0 0 P o w e r S o l u t i o n s 240 P l u g - i n P H P : 1 0 0 P o w e r S o l u t i o n s The Plug-in function PIPHP_CreateGoogleChart($title, $tcolor, $tsize, $type, $bwidth, $labels, $legends, $colors, $bgfill, $border, $bcolor, $width, $height, $data) { $types = array('line' => 'lc', 'vbar' => 'bvg', 'hbar' => 'bhg', 'gometer' => 'gom', 'pie' => 'p', 'pie3d' => 'p3', 'venn' => 'v', 'radar' => 'r'); if (!isset($types[$type])) $type = 'pie'; $tail = "chtt=" . urlencode($title); $tail .= "&cht=$types[$type]"; $tail .= "&chs=$width" . "x" . "$height"; $tail .= "&chbh=$bwidth"; $tail .= "&chxt=x,y"; $tail .= "&chd=t:$data"; if ($tcolor) if ($tsize) $tail .= "&chts=$tcolor,$tsize"; if ($labels) $tail .= "&chl=$labels"; if ($legends) $tail .= "&chdl=$legends"; if ($colors) $tail .= "&chco=$colors"; if ($bgfill) $tail .= "&chf=bg,s,$bgfill"; $url = "http://chart.apis.google.com/chart?$tail"; // Uncomment the line below to return a URL to // the chart image instead of the image itself // return $url; $image = imagecreatefrompng($url); $w = imagesx($image); $h = imagesy($image); $image2 = imagecreatetruecolor($w + $border * 2, $h + $border * 2); $clr = imagecolorallocate($image, hexdec(substr($bcolor, 0, 2)), hexdec(substr($bcolor, 2, 2)), hexdec(substr($bcolor, 4, 2))); imagefilledrectangle($image2, 0, 0, $w + $border * 2, $h + $border * 2, $clr); imagecopy($image2, $image, $border, $border, 0, 0, $w, $h); imagedestroy($image); return $image2; } . site, incorporate in your documents, and so on. However, it is quite complex and requires using a number of different command strings, which is where this plug- in comes in. Using the plug- in, . d X M L 237 About the Plug- in This plug- in returns a GD image containing a chart created using the supplied data. Upon failure, it returns FALSE. It requires the following arguments, all of. Functions $types Associative array containing the chart type names and Google Chart command equivalents $tail String containing the command tail to add to the Google Charts URL $url String containing the Google charts