Global variables reference

The most important of Cotonti global variables listed and explained

Эта страница еще не переведена на русский. Отображен оригинал страницы на английском языке. Вы можете зарегистрироваться и помочь с переводом.

Most Cotonti scripts run in the global scope as it is historically built this way. Some variables are common enough to be seen in many places around the code. This article covers the most important globals.

Note: this guide comes handy for theme developers as well. You can use any of these global variables as global template tags as well. Just remember the CoTemplate syntax. E.g. $usr['profile']['user_avatar'] in a template becomes {PHP.usr.profile.user_avatar}.

#1. Cot facade class

There are some hooks in the system are fired within system functions so includes of some extension files made in function scope.  So historically  as common practice there used global keyword to access some system variables. But thats not always good. So Cot facade class had been introduced.

Since 0.9.15 all main global variables, like ($cfg$usr$db$id$strucutre, etc.) can be accessed through cot facade class. So you don't need to use global keyword, use direct cot class instead. Example:

if ( cot::$cfg['plugin']['comments']['enabled'] )
{
  // some code
}

Full list of available variables within facade: $cache, $cfg, $cot_extrafields, $db, $db_x, $env, $L, $out, $R, $structure, $sys, $usr.

 

#2. Current user's profile

$usr represents the current user and is the most popular global variable among the others.

You can distinct logged in users from guests by checking $usr['id']:

if ($usr['id'] > 0)
{
    // The user is logged in
}
else
{
    // It is a guest
}

Here is the list of standard keys this array has:

  • $usr['id'] - unique number of the user in the database;
  • $usr['name'] - username (login) of the user;
  • $usr['maingrp'] - identifier of the main group the user belongs to, grp_id value of the groups table;
  • $usr['ip'] - current user's IP address;
  • $usr['lang'] - user's language preference. Another global $lang is a shortcut for this;
  • $usr['theme'] - user's theme preference;
  • $usr['scheme'] - user's color scheme preference;
  • $usr['timezone'] - user's timezone offset in hours;
  • $usr['timezonename'] - the name of the user's timezone;
  • $usr['lastvisit'] - a timestamp for the last user activity on site;
  • $usr['lastlog'] - a timestamp for the last time user logged in;
  • $usr['level'] - user's main group's level value;
  • $usr['profile'] - an array providing access to all the fields in the users table, explained below.

You can use $usr['profile'] to obtain raw values of user profile fields, including extra fields. It contains them prefixed with 'user_'. For instance, here are the standard ones:

  • $usr['profile']['user_birthdate'] - user's birthdate in MySQL date format. You can display it using a combination of cot_date2stamp() and cot_date() functions;
  • $usr['profile']['user_country'] - contains 2-char ISO country code of the user, if specified;
  • $usr['profile']['user_email'] - user's email address;
  • $usr['profile']['user_gender'] - one char for user's gender: 'M' for male, 'F' for female or 'U' for unknown;
  • $usr['profile']['user_hideemail'] - true if the user prefers their email to stay private (default) or false if it can be displayed;
  • $usr['profile']['user_logcount'] - the number of times a user has logged in;
  • $usr['profile']['user_regdate'] - a timestamp for user registration date and time;
  • $usr['profile']['user_text'] - user signature text.

So if you added an extrafield to users table that is called "first_name", then it can be accessed as $usr['profile']['user_first_name'] in the $usr global.

#3. Current user's settings

There are a few globals containing current values of per-user display settings for current request:

  • $lang - current language code;
  • $theme - current theme name;
  • $scheme - current color scheme name.

#4. Configuration variables

All configuration variables are accessible via $cfg global. It has several levels of nesting:

  • $cfg['option_name'] - one of the core settings;
  • $cfg['module_name']['option_name'] - setting for a specific module;
  • $cfg['plugin']['plugin_name']['option_name'] - plugin setting.

#5. Extension environment

The $env array contains information about current extension (module or plugin) being executed and status information of the request:

  • $env['type'] - 'module' for modules or 'plug' for plugins;
  • $env['ext'] - extension code, e.g. 'forums';
  • $env['location'] - a string containing textual description of user's location on site, such as 'Home page';
  • $env['status'] - HTTP rersponse status, e.g. '200 OK';

#6. System variables

There are temporary system variables that are used in several places and calculating them again and again would be a waste of resources.  Such variables may be contained in the global $sys array. Here are some of its common contents:

  • $sys['now'] - an integer timestamp for the current time in UTC, same as calling time() function for UTC (Cotonti dates are stored in UTC and timezones are applied right before displaying them);
  • $sys['site_id'] - some string unique for the site and used as its identifier (this data is public);
  • $sys['parser'] - the code for the default parser plugin or the parser selected for the current data;
  • $sys['xk'] - contains current value of CSRF protection token, used in forms;
  • $sys['noindex'] - set this TRUE if current page should not be indexed by search engines;

