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

Namespaces

From TYPO3Wiki
Jump to: navigation, search
This page belongs to the Core Team (category Core Team)

warning - Message

This document was transferred to the official TYPO3 CMS documentation, see --- Namespaces reference --- for details. This wiki page is now obsolete and will not get any additional updates

notice - Note

Under construction, currently more notes than documentation


Introduction

Since the beta1 version of TYPO3, the core makes use of namespaces. To keep compatibility with extensions, a compat layer is in place. Calls for Core classes like t3lib_div will thus still work, but redirect to the new \TYPO3\CMS\Core\Utility\GeneralUtility class. As a extension developer you are highly encouraged to use the namespaced classes from now on. The compat layer will be removed in TYPO3 version 6.2.

This extensive change in the TYPO3 infrastructure aims to further sync TYPO3 with FLOW3 and Phoenix (now Neos), make it easier to transit between the systems. Additionally, the switch had been used to streamline the class naming scheme, get rid of old naming clashes and make the classnames more meaningful. This will lower the entry barrier for new developers, too.

During the change three new system extensions were introduced. They enable the core to divide into scopes.

  • core contains basic classes like the Bootstrap, Logging Functions, Mail- and Caching handling
  • frontend contains for example the typoscript handling and the rendering functions
  • backend contains TCEmain, Forms and Modules

During the development of version 6.0 a lot of unit tests were written for all parts of the core. Not only was this done for stabilisation purposes and avoidance of regressions, but to demonstrate possible use of classes and functions, too. Thanks to the more reasonable structure and naming of classes it is easy now to find related tests. Make use of the examples the tests provide and write your own for own extensions or the core, every contribution in this area is welcome.

The namespace change levels the path for the next features to introduce in further TYPO3 versions like composer support (see http://getcomposer.org/doc/00-intro.md) and FLOW3 integration.

Last but not least, the use of unique vendor names enables the use of extensions with the same key can exist in the same installation without problems.

Implementation Details

To provide the mentioned compat layer not only all most files in the core were moved to new locations and renamed according the streamlined naming schema, but the old files are kept, too. They are still in the known places, but contain as only content a require to their namespaced successor. An adopted class loader makes use of the class_alias() function to create a language level mapping from new to old classnames. The old class names are still available although php uses the new ones physically.

Extensions may use the mechanism for own class name changes. It has to be implemented like in typo3/sysext/core/Migrations/Code/ClassAliasMap.php for example.

Does and don'ts for developers

  • Structure of a namespaced class name: {VendorName}\{PackageName}\({CategoryName}\)*{ClassName}
  • The TYPO3 core uses \TYPO3\CMS as vendor name. As a extension developer you are not allowed to use this vendor in your own extension! Instead, use your company name. Until now there is no vendor registration like it was there for extension keys, so ensure to pick a unique vendor name. Your vendor must have only one part for now, not two as the core vendor. Valid vendor names for extensions could be \Enet or \DKD for example. Please check the web/github quickly to ensure uniqueness. Domain and brand names are also good vendor names (without dots and tlds).
  • The second part of the namespace (in case of core classes the third part) is treated as the extension key. Pick an extension key to your liking, thanks to the unique vendor name collisions with other extensions will not happen. The extension key part in the namespace have to be written in UpperCamelCase and is internally transformed to lowercase_underscore.
  • Further parts of the namespace - if used - have to describe a category the class belongs to. While browsing through the class tree the category name should give you a good impression of the domain of the belonging classes.
$configurationManager = $objectManager->get('TYPO3\\CMS\\Extbase\\Configuration\\ConfigurationManagerInterface');
  • The use of include() or require() in extensions is no longer the way to go. Instead you should make use of the autoloader functionality. Create a file named ext_autoload.php in your extension and put all required files in. They will be available then without further action.
  • When you want to use class names in classes sharing the same namespacce, you may NOT use the short name, but always the full qualified version:
namespace Extbase\BlogExample\Domain\Model;
class Post extends \TYPO3\CMS\Extbase\DomainObject\AbstractEntity {
[...]
public function removeTag(\Extbase\BlogExample\Domain\Model\Tag $tag) {
    $this->tags->detach($tag);
}
[...]
}

the same goes for the definition of an objectStorage to use, you must give the full qualified name:

/**
 * @var \TYPO3\CMS\Extbase\Persistence\Generic\ObjectStorage<\Extbase\BlogExample\Domain\Model\Tag>
 */
protected $tags;

Extbase

Backend Modules

To use namespaces in backend modules you need to prefix the extension key with your vendor namespace when registering the module (in ext_tables.php):

\TYPO3\CMS\Extbase\Utility\ExtensionUtility::registerModule(
    '<vendorName>.' . $_EXTKEY,
    ...
);

Frontend Plugins

To use namespaces in frontend plugins you need to prefix the extension key with your vendor namespace when configuring the module (in ext_localconf.php):

\TYPO3\CMS\Extbase\Utility\ExtensionUtility::configurePlugin(
    '<vendorName>.' . $_EXTKEY,
    ...
);

notice - Note

Replace the <vendorName> with your own vendor, do not use dots or tlds inside. Don't forget the dot inside the string, it is used as delimiter

Compatibility

  • Hint about ext_localconf and ext_tables that requires are evil and should be avoided in general (and especially at this point). This especially gives issues with the php < 5.3.7 compat layer.


Further questions / best practice

  • When should a class for example in makeInstance begin with \\ and when not?
  • Why are there two \\ in strings, especially if we only use single quotes and not double quotes?