Ariadne

• Programmers Ref…»
• Ariadne General…»

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

acquire

Available in Ariadne > 2.7.4

(mixed) ar::acquire( $varname )

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 )

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 )

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 )

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 )

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:

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, ... )

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:

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 )

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 )

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 )

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 )

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 = '' )

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:

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

• FAQ
• Installation
• User Manual
• Tutorials
• Programmers Reference
  • architecture
  • classes
  • Ariadne General API
    • Cache
    • Content
    • connect
    • CSS
    • error
    • events
    • HTML
    • HTTP
    • loader
    • PINP
    • store
    • URL
    • XML
  • modules
  • Templates
• Installation Requirements
• Examples