ptg 322 Chapter 13 PHP in WebSphere sMash Figure 13.10 Results of a simple_xml request There are few topics that should to be discussed on this sample. First, the get_connection() call requires the zero:zero.php.connection dependency. So, it needs to be added to the project, or else you will receive an error about a missing function. This depend- ency will likely not show up in your repository by default, so access the manage repository sec- tion, search for this module, and select the latest version. After it’s been downloaded and added to your project, you’ll be ready to pull in XML document from anywhere. Technically, you also need to enable the zero.php.ConnectionExtension, but it’s enabled by default in all PHP application. For reference sake, this is defined in the /config/php.ini file in your project. Go ahead and make sure it’s there, and also explore some of the other setting defined in this file: extension = zero.php.ConnectionExtension There are a few final items to take note of in this simple application. The first line enables error reporting to Standard Out, which when called by URL is the browser itself. Although this makes it easy to debug a misbehaving application, it is probably not appropriate for production applications. Get in the habit of wrapping complex logic in try/catch blocks and returning a friendly error message to your users. There are also a couple other commented debugging lines that can be useful for error resolution. The var_dump() function does exactly as you would expect and dumps the contents of a variable to Standard Out. The rest of this script should be self-explanatory. Experiment with pulling other XML documents and how to process and manipulate their content using PHP’s SimpleXML. Download from www.wowebook.com ptg WebSphere sMash PHP Extensions 323 WebSphere sMash PHP Extensions WebSphere sMash provides many extensions to assist in the development of PHP-based applica- tions. These extensions are enabled by defining them in the /config/php.ini file for the appli- cation. Each of the extensions shown next can be enabled by adding a line similar to that shown here in the php.ini file: extension = zero.php.ExtensionName If these extensions don’t quite meet your needs, there is a process to create your own exten- sions for others to use. PHP Extensions were covered previously in this chapter. The remainder of this chapter details the PHP extensions provided by WebSphere sMash. Becoming acquainted with these APIs can greatly improve your ability to write PHP applications that access relational databases, interact with remote resources, and provide application protec- tion support and other helpful features. The following API groups are presented: • WebSphere sMash utilities—Provides access to the global context (GC) and the vir- tual files system • URI utilities—Provides access to build application-specific URIs • Java extensions—Provides access to Java resources from PHP • Groovy extensions—Provides access to Groovy resources from PHP • Remote connections—Provides utilities to enable easy access to remote resources • JSON utilities—Provides methods for processing JSON data • Active content filtering—Provides protection from malicious incoming data • Cross-Site Request Forgery (CSRF)—Provides programmatic protection from CSRF attacks • Login—Provides ability to log into WebSphere sMash applications programmatically • Database access—Provides a series of database-related functions broken down by: General, Query, Results, and Transactions • XML utilities—Provides methods to process XML data WebSphere sMash Utilities Extension name: zero.php.ZeroExtension The following functions provide support for accessing WebSphere sMash-specific con- cepts. These are used to access the global context, process included views, and access the virtual file system defined by WebSphere sMash (see Table 13.5). Download from www.wowebook.com ptg 324 Chapter 13 PHP in WebSphere sMash Table 13.5 WebSphere sMash Utility Functions Function Description DOCROOT Returns the document root directory path of the Zero Application that is execut- ing the calling script. fire_event Fires an event registered in the configuration file of the application. Arguments: String eventName—Name of the event to fire. Array args—Argument list to be passed into the event handler. getVFile Gets the absolute path of a file within the application’s virtual directory stack. This is the flattened directory structure; the top-most file wins in conflicts, except for special files such as zero.config, which are logically merged together. Arguments: String vFile—Logical relative file based on the application’s root location. Returns: String—Absolute path to the virtual file location. Returns NULL if vFile does not exist. listFiles List all the files under a virtual directory. The first file of a given name is added to the list, while any subsequent files with the same name are skipped. Arguments: String vDirectory—Logical relative directory based on the applications root loca- tion. Returns: Array of strings containing the vFile paths of all files in the merged logical vDirectory. Returns NULL if directory does not exist. render_view Helper function to render a view of data in the global context. Views are located relative to the /app/views vDirectory. zcontains Checks for the existence of a key within the given global context (GC). Arguments: String key—Key to check for existence. Returns: boolean—True if key exists; false otherwise. Download from www.wowebook.com ptg WebSphere sMash PHP Extensions 325 Table 13.5 WebSphere sMash Utility Functions Function Description zdelete Deletes keys (and associated values) from the global context (GC). Arguments: String key—Global context key to be deleted. boolean deleteChildren—[Optional] If true, key is treated as a prefix or context qualifier, and any matching children keys will be deleted. False means exact match on key name. Returns: boolean—True if key(s) successfully deleted; false otherwise. zdump Dump the entire contents of the global context. Arguments: String key—The global context name to dump. Returns: String—Contents of global context being dumped. zget Returns a value form the global context based on the provided key. The key must contain the fully qualified “/zone/ ” prefix. Example: “/request/headers/in/Con- tent-Type” or “/user/myKey”. To manually add new values to the global context, see zput(). Arguments: String key—Key to locate value upon. Must include full zone prefix. Object defaultValue—Value to return if key is not found in the requested zone. Returns: The value matching that key in the appropriate GC zone, the supplied default value if provided in the arguments, or NULL if not found. zlist zlist_all List all the global context paths at the specified key prefix. Arguments: String key—Key to search upon. May be full of partial, but must include the full zone prefix. boolean includePrefix—True causes results to be returned with the enclosing zone prefix; false strips the zone prefix from the results. Default is false. Returns: Array—List of matching key strings. Download from www.wowebook.com ptg 326 Chapter 13 PHP in WebSphere sMash Table 13.6 URI Utility Functions Function Description get_absolute_uri Returns a fully qualified URI based on a relative path. The results will include the protocol, host, port, context root, URI path, and formatted parameters. If the path argument contains a leading slash, the returned URI is based from the application’s root; otherwise, it is based relative to the calling script. Arguments: String path—URI path to convert to proper URI. Map params—[Optional] Any query parameters to include in URL (for example, “?key1=val1&key2=val2”). Returns: Proper URI based on defined path. URI Utilities Extension name: zero.php.URIUtilsExtension This extension provides functions that allow the developer to create WebSphere sMash- appropriate URIs. These URIs take into account any defined context root and virtual directory paths. The paths provided are validated, and any parameters are automatically encoded. It is always best to use relative URIs when accessing local resources such as images, style sheets, and scripts. This prevents issues when dealing with reverse proxies and deployment time changes, such as port number or context root changes (see Table 13.6). Table 13.5 WebSphere sMash Utility Functions Function Description zpost zput Provides for storing key/value pairs into the global context. The difference between the functions is that zput will replace an existing value located by the key, and zpost will append to an existing value, coercing it into an array if needed. Arguments: String key—Fully qualified key to use. Object value—The value to append to existing value at the specified key location. boolean binary—If true, do not automatically encode the value being stored. Default of false performs encoding. Download from www.wowebook.com ptg WebSphere sMash PHP Extensions 327 Java Extensions Extension Name: com.ibm.p8.engine.xapi.reflection.impl.JavaExtensionLibrary This subsystem provides direct access to Java resources from PHP files (see Table 13.7). See the “PHP to Java Bridge” section of this chapter for more information on using Java from within PHP files. Table 13.6 URI Utility Functions Function Description get_relative_uri Returns a relative URI based on path. This is the preferred function to use if accessing resources within the same application. If the path argument contains a leading slash, the returned URI is based from the application’s root; otherwise, it is based relative to the calling script. Arguments: String path—URI path to convert to application-specific URI. Map params—[Optional] Any query parameters to include in URL. Returns: Proper URI based on defined path. get_requested_uri Returns a proper URI based on the presumed URL used on the originating request. Reverse proxies and other external factors may alter the actual URL used to access the resource. Arguments: boolean includeQuery—True if the returned URI should include the query string portion of the URI (for example, “?key1=val1&key2=val2”). Returns: Full URI, with or without the additional query string appended. Download from www.wowebook.com ptg 328 Chapter 13 PHP in WebSphere sMash Table 13.8 Groovy Functions for PHP Function Description groovy_create_ closure Provides the ability to create a Groovy closure around an object/function. Arguments: Callback callback—PHP style callback (array containing an object and method/function name). Returns: Groovy closure object to pass to callback. Groovy Extensions Extension name: com.ibm.p8.engine.xapi.groovy.GroovyExtensionLibrary The following functions provide facilities to access Groovy classes from within PHP (see Table 13.8). See the extended discussion later in this chapter on the PHP to Groovy bridge for more details. Table 13.7 Java Bridge Functions Function Description java_import Provides a means to directly import Java classes into the PHP runtime. When imported, the class is available for instantiation and/or direct access to static members and functions. Arguments: String classname—The package and classname to be imported. Array interfaces—[Optional] List of interfaces to be defined that this class implements. Default is NULL. boolean includeBase—[Optional] PHP class to declare the same base class as the Java class being imported. Default is true. String importedName—[Optional] Name to be used in PHP to reference this class. Default is NULL, which is to use the classname without package names. Used to prevent potential naming conflicts in import. Boolean includeNestedClasses—[Optional] Include inner classes as part of import. Default is true. Returns: boolean—Did import succeed. Download from www.wowebook.com ptg WebSphere sMash PHP Extensions 329 Remote Connections Extension name: zero.php.ConnectionExtension This extension assists in making connections to remote resources (see Table 13.9). Table 13.8 Groovy Functions for PHP Function Description groovy_eval Executes a simple Groovy code block on-the-fly. Arguments: String script—Groovy script string to be evaluated by Groovy runtime. Returns: Return value from script evaluation. Defaults return is a numeric value (0=success, non-0=fail). groovy_import Imports a Groovy class to be visible by the PHP runtime. Once imported, the Groovy class is treated as a PHP class with all members and functions available. The Groovy class is located by searching the include path of the PHP runtime (located in the php.ini). Arguments: String scriptname—The package and script name containing the Groovy class(es) to be imported. Array interfaces—[Optional] List of interfaces to be defined that this class implements. Default is NULL. boolean includeBase—[Optional] PHP class to declare same base class as the Groovy class being imported. Default is true. String importedName—[Optional] Name to be used in PHP to reference this class. Default is NULL, which is to use the classname without package names. Used to prevent potential naming conflicts in import. Returns: boolean—Did import succeed. Download from www.wowebook.com ptg 330 Chapter 13 PHP in WebSphere sMash Table 13.10 JSON Utility Functions Function Description json_decode Decodes a JSON-encoded string. Arguments: String json—String containing serialized JSON structure. JSON Utilities Extension name: zero.php.JSONExtension This extension provides facilities for working with JSON data. Methods are provided for reading and writing JSON. JSON is often used when working with RESTful resources (see Table 13.10). Table 13.9 Connection API Functions Function Description connection_get Provides the ability to perform a GET request on a remote resource. Custom headers may be sent as well. Arguments: String URL—Full URL of remote resource. Map headers—[Optional] Map of key/value headers to send with request. Returns: Map response, with the following keys: status—Response status code value (for example, 200). body—Main response data. connection_post Provides ability to perform POST request on a remote resource. Arguments: String URL—Full URL of remote resource. Map headers—[Optional] Map of key/value headers to send with request. String body—Contents to be POSTed to remote resource. Returns: Map response, with the following keys: status—Response status code value (for example, 200). body—Main response data. Download from www.wowebook.com ptg WebSphere sMash PHP Extensions 331 Table 13.11 ACF Functions Function Description acf_process Processes a string for ACF content, returning the cleansed string. acf_process_stream Processes an input stream for ACF content, removing any active content. acf_validate Processes a string for ACF content, returning any active content located. acf_validate_stream Processes an input stream for ACF content, returning any active con- tent located. Active Content Filtering Extension name: zero.php.ACFExtension This extension provides protection from malicious incoming data. Active Content Filtering (ACF) provides methods to scan and cleanse data for <script> tags and other potentially harm- ful string structures (see Table 13.11). Each of these functions take the following arguments: String | Stream input—Source string to be processed. String contentType—[Optional] Type of content (for example, text/html). String encoding—[Optional, default=“UTF-8”] Encoding of input data. String filterRuleFile—[Optional] File containing rules for this ACF process. Cross-Site Request Forgery Extension name: zero.php.CSRFExtension This extension provides programmatic protection from Cross-Site Request Forgery (CSRF); see Table 13.12. Consult the Project Zero website for more information on CSRF procedures. Table 13.10 JSON Utility Functions Function Description json_encode Encodes a complex structure (maps, arrays, strings, ints, and so on) into a serialized JSON string. Arguments: Object val—Object to be encoded. Download from www.wowebook.com . how to process and manipulate their content using PHP’s SimpleXML. Download from www.wowebook.com ptg WebSphere sMash PHP Extensions 323 WebSphere sMash PHP Extensions WebSphere sMash provides. write PHP applications that access relational databases, interact with remote resources, and provide application protec- tion support and other helpful features. The following API groups are presented: •. to process XML data WebSphere sMash Utilities Extension name: zero.php.ZeroExtension The following functions provide support for accessing WebSphere sMash- specific con- cepts. These are used to