Configs

Contents...

All app-related configuration files reside in lib/config/ subdirectory inside the app directory. Changing the location or the name of a configuration file is not allowed.

app.php

File app.php is the main configuration file of an app. It contains the app name, the path to the app icon file, the current version number, the database tables name prefix, availability of an app interface optimized for mobile devices, availability of the frontend interface, and other parameters.

Example
<?php
    
return [
    'name'     => 'My app',
    'img'      => 'img/myapp.png',
    'rights'   => true,
    'frontend' => true,
    'version'  => '1.0.0',
];

Below is the list of all parameters which can be used in file app.php:

  • name: app name, required parameter. The name of an app represents it in the common app selection menu displayed in the Webasyst backend. The string specified in the configuration file is automatically processed by gettext as a localization key; therefore, for multilingual apps we recommend specifying a name in English.
  • img: the path to the app icon file relative to the root app directory. The icon is displayed next to the app name in the main Webasyst menu. An icon image must be 48*48 pixels large. The path to an icon file is not a required parameter. If it is omitted, the default path is automatically calculated according to the following rule: img/[app_id].png.
  • icon: contains an array of paths to app icon files of different size. This parameter is used instead of img, when icons of different size are stored as separate files. 24х24 px and 16х16 px large icons are used for integration with the Site app. If individual icon files for smaller sizes are missing, the default 48х48 px large icon is used, which is resized by the web browser.
    Example: 
    'icon' => [
    48 => 'img/site.png',
    24 => 'img/site24.png',
    16 => 'img/site16.png'
],
  • prefix: database table names prefix. Optional parameter. Default value: [app_id].
  • rights: detailed access rights availability flag. Optional parameter. Default value: false. (Read more about the access rights setup in section "Access rights".)
  • frontend: frontend availability flag. Optional parameter. Default value: false.
  • mobile: mobile interface availability flag. Optional parameter. Default value: false.
  • system: system level app flag. Optional parameter. Default value: false.
  • version: app version number. Required parameter for apps published in Webasyst Store.

db.php

File db.php contains the app database tables description in the following form:

[
    'table1' => [
        'field1' => [FIELD_TYPE,  PARAMETERS...],
        'field2' => [FIELD_TYPE,  PARAMETERS...],
        ...
    ],
    'table2' => [ 
        ...
    ]
];

Field types are standard for MySQL: int, varchar, text, datetime, etc.

Example (app Guestbook 2):

<?php

return [
    'guestbook2' => [
        'id' => ['int', 11, 'null' => 0, 'autoincrement' => 1],
        'contact_id' => ['int', 11, 'null' => 0, 'default' => '0'],
        'name' => ['varchar', 255, 'null' => 0, 'default' => ''],
        'text' => ['text', 'null' => 0],
        'datetime' => ['datetime', 'null' => 0],
        ':keys' => [
            'PRIMARY' => 'id',
            'datetime' => 'datetime',
        ],
    ],
];

You can generate file db.php for any app by executing the following command:

php wa.php generateDb app_id

