--- layout: default title: Documentation ---

Documentation

This Documentation gives you a quick reference about all classes and methods that comes with the basic framework package.


Hive

F3::set( string key, mixed value, [ bool = FALSE persist ], [ bool = TRUE resolve ]); void

Bind value to framework variable

setting framework variables

{% highlight php startinline %} F3::set('a',123); // a=123, integer F3::set('b','c'); // b='c', string F3::set('c','whatever'); // c='whatever', string F3::set('d',TRUE); // d=TRUE, boolean {% endhighlight %}

setting arrays

{% highlight php startinline %} F3::set('hash',array( 'x'=>1,'y'=>2,'z'=>3 ) ); // dot notation is also possible F3::set('hash.x',1); F3::set('hash.y',2); F3::set('hash.z',3); {% endhighlight %}

If the persist parameter is TRUE, and the F3 CACHE is enabled, the var is going to be cached.
You can cache strings, arrays and all other types - even complete objects. F3::get() will load them automatically.

{% highlight php startinline %} // cache string F3::set('simplevar','foo bar 1337', TRUE); //cache big computed arrays F3::set('fruits',array( 'apple', 'banana', 'peach', ), TRUE); // cache objects F3::set('myClass1', new myClass('arg1'), TRUE); {% endhighlight %}

By default, the resolve parameter allows you to use the F3 specific syntax in getting and setting vars.

{% highlight php startinline %} F3::set('{{ "{{@b" }}}}','wherever'); // c='wherever' F3::set('{{ "{{@b" }}}}','{{ "{{@a+1" }}}}'); // c='124' F3::set('{{ "{{@b" }}}}',F3::get('a')+1); // c=124 F3::set('color','green'); F3::set('car','this car is {{ "{{@color" }}}}.'); // car='this car is green.' {% endhighlight %}
Notice: changing `color` afterwards, wont affect `car`, as it gets resolved and saved to var on setting it.

F3::get( string key, [ mixed = NULL arguments ]); mixed

Retrieve value of framework variable and apply locale rules

to get a previously saved framework var use:

{% highlight php startinline %} F3::set('c','whatever'); F3::get('c'); // [ string ] = 'whatever' {% endhighlight %}

you can also resolve other vars

{% highlight php startinline %} F3::set('foo','bar'); F3::set('bar','nice'); F3::get('{{ "{{@foo" }}}}'); // returns: nice {% endhighlight %}
Notice: A cached framework var gets loaded by get() automatically, if the var was not defined at runtime before.

Since F3 version 2.0.13 it is also possible to use expressions along with variable array keys. Using these operations makes it easier to access i.e. the next and previous keys of an array like this:

{% highlight php startinline %} F3::set('myarray', array( 0 => 'value_0', 1 => 'value_1', )); F3::set('akey',0); F3::get('myarray[@akey+1]'); // returns: value_1 {% endhighlight %}

F3::clear( string key ); void

Unset framework variable

If you want to remove a framwork variable from memory, you can clear it like this:

{% highlight php startinline %} F3::clear('foobar'); F3::clear('myArray.param1'); // removes key `param1` from array `myArray` F3::clear('SESSION'); // destroys the user SESSION {% endhighlight %}

F3::exists( string key ); bool

Return TRUE if framework variable has been assigned a value

To find out if a variable has been previously defined:

{% highlight php startinline %} F3::set('foo','var'); F3::set('var',1234); F3::exists('var'); // true F3::exists('{{ "{{@foo" }}}}'); // true F3::exists('bar'); // false {% endhighlight %}

F3::valid( string key ); bool

Return TRUE if specified string is a valid framework variable name

Usage:

{% highlight php startinline %} F3::valid('var'); // true F3::valid('var-1'); // error F3::valid('*as'); // error F3::valid('Gemüse'); // error {% endhighlight %}

F3::mset( array argument, [ string prefix ], [ bool = TRUE resolve ]); void

Multi-variable assignment using associative array

With a key=>value paired associative array you can define multiple vars.

{% highlight php startinline %} F3::mset(array( 'var1'=>'value1', 'var2'=>'value2', 'var3'=>'value3', )); F3::get('var1'); // value1 F3::get('var2'); // value2 F3::get('var3'); // value3 {% endhighlight %}

Using the prefix argument, you can append all key names.

{% highlight php startinline %} F3::mset(array( 'var1'=>'value1', 'var2'=>'value2', 'var3'=>'value3', ), 'pre_'); F3::get('pre_var1'); // value1 F3::get('pre_var2'); // value2 F3::get('pre_var3'); // value3 {% endhighlight %}

