Core Documentation

Here you will find the new official reference manuals. These documents are related to the core of TYPO3 and address the built in functionality of TYPO3. They are designed to provide you with in-depth information.

Old Core Documentation


1.3. Variables and Constants

Naming convensions

  1. Global variables should be named in uppercase.

  2. Variables with a large scope should have long names, variables with a small scope can have short names. Temporary variables are best kept short. Someone reading such variables should be able to assume that its value is not used outside a few lines of code.

  3. Common temporary variables are $i, $j, $k, $m and $n. Since these variables should have small scope prefixes are a bit of overkill.

Global variables, constants and input values

  1. Always access GET and POST vars by a TYPO3 API function (and directly through HTTP_GET_VARS or $_GET or the same for POST)

    1. t3lib_div::_GET() : will return the current global HTTP_GET_VARS (unescaped recursively)

    2. t3lib_div::_POST() : will return the current global HTTP_POST_VARS (unescaped recursively)

    3. t3lib_div::_GP($var) : will return a POST or GET var by name $var, with priority to POST (unescaped recursively)

  1. If you need to set a value in HTTP_GET_VARS globally, always use t3lib_div::_GETset() to write back the HTTP_GET_VARS array (will set both HTTP_GET_VARS and the superglobal $_GET)

  2. If you access values directly in HTTP_GET_VARS/HTTP_POST_VARS you MUST only do so if your code acts if there are no slashes on the values! (It is not allowed to check magic_quotes settings since TYPO3 will normalize the arrays no matter what!)

  3. It is also acceptable to use HTTP_GET_VARS and HTTP_POST_VARS directly if you use such as isset() to check whether a value is set.

  4. If possible, group requests after input variables in an init() function of your classes - thus it is clear to see what external input your application expects. (There are multiple examples in the core of the init() function loading all input variables into internal vars of the class by a series of t3lib_div::_GP() function calls!)

  1. Do NOT expect in your scripts that input from outside is found in the global vars. It's recommended to use the php.ini-optimized with TYPO3 and that means that the content of HTTP_POST/GET_VARS is NOT transferred to the global name-space.

t3lib_div::_GET(), t3lib_div::_POST() and t3lib_div::_GP() always return a value which is unescaped regardless of PHP settings for magic_quotes. (This is one reason to use them!)

Example:

Correct:

$myName = t3lib_div::_GP('myname');
or
$myName = t3lib_div::_GET('myname');
or
$myName = t3lib_div::_POST('myname');

Wrong:

$myName = $GLOBALS['myname'];
or
$myName = $GLOBALS['HTTP_POST_VARS']['myname'];

  1. Generally keep variables safe inside of classes in whatever work you do with TYPO3.

  1. Use a namespace for your GET and POST variables in extensions:If you want to make a form-field with the email address, name it:

    <input name="tx_myext[email]"> or <input name="tx_myext[DATA][email]">

    Apply the same principles of naming on GET vars as well. You can retrieve that array by a simple function call to t3lib_div::_GP('tx_myext'); or t3lib_div::_GET('tx_myext'); Please see the Extension API and tutorials in this regard for more guidelines.

Notice: For a list of global variables and constants available in the TYPO3 core see the document "TYPO3 Core API"!

System/PHP Variables - the nightmare

In any case you want to use any of the system variables below, please DO NOT use getenv(), preferably not HTTP_SERVER_VARS either, but call the API function t3lib_div::getIndpEnv().

Follow these guidelines:

  1. Never use getenv()

  2. Always use the t3lib_div::getIndpEnv() function if you can. You can depend on those values, that they will work on any platform TYPO3 supports.

  3. If you really need a variable from HTTP_SERVER_VARS for some reason, you can most likely do so. You may then help us testing the availability of this variable on a variety of systems and suggest to include it as a key in t3lib_div::getIndpEnv().

The whole point of this is to have an “abstraction method” for returning these values regardless of TYPO3 running on a UNIX or WINDOWS server, Apache or ISS, CGI or module.  Some of these variables are different from system to system, some does not even exist on some servers, some are swapped around depending on SAPI-type and the story goes on. The declared target of this function, t3lib_div::getIndpEnv(), is to deliver a system independant value which you can always trust to be correct. If its not, we are going to fix it.