In this case all tables with names containing app_id or app_id_% will be found (be careful if you have some plugins installed, because the descriptions of their tables will also be added to the app's db.php file).

Update db.php
php wa.php generateDb app_id --update
This command will simply update the descriptions of tablew, which are already contained in file db.php

Explicitly specify the table names of an app:
php wa.php generateDb app_id table1 table2 table3
This command will write only the descriptions of the specified tables to file db.php.

The same applies for plugins with the exception that you have to specify app_id/plugin_id. Example:
php wa.php generateDb blog/tag blog_tag blog_post_tag
blog is an app_id, tag is a plugin_id; blog_tag and blog_post_tag are the plugin's table names.

routing.php

File routing.php contains HTTP request routing rules for the app frontend.

Example of file routing.php for Blog app:

<?php

return [
    'post/[i:id]/?' => 'frontend/post',
    'comment/add/[i:id]' => 'frontend/addComment'
    'rss/?' => 'frontend/rss',
    '' => 'frontend',
    '[s:url]/?' => 'frontend/post'
];

Read more about frontend request routing.

logs.php

File logs.php contains the list of user-triggered app actions, which must be saved in the system log.

Example of file logs.php for Stickies app:

<?php

return [
    'board_add' => [],
    'board_edit' => [],
    'board_delete' => [],
    'sticky_add' => [],
    'sticky_edit' => [],
    'sticky_move_to_board' => [],
    'sticky_delete' => [],
];

Read more about logging user actions in section User actions logging.

install.php & uninstall.php

If some additional actions must be executed during the app installation; e.g., adding some entries to database tables, then such logic must be described in file lib/config/install.php.

Similarly, actions executed when the app is deleted must be described in file lib/config/uninstall.php.

factories.php

This file is useful for overriding some system parameters; e.g., to use an alternative template engine instead of the default Smarty or to use app’s own backend requests dispatcher.

The file must contain an associative PHP array. Array keys must be the names of the parameters which you need to override, and their new values must be the array items’ values.

If a value is a string then it must be the name of a custom class which must be used instead of the framework’s default class. If a value is a simple array then its first item must be the class name, and the second parameter must be its constructor parameters.

What system parameters you can override:

  • 'front_controller': name of front controller class which is used for dispatching user requests to app backend; default front controller class name is waFrontController.
  • 'default_controller': name of default controller which handles user requests to action classes; default name of default controller class is waDefaultViewController.
  • 'view': name of template engine class for generating HTML code for web pages; default class name is waSmarty3View. Below are listed parameters which you can pass to default template engine class constructor:
    • 'auto_literal': whether Smarty tags must be ignored if surrounded by white spaces; default value is true.
    • 'left_delimiter': characters used as left delimiter for Smarty tags; default left delimiter is { character.
    • 'right_delimiter': characters used as right delimiter for Smarty tags; default right delimiter is } character.
    • 'template_dir': path to directory containing templates/ subdirectory with app’s HTML template files; by default, main app source files directory is used.
    • 'compile_dir': path to directory with compiled HTML templates; by default, wa-cache/apps/[app_id]/templates/compiled/ directory is used.
  • 'captcha': CAPTCHA class name; default class name is waCaptcha. CAPTCHA class constructor parameters differ for each class. Below are listed parameters for default CAPTCHA class waCaptcha:
    • 'chars': string of characters used to generate CAPTCHA text; default character string is 'abdefhknrqstxyz23456789'.
    • 'fonts': array of names of font files which must be randomly used to generate CAPTCHA text; by default, font DroidSans is used. Font files must be located in wa-system/captcha/data/ directory.
    • 'width': CAPTCHA image width in pixels; default width is 120.
    • 'height': CAPTCHA image height in pixels; default height is 40.
    • 'font_size': size of font, expressed in “pt” units, used to generate CAPTCHA text; default font size is 25.
    • 'background': name of image file to be used as CAPTCHA image background. Background file must be located in wa-system/captcha/data/ directory; default background is white and contains no additional image.
Example

Overriding default Smarty parameters: use double curly brackets instead of single brackets in HTML templates.

<?php
    
return [
    'view' => [
        'waSmarty3View',
        [
            'left_delimiter'  => '{{',
            'right_delimiter' => '}}',
        ]
    ],
];

Detailed access rights configuration file

Detailed access rights are described in a PHP class extending abstract system class waRightConfig. The PHP file of the access rights settings class must be named according to rule [app_id]RightsConfig.class.php. For example, access rights configuration file for an app with APP_ID guestbook must be named guestbookRightConfig.class.php:

<?php

class guestbookRightConfig extends waRightConfig
{
    public function init()
    {
        $this->addItem('delete', 'Can delete posts', 'checkbox');
    }
}

Custom configuration files

In addition to the standard configuration files, your app can use its own files to store various useful parameters.

The default method of storing configuration data in Webasyst apps is a PHP file returning an array of data. This format is handy for easily retrieving configuration data and using them in your app's source code. Note that all configuration should reside in directory wa-apps/APP_ID/lib/config/.

PHP arrays are not the only acceptable format for storing data in a configuration file. Each developer is free to define his own format and the appropriate data reading routine. For example, a configuration file may contain a class or the result of the json_encode() function.

Suppose that your app (which will be used for processing customer requests) requires some initial data for normal functioning; e.g. a basic list of request statuses (which you may want to make editable). These statuses will be available right after the installation, which will make the app ready for use without prior setup.

Below is an example of simple configuration file statuses.php with a status list:

<?php

return [
    'new',
    'discussion',
    'closed',
    'reopened',
    'canceled',
    'deleted',
];

To make this status list accessible in your app, you need to read the contents of the configuration file and assign it to a variable. Framework's system class waAppConfig provides a useful method returning the absolute path to an app configuration file by its name: getAppConfigPath(). To use this method, first obtain access to an instance of class waAppConfig as shown below:

wa()->getConfig()->getAppConfigPath($config)

Method getAppConfigPath() accepts a string parameter containing the name of the configuration file without extension .php. For example, to obtain the absolute path to file wa-apps/APP_ID/lib/config/statuses.php, use the following code:

wa()->getConfig()->getAppConfigPath('statuses')

Once you have the path to the file, assign the file's contents to a variable; e.g.:

$statuses = include wa()->getConfig()->getAppConfigPath('statuses');

User-defined configuration

The above-described method of storing configuration data allows specifying some static parameters, which cannot be modified by users because such configuration files will be overwritten during installation of updates. To preserve custom parameters, you may use configuration files which are not affected by software updates. Such files should be saved in wa-config/apps/APP_ID/ directory. To obtain the path to some file in that directory, use method getConfigPath() of system class waSystemConfige.g.:

$config_file_path = wa()->getConfig()->getConfigPath('userconfig.php', true, 'myapp');

This example will return the path to file wa-config/apps/myapp/userconfig.php.