TYPO3 Extension Development:

t3lib stands for "TYPO3 library". This name is historical, and everyone just calls it t3lib (tee-three-lib). t3lib is the largest collection of classes in TYPO3. It includes most Common, FE, and BE classes. It is easy to say that a class belongs to t3lib by looking at its name. Here are some examples:

We will look at some t3lib classes later in this chapter.

tslib stands for "TypoScript Library", The name has historical reasons as well and everyone calls this library tslib (tee-es-lib). It is located in the typo3/sysext/cms/tslib directory (inside the cms system extension). Most of these classes are already included when code runs in FE. So there is no need to include them explicitly in extensions.

The library classes are responsible for the rendering of the website and most of the FE logic. The base class for FE plugins (modules that extend TYPO3 Frontend functionality) is also located here.

We will discuss tslib classes in the Frontend API section.

Here is a list of some classes in tslib:

This namespace is reserved for extensions ("tx" stands for "TYPO3 Extensions"). All extension classes must begin with tx_ (with the exception of "ux" classes).

This namespace is reserved for XCLASSes. XCLASS is a way to subclass a class in TYPO3 and make use of the subclass instead of the parent class in a way that is transparent to all the other classes in the system. Normally, XCLASSes are provided by extensions. XCLASSes take the class and file name of the parent class but prepend it with ux_, as in class.ux_tslib_fe.php or class.ux_t3lib_tcemain.php.

While XCLASSes may seem the easiest way to modify system behavior, they should be avoided and used only if there is absolutely no other way to change system behavior. The fundamental limitations of XCLASSes is that there can be only one XCLASS for a given class in the system. If two extensions try to XCLASS the same class, only the last one will succeed.

This namespace is reserved for PHP functions outside of a class. TYPO3 will refuse to call any function outside of a class that is not prefixed with user_. If an extension key has this prefix, it means that the extension is private. Such extensions cannot be sent to the TYPO3 Extension Repository. Typically, such extensions are created for testing purposes.

Database API is the most independent class of all the TYPO3 API classes. It contains functions to manipulate data in the MySQL database. The class name is t3lib_DB. There is no TYPO3-specific functionality, only a set of convenient methods to access the database. The instance of this class is available, both in FE and BE, as $GLOBALS['TYPO3_DB'].

All core classes and all extensions must work with the TYPO3 database by using t3lib_DB. This ensures that the database is accessed correctly. Using MySQL PHP functions directly is strongly discouraged and may, in certain cases, interfere with TYPO3 database access, or even break the TYPO3 database.

Besides convenient methods, t3lib_DB has another purpose. Since this is an API class, it can be XCLASSed to provide access to other databases transparent to the rest of TYPO3. This is what the extension DBAL does.

Here is an example of how the TYPO3 database can be accessed using t3lib_DB:

// Select number of non-deleted pages
$res = $GLOBALS['TYPO3_DB']->exec_SELECTquery(
'COUNT(*) AS t', 'pages',
'deleted=0');
if ($res !== false) {
// Fetch array with data
$row = $GLOBALS['TYPO3_DB']->sql_fetch_assoc($res);
if ($row !== false) {
$numberOfDeletedPages = $row['t'];
}
// Free resultset (or memory leak will happen)
$GLOBALS['TYPO3_DB']->sql_free_result($res);
}

As you can see, these functions look very similar to MySQL PHP functions. This similarity is not accidental. The default database for TYPO3 is MySQL, and the database API is modeled using MySQL PHP functions.

Generally, all functions can be divided into several groups.

The first group consists of functions that generate various SQL queries. Functions accept certain parameters (such as field names, table name, SQL WHERE condition, and so on) and return a properly constructed SQL query. This is good for extensions that need compatibility with different database types. However, it should be noted that these functions cannot always be used, especially if the query is complex, such as with SQL JOIN constructs, and so on. Functions in this group are:

The next group is similar to the first group. It consists of functions that build and execute queries. Most functions in this group are built around functions belonging to the first group. Here you may ask a question: why does the first group exist then? The answer is simple. Sometimes, you want to get a query first, log it somewhere, and then execute it. In that case, you may want to use functions from the first group.

Here is a list of functions from the second group:

The last three functions may raise questions. Two of them are rarely used. The exec_SELECT_mm_query function is a TYPO3 way to execute a query on tables with many-to-many relations. The exec_SELECT_queryArray function executes a SELECT SQL query, taking parameters from the passed array. This function is rarely used. The last one will perform a SELECT SQL query, fetch rows, and return them in an array. This function should be used with caution; if the result is big, it may exhaust PHP memory easily. But for some results, it is the most convenient way to fetch data from the database.

