edit

Quick Reference

System Variables

To use these variables, simply get them from the $f3 object, as in:

$current_url = $f3->get('PATH');

AGENT

Type: string, Read-only

A string containing the auto-detected HTTP user agent, e.g. 'Mozilla/5.0 (Linux; Android 4.2.2; Nexus 7) AppleWebKit/537.31'

AJAX

Type: bool, Read-only

TRUE if an XML HTTP request is detected, FALSE otherwise. Default value: Result of the expression $headers['X-Requested-With']=='XMLHttpRequest'

ALIAS

Type: string

Contains the alias (name) of the current route. Empty if the current route is not named.

ALIASES

Type: array

This array contains all named routes which can be used to render the appropriate link urls in your templates.

AUTOLOAD

Type: string|array     Default: './'

Search path(**s**) for user-defined PHP classes that the framework will attempt to autoload at runtime. When specifying multiple paths, you can use a pipe (|), comma (,), or semi-colon (;) as path separator.

REMEMBER: paths must end with a slash. E.g: $f3->set('AUTOLOAD', 'app/;inc/,./');

See here for more details.

BEWARE: if you define this variable in a config file, remember that commas have a special meaning (array separator).
So the following syntaxes are valid:
  • AUTOLOAD = foo/;bar/,Customer::casehandler
  • AUTOLOAD = foo/;bar/
  • AUTOLOAD = foo/|bar/
  • AUTOLOAD = "foo/,bar/"
while AUTOLOAD = foo/,bar/ is not.

BASE

Type: string, Read-only     Default: auto-detected

Path to the index.php main/front controller.

BODY

Type: string, Read-only

HTTP request body for ReSTful post-processing. Contains the php://input stream used by PUT requests, if RAW is false.

CACHE

Type: bool|string     Default: FALSE

Cache backend. F3 can handle Memcache module, APC, WinCache, XCache and a filesystem-based cache.

For example: if you'd like to use the memcache module, a configuration string is required, e.g. $f3->set('CACHE','memcache=localhost') (port 11211 by default) or $f3->set('CACHE','memcache=192.168.72.72:11212').