F3::cached( string key ); mixed

Determine if framework variable has been cached

If the variable has been cached, it return the timestamp of being cached, otherwise it returns false. {% highlight php startinline %} F3::set('var1','foo',TRUE); F3::set('var2','bar'); F3::cached('var1'); // returns timestamp like 1341584513 F3::cached('var2'); // returns false {% endhighlight %}

F3::csv( mixed args ); string

Flatten array values and return as CSV string

{% highlight php startinline %} $data = array('value1','value2','value3'); F3::csv($data); // returns: 'value1','value2','value3' {% endhighlight %}
Notice: Further single quotes are not escaped automatically. Values containing a ' has to be escaped before.

F3::split( string str ); array

Split pipe-, semi-colon, comma-separated string

{% highlight php startinline %} $data = 'value1,value2;value3|value4'; print_r(F3::split($data)); /* output: Array ( [0] => value1 [1] => value2 [2] => value3 [3] => value4 ) */ {% endhighlight %}

F3::sign( mixed num ); int

Returns -1 if the specified number is negative, 0 if zero, or 1 if the number is positive

F3::&ref( string key, [ bool = TRUE set ]); mixed

Get framework variable reference/contents

{% highlight php startinline %} F3::set('foo','bar'); $var = &F3::ref('foo'); $var .= '123'; echo $var; // "bar123" echo F3::get('foo'); // "bar123" {% endhighlight %}

If you set the set argument to false, it basically behaves like F3::get() and it only returns a read-only variable.

F3::copy( string src, string dst ); void

Copy contents of framework variable to another

{% highlight php startinline %} F3::set('var_1','value123'); F3::copy('var_1','foo'); echo F3::get('foo'); // outputs "value123" {% endhighlight %}

F3::concat( string var, string val ); void

Concatenate string to framework string variable

Usage:

{% highlight php startinline %} F3::set('var','hello'); F3::concat('var',' world'); echo F3::get('var'); // output: hello world {% endhighlight %}

F3::sprintf(); string

Format framework string variable

Usage:

{% highlight php startinline %} $count = 5; $location = 'tree'; $format = 'There are %d apes on the %s.'; echo F3::sprintf($format, $count, $location); // There are 5 apes on the tree. {% endhighlight %}

F3::append( string var, string key, mixed val ); void

Add keyed element to the end of framework array variable

Usage:

{% highlight php startinline %} $stock = array('apple'=>12,'cherry'=>4,'banana'=>8); F3::set('fruits',$stock); F3::set('pineapple',3); F3::append('fruits','peach',20); print_r(F3::get('fruits')); /* output: Array ( [apple] => 12 [cherry] => 4 [banana] => 8 [peach] => 20 ) */ {% endhighlight %}

You can also resolve other vars within the arguments, to easily switch the processed data, without changing code.

{% highlight php startinline %} F3::set('stock','fruits'); F3::set('newFruit','pineapple'); F3::append('{{ "{{@stock" }}}}','{{ "{{@newFruit" }}}}',20); print_r(F3::get('{{ "{{@stock" }}}}')); /* output: Array ( [apple] => 12 [cherry] => 4 [banana] => 8 [peach] => 20 [pineapple] => 20 ) */ {% endhighlight %}

F3::flip( string var ); void

Swap keys and values of framework array variable

Usage:

{% highlight php startinline %} F3::set('data',array( 'foo1'=>'bar1', 'foo2'=>'bar2', 'foo3'=>'bar3', )); F3::flip('data'); print_r(F3::get('data')); /* output: Array ( [bar1] => foo1 [bar2] => foo2 [bar3] => foo3 ) */ {% endhighlight %}

F3::merge(); void

Merge one or more framework array variables

Usage:

{% highlight php startinline %} F3::set('data1',array( 'foo1'=>'bar1', 'foo2'=>'bar2', )); F3::set('data2',array( 'foo3'=>'bar3', )); print_r(F3::merge(F3::get('data1'),'data2',array('foo4'=>'bar4'))); /* output: Array ( [foo1] => bar1 [foo2] => bar2 [foo3] => bar3 [foo4] => bar4 ) */ {% endhighlight %}

F3::push( string var, mixed val ); void

Add element to the end of framework array variable

Usage:

{% highlight php startinline %} F3::set('fruits',array( 'apple', 'banana', 'peach', )); F3::push('fruits','cherry'); print_r(F3::get('fruits')); /* output: Array ( [0] => apple [1] => banana [2] => peach [3] => cherry ) */ {% endhighlight %}

