Xoops APIs

Xoops::config()

value|Xoops\Application\Config Xoops::config(string $name = null, string $domain = '')

This static method is provided by system, it is used to load configuration data of XoopsEngine. The object this method could operate are the files in the var/config directory and data similar to application's config table where category is general and module is system.

Parameters

name

Specifying the name of configuration element and configuration data will be returned according to this parameter.

domain

Configuration domain.

Return values

This API will return the configuration data of XoopsEngine by passed name parameter, if the name parameter is not set, this API will return a Xoops\Application\Config handler. It can help you to operate with configuration data.

The default values of name parameter you can use are come from two resources:

Fields in config array of var/config/engine.php folder;
The value of title field in application's config table where category is general.

For example:

$config = Xoops::config('environment');
$config = Xoops::config('sitename');
$config = Xoops::config('theme');

The value of $config will be:

'debug'
'Web Applications'
'default'

Xoops/Application/Config

Methods in this class can help you to fetch configuration data from the file specified. Methods in Config class are:

mixed value get(string $name, string $domain = '');
Config object set(string $name, mixed $value, string $domain = '');
Config object setConfigs(array $configs, string $domain = '');
Config object unsetDomain(string $domain = '');
Config object loadDomain(string $domain = '');
array load(string $configFile);

loadDomain()

This method is used to load configuration data of a domain from table config, it do not return the data directly, but call setConfigs() to store data, you can call get() method to fetch the data.
```
  $configs = Xoops::config()->loadDomain();
  $configs = Xoops::config()->loadDomain('meta')->get('author', 'meta');
```
The $configs value of second line may be the following data as default:
```
  'Xoops Engine'
```
The loadDomain() method achieves loading data for later uses, so we can fetch the data indirectly:
```
  $config = Xoops::config()->loadDomain('meta');
  ...
  $configs = $config->get('author', 'meta');
```

load()

This method is used to load configuration data in var/config directory by file name:

  $configs = Xoops::config()->load('host.php');
  $configs = Xoops::config()->load('service.database.php');

Xoops::service()

Xoops\Application\Service\ServiceAbstract|Xoops\Application\Service Xoops::service(string $name = null, array $options = array())

Parameters

name

Name of service classes to load. This value should be the file name without suffix in the Xoops/Application/Service directory.

options

Value for constructing an object.

Return values

If the name parameter is not set, a Xoops\Application\Service handler will be returned. Or else, it will return a handler relates to the parameter name. For example, if the first parameter set to database, and class Xoops\Application\Service\Database is exists, the handler of this class will be returned.

The following two examples will have the same results:

$assetService = Xoops::service()->load('asset');
$assetService = Xoops::service('asset');

The output is a handler:

'Xoops/Application/Service/Asset'

Xoops/Application/Service/Asset

This class is used to operate the asset directory of XoopsEngine. Part of methods in this class are list as follows:

string getBasePath();
string getBaseUrl();
string getPath(string $component);
string getUrl(string $component);
string getAssetPath(string $component, string $file);
string getAssetUrl(string $component, string $file);
string getModuleAsset(string $file, string $module = null);
string getThemeAsset(string $file, string $theme = null);
string getSourcePath(string $component, string $file = '');

getBasePath() and getBaseUrl()

These two methods will return the path and url of asset folder respectively.
```
  echo Xoops::service('asset')->getBasePath();
  echo Xoops::service('asset')->getBaseUrl();
```
The output will list as follows if XoopsEngine is installed in D:/wamp/www directory:
```
  'D:/wamp/www/XoopsEngine/www/asset'
  'http://localhost/XoopsEngine/www/asset'
```

getPath() and getUrl()

These two methods are used to get the path and url of the component in www/asset directory.

  echo Xoops::service('asset')->getPath('theme/default');
  echo Xoops::service('asset')->getUrl('module/system');

The output is:

  'D:/wamp/www/XoopsEngine/www/asset/theme-default'
  'http://localhost/XoopsEngine/www/asset/module-system'

getAssetPath() and getAssetUrl()