The next group includes functions to fetch the result, get the number of rows, and so on. They are identical to the corresponding MySQL PHP functions. They are so trivial that we will not discuss them much, only list them here for the sake of completeness:

One important note for extension authors: do not forget to call the sql_free_result() function! Though the PHP manual says that MySQL resources are automatically released when the script terminates, in practice, this does not always happen (especially, if persistent connections are enabled). Moreover, if DBAL is enabled, automatic freeing of resources may not always work. It is always better to clean them up in the code.

The last group of functions are the utility functions. While we are looking at it as the last group, functions in this group are used (or must be used) all the time. This group includes functions to escape database parameters and to do query manipulation. Here is a list:

The fullQuoteStr() function is possibly the most used (or again—the most "must-be-used") function in this group. It escapes all special characters in the string and additionally wraps the string in quotes in a manner compatible with the current database. Therefore, extension developers should use this function for both escaping and quoting parameters, and not use any "home-made" solution. This is a good security-related function. Other functions do more or less the same but in more specialized way. The "strip" and "split" functions are specific for some TYPO3 core calls (but can be called by extensions too).

Now, we are ready to see more complex examples of database API functions. Notice that this example is focused on the database API only. You should not use this code in the extension because it lacks certain calls to other APIs, is not effective from the point of view of database performance, and uses echo (TYPO3 uses other ways of showing generated content). But this example gives a good idea of how to use the database API.

/**
* Retrieves all news written by the given author
*
* @param string $authorName Author name
* @return array A list of news items for author
*/
function findNewsByAuthor($authorName) {
$res = $GLOBALS['TYPO3_DB']->exec_SELECTquery('uid,title', 'tt_news', 'author=' . $GLOBALS['TYPO3_DB']->fullQuoteStr( $authorName, 'tt_news'));
$news = array();
while (false !== ($row = $GLOBALS['TYPO3_DB']->sql_fetch_assoc($res))) {
$news[$row['uid']] = $row['title']
}
$GLOBALS['TYPO3_DB']->sql_free_result($res);
return $news;
}
/**
* Marks all news written by the given author as deleted
*
* @param string $authorName
* @return void
*/
function deleteNewsForAuthor($author) {
$news = findNewsForAuthor($author);
$fields = array('deleted' => 1);
foreach ($news as $uid => $title) {
echo 'Deleted news item with id=' . $uid . ' (' . $title . ')' . chr(10);
$GLOBALS['TYPO3_DB']->UPDATEquery('tt_news', 'uid=' . $GLOBALS['TYPO3_DB']->fullQuoteStr(
$uid, 'tt_news'), $fields);
if ($GLOBALS['TYPO3_DB']->sql_affected_rows() == 0) {
echo 'The above news item was already deleted';
}
}
}

Extension management is a class with functions that provides various levels of information about extensions. This class is not to be confused with TYPO3 Extension Manager.

The Extension management class is named t3lib_extMgm. The functions that developers are likely to use are:

Here are some code examples:

$extkey = 'templavoila';
require_once(t3lib_extMgm::extPath($extkey,
'pi1/class.tx_templavoila_pi1.php'));
// From Backend:
$link = '<a href="' . t3lib_extMgm::extRelPath($extkey) .
'mod1/index.php">Reload</a>';
// From Frontend
$link = '<img src="' . t3lib_extMgm::siteRelPath($extkey) .
'res/image.gif" />';

There are also other functions to use form extensions, but we will discuss them in detail when we meet them because they have very specific usage.

There is a class in TYPO3 that contains the largest collection of various public functions (138 at the time of writing). This class is probably the most used one in TYPO3. The class name is t3lib_div. It is located in t3lib/class.t3lib_div.php.

All functions in this class are divided into several groups. Most popular functions will be described in the forthcoming sections. They all need to be called statically (using t3lib_div::funcName() syntax). The t3lib_div function is always included and available in any extension. There is no need to include this file in your own scripts.

If you think you need a generic function, it is good to check if t3lib_div already has it, before writing your own.

<data>
<node index="1"><value>value 1</value></node>
<node index="2"><value>value 2</value></node>
<node index="3"><value>value 3</value></node>
</data>

Array
(
[1] => Array
(
[value] => value 1
)
[2] => Array
(
[value] => value 2
)
[3] => Array
(
[value] => value 3
)
)

Array
(
[node] => Array
(
[value] => value 3
)
)

$params = array();
$result = t3lib_div::callUserFunction( 'EXT:myext/subdir/class.tx_myext_class.php:' . 'tx_myext_class->main', $params, $this);

