Warning: The documentation is up to date to Ariadne 2.7.5, but some new features are only available in the latest SVN version of Ariadne. We try to indicate the minimum version for every feature, but there are no guarantees. The API is still fairly unstable and subject to change without notice.

Ariadne General API

The Ariadne General API is the new way to interact with Ariadne. In time it will replace all modules and most class specific methods. The new API is the same whether you are writing a PINP template, a PHP disk template or are modifying Ariadne itself.

The API is divided into two main parts: The public API, which can be used in PINP as well as PHP code, and the private Core API, which can only be accessed from PHP code.

Access to the API is through the ar() method, like this:

  ar('http/headers')->redirect('http://www.muze.nl/');

Or directly like this:

  ar_http_headers::redirect('http://www.muze.nl/'); 

However this only works in PHP code, not PINP.

API Reference

This describes the current state of the Ariadne General API:

ar Loads other modules, contains shortcut to the ar\store methods.
ar\cacheDatacache and cache proxy class.
ar\connect API for all kinds of protocols. Currently:
ar\connect\db, ar\connect\ftpar\connect\oauth, ar\connect\rssar\connect\soapar\connect\twitter, ar\connect\xmlrpc
ar\contentWorking with content stored in Ariadne:
ar\content\files
ar\css Easy CSS generation an manipulation.
ar\error Error handling and raising.
ar\events Event handling and firing.
ar\html Easy HTML generation and manipulation.
ar\html\form, ar\html\menuar\html\table
ar\http Reading and sending HTTP headers and sending HTTP requests.
ar\http\headers, ar\http\files
ar\loader Access to loader specific methods, like redirect, header, etc.
ar\pinp Setting and checking allowed methods
ar\store Access to the Ariadne store.
ar\store\files
ar\url Easy URL generation and manipulation.
ar\xml Easy XML generation and manipulation.

ar

(mixed) acquire Returns a configuration variable from config.ini.
(mixed) call Calls the given template with given arguments on the current object.
(mixed) callSuper Calls the parent template of the current template.
(object) error Shortcut to ar_error::raiseError
(mixed) exists Shortcut to ar_store::exists.
(object) find Shortcut to ar_store::find.
(object) get Shortcut to ar_store::get.
(mixed) getvar Returns an argument passed to the current template.
(object) listExpression Generates a new ar_listExpression object.
(object) listPattern Generates a new ar_listPattern object.
(object) load Loads an Ariadne API module and returns an instance of it.
(object) ls Shortcut to ar_store::ls.
(object) parents Shortcut to ar_store::parents.
(mixed) putvar Makes a variable available globally in Ariadne.
(void) taint Taints a variable as unsafe.
(void) untaint Removes previous tainting of a variable, if set.
(object) url Creates a URL helper object.

acquire

Available in Ariadne > 2.7.4

(mixed) ar::acquire( $varname )

(string) $varname The name of the configuration variable to retrieve.

Returns the value of the given configuration variable for the current path. Configuration variables can be set in the user defined config.ini template as follows:

<pinp>
$arConfig = ar::getvar( 'arConfig' );
$arConfig['mySetting'] = 'myValue';
ar::putvar( 'arConfig', $arConfig );
</pinp>

Once set the value for 'mySetting' can be 'acquired' on any child object of the object on which the above config.ini is defined.

call

(mixed) ar::call( $template, $params = null )

(mixed) $template The name of the template to call
(array) $params The list of parameters for the template.

Calls the given template with the given parameters on the current object and returns the result. The $template argument may be a simple string with the name of the template or it can be a listExpression. In that case each time you call ar::call() with the same listExpression, the actual template to call will be generated by the listExpression. e.g.:

<pinp>
$le = ar::listExpression(5)->pattern( '( odd.html even.html? )*' );
for ( $i = 0; $i < 5; $i++ ) {
ar::call($le, array( 'number' => $i) );
}
</pinp>

This is the same as if you had written:

<pinp>
  ar::call('odd.html', array( 'number' => 0 ) );
  ar::call('even.html', array( 'number' => 1 ) );
  ar::call('odd.html', array( 'number' => 2 ) );
  ar::call('even.html', array( 'number' => 3 ) );
  ar::call('odd.html', array( 'number' => 4 ) );