F3::pop( string var ); mixed

Remove last element of framework array variable and return the element

Usage:

{% highlight php startinline %} F3::set('fruits',array( 'apple', 'banana', 'peach' )); F3::pop('fruits'); // returns "peach" print_r(F3::get('fruits')); /* output: Array ( [1] => apple [2] => banana ) */ {% endhighlight %}

F3::unshift( string var, mixed val ); void

Add element to the beginning of framework array variable

Usage:

{% highlight php startinline %} F3::set('fruits',array( 'apple', 'banana', 'peach' )); F3::unshift('fruits','cherry'); print_r(F3::get('fruits')); /* output: Array ( [0] => cherry [1] => apple [2] => banana [3] => peach ) */ {% endhighlight %}

F3::shift( string var ); mixed

Remove first element of framework array variable and return the element

Usage:

{% highlight php startinline %} F3::set('fruits',array( 'apple', 'banana', 'peach' )); F3::shift('fruits'); // returns "apple" print_r(F3::get('fruits')); /* output: Array ( [0] => banana [1] => peach ) */ {% endhighlight %}

Encoding & Conversion

F3::htmlencode( string string, [ bool = FALSE all ]); string

Convert special characters to HTML entities using globally-defined character set

The basic usage uses `htmlspecialchars` to convert symbols like `& " ' < >` based on your applications ENCODING (default: utf-8):

{% highlight php startinline %} echo F3::htmlencode("we want 'sugar & candy'"); // output: we <b>want</b> 'sugar & candy' {% endhighlight %}

If that's not enough, set the all argument `true`, and it will encode even more chars using `htmlentities`.

{% highlight php startinline %} echo F3::htmlencode("§9: convert symbols & umlauts like ä ü ö",true); //output: §9: convert symbols & umlauts like ä ü ö {% endhighlight %}

F3::htmldecode( string string, [ bool = FALSE all ]); string

Convert HTML entities back to their equivalent characters

{% highlight php startinline %} echo F3::htmldecode("we <b>want</b> 'sugar & candy'",true); // output: we want 'sugar & candy' {% endhighlight %}

For decoding more special chars like entities and umlauts, set the all argument to `true`.

{% highlight php startinline %} echo F3::htmldecode("§9: convert symbols & umlauts like ä ü ö",true); //output: §9: convert symbols & umlauts like ä ü ö welcome! {% endhighlight %}
Notice: It will encode your given string into the target character encoding defined in `ENCODING` var. If you don't want it in UTF-8, set another one like F3::set('ENCODING','ISO-8859-1') before encoding.

F3::fixslashes( string str ); string

Convert Windows double-backslashes to slashes; Also for referencing namespaced classes in subdirectories

F3::stringify( mixed arg ); string

Convert PHP expression/value to compressed exportable string

F3::hash( string str ); string

Generate Base36/CRC32 hash code

{% highlight php startinline %} echo F3::hash('foo bar'); //output: 1gsl6pg {% endhighlight %}

F3::hexbin( string hex ); string

Convert hexadecimal to binary-packed data

{% highlight php startinline %} echo F3::hexbin('0066006F006F006200610072'); // shortcut like 666f6f626172 is also possible //output: foobar {% endhighlight %}

F3::binhex( string bin ); string

Convert binary-packed data to hexadecimal

{% highlight php startinline %} echo F3::binhex('foobar'); //output: 666f6f626172 {% endhighlight %}

F3::bytes( string str ); int

Convert engineering-notated string to bytes

{% highlight php startinline %} // 1KB F3::bytes('1K'); // 1024 // 5MB F3::bytes('5M'); // 5242880 // 2GB F3::bytes('2G'); // 2147483648 // 1TB F3::bytes('1T'); // 1099511627776 {% endhighlight %}

F3::remix( string key ); string

Convert from JS dot notation to PHP array notation

{% highlight php startinline %} F3::remix('foo.bar'); // returns: foo['bar'] {% endhighlight %}

Routing

F3::status( string code ); false | string

Send HTTP status header. Return text equivalent of status code

F3::headers(); array

Retrieve HTTP headers

F3::expire([ int = 0 secs ]); void

Send HTTP header with expiration date ( seconds from current time )

F3::reroute( string uri ); void

Reroute to specified URI

F3::route( string pattern, mixed funcs, [ int = 0 ttl ], [ int = 0 throttle ], [ bool = TRUE hotlink ]); void

Assign handler to route pattern

F3::map( string url, string class, [ int = 0 ttl ], [ int = 0 throttle ], [ bool = TRUE hotlink ], [ string prefix]); void

