The play/play.php file is the center of the Play Library. Its base classes exist to create and support Plugin objects.
The Play class is the root class for most library classes. It defines a set of static variables and methods listed below.
final static public function PlayPath($path=NULL)
The static PlayPath method always returns the path to the directory containing the play.php file, appending the $path argument if sepecified.
final static public function UserPath($path=NULL)
The static UserPath method exists as a way to replace Play Libarary plugins and templates without altering the contents of the play folder. All Play Library classes will attempt to use the UserPath when including plugin or template files.
If the static Play::$UserPath variable has been set, the static UserPath method appends the given $path to the $UserPath. If that file exists, this concatenation is returned. Otherwise, the $path argument is appended to the Play::$PlayPath and returned regardless of whether the result file exists.
If no $path argument is given, the $UserPath is returned if it's been set. If no $UserPath has been specified, $PlayPath is returned.
final static public function SafePath($path, $base=NULL)
The static SafePath method reduces the $path argument to it's leanest form, removing empty, single and double-dot elements and adjusting the path as appropriate. If $path is brought below it's own root level by reduction of double-dot elements, NULL is returned.
If $path is reduced to a valid path and the $base argument is not null, $base is prepended to $path before returning.
Warning: To discourage unwanted snooping and hacking, never use the $base argument that can be altered by users. The $base argument is intended to set the very lowest level a user-specified path can access.
final static public function Template($template)
Templates are PHP files that produce HTML content. They're generally associated with one plugin. Play Library templates are stored in the template folder, but can be replaced by specifying a Play::$UserPath directory and placing your own templates there within the same directory structure.
The static Template method includes the specified $template, looking first for the file in $UserPath/template, then in $PlayPath/template. Missing files are handled just as PHP would handle the inclusion of a file that does not exist.
Warning: To discourage unwanted snooping and hacking, always pass any $template path that can be altered by users through the SafePath method before processing.
final static public function Plugin($pluginName, $param=NULL)
The static Plugin method returns a plugin object specified by $pluginName. Any given plugin can be created only one time. If the plugin has already been created, that same plugin object will be returned.
The $param argument is available for convenience in simple circumstances, but should never be relied on in cases where a plugin might be created in more than one place. It is much safer to predefine plugin parameters by setting values in the static $PluginParams array.
// Set the default plugin params so that auth plugin always uses the
// demo datasource and the captcha plugin has only 5 characters but
// only lasts 99 seconds.
Play::$PluginParams = array (
'auth' => array('dsn'=>'demo'),
'captcha' => array('length'=>5, 'timeout'=>99)
);
Caution: If given, $param argument key/values are merged over the predefined $PluginParams keys for a given $pluginName. This allows you to override defaults set in Play::$PluginParams, but also presents the danger that some previous call for this plugin will have created it with an unexpected set of parameters.
final static public function Datasource($dsName)
The static Datasource method is intended to return an object that provides access to database functionality. The Datasource class defines a minimal set of abstract methods that should allow any dbms to be represented. The "datasource" plugin (defined in play.php as the plugin_datasource class) includes a "create" method that handles creation of Datasource objects given an associative array of named values required to instantiate a connection.
Note: This method will not work automatically! If you need library functionality that requires a database, you must replace the static Play::$OnDatasource callback function to return a Datasource plugin object when requested by name.
Play::$OnDatasource = function($dsn) {
switch ($dsn) {
case 'demo':
return Play::Plugin('datasource')->create(array(
'dbms'=>'mysql',
'user'=>'myUsername', 'pass'=>'myPass',
'host'=>'localhost', 'db'=>'myDemoDB'
));
break;
}
};
final static public function SlowHash($value, $salt)
Hashes the $value with the given $salt by calling the Play::$OnSlowHash callback function.
Warning: To discourage unwanted snooping and hacking, always replace the default Play::$OnSlowHash method with your own routine!.
Play::$OnSlowHash = function($value, $salt)
{
// Pick your own number $i of iterations. Avoid quick hashing - a slow
// routine may help to discourage hackers. Once it's in production use,
// don't change it.
for ($i=0; $i < 117; $i++)
{
// ...and pick your own hash algos and a different configuration.
// Be creative here!
$value = hash('sha256', hash('sha256', hash('ripemd', "$value$salt")));
}
return $value;
};
Note that the static Play::RandomString method is a good candidate for generating salt.
final static public function RemoteID()
The static RemoteID method, if successful, returns a string that should include or consist of the best guess at the remote ip address of the connecting client. The server variable HTTP_X_REMOTE_ADDR is attempted first. If that's not present, REMOTE_ADDR is attempted. If neither of these is present, it returns SSH_CONNECTION in hopes that a CLI script is using the play library.
If none of the above succeeds for your application, set the static Play::$OnRemoteID variable with a function that returns a string identifying the remote client as uniquely as possible.
Play::$OnRemoteID = function() {
// This should be something that identifies the remote client.
return my_remote_id_function();
};
static public function RandomString()
The static RandomString method generates and returns a randomly generated string in base64 notation. Library functionality currently uses this method to generate hashing salt and session id values.
static public function Error ($args=NULL)
The static Error method records errors when arguments are passed to it. It accepts either one argument, an Exception object, or four arguments, the integer error code, string error message, string filepath, and integer line where the error occurred.
When called with no arguments, it displays all previously recorded errors and clears the error list.
This method requires the presence of the error plugin, which is included in the plugin/error directory. This plugin is automatically created and used as necessary.
static public function Init()
The static Init method is called automatically when play.php is loaded. It prepares the variables needed by the library. Calling it again will have no effect.
public function Call($callback)
The Call method is a convenient way to call the given $callback function. When calling $callback, it replaces the first argument with $this and sends any additional arguments just as they were received.
Call() is the only non-static Play class method. It's intended to be used by subclasses such as plugins but could be very useful to the end-developer, too.
Plugins are discrete packages of PHP code generally meant to perform a small, focused set of tasks - hopefully, related to their name. Play Library plugins are typically stored in the plugin folder, each inside a subfolder matching its plugin name, in a file matching its plugin name with the extension ".php". Every plugin is defined as a class named "plugin_" plus the plugin name.
The bulk of Play Library functionality is provided by Plugin objects. Plugin documentation will be provided individually by plugin.
Currently, there is only one method defined by the Plugin class - the respond method.
public function respond ()
The respond method is an open invitation to the plugin to respond in any way it sees fit. This is primarily intended for handling ajax calls and form submissions.
Database access is provided through the use of two classes: Datasource and Query. Datasource represents a connection to a database and Query represents the results of one SQL query.
Query objects are returned by passing an SQL statement to a Datasource object's query function.
In general, a datasource should be created by passing a datasource name to the static Play::Datasource method. If the named datasource does not already exist, it's created and stored so that it can be reused if called for again.
For the Play::Datasource method to work, the static variable Play::$OnDatasource must be set to a callback function that returns a Datasource based on the $dsn argument. To actually instantiate a new Datasource object, pass an array of connection parameters to the datasource plugin's "create" method.
An example implementation of the Play::$OnDatasource callback can be found above under the Play::Datasource() section.
The plugin_datasource class is defined in play.php, but there is still a datasource folder within the plugin folder where new implementations of the Datasource class can be stored. The database plugin looks for a "dbms" key in the create method's array argument and loads the file with a matching name from the plugin/datasources folder.
Currently, mysql.php is included there, and can be used to create MySQL database connections. The following section indicates how each of the abstract Datasource and Query class methods must respond when called, so it should be relatively easy to create your own Datasource (and Query) subclasses if necessary.
Extend the Datasource class to provide access to a DBMS.
public function isConnected()
The isConnected method must return true or false to indicate whether the datasource is properly connected as described in the connection parameters with which it was created.
public function exec($sql);
The exec method must execute the string argument $sql, an SQL query. This method should be used for operations that do not select result data.
public function query($sql='');
The query method must execute the string argument $sql, an SQL query and return a Query object that holds the results. This method Exec should be used for operations that do select result data.
public function errorMessage();
The errorMessage method must return the most recent error message as a string.
public function escapeValue($value);
The escapeValue method must escape the string $value argument as appropriate to this DBMS.
public function startTransaction();
The startTransaction method must initiate a transaction.
public function commit();
The commit method must commit a transaction.
public function rollback();
The rollback method must rollback a transaction.
Extend the Query class to provide access to result data selected by calling the Datasource class query method.
public function exec($sql)
The exec method must execute the $sql argument.
public function fetchRow()
The fetchRow method must return the current row as a numeric array.
public function fetchAssoc()
The fetchAssoc method must return the current row as an associative array.
public function seek($iOffset)
The seek method must move the cursor to the numbered row given by the $iOffset argument, starting at zero.
public function numRows()
The numRows method must return the number of rows represented in this query's results.
public function numFields()
The numFields method must return the number of result fields in this query.
public function fieldName($inFieldNum)
The fieldName method must return the nth field name as given by the $inFieldNum argument, starting at 0 for the first field.