The TYPO3 Core Engine is the class that handles all data writing to database tables configured in $TCA. In addition the class handles commands such as copy, move, delete. It will handle undo/history and versioning of records as well and everything will be logged to the sys_log. And it will make sure that write permissions are evaluated correctly for the user trying to write to the database. Generally, any processing specific option in the $TCA array is handled by TCE.

Using TCE for manipulation of the database content in the TCA configured tables guarantees that the data integrity of TYPO3 is respected. This cannot be safely guaranteed if you write to $TCA configured database tables directly. It will also manage the relations to files and other records.

TCE requires a backend login to work. This is due to the fact that permissions are observed (of course) and thus TCE needs a backend user to evaluate against. This means you cannot use TCEmain from the frontend scope. Thus writing to tables (such as a guestbook) will have to be done from the frontend without TCEmain.

The features of the $TCA (Table Configuration Array) array are discussed in the end of this document.

TCE also has a part for handling files. The file operations are normally performed in the File > List module where you can manage a directory on the server by copying, moving, deleting and editing files and directories. The file operations are managed by two core classes, t3lib_basicFileFunc and t3lib_extFileFunc.

Syntax:

$cmd[ tablename ][ uid ][ command ] = value

Description of keywords in syntax:

Command keywords and values:

Syntax:

$data[ tablename ][ uid ][ fieldname ] = value

Description of keywords in syntax:

Notice: For FlexForms the data array of the FlexForm field is deeper than three levels. The number of possible levels for FleFforms is infinite and defined by the data structure of the FlexForm. But FlexForm fields always end with a "regular value" of course.

TCE also has an API for clearing the cache tables of TYPO3:

Syntax:

$tce->clear_cacheCmd($cacheCmd);

Hook for cache post processing

You can configure cache post processing with a user defined PHP function. Configuration of the hook can be done from (ext_)localconf.php. An example look like:

$TYPO3_CONF_VARS['SC_OPTIONS']['t3lib/class.t3lib_tcemain.php']['clearCachePostProc'][]='myext_cacheProc->proc';

require_once(t3lib_extMgm::extPath('myext').'class.myext_cacheProc.php');

There are a few internal variables you can set prior to executing commands or data submission. These are the most significant:

This is the most basic example of how to submit data into the database. It is four lines. Line 1 instantiates the class, line 2 defines that values will be provided without escaped characters (recommended!), line 3 registers the $data array inside the class and initializes the class internally! Finally line 4 will execute the data submission.

   1: $tce = t3lib_div::makeInstance('t3lib_TCEmain');

   2: $tce->stripslashes_values = 0;

   3: $tce->start($data,array());

   4: $tce->process_datamap();

The most basic way of executing commands. Line 1 creates the object, line 2 defines that values will be provided without escaped characters (recommended), line 3 registers the $cmd array inside the class and initializes the class internally! Finally line 4 will execute the commands.

   1: $tce = t3lib_div::makeInstance('t3lib_TCEmain');

   2: $tce->stripslashes_values=0;

   3: $tce->start(array(),$cmd);

   4: $tce->process_cmdmap();

In this example the clear-cache API is used. No data is submitted, no commands executed. Still you will have to initialize the class by calling the start() method (which will initialize internal variables).

Notice: Clearing "all" cache will be possible only for users that are "admin" or for users with specific permissions to do so.

   1: $tce = t3lib_div::makeInstance('t3lib_TCEmain');

   2: $tce->start(Array(),Array());

   3: $tce->clear_cacheCmd('all');

Imagine the $data array something like this:

$data = array(

    'pages' => array(

        'NEW_1' => array(

            'pid' => 456,

            'title' => 'Title for page 1',

        ),

        'NEW_2' => array(

            'pid' => 456,

            'title' => 'Title for page 2',

        ),

    )

);

This aims to create two new pages in the page with uid "456". In the follow code this is submitted to the database. Notice how line 3 reverses the order of the array. This is done because otherwise "page 1" is created first, then "page 2" in the same PID meaning that "page 2" will end up above "page 1" in the order. Reversing the array will create "page 2" first and then "page 1" so the "expected order" is preserved.

Apart from this line 6 will send a "signal" that the page tree should be updated at the earliest occasion possible. Finally, the cache for all pages is cleared in line 7.

   1: $tce = t3lib_div::makeInstance('t3lib_TCEmain');

   2: $tce->stripslashes_values = 0;

   3: $tce->reverseOrder = 1;

   4: $tce->start($data,array());

   5: $tce->process_datamap();

   6: t3lib_BEfunc::getSetUpdateSignal('updatePageTree');

   7: $tce->clear_cacheCmd('pages');

In this case it is shown how you can use the same object instance to submit both data and execute commands if you like. The order will depend on the order of line 4 and 5.

In line 3 the start() method is called, but this time with the third possible argument which is an alternative BE_USER object. This allows you to force another backend user account to create stuff in the database. This may be useful in certain special cases. Normally you should not set this argument since you want TCE to use the global $BE_USER.

   1: $tce = t3lib_div::makeInstance('t3lib_TCEmain');

   2: $tce->stripslashes_values = 0;

   3: $tce->start($data,$cmd,$alternative_BE_USER);

   4: $tce->process_datamap();

   5: $tce->process_cmdmap();

Syntax:

$file[ command ][ index ][ key ] = value

Description of keywords in syntax:

Command keywords and values:

It is unlikely that you will need to use this internally in your scripts like you will need t3lib_TCEmain. It is fairly uncommon to need the file manipulations in own scripts unless you make a special application. Therefore the most typical usage of this API is from tce_file.php and the core scripts that are activated by the "File > List" module.

However, if you need it this is an example (taken from tce_file.php) of how to initialize the usage.

   1:     // Initializing:

   2: $this->fileProcessor = t3lib_div::makeInstance('t3lib_extFileFunctions');

   3: $this->fileProcessor->init($FILEMOUNTS, $TYPO3_CONF_VARS['BE']['fileExtensions']);

   4: $this->fileProcessor->init_actionPerms($BE_USER->user['fileoper_perms']);

   5:

   6: $this->fileProcessor->start($this->file);

   7: $this->fileProcessor->processData();

Line 2 makes an instance of the class and line 3 initializes the object with the filemounts of the current user and the array of allow/deny file extensions in web-space and ftp-space (see below). Then the file operation permissions are loaded from the user object in line 4. Finally, the file command array is loaded in line 6 (and internally additional configuration takes place from $TYPO3_CONF_VARS!). In line 7 the command map is executed.

The control of fileextensions goes in two catagories. Webspace and Ftpspace. Webspace is folders accessible from a webbrowser (below TYPO3_DOCUMENT_ROOT) and ftpspace is everything else.

The control is done like this: If an extension matches 'allow' then the check returns true. If not and an extension matches 'deny' then the check return false. If no match at all, returns true.

You list extensions comma-separated. If the value is a '*' every extension is matched. If no fileextension, true is returned if 'allow' is '*', false if 'deny' is '*' and true if none of these matches. This (default) configuration below accepts everything in ftpspace and everything in webspace except php3 or php files:

$TYPO3_CONF_VARS['BE']['fileExtensions'] = array (

    'webspace' => array('allow'=>'', 'deny'=>'php3,php'),

    'ftpspace' => array('allow'=>'*', 'deny'=>'')

);