TYPO3 supports many languages and works very well with them. It has a set of functions and classes that provide access to localized (translated) strings. These strings are stored in XML files. Extensions need not care about finding the right language or parsing XML because TYPO3 has a very good API for it. While using this API, all strings from XML can be referenced by their index. The index is also a string, but it stays non-localized. A string changes, but its index does not. So it is always possible to find the value of the string by its index. To give a short example, the "Click here" string may have a "click_here" index (the code example at the end of this section will make it clearer).

Usually, localization is one of the areas that lacks a developer's attention. It is much easier to hard-code strings in the PHP code than to write them to an XML file and add an extra line to load that string. But supporting translations is one thing that makes a good extension. Do not postpone the creation of language files. Do it properly from the beginning; do not hard-code. Write a string to an XML file and use the API to get its value.

What happens if an extension is not translated to another language (partially or fully)? The labels in the default language (English) will be used instead.

The class that implements localization support for strings is an old class and, as many old classes, it is an exception to the naming rule described earlier in this chapter. The class name is language and it is located in typo3/sysext/lang (system extension lang). In the BE, it is usually available as $GLOBALS['LANG']. In the FE, it is not available directly, but there are similar ways to get localized strings.

The following methods are the most used ones:

Here is a full code example:

require_once(t3lib_extMgm::extPath('lang', 'lang.php'));
$lang = t3lib_div::makeInstance('language');
/* @var $lang language */
$lang->init('default');
$fileRef = 'EXT:lang/locallang_general.xml';
$label1 = $lang->sL('LLL:' . $fileRef . ':LGL.image');
$LL = $lang->readLLfile($fileRef);
$label2 = $lang->getLLL('LGL.image', $LL);
$lang->includeLLFile($fileRef);
$label3 = $lang->getLL('LGL.image');

All three labels are identical in this example.

TYPO3 stores data in the database. Often, data records refer to other data records or files in the file system. If a data record is deleted and it has a reference to a file, the file stays in the file system. If another data record refers to the deleted data record, there will be a dead link.

To prevent these kinds of problems, TYPO3 maintains a separate list of references between data records and files in the system. This is called the "reference index". The class name is t3lib_refindex.

When data records are created, modified, or deleted in Backend using TCEmain (described in the Backend API section below), the system will update the reference index automatically. FE is different; TCEmain does not work there. FE plugins usually insert data directly into the database using the database API described earlier in this book. So, extension developers have to take care and update the reference index manually. Unfortunately, very few extensions do. Originally, the reference index was developed for BE usage, but its dependency on BE functions is minimal and solved by including class.t3lib_befunc.php in the FE plugin.

When the reference index is used, the system will show a number of references to the current record in the List module, and a clean-up script will be able to detect hanging files and remove them.

We are interested in the following function:

This function will examine the record and update the reference index. Here are some code examples:

require_once(PATH_t3lib . 'class.t3lib_befunc.php');
require_once(PATH_t3lib . 'class.t3lib_refindex.php');
$fields = array(
// Fill array with fields
);
$GLOBALS['TYPO3_DB']->exec_INSERTquery('tx_myext_table',
$fields);
$uid = $GLOBALS['TYPO3_DB']->sql_insert_id();
$refIndex = t3lib_div::makeInstance('t3lib_refindex');
/* @var $refIndex t3lib_refindex */
$refIndex->updateRefIndexTable('tx_myext_table', $uid);

This is all that has to be done to update the reference index. The @var comment helps modern PHP IDEs show code assist for the variable.

Hooks in TYPO3 are special functions that the system calls while it performs some actions. Using hooks, extensions can modify a process in the middle, observe system state, pre- and post-process data, and do many other things.

Typically, a hook function is defined either as a regular function with user_ prefix or as a class prefixed with tx_extkey_. Hooks are registered in the extension's ext_localconf.php file (see Chapter 2) in the following way:

$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']
['cms/layout/class.tx_cms_layout.php']
['list_type_Info']['extkey_pi1'][] =
'EXT:extkey/class.tx_extkey_cms_layout.php
:tx_extkey_cms_layout->getExtensionSummary';

This particular hook will provide additional information to the page module to display near the extension's instance.

TCEforms is visually familiar to anyone who has used TYPO3.

From a developer's viewpoint, TCEforms is an automated way of presenting the content of a database table to the user in a form suitable for editing. TCEforms reads the table configuration array (or TCA) for the table and builds controls dynamically according to the information in the TCA. The TCA for each TYPO3 core table is stored in the TYPO3 core. Extensions provide additional TCA entries for each extension table. If a TCA entry is not provided for the table, the TYPO3 Install tool will complain about it.