Many, many reported bugs in TYPO3 has been due to these variables returning different values. People have then tried to fix it and found a fix which works on their system, but which would break another system. Therefore this function is really necessary. And unfortunately changing it for a certain non-supported setup can only be done with extensive testing afterwards - we don't want to break TYPO3 on systems that do work!

If you need a system variable which is not listed below, please investigate the cross-platform/cross-webserver availability and suggest an addition.

Please see the documentation inside the t3lib_div::getIndpEnv() function for the most up-to-date information.

t3lib_div::getIndpEnv()

 

First some definition of terms:

output from parse_url():

URL:http://username:password@192.168.1.4:8080/typo3/32/temp/phpcheck/index.php/arg1/arg2/arg3/?arg1,arg2,arg3&p1=parameter1&p2[key]=value#link1

    [scheme] => 'http'

    [user] => 'username'

    [pass] => 'password'

    [host] => '192.168.1.4'

[port] => '8080'

    [path] => '/typo3/32/temp/phpcheck/index.php/arg1/arg2/arg3/'

    [query] => 'arg1,arg2,arg3&p1=parameter1&p2[key]=value'

    [fragment] => 'link1'

Further definition: [path_script] = '/typo3/32/temp/phpcheck/index.php'

[path_dir] = '/typo3/32/temp/phpcheck/'

[path_info] = '/arg1/arg2/arg3/'

[path] = [path_script/path_dir][path_info]

 

URI:

 

SCRIPT_NAME

[path_script]++= /typo3/32/temp/phpcheck/index.php

NOTICE THAT SCRIPT_NAME will return the php-script name ALSO. [path_script] may not do that (eg. "/somedir/" may result in SCRIPT_NAME "/somedir/index.php")!

PATH_INFO

[path_info] = /arg1/arg2/arg3/

(Does not work with CGI-versions AFAIK)

HTTP_HOST

[host][:[port]] = 192.168.1.4:8080

REQUEST_URI

[path]?[query] = /typo3/32/temp/phpcheck/index.php/arg1/arg2/arg3/?arg1,arg2,arg3&p1=parameter1&p2[key]=value

Suggestion. This is very usefull to make self-referencing URLs or “returnUrl”'s in scripts! Eg in a parameter string:

returnUrl=".rawurlencode(t3lib_div::getIndpEnv("REQUEST_URI"))

QUERY_STRING

[query]= arg1,arg2,arg3&p1=parameter1&p2[key]=value

HTTP_REFERER

[scheme]://[host][:[port]][path]= http://192.168.1.4:8080/typo3/32/temp/phpcheck/index.php/arg1/arg2/arg3/?arg1,arg2,arg3&p1=parameter1&p2[key]=value

CLIENT:

 

REMOTE_ADDR

(client IP)

REMOTE_HOST

(client host)

HTTP_USER_AGENT

(client user agent)

HTTP_ACCEPT_LANGUAGE

(client accept language)

SERVER:

 

SCRIPT_FILENAME

Absolute filename of script(Differs between windows/unix). On windows "C:\\blabla\\blabl\\" will be converted to "C:/blabla/blabl/"

DOCUMENT_ROOT

Absolute path of root of documents:DOCUMENT_ROOT.SCRIPT_NAME = SCRIPT_FILENAME

Special TYPO3 extras:

 

TYPO3_HOST_ONLY

[host]= 192.168.1.4

TYPO3_PORT

[port]= 8080 (blank if 80, taken from host value)

TYPO3_REQUEST_URL

[scheme]://[host][:[port]][path]?[query](sheme will by default be "http" until we can detect if it's https -

TYPO3_REQUEST_SCRIPT

[scheme]://[host][:[port]][path_script]

TYPO3_REQUEST_DIR

[scheme]://[host][:[port]][path_dir]

TYPO3_SITE_URL

[scheme]://[host][:[port]][path_dir] of the TYPO3 websites root