These two methods will return complete path and url of files.

  echo Xoops::service('asset')->getAssetPath('theme/default', 'image/logo.png');
  echo Xoops::service('asset')->getAssetUrl('theme/default', 'image/logo.png');

Output:

'D:/wamp/www/XoopsEngine/www/asset/theme-default/image/logo.png'
'http://localhost/XoopsEngine/www/asset/theme-default/image/logo.png'

Xoops/Application/Authentication

This class is used for user identity authentication. Its methods are list as:

Zend\Authentication\Result authenticate();
$this object setAdapter(Adapter $adapter);
getAdapter();
$this object setStorage(Storage $storage);
getStorage();
Boolean hasIdentity();
mixed|null getIdentity();
clearIdentity();
wakeup(string $identity = null);

authenticate() and wakeup()

The authenticate() method is used to authenticate user identity by passed identity and credential. The wakeup() method is used to wake up a user by passed identity.

  $identity = $post['identity'];
  $credential = $post['credential'];

  $result = Xoops::service('authentication')->authenticate($identity, $credential);
  if (!$result->isValid()) {
      ...
  }

  Xoops::service('authentication')->wakeup($identity);

hasIdentity() and getIdentity()

These two methods can be used to check and fetch the identity, for example:

  if (Xoops::service('authentication')->hasIdentity()) {
      ...
      $identity = Xoops::service('authentication')->getIdentity();
  }

setStorage() and getStorage()

Xoops/Application/Service/Captcha

This class mainly used to operate captcha. The methods are list as follows:

AdapterInterface load(string $type = null, array $options = array());

load()

This method is used to load a captcha adapter, it takes two parameters, the first one is the type of captcha, it decides which handler to get. The second parameter is optional, and is used as parameter for constructing an object.
```
  Xoops::service('captcha')->load('image')->generate();
```

Xoops/Application/Service/Database

This class is used to operate database, it mainly load a database handler to operate with database.

Xoops\Application\Db db($options = array());
Xoops\Application\Db loadDb($option = array());

db()

This method mainly return a Xoops\Application\Db handler for user to operate tables.
```
  echo Xoops::service('database')->db()->prefix('login', 'system');
```
If the prefix of XoopsEngine database is xe, this code will return:
```
 'xe_system_login'
```

Xoops/Application/Service/Module

This class is used to operate module, such as getting module name and meta, etc.

Module object setModule(string $module);
string current();
string getMetaFile();
array createMeta();
Boolean init(boolean $force = false);
array|Boolean meta(string $module = null);
Boolean isActive(string $module);
array config(string $key = null, string $module = null);
array loadMeta(string $module, string $type = null);
string path(string $module);
string directory($module = null);
array content(array $variables, array $conditions);

current()

This method is used to get current active module, it will return the module name.
```
  $module = Xoops::service('module')->current();
  echo $module;
```
If current module is demo, the output will be:
```
  'demo'
```
getMetaFile()

This method will return a meta file name which contains the active module meta data. Generally, the meta file is module.meta.php.
createMeta()

This method will write meta data fetching from DB into the meta file.
init()

This method is used to initialize the service, it will load all meta data from meta file.

meta()

This method is used to get module meta data.

  if (Xoops::service('module')->init(true)) {
      $meta = Xoops::service('module')->meta('system');
  }

The $meta variable is an array:

  array(
      'directory'    => 'system',
      'active'       => '1',
  )

isActive()

This method will check whether a module is active.
config()

This method will fetch configuration data from application's config table according to its parameters.

The $module parameter of this method indicates the module name, the system configuration data will be returned if this parameter is not set.
```
  echo Xoops::service('module')->config('sitename');
  echo Xoops::service('module')->config('author', 'user');
```
The first line will output:
```
  'Web Application'
```
loadMeta()

This method will load meta data in the module.php of a module according to its parameter. If the type parameter is not set, all data will be returned.
```
  Xoops::service('module')->loadMeta('user');
  Xoops::service('module')->loadMeta('user', 'meta');
```
path()

This method is used to get path of a module.

Xoops/Application/Service/Registry