</pinp>

callSuper

Available in Ariadne > 2.7.4

(mixed) ar::callSuper( $params = null )

(array) $params The parameters to pass on to the parent template.

This method calls the template that is overridden by the current template. So if you have two templates called 'view.html', one for 'pobject' and one for 'ppage', the view.html template for ppage can call the one for pobject using this method. This way you do not have to know which exact template is overridden.

If you do not pass any parameters, it will automatically use the same parameters as for the current template.

getvar

(mixed) ar::getvar( $varname )

(string) $varname The name of the variable to return.

Returns a variable either passed to the current template or made available globally in Ariadne using ar::putvar(). Any variables passed to the loader, e.g. as HTTP Get or Post parameters are also available. The order of precedence is as follows:

  1. Parameters passed directly to the current template in ar::call()
  2. Parameters made globally available using ar::putvar()
  3. Parameters passed to the loader, for the default HTTP loader:
    1. POST parameters
    2. GET parameters

See the chapter on the magic of ar::getvar() in the user manual for a more thorough explanation.

listExpression

(object) ar::listExpression( $list )

(mixed) $list The list (array or ArrayObject) to base the list expression on or the length (integer) of the list.

This method returns an ar_listExpression object, which allows you to generate list patterns based on the length of the list supplied. See the explanation and examples at ar::listPattern().

If $list is an object, it must implement the countable interface. In addition the generated ar_listExpression will have a reference to the list and so whenever the length of $list changes, the ar_listExpression is always up to date.

The ar_listExpression implements the ArrayAccess, Iterator and Countable interface, so you can treat it like a 'normal' array. In addition it has the following methods:

(array) item Returns the list pattern results for a list position.
(object) pattern Adds one or more list patterns to the list expression.

item

(array) ar_listExpression::item( $position )

Returns the results of the patterns applied at the given position.

pattern

(object) ar_listExpression::pattern( $pattern, ... )

Adds one or more list patterns to the list expression. Returns the list expression object. See ar::listPattern() for a more complete description.

listPattern

(object) ar::listPattern( $pattern, ... )

(string) $pattern A list pattern to add to the list expression

A list pattern is similar to a regular expression, but instead of matching string contents it matches list positions. A simple example:

<pinp>
$list = array( 'a', 'b', 'c', 'd' );
$le = ar::listExpression( $list )->pattern( '(odd even?)*' );
foreach ($list as $position => $value) {
echo $position.": ".$value." - ".$le->item( $position );
}
</pinp>

Results in:

0: a - odd
1: b - even
2: c - odd
3: d - even

What happens is that for each position in the list, the list expression tries to match one of the values in a pattern. In this case the values are 'odd' and 'even'. The pattern specifies that the first item should always be 'odd'. The second item is 'even', but it is optional, denoted with the '?' meta character. If it was not optional, the pattern would only ever match with lists which have an even length. A pattern will only match if it can supply the correct number of items, without violating the pattern.

Other meta characters are:

* Repeat the previous part 0 or more times.
+ Repeat the previous part 1 or more times.
? The previous part is optional.
| OR operator, what follows is an alternative to the previous parts of this (sub)pattern.
{n} Repeat the previous part exactly n times.
{n, m} Repeat the previous part at least n and up to m times, depending on the length of the list.
(...) Creates a new sub pattern. Any modifiers after a closing bracket apply on the entire sub pattern.
. Doesn't return a value for the matching position.
"..." Treat the contents of the double quotes as a single value in the pattern. Escape a double quote that is part of the value with a backslash ( \" ).
'...' Identical to " ... ", except using single quotes. Escape a single quote with a backslash.

More examples of patterns are:

ar::listPattern( "first .*", ".* last" );

Marks the first and last elements of a list. Could also be written as:

ar::listPattern( " 'first last' | first .* last " );

The difference is that the first listPattern actually consists of two patterns, which are both applied to the list. That is why in the second pattern there is a special case for a list with one item, with the result 'first last'. You could also write this:

ar::listPattern( " single | first .* last " );

This returns 'single' for a listExpression with one item. You aren't limited to first/last or odd/even patterns, this one for example:

ar::listPattern( " ( .{2} line )* " );

Marks every third element of a list with the value 'line'. When applied to the class attribute of a piece of html you could use this to automatically generate a horizontal line after every 3rd line, improving readability.

List patterns can be used in a number of modules, e.g.:

ar\xml and ar\html

<pinp>
$x = ar('xml');
  $ul = $x->tag('ul',
    $x->tag('li', 'item 1'),
    $x->tag('li', 'item 2')
    $x->tag('li', 'item 3')
  );
$ul->childNodes->setAttribute(
    'class',
    ar::listPattern( '(odd even?)*' )
  );
echo $ul;
</pinp>

ar\store

<pinp>
ar::ls()->call(
ar::listPattern( '( show.odd.html show.even.html? )*' )
);
</pinp> 
<pinp>
ar::find( "object.implements = 'pdir'")->call(
ar::listPattern(
'show.single.html | ' .
'show.first.html ( show.odd.html show.even.html? )* show.last.html'
)
);
</pinp>

load

(object) ar::load( $name = null )

or: (object) ar( $name = null )

(string) $name The name of the Ariadne API module to load

This method loads the named Ariadne API module and returns an instance of it. This can also be done through the ar() method.

Examples:

ar::load('http/headers')->redirect($url);
ar('http/headers')->header($header);

putvar

(void) ar::putvar( $varname, $value )

(string) $varname The name of the variable
(mixed) $value The value of the variable

This method creates a new global variable in Ariadne with the given name and value. The variable can be retrieved using ar::getvar().

taint

(void) ar::taint( &$variable )

(mixed) $variable The variable to taint as unsafe.

This method will 'taint' the given variable as 'unsafe'. Any later use of such a variable as a string will automatically escape all special characters in the string. It will only do this for string variables. If the variable is an array, it will taint all string values in the array. Number type variables and objects remain untouched.

The method is meant to be used on variables which enter Ariadne's context from 'outside', e.g. through a form input or through a request parameter in the URL. As such there is no need to handle objects and taint doesn't attempt to. Variables which are of a number type are also exempt, since there is no way they can contain unsafe characters.

This method is currently automatically called on all variables returned from ar('http')->getvar().

The tainted variable can be untainted by hand using the ar::untaint() method.

Ariadne has a safety net mechanism to prevent XSS attacks which kicks in if you haven't properly untainted user input.

untaint

(void) ar::untaint( &$variable, $filter = FILTER..., $options = null )

(mixed) $variable The variable to untaint.
(int) $filter The filter to use when untainting the variable. The default is FILTER_SANITIZE_SPECIAL_CHARS. See the PHP Sanitize Filters page for a full list of filters you can use.
(array) $options Optional parameters for the given filter. See the PHP Filter Flags page for a full list of options you can use. 

This method 'untaints' a previously tainted variable. If the variable is not tainted it will do nothing, otherwise it will filter the contents of the variable, using php's filter_var() method with the given filter and options. If the variable is an array, it will recursively search the array for tainted values and untaint them.

Ariadne has a safety net mechanism to prevent XSS attacks which kicks in if you haven't properly untainted user input.

url

(object) ar::url( $url = '' )

(string) $url The url to parse.

Available from Ariadne > 2.7.3. This method parses the given url and returns an ar_url object in which all the components of the url can be easily accessed and changed. The object also has a __toString() method which returns a valid url with all its components.

<pinp>
$url = ar::url( 'http://www.ariadne-cms.org/' );
$url->path = '/docs/search/';
$url->query->searchstring = 'test';
echo $url;
</pinp>

This code echoes the following url:

http://www.ariadne-cms.org/docs/search/?searchstring=test

You can change any of the following components:

scheme e.g. 'http'
user A user name to include in the url.
password A password to include in the url, will only be included if a username is also specified.
host The host name, e.g. 'www.ariadne-cms.org'.
port The port number.
path The path.
query The query string. This is also automatically parsed to an object and you can access any variable inside it as a normal php variable. See the example above. You can also use it as an array, it extends ArrayObject.
fragment The html fragment after the '#'.

When parsing a URL the query arguments are automatically tainted if tainting is enabled in ar\http. See ar/url for more information.