Generally, a package does not require application package scripts. The scripts and their associated files can be written by application package developers to manage the application package and its instances. Script-writing language is not regulated by the Specification except for that it must be declared in the metadata file.
Typically, Controllers input the data to scripts in a form of environment variables. The variables bring all information about resources and settings of application instance(s). For details on what variables can be used by the scripts, refer to the 4.6.2. Environment Variables section of the Specification. For better understanding of what environment variables are passed to a particular application package configuration script, refer to the example provided in the Appendix B.
The package can include the configuration script and maintenance scripts. Configuration script is invoked by Controller to configure application instances on installation, removal or upgrade. It is also called to reconfigure an application instance. Maintenance scripts are invoked by Controller to accomplish application package management tasks (license keys upgrade, databases backup, etc.).
Configuration script should configure application instances in the following situations: Installation on a web site, reconfiguration, upgrade, or removal from a web site. It must be named configure.
The script is always invoked by Controller with one or more arguments that specify what task is performed by the script. For details on the script invocation and its arguments, refer to the 4.6.1. Configuration script actions section of the Specification.
For more information on configuration script, refer to the 4.6. Configuration script section of the Specification.
The following example presents a template of the configure script (written in PHP). The sample also shows how to operate with database environment variables passed to the script. When invoked with the install argument, the script connects to the database specified by environment variables and executes SQL queries stored in the schema.sql file.
<?php
if(count($_SERVER['argv']) < 2)
Previous page
Next page
Locate page
{
print "Usage: configure (install | upgrade <version> | configure | remove)\n";
exit(1);
}
$command = $_SERVER['argv'][1];
//$command stores the argument with which the script was invoked.
if($command == "install")
{
$db_id = 'main';
//The database identifier value is to be substituted by the value
//defined in the application requirements section of the
//metadata file.For details, see the 6.3.1.1. Database requirement
//type section of the Specification.
$query_file = 'schema.sql'; //File containing list of SQL queries.
//List of database-related variables that are passed to the configuration
//script. See the 6.3.1.1.1. Environment variables section of the
//Specification for details.
$db_address = getenv("DB_${db_id}_HOST");
if (fetch_env_var("DB_${db_id}_PORT") !== False)
$db_address .= ':' . fetch_env_var("DB_${db_id}_PORT");
$dblogin = getenv("DB_${db_id}_LOGIN");
$dbpassword = getenv("DB_${db_id}_PASSWORD");
$dbname = getenv("DB_${db_id}_NAME");
//PHP functions for connecting to the mysql server and
//executing SQL queries.
mysql_connect($dbaddress, $dblogin, $dbpassword);
mysql_select_db($dbname);
$sql_queries = file($query_file);
foreach ($sql_queries as $query) mysql_query($query);
//Other code to be executed on invoking configure with
//the install argument.
exit(0);
}
if($command == "remove")
{
//Code to be executed on invoking configure with the remove argument
exit(0);
}
if($command == "upgrade")
{
//Code to be executed on invoking configure with the upgrade argument
exit(0);
}
if($command == "configure")
{
//Code to be executed on invoking configure with the configure argument
exit(0);
}
print "Error: unknown command $command.\n";
exit(1);
?>
Sometimes it is useful to add scripts performing application package maintenance tasks. For example, the maintenance script can upgrade the license key for an application instance.
Note: Each maintenance script must be described by an aspect and declared in the APP-META.xml file.
For more info on maintenance scripts, refer to the 5.5. Additional scripts section of the Specification.