This class mainly provides users a handler point to Xoops/Application/Registry directory.

For example:

Xoops::service('registry')->config;

This code will return a Xoops\Application\Registry\Config handler, then you can use the handler to call its methods.

You can also use a method directly, the following two line has similar results:

Xoops::service('registry')->config->read('system', 'general');
Xoops::service('registry')->config('read', 'system', 'general');

Xoops/Application/Service/Session

This class contains a magic method __get(), it will return a Zend\Session\Container handler, then you can use this hanlder to operate sessions.

For example:

$session = Xoops::service('session')->session;

Now you can set sessions:

$session->offsetSet('email', $email);
Xoops::service('session')->email = $email;

Checking whether key exists:

$session->offsetExists('email');

Getting value by key:

$email = $session->offsetGet('email');
$email = Xoops::service('session')->email;

Getting container name:

echo $session->getName();

The output of this code will be:

'session'

It also allows you to get a session manager for more operations, a getManager() method can be used to achieve it:

$sessionManager = Xoops::sevice('session')->session->getManager();

It may return a Zend\Session\SessionManager hanlder:

$sessionManager->setSessionCookieLifetime(30);

Xoops/Application/Service/Theme

This class is used to operate with theme.

Theme setTheme(string $theme);
string current();
array loadConfig(string $theme);
string path(string $theme);

current()

This method will return the current theme name.
loadConfig()

This method is used to load theme configuration data from the config.php of theme package.
```
  Xoops::service('theme')->loadConfig('default');
```

Xoops::engine()

Xoops\Application\Engine\AbstractEngine engine(string $type, array $config = array())

This method mainly used to initilize the XoopsEngine application.

Parameters

type

Application type, this parameter decides which handler to return.

config

Configuration data used for constructing object.

Return values

This method will return a handler according to its type parameter, for example, a root type will return a Xoops\Application\Engine\Root handler. If the type is set to '', it will return Xoops\Application\Engine\Standard as default.

If you want to get a hanlder of root class in Xoops\application\engine directory, you can use:

$root = Xoops::engine('root');

If you want to load and boot the application, using the following code:

Xoops::engine()->run();

Xoops/Application/Engine/Admin

This class inherits from standard class, and it achieve tasks of loading configs, default listeners, module maneger, bootstrap, application and running application.

mixed loadResource(string $resource, array $options = array());

loadResource()

This method is used to load resources according to its parameter. It will get a hanlder of the class in Xoops\Application\Resource directory by setting the $resource parameter. Then the boot() method of the class will be called.
```
  Xoops::engine('admin')->loadResource('acl');
```

Xoops::registry()

mixed registry(string $index, mixed $value = null)

This method is used to registry container for global variables.

Parameters

index

The location to store the value, if value is not set, to load the value.

value

The object to store.

Return value

Return void if the $value parameter is set, or else return a mixed result according to the $index parameter.

Xoops::log()

void log(string $message, array|Traversable $extra = array())

This method will output a log audit message in the debug block for user to view or debug.

Parameters

message

Log message.

extra

Extra message such as time. If it is not set, the application will get current time automatically.

Example

Xoops::log('Audit test in shortcut way.');

Output:

03:59:10.317
       [audit]
       Audit test in shortcut way.

The above code will have the same effect with the following code:

Xoops::service('log')->audit('Audit test in shortcut way.');

Xoops::model()

Xoops\Application\Model\ModelAbstract model(string $name, string $module)

This method is used to get a hanlder relates to the table indicated by passed name parameter.

Parameters

name

Name of table, this parameter has a format such as {module name}/{table name}, the module name can be ignored if you want to operate the system table. If you want to operate a module table, this parameter can be ignored, but you must set the $module parameter.

module

Module name, optional.

The following two line will operate the same table:

$model = Xoops::model('login/user');
$model = Xoops::model('user', 'login');

If the table prefix is xe, these codes will operate the table xe_login_user.

The following code will operate the table xe_core_config:

$model = Xoops::model('config');

Please refer to database for more information on how to operate with database.

The Nested Set Model