Provide REST interface by mapping URL to object/class

F3::call( string funcs, [ bool = FALSE listen ]); mixed

Call route handler

F3::run(); void

Process routes based on incoming URI

Validation

F3::scrub( string input, [ string tags ]); string

Remove HTML tags ( except those enumerated ) to protect against XSS/code injection attacks

F3::input( string fields, mixed funcs, [ string = NULL tags ], [ int filter ], [ array opt ], [ bool = TRUE assign ]); void

Call form field handler

Default filter id is FILTER_UNSAFE_RAW. Other useful filter might be: FILTER_VALIDATE_EMAIL, FILTER_VALIDATE_URL, FILTER_VALIDATE_IP. To get a list of all supported filter use print_r( filter_list() );

The ops argument describes options, used by the filter, if that filter supports options.

File System

F3::send( string file, [ int = 0 kbps ], [ bool = TRUE partial ], [ bool = FALSE attach]); bool

Transmit a file for downloading by HTTP client

If kilobytes per second is specified, output is throttled ( bandwidth will not be controlled by default ).

It returns TRUE if successful, FALSE otherwise. Support for partial downloads is indicated by third argument. Download as attachment if fourth argument is TRUE

F3::getfile( string file ); string

Lock-aware file reader

F3::putfile( string file, string data, [ bool = FALSE append]); mixed

Lock-aware file writer. Returns number of bytes written or false. Use `append` arguement to just add data to the end of the file, instead of writing/overwriting the whole file.

F3::mkdir( string name, [ int = 0775 perm ], [ bool = TRUE recursive]); bool|void

Create folder; Trigger error and return FALSE if script has no permission to create folder in the specified path

Debug

F3::profile( string file ); array

Return runtime performance analytics

It contains information about memory usage, elapsed time and caching.

F3::expect( bool cond, [ string pass ], [ string fail ]); string

Perform test and append result to TEST global variable

F3::error( int code, [ string str ], [ array trace ], [ bool = FALSE fatal ]); void

Display default error page; Use custom page if found

F3::mock( string pattern, [ array = NULL args ]); void

Mock environment for command-line use and/or unit testing. It simulates an incoming HTTP request for a URL.

Misc

F3::autoload( string class ); void

Intercept instantiation of objects in undefined classes

Internal! You probably never need this method.

F3::config( string file ); void

Configure framework according to INI-style file settings Cache auto-generated PHP code to speed up execution

F3::mutex(); mixed

Execute callback as a mutual exclusion operation.

F3::instance(); object

Return instance of child class

Internal! You probably never need this method.

F3::loadstatic( string class ); void

onLoad event handler ( static class initializer )

Internal! You probably never need this method.

F3::realip(); string

Sniff headers for real IP address

F3::render( string file ); string

Render user interface

F3::resolve( mixed val ); string

Evaluate template expressions in string

F3::privateip([ string addr ]); bool

Return TRUE if IP address is local or within a private IPv4 range

F3::start(); void

Bootstrap code

F3::stop(); void

Execute shutdown function

F3::tidy( string html ); string

Clean and repair HTML

Axon

Axon->load(); object

{% highlight php startinline %} $ax = new Axon('users'); $ax->load(array('name = :name', array(':name' => 'John'))); // Axon will automatically escape quotes, type cast etc. {% endhighlight %}

Axon->save();

Saves current object values to the database. Axon decides whether to created or update the entry.

{% highlight php startinline %} $ax = new Axon('users'); $ax->name = 'John'; $ax->lastname = 'Doe'; $ax->save(); {% endhighlight %}

Axon->dry(); bool

Checks whether the Axon object is hydrated or not. Hydrated = load() / find() was successfull.

Axon->erase();

Deletes the current hydrated object from the database.

Axon->find(); object

Finds all entries depending on the condition and returns an object

Axon->afind(); array

Equal to find(), but returns an array

Axon->findone(); object

Equal to find(), but returns only the first retsult

Axon->afindone(); array

Equals to afind(), but returns only the first retsult

Axon->found(); int

found() returns the number of records found by the condition or an already issued found() / load().

Axon->reset();

Dehydrates (clears) the current object.

Axon->skip(); mixed

Equal to findone(), but you can choose the nth record.

Axon->next(); array

Returns the next record.

Axon->prev(); array

Returns the previous record.

Axon->copyFrom();

Hydrate Axon with elements from array variable.

Axon->copyTo();

Populate array variable with Axon properties.

Axon->sync();

Axon->def(); object

Axon->undef(); object

Axon->isdef(); object