TCEforms is the most complex TYPO3 class you can use from. Its API was never meant for external use, but it is still possible to do it. Though this will not be described in this book, developers can figure it out by looking at the file typo3/mod/user/ws/workspaceforms.php. This file makes use of TCEforms to create custom rendering of workspace records.

TCEmain is the TYPO3 record processor. It handles the following tasks:

Though this list does not contain all the functions, the class contains over 100 functions and nearly 5500 lines of code. The class name for TCEmain is t3lib_TCEmain.

Most extension developers are interested in the first two entries from the list above. We will review these in the later sections.

$datamap = array(
$tableName => array(
$recordUid => array(
$fieldName => $fieldValue
)
)
);

$cmdmap = array(
TCEmain, BE APIrecord, manipulating$tableName => array(
$recordUid => array(
$command => $command_data
)
)
);

require_once(PATH_t3lib . 'class.t3lib_tcemain.php');
$pid = 'NEW' . uniqid('');
$content_uid = 'NEW' . uniqid('');
$tstamp = time();
// Datamap for page and content
$datamap = array(
'pages' => array(
$pid => array(
'pid' => 1,
'title' => $GLOBALS['LANG']->getLL('my_page_title'),
'hidden' => 0,
// Next line says that page is "Standard"
'doktype' => 1,
'crdate' => $tstamp,
'tstamp' => $tstamp,
// Next line says what user created the page
'cruser_id' => $GLOBALS['BE_USER']->user['uid'],
// Set some permissions. See TSConfig document
'perms_userid' =>
$GLOBALS['BE_USER']->user['uid'],
'perms_groupid' => 0, // No group
'perms_user' => 31, // See TSConfig
'perms_group' => 27,
'perms_everyone' => 0,
)
),
'tt_content' => array(
$content_uid => array(
'pid' => $pid,
'header' =>
$GLOBALS['LANG']->getLL('content_title'),
'CType' => 'text',
'bodytext' => 'Hello, TYPO3!',
'crdate' => $tstamp,
'tstamp' => $tstamp,
'cruser_id' => $GLOBALS['BE_USER']->user['uid'],
'colPos' => 0
)
)
);
// Create TCEmain instance
$tce = t3lib_div::makeInstance('t3lib_TCEmain');
/* @var $tce t3lib_TCEmain */
$tce->start($datamap, null);
$tce->process_datamap();
if (count($tce->errorLog) != 0) {
// $tce->errorLog is an array of error messages
}
// Prepare cmdmap to delete created records.
// BE user must have 'recursive delete' enabled
// for this example!
$cmdmap = array();
foreach ($tce->substNEWwithIDs as $new => $uid) {
// $tce->substNEWwithIDs_table is like
// $tce->substNEWwithIDs but contains
// table names
$cmdmap[$tce->substNEWwithIDs_table[$new]][$uid] = array('delete' => '');
}
$tce = t3lib_div::makeInstance('t3lib_TCEmain');
/* @var $tce t3lib_TCEmain */
$tce->start(null, $cmdmap);
$tce->process_cmdmap();
if (count($tce->errorLog) != 0) {
// Process error messages
}

require_once(PATH_t3lib . 'class.t3lib_tcemain.php');
// Create TCEmain instance
$tce = t3lib_div::makeInstance('t3lib_TCEmain');
/* @var $tce t3lib_TCEmain */
$tce->clear_cacheCmd(123);

TSFE (historically stands for "TypoScript Frontend") is the main FE class. It is sometimes called "page" object among developers. This class contains methods that determine page ID, parse TypoScript templates, execute templates, process output and cache it. Also, TSFE is responsible for managing FE user object. TSFE is located in the class tslib_fe (exercise: see if you can guess the path to the file name).

Normally, extensions do not call TSFE methods but use some TSFE class attributes. We will describe the most important attributes here:

Content objects display information on the page. All content object types are described in TSRef and they are implemented by the class named tslib_cObj, which is located in typo3/sysext/cms/tslib/class.tslib_content.php. A quick look at this class reveals familiar names such as TEXT, HTML, USER, or stdWrap.

This class is used very often in FE plugins. It has lots of very well-documented methods. We will describe many of them in due course when we have to use them in our real extension.

Last but not the least in its importance is the tslib_pibase class. This is a base class for the FE plugins. While it is not mandatory to use it, most plugins do because this class provides many helpful methods. We will discuss this class in detail in Chapter 5 of the book. For now, we should know that this class provides the following function groups: