.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
.. include:: ../../../Includes.txt
.. _high-priority-functions:
High priority functions
^^^^^^^^^^^^^^^^^^^^^^^
The functions listed in this table are of high priority. Generally
they provide APIs to functionality which TYPO3 should always handle in
the same way. This will help you to code TYPO3 applications with less
bugs and greater compatibility with various system conditions it will
run under.
Remember, this list only serves to point out important functions! The
real documentation is found in the source scripts (and the
`online API `_). The comments given are only a supplement to that.
.. _high-priority-functions-general-utility:
\\TYPO3\\CMS\\Core\\Utility\\GeneralUtility
"""""""""""""""""""""""""""""""""""""""""""
.. t3-field-list-table::
:header-rows: 1
- :Function,30: Function
:Comments,70: Comments
- :Function:
:code:`_GP`
:code:`\_GET`
:code:`\_POST`
:Comments:
**Getting values from GET or POST vars**
APIs for getting values in GET or POST variables with slashes stripped
regardless of PHP environment. Always use these functions instead of
direct access to :code:`$_GET` or :code:`$_POST`.
:code:`\TYPO3\CMS\Core\Utility\GeneralUtility::_GP($varname)` will give you the value of either the GET
or POST variable with priority to POST if present. This is useful if
you don't know whether a parameter is passed as GET or POST. Many
scripts will use this function to read variables during initialization::
// Setting GPvars:
$this->file = \TYPO3\CMS\Core\Utility\GeneralUtility::_GP('file');
$this->size = \TYPO3\CMS\Core\Utility\GeneralUtility::_GP('size');
:code:`\TYPO3\CMS\Core\Utility\GeneralUtility::_GET()` will give you GET vars. For security reasons you
should use this if you know your parameters are passed as GET
variables. This example gives you the whole :code:`$_GET` array::
$params = \TYPO3\CMS\Core\Utility\GeneralUtility::_GET();
:code:`\TYPO3\CMS\Core\Utility\GeneralUtility::_POST()` will give you POST variables. Works like
:code:`\TYPO3\CMS\Core\Utility\GeneralUtility::_GET()`. For security reasons you should use this if you
know your parameters are passed as POST variables.
This example gives you the content of the POST variable
TSFE\_ADMIN\_PANEL, for instance it could come from a form field like
:code:`` ::
$input = \TYPO3\CMS\Core\Utility\GeneralUtility::_POST('TSFE_ADMIN_PANEL');
- :Function:
:code:`makeInstance`
:Comments:
**Creating objects**
Factory API for creating an instance of an object given a class name. This
function makes sure the "XCLASS extension" principle can be used on
(almost) any class in TYPO3. You **must** use this method when
creating objects in TYPO3.
Examples::
// Making an instance of class "\\TYPO3\\CMS\\Core\\TypoScript\\Parser\\TypoScriptParser":
$parseObj = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance('TYPO3\\CMS\\Core\\TypoScript\\Parser\\TypoScriptParser');
// Make an object with arguments passed to the constructor:
$message = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance('TYPO3\\CMS\\Core\\Messaging\\FlashMessage',
'My message text',
'Message Header',
\TYPO3\CMS\Core\Messaging\FlashMessage::WARNING,
TRUE
);
- :Function:
:code:`getIndpEnv`
:Comments:
**Environment-safe server and environment variables.**
API function for delivery of system and environment variables on any
web-server brand and server OS. Always use this API instead of
:code:`$_ENV/$_SERVER` or :code:`getenv()` if possible.
Examples::
if (\TYPO3\CMS\Core\Utility\GeneralUtility::getIndpEnv('HTTP_ACCEPT_LANGUAGE') == $test)...
if (\TYPO3\CMS\Core\Utility\GeneralUtility::cmpIP(\TYPO3\CMS\Core\Utility\GeneralUtility::getIndpEnv('REMOTE_ADDR'), $pcs[1]))...
$prefix = \TYPO3\CMS\Core\Utility\GeneralUtility::getIndpEnv('TYPO3_REQUEST_URL');
$redirectTo = \TYPO3\CMS\Core\Utility\GeneralUtility::getIndpEnv('TYPO3_SITE_URL').$redirectTo;
if (!\TYPO3\CMS\Core\Utility\GeneralUtility::getIndpEnv('TYPO3_SSL')) ...
- :Function:
:code:`getFileAbsFileName`
:code:`validPathStr`
:code:`isAbsPath`
:code:`isAllowedAbsPath`
:code:`fixWindowsFilePath`
:Comments:
**Evaluate files and directories for security reasons**
When you allow references to files to be input from users there is
always the risk that they try to cheat the system to include something
else than intended. These functions makes it easy for you to evaluate
filenames for validity before reading, writing or including them.
Here the functions are described in order of importance:
:code:`\TYPO3\CMS\Core\Utility\GeneralUtility::getFileAbsFileName()` - Returns the absolute filename
of a relative reference, resolves the "EXT:" prefix (way of referring
to files inside extensions) and checks that the file is inside the
:code:`PATH_site` of the TYPO3 installation and implies a check with
:code:`\TYPO3\CMS\Core\Utility\GeneralUtility::validPathStr()`. Returns false if checks failed. Does not
check if the file exists. ::
// Getting absolute path of a temporary file
$cacheFile = \TYPO3\CMS\Core\Utility\GeneralUtility::getFileAbsFileName('typo3temp/tempfile.tmp');
// Include file if it exists:
$file = \TYPO3\CMS\Core\Utility\GeneralUtility::getFileAbsFileName($fileRef);
if (@is_file($file)) {
include($file);
}
:code:`\TYPO3\CMS\Core\Utility\GeneralUtility::validPathStr()` - Checks for malicious file paths.
Returns true if no '//', '..' or '\\' is in the $theFile. This should
make sure that the path is not pointing 'backwards' and further
doesn't contain double/back slashes. ::
// If the path is true and validates as a valid path string
if ($path && \TYPO3\CMS\Core\Utility\GeneralUtility::validPathStr($path)) {
...
}
:code:`\TYPO3\CMS\Core\Utility\GeneralUtility::isAbsPath()` - Checks if the input path is absolute or
relative (detecting either '/' or 'x:/' as first part of string) and
returns true if so. ::
// Returns relative filename for icon:
if (\TYPO3\CMS\Core\Utility\GeneralUtility::isAbsPath($Ifilename)) {
$Ifilename = '../' . substr($Ifilename, strlen(PATH_site));
}
:code:`\TYPO3\CMS\Core\Utility\GeneralUtility::isAllowedAbsPath()` - Returns true if the path is
absolute, without backpath '..' and within the :code:`PATH_site` OR within
the :code:`lockRootPath`. Contrary to :code:`\TYPO3\CMS\Core\Utility\GeneralUtility::getFileAbsFileName()` this
function can also validate files in filemounts outside the web-root of
the installation, but this is rarely used! ::
if (@file_exists($path) && \TYPO3\CMS\Core\Utility\GeneralUtility::isAllowedAbsPath($path)) {
$fI = pathinfo($path);
....
:code:`\TYPO3\CMS\Core\Utility\GeneralUtility::fixWindowsFilePath()` - Fixes a path for Windows-
backslashes and reduces double-slashes to single slashes
- :Function:
:code:`mkdir`
:Comments:
**Creates directory**
One would think that creating directories is one thing you can do
directly with PHP. Well, it turns out to be quite error-prone if it
should be compatible with Windows servers and safe-mode at the same
time. So TYPO3 offers a substitution function you should always use.
Example::
$root.=$dirParts . '/';
if (!is_dir($extDirPath . $root)) {
\TYPO3\CMS\Core\Utility\GeneralUtility::mkdir($extDirPath . $root);
if (!@is_dir($extDirPath . $root)) {
return 'Error: The directory "' .
$extDirPath . $root .
'" could not be created...';
}
}
- :Function:
:code:`upload_to_tempfile`
:code:`unlink_tempfile`
:code:`tempnam`
:Comments:
**Functions for handling uploads and temporary files**
You need to use these functions for managing uploaded files you want
to access as well as creating temporary files within the same session.
These functions are safe\_mode and open\_basedir compatible which is
the main point of you using them!
:code:`\TYPO3\CMS\Core\Utility\GeneralUtility::upload_to_tempfile()` - Will move an uploaded file
(normally in "/tmp/xxxxx") to a temporary filename in
:code:`PATH\_site . 'typo3temp/'`.
Remember to use :code:`\TYPO3\CMS\Core\Utility\GeneralUtility::unlink_tempfile()` afterwards - otherwise
temp-files will build up! They are *not* automatically deleted in
:code:`PATH\_site . 'typo3temp/'`!
:code:`\TYPO3\CMS\Core\Utility\GeneralUtility::unlink_tempfile()` - Deletes (unlink) a temporary
filename in :code:`PATH\_site . 'typo3temp/'` given as input. The function
will check that the file exists, is in :code:`PATH_site . 'typo3temp/'` and
does not contain back-spaces ("../") so it should be pretty safe. Use
this after :code:`upload_to_tempfile()` or :code:`tempnam()` from this class!
This example shows how to handle an uploaded file you just want to
read and then delete again::
// Read uploaded file:
$uploadedTempFile = \TYPO3\CMS\Core\Utility\GeneralUtility::upload_to_tempfile(
$_FILES['upload_ext_file']['tmp_name']
);
$fileContent = \TYPO3\CMS\Core\Utility\GeneralUtility::getUrl($uploadedTempFile);
\TYPO3\CMS\Core\Utility\GeneralUtility::unlink_tempfile($uploadedTempFile);
:code:`\TYPO3\CMS\Core\Utility\GeneralUtility::tempnam()` - Create temporary filename (creates file
with unique file name). This function should be used for getting
temporary filenames - will make your applications safe for
"open\_basedir = on". Remember to delete the temporary files after
use! This is done by :code:`\TYPO3\CMS\Core\Utility\GeneralUtility::unlink_tempfile()`.
In the following example it is shown how two temporary filenames are
created for being processed with an external program (diff) after
which they are deleted again::
// Create file 1 and write string
$file1 = \TYPO3\CMS\Core\Utility\GeneralUtility::tempnam('diff1_');
\TYPO3\CMS\Core\Utility\GeneralUtility::writeFile($file1, $str1);
// Create file 2 and write string
$file2 = \TYPO3\CMS\Core\Utility\GeneralUtility::tempnam('diff2_');
\TYPO3\CMS\Core\Utility\GeneralUtility::writeFile($file2, $str2);
// Perform diff.
$cmd = $GLOBALS['TYPO3_CONF_VARS']['BE']['diff_path'].
' '.$this->diffOptions . ' ' . $file1 . ' ' . $file2;
exec($cmd, $res);
unlink($file1);
unlink($file2);
- :Function:
:code:`fixed_lgd_cs`
:Comments:
**Truncating a string for visual display, observing the character set
(backend only)**
This function allows you to truncate a string from e.g. "Hello World"
to "Hello Wo..." so for example very long titles of records etc. will
not break the visual appearance of your backend modules.
Since text strings cannot be cropped at any byte if the character set
is utf-8 or another multibyte charset this function will process the
string assuming the character set to be the one used in the backend.
It is recommended to use $BE\_USER->uc['titleLen'] for the length
parameter. ::
// Limits Record title to 30 chars
\TYPO3\CMS\Core\Utility\GeneralUtility::fixed_lgd_cs($thisRecTitle, 30);
// Limits string to title-length configured for backend user:
$title = \TYPO3\CMS\Core\Utility\GeneralUtility::fixed_lgd_cs(
$row['title'],
$this->BE_USER->uc['titleLen']
);
- :Function:
:code:`formatForTextarea`
:Comments:
**Preparing a string for output between