Functions and Utilities

Logger

APS Logger prints messages in default PHP log. On Apache, it is /var/log/httpd/error_log.

To change log location, use the setLogFile method, as follows:

require_once("aps/2/runtime.php");

$logger = \APS\LoggerRegistry::get();
// setting new log file, path relative to your script current directory
$logger->setLogFile("logs/myapplication.log");
...
public function provision() {
....

APS Logger allows several kinds of log messages, and provides corresponding functions:

• fatal
• error
• info
• debug
• trace

The debug and trace log levels are enabled if APS_DEVELOPMENT_MODE is defined. Make sure the APS_DEVELOPMENT_MODE definition is removed, when you release the package into production.

Usage example:

if (!defined('APS_DEVELOPMENT_MODE')) define ('APS_DEVELOPMENT_MODE', 'on');

require_once("aps/2/runtime.php");
...

public function provision() {
   ....
   \APS\LoggerRegistry::get()->error("This is error log message");
   \APS\LoggerRegistry::get()->debug("APS Dev mode is on, so this message is printed in log");
...

Default logger can be replaced with a custom logger using function \APS\LoggerRegistry::set, as follows:

\APS\LoggerRegistry::set(new MyLogger());

Refer to custom logger example.

Warning

Starting from aps-php-runtime-2.0-331, function \APS\Logger::get() is deprecated. Use \APS\LoggerRegistry::get() instead.

Shared Apps helpers

The PHP Runtime library provides functions to cover the default needs of shared applications:

1. Database population.
2. Configuration files creation.

Databases are populated from schemas (database dumps). Configuration files are created from templates. Before writing the configurations and database, the PHP Runtime replaces placeholders in the configuration templates and schemas with their actual values.

Placeholders have the following format: @@{<name>}@@

Examples:

@@{db->name}@@ @@{locale}@@ @@{admin_name}@@ @@{admin_email}@@

The <name> part of a placeholder is a property of an application class (the class that extends the ResourceBase class).

Note the use of DocComment blocks in the module, for example:

/**
 * Class Wordpress
 * @type("http://www.odin.com/web/wordpress/1.0";)
 * @implements("http://aps-standard.org/types/core/application/1.0";)
 */
class Wordpress extends \APS\ResourceBase

The DocComments instruct the PHP Runtime about the meaning of the properties and their connections with the application schema properties and relations.

For example, the definition of a $db object:

/**
 * @link("http://aps-standard.org/types/infrastructure/database/mysql/1.0";)
 * @required
 * @requirement("version >= 5.0")
 */
public $db;

According to this definition, the PHP Runtime pulls database information from an APS Controller, and populates the $db object. WordPress uses the following Database placeholders in the config templates and database schemas:

@@{db->name}@@

@@{db->login}@@

@@{db->password}@@

@@{db->host}@@

@@{db->port}@@

@@{db->tablePrefix}@@

Website environment definition:

# Webspace information
/**
 * @link("http://aps-standard.org/types/infrastructure/environment/web/1.0";)
 * @requirement("engines =='php'")
 * @requirement("php.extensions =='mysql', php.safe_mode |= 'yes'")
 * @required
 */
public $website;

WordPress uses the @@{website->urls[0]}@@ placeholder in its DB schema file. It is the first url from the $website->urls[] array.

In addition, there are scalar properties (settings). The PHP Runtime populates them with the values passed by an APS Controller. Settings initially come from application installation wizard forms, filled by the customer.

Here are the WordPress settings:

# Settings
/**
 * @type(string)
 * @title("Administrator Name")
 * @description("Administrator Name")
 */
public $admin_name = "admin";

/**
 * @type(string)
 * @title("Administrator password")
 * @description("Administrator password")
 * @crypt
 */
public $admin_password;

/**
 * @type(string)
 * @title("Administrator email")
 * @format(email)
 */
public $admin_email;

/**
 * @type(string)
 * @title("Blog Name")
 */
public $title;

/**
 * @type(string)
 * @title("Interface language")
 * @option("en-US", "English")
 * @option("da-DK", "Danish")
 * @option("nl-NL", "Dutch")
 * @option("de-DE", "German")
 * @option("fr-FR", "French")
 * @option("it-IT", "Italian")
 * @option("ja-JP", "Japanese")
 * @option("ru-RU", "Russian")
 * @option("pl-PL", "Polish")
 * @option("es-ES", "Spanish")
 * @option("tr-TR", "Turkish")
 * @option("zh-CN", "Chinese Simplified")
 * @option("zh-TW", "Chinese Traditional")
 */
public $locale = "en-US";

Their placeholders in the WordPress schema and configuration files are as follows: @@{admin_name}@@, @@{admin_password}@@, etc.

In addition to the application properties defined in a schema, an application class can contain your own variables. They can also be used as placeholders, but you need to define them before calling the PHP Runtime utilities.

Here are some additional variables from WordPress:

// some security keys
public $auth_key;
public $secure_auth_key;
public $logged_in_key;
public $nonce_key;
public $auth_salt;
public $secure_auth_salt;
public $logged_in_salt;
public $nonce_salt;
public $admin_password_hash;

Have a look at the ‘init’ function where these variables are defined, and other initial actions done - the password encrypted, locale value adjusted according to WordPress needs:

function init() {
       $this->locale = preg_replace("/-/", "_", $this->locale); # WP locale has format en_EN
       $this->admin_password_hash = md5($this->admin_password); # WP password - encrypt md5
       # keys and salts for WP cookies
       $this->auth_key = \APS\generatePassword(64);
       $this->secure_auth_key = \APS\generatePassword(64);
       $this->logged_in_key = \APS\generatePassword(64);
       $this->nonce_key = \APS\generatePassword(64);
       $this->auth_salt = \APS\generatePassword(64);
       $this->secure_auth_salt = \APS\generatePassword(64);
       $this->logged_in_salt = \APS\generatePassword(64);
       $this->nonce_salt = \APS\generatePassword(64);
       $this->website->path;
}

This init function is called in the begining of each WordPress method, for example, in provision():

public function provision()
{
   $this->init();
   # Executing schema.sql script against $db. Placeholders in schema.sql are replaced with their values
   $dHelper = new \APS\DatabaseConfigurator($this, $this->db);
   $dHelper->importSchema('schema.sql');
   # Installing wp config from wp-config.php.in template. Placeholders in wp-config.php.in are replaced with their values
   $fSystemHelper = new \APS\FilesConfigurator($this, $this->website);
   $fSystemHelper->writeConfigFile('wp-config.php.in', $this->website->path.'/'.$this->website->root.'/wp-config.php');
}

PHP Runtime Utilities

1. APSDatabaseConfigurator class

   This object is intended for populating a database from a DB schema.

   Constructor:

   new \APS\DatabaseConfigurator(<application object>, <database object>)
   

   Methods:

   importSchema(<schema>)
   

   <schema> - path to the schema file, either absolute or relative, from the calling module location.

   importSchemas(<schemas>)
   

   <schemas> - an array of schema file paths

   Example from WordPress:

   $dHelper = new \APS\DatabaseConfigurator($this, $this->db);
   $dHelper->importSchema('schema.sql');
   

2. APSFilesConfigurator class.

   FilesConfigurator creates configuration files from templates.

   Constructor:

   new \APS\FilesConfigurator(<application object>, <website object>)
   

   Methods:

   writeConfigFile(<template file path>, <destination file path>)
   

   <template file path> - full or relative path to the config template.

   <destination file path> - full path to the destination file.

   It reads template file contents, replaces placeholders with values, writes the result to the destination file.

   Example from WordPress:

   $fSystemHelper = new \APS\FilesConfigurator($this, $this->website);
   $fSystemHelper->writeConfigFile('wp-config.php.in', $this->website->path.'/'.$this->website->root.'/wp-config.php');
   

3. Additional functions in the APS namespace.

   In addition, the class provides the following useful functions:

   setWritePermissions(<file path>)
   

   <file path> - full path to the file for which the write permissions will be set

   setReadonlyPermissions(<file path>)
   

   <file path> - full path to the file for which the read-only permissions will be set

   function isLinux() {
          return preg_match('/Windows/', $this->environment->Platform->os) ? 0 : 1;
   }
   

   deleteDirectory(<full directory path>)
   

   <full directory path> - path to the directory to be deleted.

   $this->auth_key = \APS\generatePassword(64);
   

   Generates password compatible with Odin Automation password requirements, for example when registering a user in the platform.

← Operations with Resources

Operating APS Versions →