The following variables are related to runtime detection of current URL and its parts:

  • $sys['scheme'] - URL scheme, like 'http' or 'https';
  • $sys['secure'] - a flag which is TRUE for HTTPS protocol being used;
  • $sys['host'] - full host part of the URL, e.g. 'my.example.com';
  • $sys['domain'] - 2nd level domain of the URL, such as 'example.com';
  • $sys['port'] - the port if other than 80, containing comma, e.g. ':8080';
  • $sys['site_uri'] - relative path of the site root on server with trailing slash. E.g. if you run Cotonti in 'example.com/cotonti/' then this path will be '/cotonti/';
  • $sys['abs_url'] - absolute URL to the site root, e.g. 'http://my.example.com/cotonti/'. This is normally same as $cfg['mainurl'] with a forward slash, but on sites using multiple subdomains this would be different from $cfg['mainurl'] if accessing from subdomain;
  • $sys['canonical_url'] - is used to get and set the canonical URL for the current page (used in html head);
  • $sys['uri_curr'] - contains the current request URI part of the URL, e.g. '/cotonti/foo?bar=baz';

#7. Output variables

These variables are used to make global tags to output them in multiple templates. They are collected in $out array. Here are some standard elements:

  • $out['uri'] - the URI part of the current URL valid for HTML, e.g. '/index.php?foo=bar&boo=baz';
  • $out['notices_array'] - user personal bar notifications array;
  • $out['copyright'] - prints "Powered by Cotonti" link;
  • $out['meta_contenttype'] - MIME type of the document, 'text/html' is default;
  • $out['logstatus'] - displays user's login status as a string message;
  • $out['userlist'] - displays the list of online users;
  • $out['subtitle'] - sets the variable part of the head <title> tag. E.g. if you set it to 'Apples', the full title would look somewhat like 'Apples - Fruits - My Cool Garden Site';
  • $out['meta_desc'] - sets meta description of the page;
  • $out['meta_keywords'] - sets meta keywords of the page;
  • $out['meta_lastmod'] - sets last modification date of the page;
  • $out['adminpanel'] - displays the link to Administration panel for logged administrators;
  • $out['loginout_url'] - a URL to log the current user out;
  • $out['loginout'] - HTML link to log the current user out;
  • $out['profile'] - HTML link to current user's profile settings;
  • $out['guest_username'] - username form input for guests;
  • $out['guest_password'] - user password input for guests;
  • $out['guest_cookiettl'] - "remember me" checkbox for guests;
  • $out['guest_register'] - a link to registration for guests;

#8. Structure tree

The entire tree of site's categories, managed in Administration / Structure, is accessed via $structure global. It has the signature:

$structure['module_name']['category_code']

Where 'module_name' is the module code such as 'page' and 'category_code' is the code of the category such as 'articles'. The returned element is an associative array containing the keys:

  • 'path' - the dot separated path of the codes from structure root, such as 'goods.electronics.blenders';
  • 'tpath' - a path consisting of category titles instead, e.g. 'Goods - Electronics - Blenders';
  • 'rpath' - raw path property of the category, e.g. 'goods.1.3';
  • 'id' - integer identifier;
  • 'title' - category title;
  • 'desc' - category description';
  • 'icon' - category icon path, if present;
  • 'locked' - whether category accepts adding new items;
  • 'count' - number of items contained.

Structure extra fields are also accessible via $structure. For example, if you have added an extrafield with code 'specialty', then it is accessible as

$structure['module_name']['category_code']['specialty']

#9. Database and cache access

There are two other rather important global variables:

  • $db - an instance of CotDB class used to query the database, see CotDB class reference and PDO for more information;
  • $cache - an instance of Cache class, see Cache API documentation for more information.

#10. Other global lists

There are some other global collections good to be mentioned for extension developers:

/**
 * Contains information about user groups, you'd better find yourself in system/common.php file
 */
$cot_groups = array();

/**
 * Registry for captcha functions
 */
$cot_captcha = array();

/**
 * Registry for hash functions
 */
$cot_hash_funcs = array('md5', 'sha1', 'sha256');

/**
 * Array of custom cot_import() filter callbacks
 */
$cot_import_filters = array();

/**
 * Custom e-mail send callbacks
 */
$cot_mail_senders = array();

/**
 * Custom parser functions registry
 */
$cot_parsers = array();

/**
 * Parameters to be automatically appended to all URLs if present
 */
$cot_url_appendix = array();

/**
* List of installed (active) plugins. Where keys is a plugin name and value is boolean (TRUE/FALSE).
*/
$cot_plugins_active = array();

/**
* List of installed (active) modules. Where keys is a module name and value is boolean (TRUE/FALSE).
*/
$cot_modules = array();

1. Macik  02.02.2013 02:21

Thanks! Long time expected article.

Добавление комментариев доступно только зарегистрированным пользователям