Generally, most users may encounter with hierarchical data in SQL database. A nested set model is a type of hierarchical data, in a nested set model, it uses left, right and depth three fields to describe this model. You can refer to this article for more knowledge of nesed set model: `Managing Hierarchical Data in MySQL http://web.archive.org/web/20110606032941/http://dev.mysql.com/tech-resources/articles/hierarchical-data.html>.

The figure of the nested set model is:

.. image:: image/nest1.png

It also can use tree to describe:

.. image:: image/nest2.png

Therefore, you at least should include three field left, right and depth in your table. XoopsEngine provides us a class named AbstractNest to operate nest model database, the method in this class are list as:

void trim(int $start = 1, bool $leftVerified = false);
mixed add(array $data, mixed $objective = null, string $position = 'lastOf');
mixed remove(mixed $objective, bool $recursive = false);
bool move(mixed $objective, int $reference = null, string $position = 'lastof');
array getPosition(mixed $objective = null, string $position = 'lastOf')
int getDepth(mixed $objective);
Rowset getRoots(Where $where = null);
mixed getAncestors(mixed $objective, array $cols = null);
mixed getChildren(mixed $objective, array $cols);

Creating database for nested set model

A table is the basic requirement if you want to operate nested set model, then you should at least define three field named left, right, and depth, the code to create table is list as follows:

CREATE TABLE `{table name}` (
    `id`       int(10) unsigned        NOT NULL auto_increment,
    `left`     int(10) unsigned        NOT NULL default '0',
    `right`    int(10) unsigned        NOT NULL default '0',
    `depth`    smallint(3) unsigned    NOT NULL default '0',
    // add your own fields

PRIMARY KEY  (`id`)
);

Creating a class inherit from Nest class

A Nest class include methods to operate nested database, but it also need a handler which include the table information, therefore, it is necessary to creating a class inherits from Nest class. You should follow three steps as follows:

Creating a Model folder in the module/{module name}/src/ folder;
Creating a PHP file to add a class, the file name should as same as the table name, and its first letter is uppercase;
Setting the class's namespace, and let the class inherits from the Nest class.

For example:

namespace Module\Login\Model;

use Xoops;
use Xoops\Application\Model\Nest;
use Xoops\Db\RowGateway\Node;

class Items extends Nest
{ 
}

Adding node in controller

In controller you should create an instance includes table information, by using the Xoops::model() API, you can initilize the class create in Model folder, then you can call methods define in AbstractNest class:

$modelItems = $this->getModel('items');
$resource = array(
    'id'    => null,
    'name'  => 'electronic',
);
$resourceId = $modelItems->add($resource);

trim()

This method is used to strip empty positions starting from a specific position, it takes two parameters, the first one describes the start position and the second parameter tells to detect empty position on left side if it set to false.

add()

This method is used to add a leaf node for nest set, its first parameter is an array type, it include data to insert into database; the second parameter is the target node ID or node, if you want to set root node, set this parameter to null; the third parameter decides which position to insert, its value can be firstOf, lastOf, nextTo and previousTo.

    $modelItems = $this->getModel('items');
    // Adding a root node
    $modelItems->add(array('id' => null, 'name' => 'root'));
    // Adding a child node for 'root' by parent source
    $parent = $modelItems->select(array('name' => 'root'))->current();
    $itemsId = $modelItems->add($resource, $parent);
    // Adding a child node for 'root' by parent ID
    $parent = $modelItems->select(array('name' => 'root'))->current()->toArray();
    $parentId = $parent['id'];
    $modelItems->add(array('id' => null, 'name' => 'child-leaf'), $parentId);

remove()

This method is used to remove a node by passed parameter. Its second parameter decides whether to delete all children nodes. It will return node deleted.

    // Removing node including children by node resource
    $deleteItem = $modelItems->select($where)->current();
    $rowset = $modelItems->remove($deleteItem, true);
    // Removing node only by node Id
    $deleteItem = $modelItems->select($where)->current()->toArray();
    $rowset = $modelItems->remove($deleteItem['id']);

move()

This method is used to move a node to an indated position, its second parameter describes the reference node.

    $sourceNode = $modelItems->select($where);
    $referenceNode = $modelItems->select($referWhere);
    $modelItems->move($sourceNode, $referenceNode, 'firstOf');

getDepth()

This method is used to calculate depth for a node.

    // Getting depth by ID
    $currentNode = $modelItems->select(array('name' => 'root'))->current()->toArray();
    $test = $modelItems->getDepth($currentNode['id']);
    // Getting depth by node resource
    $currentNode = $modelItems->select(array('name' => 'root'))->current();
    $test = $modelItems->getDepth($currentNode);

getRoots()

This method is used to get root nodes by passing condition.

    $root = getRoots(array('name' => 'cd'))->toArray();

getAncestors()

This method is used to get all the ancestor nodes of current node. The second parameter decide which columns to fetch.

    $currentNode = $modelItems->select(array('name' => '111'))->current();
    $rowset = $modelItems->getAncestors($currentNode)->toArray();
    $rowset = $modelItems->getAncestors($currentNode, array('name', 'title'))->toArray();

getChildren()

This method is used to get all the children nodes of current node, its second parameter is also used to decide the columns to fetch.

    $rowset = $modelItems->getChildren($currentNode)->toArray();
    $rowset = $modelItems->getChildren($currentNode, array('name', 'title'));

Xoops::db()

Xoops\Application\Db db()

This method is used to load a database identifier.

Return value

It will return a Xoops\Application\Db handler.

For example:

echo Xoops::db()->prefix('user', 'login');

If the prefix is xe, it will output:

'xe_login_user'

Xoops\Debug

d()

d(mixed $data = '')

This method is used to display a debug message.

data

A variable or an object.

For example:

d('Hello');

Output:

[06:20:26.671 D:\wamp\www\XoopsEngine\usr\module\login\src\Controller\Admin\IndexController.php:39]
Hello

b()

This method displays backtrace messages.

b();

Parts of messages will be:

Backtrace at: 1344320700.7049

D:\wamp\www\XoopsEngine\www\admin.php(22): include()
D:\wamp\www\XoopsEngine\www\boot.php(34): Xoops::boot()
D:\wamp\www\XoopsEngine\lib\Xoops.php(293): Xoops\Application\Engine\Standard::run()
D:\wamp\www\XoopsEngine\lib\Xoops\Application\Engine\Standard.php(68): Zend\Mvc\Application::run()
...

dc()

dc(mixed $data)

This method is used to display a debug message druing conditional debug. It should call denable() method first to enable output.

data

Data to output, can be string, array or object.

For example:

// No output
dc(array('name', 'age'));

// No output
denable(false);
dc(array('name', 'age'));

// Output message
denable(true);
dc(array('name', 'age'));

Output:

[06:52:12.113 D:\wamp\www\XoopsEngine\usr\module\login\src\Controller\Admin\IndexController.php:40]
Conditional debug enabled

06:52:12.1131 D:\wamp\www\XoopsEngine\usr\module\login\src\Controller\Admin\IndexController.php:41
Array
(
    [0] => name
    [1] => age
)

Xoops::path()

string path(string $url)

Parameters

url

Deciding which path to fetch.

Return values

Return a path string. If url parameter is not equal to existed folder name, it will return the path begin with www directory of XoopsEngine.

For example, the vendor folder is exists in current package, and image is not exists:

echo Xoops::path('vendor');
echo Xoops::path('image');

Output:

'D:/wamp/www/XoopsEngine/lib/vendor'
'D:/wamp/www/XoopsEngine/www/image'

Actual the second path is not exists.

Xoops::url()

string url(string $url, bool $absolute = false)

Parameters

url

The url name to convert.

absolute

Whether convert to full URI.

Return values

Return a url string.

For example:

echo Xoops::url('www');

Output:

'http://localhost/XoopsEngine/www'

Xoops APIs

Contents

Xoops::config()

Xoops::service()

Xoops::engine()

Xoops::registry()

Xoops::log()

Xoops::model()

Xoops::db()

Xoops\Debug

Xoops::path()

Xoops::url()

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally