Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

Autoload

From TYPO3Wiki
Jump to: navigation, search

warning - Message

This document was transferred to the official TYPO3 CMS documentation, see https://docs.typo3.org/typo3cms/CoreApiReference/ApiOverview/Autoloading/Index.html for details. This wiki page is now obsolete and will not get any additional updates


This page belongs to the Core Team (category Core Team)

Introduction

The autoloader takes care of finding classes in TYPO3. It is linked to t3lib_div::makeInstance() which takes care of singleton and XCLASS handling. Codewise, every developer should always instantiate classes either through t3lib_div::makeInstance() or with the extbase ObjectManager (which internally uses makeInstance() again).

This document is targeted at developers to understand the autoload mechanisms and how to use it in own projects.

Naming convention or ext_autoload

In TYPO3 every class must have an own file – with only one class definition in it. Extensions must not use require() or include() of class files, and instead use the TYPO3 core API to automatically require a file upon request of the class.

A developer has two options to help the core find a specific class:

  • Use the class naming convention and file location.
  • Registration of a class name together with its location in an ext_autoload.php file.

Find classes by naming convention

If a developer sticks to the "extbase" naming scheme for class names and puts the class to a specified location that is constructed from the class name, no further hinting is required to successfully instantiate the class (or to use it statically). Using this scheme is the preferred way of handling the autoloader.

Non-namespaced example

If not using name spaced classes, the autoloader will find a class located in the file system, if the class name and the file location are bound to each other. Nothing else needs to be done to let the autoloader find the class.

Example:

  • Extension name: my_extension
  • Extension location: typo3conf/ext/my_extension
  • Class name: Tx_MyExtension_Utility_FooBar
  • Required file location: typo3conf/ext/my_extension/Classes/Utility/FooBar.php

Rules:

  • The class name must start with "Tx_"
  • In the extension name underscores are converted to upper camel case: "my_extension" -> "MyExtension"
  • Every underscore after the extension name in the class name is resolved to a uppercases folder name below the "Classes" directory: "_utility" -> Folder "Utility"
  • The last part of the class name resolves to the file name with suffix ".php"

Namespaced example

Namespaced classes and class file locations are handled similar to the non-namespaced example. See namespace documentation for more details on this topic.

Example:

  • Extension name: shop
  • Vendor name: Enet
  • Extension location: typo3conf/ext/shop
  • Full class name with namespace: \Enet\Shop\Utility\FooBar
  • Namespace: \Enet\Shop\Utility
  • Class name: FooBar
  • Required file location: typo3conf/ext/shop/Classes/Utility/FooBar.php

Rules:

  • The class name must start with the vendor name, here "Enet"
  • In the extension name underscores are converted to upper camel case: "my_extension" -> "MyExtension"
  • Every Underscore after the extension name in the class name is resolved to a uppercases folder name below the "Classes" directory: "_utility" -> Folder "Utility"
  • The last part of the class name resolves to the file name with suffix ".php"

Registering class files in ext_autoload

If an extension scheme can not stick to the above convention for whatever reason, it can ship an own "ext_autoload.php" file in the extensions base directory to hint the autoloader about class locations. The autoloader searches for this file automatically if the extension is loaded and takes the registered classes into account when looking up class locations.

The ext_autoload file must only return a one dimensional array with the class name as key, and the file location as value. No other code is allowed in this file.

Example from extension "scheduler" for a non-namespaced class

notice - Note

Before TYPO3 6.0, the key part of the returned array – the class name – had to be lower case! So, even camel case class names had to be lower case in the ext_autoload.php file! If the key was not lower case, the according class was NOT found! This hurdle was removed with TYPO3 6.0.
PHP script:
<?php
$extensionPath = t3lib_extMgm::extPath('scheduler');
return array(
	'tx_scheduler_croncmd' => $extensionPath . 'class.tx_scheduler_croncmd.php',
	'tx_scheduler_croncmd_normalize' => $extensionPath . 'Normalize/class.tx_scheduler_croncmd_normalize.php',
);
?>

This registers the classes "tx_scheduler_CronCmd" with the location "path-to-the-extension/class.tx_scheduler_croncmd.php" and "tx_scheduler_CronCmd_Normalize" with "path-to-the-extension/Normalize/class.tx_scheduler_croncmd_normalize.php". Since extensions can be located in different directories, the API method t3lib_extMgm::extPath('scheduler') is used to determine the final extension location.

Example for a namespaced class

PHP script:
<?php
$extensionPath = \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::extPath('foo');
return array(
	'Enet\Foo\SomeClass' => $extensionPath . 'Path-below-extension-root/SomeClassIsHere.php',
);
?>

See also

XLASS usage documentation

Namespace documentation