When set to TRUE, or when the connection with the specified memcached server above failed, F3 will auto-detect, in that order, the presence of APC, WinCache, XCache and use the first available of these PHP module. If none of these shared memory engine has been detected or is available, a filesystem-based backend is used as a fallback (default directory: tmp/cache or you can specify a folder outside the scope of the website, e.g. $f3->set('CACHE','folder=/var/tmp/f3filescache/').

The framework doesn't use any cache engine when a FALSE value is assigned.

CASELESS

Type: bool     Default: TRUE

Pattern matching of routes against incoming URIs is case-insensitive by default. Set to FALSE to make it case-sensitive.

COOKIE, GET, POST, REQUEST, SESSION, FILES, SERVER, ENV

Type: array

Framework equivalents of PHP globals. For your convenience, F3 automatically synchronizes these variables with the underlying PHP globals. These variables may be used throughout an application. However, direct use in templates is not advised due to security risks.

It could be possible that the PHP configuration is not populating all globals. If for instance the environment variables are missing, then you have to add E to the PHP configuration directive variables_order.

CORS

Type: array

Cross-Origin Resource Sharing configuration parameters. Consists of the following options:

  • headers, string or array, default: '', allowed headers in the request
  • origin, string or false, default: false, allowed origin host, i.e *.mydomain.com
  • credentials bool, default: false, allow cookies
  • expose, string or array, default: false, controls which headers from the response are exposed to the client browser
  • ttl, int, detault: 0, caching time of the preflight OPTIONS request

To enable basic CORS support, just set CORS.origin to *. For a more defined setup, you can use $f3->copy('HEADERS.Origin','CORS.origin');.

DEBUG

Type: integer     Default: 0

Verbosity level of the stack trace. Assign values between 0 to 3 for increasing verbosity levels as follow:

  • 0 : suppresses logs of the stack trace.
  • 1 : logs files & lines.
  • 2 : logs classes & functions as well.
  • 3 : logs detailed infos of the objects as well.
Notice: Only the default value of 0 should be used on production servers.

DIACRITICS

Type: array     Default: array(), empty array

Additional key-value pairs for foreign-to-ASCII character translations.

DNSBL

Type: string     Default: '', empty string

Comma-separated list of DNS blacklist servers. Framework generates a 403 Forbidden error if the user's IPv4 address is listed on the specified server(s).

EMOJI

Type: array     Default: array(), empty array

Additional key-value pairs of emoji tokens to add to the basic set used when translating a string to Unicode font-supported symbols. (see \UTF->emojify())

ENCODING

Type: string     Default: 'UTF-8'

Character set used for document encoding.

ERROR

Type: array, Read-Only

Information about the last HTTP error that occurred:

  • ERROR.code is the HTTP status code. e.g. 307
  • ERROR.status is a brief description of the HTTP status code. e.g. 'Temporary Redirect'
  • ERROR.text contains a brief description of the error.
  • ERROR.trace is used for HTTP 500 errors, to retrieve the stack trace. array()

ESCAPE

Type: bool     Default: TRUE

Used to enable/disable auto-escaping @tokens used in templates.

EXEMPT

Type: string     Default: NULL

Comma-separated list of IPv4 addresses to exempt from DNSBL lookups.

EXCEPTION

Type: object     Default: NULL

Contains the exception object when unhandled exceptions occur.

FALLBACK

Type: string     Default: 'en'

Language (and dictionary) to use if no translation is available.

FRAGMENT

Type: string     Default: NULL

Portion of the URI after the optional hash (#) symbol (http://www.example.org/foo.html#bar) FRAGMENT = 'bar'.

HALT

Type: bool     Default: TRUE

If TRUE, the framework, after having logged stack trace and errors, stops execution (die without any status) when a non-fatal error is detected.

HEADERS

Type: array,Read-Only

HTTP request headers received by the server. e.g. (simplified)

array (
	'Host' => 'fatfreeframework.com'
	'Accept-Encoding' => 'gzip,deflate,sdch',
	'Accept-Language' => 'en-US,en;q=0.8,ja;q=0.6'
)

HIGHLIGHT

Type: bool     Default: TRUE

Enable/disable syntax highlighting of stack traces and Markdown code blocks. When enabled, requires code.css stylesheet.

HOST

Type: string,Read-Only

Server host name.

IP

Type: string,Read-Only

Remote IP address. The framework derives the address from headers if HTTP client is behind a proxy server. Default value: First match of Client-IP then X-Forwarded-For then $_SERVER['REMOTE_ADDR'], otherwise set to ''

JAR

Type: array

Default cookie parameters. Consists of the following options:

  • expire Unix timestamp, when the cookie should expire. Default: 0
  • path The path on the server in which the cookie will be available. Default: '/'
  • domain The domain that the cookie is available to. Default: $_SERVER['SERVER_NAME'] if available, else ''
  • secure Set the cookie when a secure HTTPS connection exists. Default: $_SERVER['HTTPS']=='on'
  • httponly Make the cookie accessible only through the HTTP protocol. Default: TRUE

You can refer to session_set_cookie_params() in the PHP Manual for more information.

You can also watch a video that goes over using cookies in the Fat-Free Framework.

LANGUAGE

Type: string     Default: auto-detected

Current active language(s). Value is used to load the appropriate language(s) translation file(s) in the folder pointed to by LOCALES. Default: auto-detected from the HTTP Accept-Language request header, e.g. 'en-US,en,es'.

NB: The system locale is loaded accordingly to this variable. E.g:

$f3->set('ENCODING','UTF-8');
$f3->set('LANGUAGE','it-IT');// the locale it_IT.UTF-8 will be automatically loaded using setlocale

See the Localisation section in Base for more details and an example.

LOCALES

Type: string     Default: './'

Location of the language(s) dictionaries.

LOGS

Type: string     Default: './'

Location of custom logs.

ONERROR

Type: mixed     Default: NULL

Callback function to use as custom error handler, or NULL.

Notice: If no callback function is specified, a default error page is generated (HTML5 for synchronous requests, JSON string for AJAX requests).

ONREROUTE

Type: mixed     Default: NULL

Callback function that is called before redirect headers are send. The default behavior (301/302 redirection) will be bypassed unless FALSE is returned.

$f3->set('ONREROUTE',function($url,$permanent){
  // do something
});
$f3->reroute('/foo?bar=baz');

PACKAGE

Type: string     Default: 'Fat-Free Framework'

A string containing the name of the Framework.

PARAMS

Type: array     Default: array()

Captured values of tokens defined in a route() pattern. PARAMS[0] contains the captured URL relative to the Web root.

PATH

Type: string, Read-Only

The URL relative to BASE. Default value: parse_url($_SERVER['REQUEST_URI'],PHP_URL_PATH)

PATTERN

Type: string, Read-Only

Contains the routing pattern that matches the current request URI.

PLUGINS

Type: string     Default: __DIR__.'/'

Location of F3 plugins. The default value is the folder where the framework code resides, i.e. the path to base.php.

PORT

Type: integer, Read-Only

TCP/IP listening port used by the Web server. Default value: $_SERVER['SERVER_PORT'] or NULL if not available.

PREFIX

Type: string     Default: NULL

Prefix to use with LANGUAGE and LOCALES.

For example, if your dictionary file contains hello = Hello World, the term will be accessible via:

  • $f3->get('hello') without prefix
  • $f3->get('DICT.hello') if PREFIX=DICT.
IMPORTANT: this variable should be set before LANGUAGE and LOCALES.

PREMAP

Type: string     Default: '', empty string

This variable allows mapped route handlers to be prefixed. For example, defining:

$f3->PREMAP = 'action_';
$f3->map('/item','Item');

is the same as defining:

$f3->route('GET /item','Item->action_get');
$f3->route('POST /item','Item->action_post');
$f3->route('PATCH /item','Item->action_patch');
$f3->route('PUT /item','Item->action_put');
$f3->route('DELETE /item','Item->action_delete');

QUERY

Type: string, Read-Only

Contains the request URI query string (all after the question mark ?).

QUIET

Type: bool     Default: FALSE

Toggle switch for suppressing or enabling standard output and error messages. Particularly useful in unit testing.

RAW

Type: bool     Default: FALSE

RAW should be TRUE when processing large data coming from php://input which will not fit in memory (cf. BODY).

REALM

Type: string, Read-Only

Full canonical URL. Default value: Result of 'http(s)://'.$_SERVER['SERVER_NAME'].$_SERVER['REQUEST_URI']

RESPONSE

Type: string, Read-Only

The body of the last HTTP response. F3 populates this variable regardless of the QUIET setting.

ROOT

Type: string, Read-Only

Absolute path to document root folder.

ROUTES

Type: array     Default: array()

Contains the defined application routes.

Notice: A route is more than just a URL. It's an HTTP verb (or verbs) and an URL.

SCHEME

Type: string, Read-Only

Server protocol. Default: 'http' or 'https'

SERIALIZER

Type: string     Default: auto-detected

The default serializer used by the Base->serialize() method. Default value: igbinary if available, otherwise php.

TEMP

Type: string     Default: 'tmp/'

Temporary folder for cache, filesystem locks, compiled F3 templates, etc. The default value is the 'tmp/' folder inside the Web root. Adjust accordingly to conform to your site's security policies.

When you're using Google App Engine (GAE) to deploy your application, it's recommended to set it to the in-memory file-system with $f3->set('TEMP', sys_get_temp_dir()).

TIME

Type: float     Default: auto-detected

Starting time of the framework. Default value: The current Unix time in seconds accurate to the nearest microsecond as per the PHP function microtime(**TRUE**).

TZ

Type: string     Default: auto-detected

Timezone to use. Changing this value automatically calls the underlying PHP function date_default_timezone_set(). See the list of supported timezones to get a possible value to use here. Falls back to 'UTC' if auto-detection fails.

UI

Type: string     Default: './'

Search path for user interface files used by the View and Template classes' render() method.
Accepts a pipe (|), comma (,), or semi-colon (;) as separator for multiple paths.

UNLOAD

Type: callback     Default: NULL

Defines the shutdown handler the framework will execute on application shutdown.

UPLOADS

Type: string     Default: './'

Directory where file uploads are saved.

URI

Type: string     Default: auto-detected

A reference to the current HTTP request URI.

VERB

Type: string     Default: auto-detected

A reference to the current HTTP request method.

VERSION

Type: string     Default: e.g. '3.2.1-Release'

A string containing the version of the Framework.

XFRAME

Type: string     Default: e.g. 'SAMEORIGIN'

Used to set the X-Frame-Options header.

Template Directives

Token

  • @token

    Replace @token with the value of the equivalent F3 variable.

  • {{ mixed expr }}

    Evaluate expression expr. Expression can include template tokens, constants, operators (unary, arithmetic, ternary and relational), parentheses, data type converters, and functions. If not an attribute of a template directive, the result is echo'ed.

  • {{ string expr | esc }}

    Render expression expr escaped. This is the default framework behavior. The | esc suffix is only necessary if the ESCAPE global variable has been set to FALSE.

  • {{ string expr | raw }}

    Render expression expr unescaped. As F3 auto-escapes string tokens by default, you can use this suffix to by-pass the escaping of a particular token.

  • {{ string expr, arg0, …, argN | format }}

    Render the expression expr in ICU-format and pass the comma-separated arguments, where arg0, …, argN is used in expr as reference, each with an optional formatter that can be one of: 'date', 'time', 'number' or 'plural' (additional formatter options possible). Have a look at the format method for more usage examples. More information about ICU formatting of Numbers, Currencies, Dates and Times. Sample: {{'date: {0,date} - time: {0,time} - price: {1,number,currency}',time(),@price | format}}

  • {{ string name, args | alias }}

    builds an URL of a named route, i.e: {{ @name, 'a=5,b='.@id | alias }}

  • {~ string expr ~}

    Evaluate expression expr, similar to {{expr}} but does not echo the result.

  • {* text-block *}

    Exclude a segment of your template. Alias to <exclude>

  • {- {{@BASE}} -}

    Ignore all tokens within {- -} expression and print them as they are.

Include

<include [ if="{{ bool condition }}" ] href="{{ string subtemplate }}" [ with="{{ string additional_variables }}" ] />

Get contents of subtemplate and insert at current position in template [ if optional condition is true ].

The current data hive is passed to the subtemplate, enriched with additional_variables if provided (see here for examples).

Exclude

<exclude>text-block</exclude>

Exclude text-block at runtime. Used for embedding comments in templates. An Alias for this is:

{* text-block *}

Ignore

<ignore>text-block</ignore>

Display text-block as it is, without any interpretation/modification by the template engine.

Check

<check if="{{ bool condition }}">
    <true>true-block</true>
    <false>false-block</false>
</check>

Evaluate condition. If TRUE, the true-block is rendered; else the false-block is rendered.

Short form: If you don't need and don't specify a false block, then, for your convenience, F3 makes the opening and closing tags for true optional:

<check if="{{ @debugmode && @showtrace }}"><code>{{ @showtrace }}</code></check>

Loop

<loop from="{{ statement }}" to="{{ bool expr }}" [ step="{{ statement }}" ]>
    text-block
</loop>

Evaluate from statement once. Check if the expression in the to attribute is TRUE, render text-block and evaluate step statement. Repeat iteration until to expression is FALSE.

Example:

<loop from="{{ @i=0 }}" to="{{ @i < count(@bar) }}" step="{{ @i++ }}">

</loop>

Repeat

<repeat group="{{ array @group|expr }}" [ key="{{ scalar @key }}" ] value="{{ mixed @value }} [ counter="{{ scalar @key }}" ]>
    text-block
</repeat>

Repeat text-block as many times as there are elements in the array variable @group or the expression expr. @key and @value function in the same manner as the key-value pair in the equivalent PHP foreach() statement. Variable represented by key in counter attribute increments by 1 with every iteration.

Switch

<switch expr="{{ scalar expr }}">
    <case value="{{ scalar @value|expr }}" break="{{ bool TRUE|FALSE }}">
        text-block
    </case>
    .
    .
    .
    <default>
        message
    </default>
</switch>

Equivalent of the PHP switch-case jump table structure.

Set

<!-- set some variables -->
<set foo="{{ 1+2 }}" bar="{{ @foo+3 }}" baz="xyz" />
<!-- set an array -->
<set myarray="{{ array('a','b','c') }}" />

Used to set some variables dynamically within the template.