TYPO3 CMS Coding Guidelines 6.2 documentation

Introduction
File system conventions
PHP file formatting
Coding: Best practices

Docstart

two three Layout: fixed adaptive

TYPO3 CMS Coding Guidelines:ref:

Previous Key:	doc_core_cgl
Version:	6.2
Language:	en
Description:	A description of the formal requirements or standards regarding PHP coding that you should adhere to when you develop TYPO3 Extensions or Core parts.
Keywords:	forDevelopers, forIntermediates
Copyright:	2000-2014
Author:	Documentation Team
Email:	documentation@typo3.org
License:	Open Content License available from www.opencontent.org/opl.shtml
Rendered:	2014-12-02 21:40

The content of this document is related to TYPO3,

a GNU/GPL CMS/Framework available from www.typo3.org

Official documentation

This document is included as part of the official TYPO3 documentation. It has been approved by the TYPO3 Documentation Team following a peer- review process. The reader should expect the information in this document to be accurate - please report discrepancies to the Documentation Team (documentation@typo3.org). Official documents are kept up-to-date to the best of the Documentation Team's abilities.

Core Manual

This document is a Core Manual. Core Manuals address the built in functionality of TYPO3 and are designed to provide the reader with in- depth information. Each Core Manual addresses a particular process or function and how it is implemented within the TYPO3 source code. These may include information on available APIs, specific configuration options, etc.

Core Manuals are written as reference manuals. The reader should rely on the Table of Contents to identify what particular section will best address the task at hand.

Table of Contents

Introduction:ref:

About this document:ref:

This document defines coding guidelines for the TYPO3 CMS project. Following these guidelines is mandatory for TYPO3 core developers and contributors to the TYPO3 core.

Extension authors are strongly encouraged to follow these guidelines when developing extensions for TYPO3. Following these guidelines makes it easier to read the code, analyze it for learning or performing code reviews. These guidelines also help preventing typical errors in the TYPO3 code.

This document defines how TYPO3 code, files and directories should be structured and formatted. It does not teach how to program for TYPO3 and does not provide technical information about TYPO3.

What's new:ref:

The latest version of the CGLs mostly contains more complete and precise information about already existing guidelines. It reflects the coding of TYPO3 CMS 6.2.

Furthermore the appendix which described how to properly set up various IDEs for working with the TYPO3 CMS Core has been moved to the wiki: wiki.typo3.org/PHP_Editors_/_IDE_for_TYPO3

Credits:ref:

The original TYPO3 coding guidelines document was written by Kasper Skårhøj. The current version is based on a complete rewrite prepared by Ingo Renner and Dmitry Dulepov in 2008. It is currently maintained by François Suter. All changes go through an approval process by the TYPO3 Active Contributors Team.

Feedback:ref:

For general questions about the documentation get in touch by writing to documentation@typo3.org .

If you find a bug in this manual, please be so kind as to check the online version on docs.typo3.org/typo3cms/CodingGuidelinesReference/. From there you can hit the "Edit me on GitHub" button in the top right corner and submit a pull request via GitHub. Alternatively you can just file an issue using the bug tracker: https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-CodingGuidelines/issues.

Maintaining high quality documentation requires time and effort and the TYPO3 Documentation Team always appreciates support. If you want to support us, please join the documentation mailing list/forum (forum.typo3.org/index.php/f/44/).

The CGL as a means of quality assurance:ref:

Our programmers know the CGL and are encouraged to inform authors, should their code not comply with the guidelines.

Apart from that, adhering to the CGL is not voluntary; the CGL are also enforced by structural means: Automated tests are run by the continuous integration tool Jenkins to make sure that every code change complies with the CGL. In case a change does not meet the criteria, Jenkins will give a negative vote in the review system and point to the according problem.

Conventions used in this document:ref:

Monospace font is used for:

File names and directories. Directories have a slash (/) at the end of the directory name.
Code examples
TYPO3 module names
Extension keys
TYPO3 namespaces

TYPO3 Frontend and Backend are spelled with the first letter in uppercase because they are seen as subsystems.

File system conventions:ref:

There are certain conventions about naming files and directories in the TYPO3 core and extensions. Some of them are historical and do not follow other formal rules. They will be described separately. New core classes and extensions are required to follow the formal rules outlined below.

TYPO3 directory structure:ref:

By default a TYPO3 installation consists of the following directories:

Directory

Description

Directory

fileadmin/

Description

This is a directory in which users can store files. Typically images, PDFs or HTML files appear in this directory and/or its subdirectories.

Often this directory is used for downloadable files. This directory is the only one accessible using the TYPO3 File module.

Directory

typo3/

Description

TYPO3 Backend directory. This directory contains most of the files coming with the TYPO3 Core. The files are arranged logically in the different system extensions in the sysext/ directory, according to the application area of the particular file. For example, the "frontend" extension amongst other things contains the "TypoScript library", the code for generating the Frontend website. In each system extension the PHP files are located in the folder Classes/. Additionally, typo3/ can contain some global extensions in the ext/ directory (which is not used by the TYPO3 core itself).

Directory

typo3conf/

Description

TYPO3 configuration directory

Directory

typo3conf/ext/

Description

Directory for TYPO3 extensions. Each subdirectory contains one extension.

Directory

typo3temp/

Description

Directory for temporary files. It contains subdirectories for temporary files of extensions and TYPO3 components.

Directory

uploads/

Description

Default upload directory. Extensions can use the uploadfolder setting in ext_emconf.php to specify a subdirectory of uploads/ for this extension.

This structure is default for a TYPO3 installation. Other non-TYPO3 applications can add their own directories.

TYPO3 files and user files:ref:

All files in the TYPO3 web site directory hierarchy are divided into TYPO3 files and user files.

TYPO3 files are files that come with the TYPO3 source package released by the TYPO3 association. This includes files inside the typo3/ directory and the file named index.php in the root of the TYPO3 installation.

All other files are user files. This for example includes extensions, files in the fileadmin/ directory or files generated by TYPO3 (like configuration files, thumbnails or temporary CSS files). User files are not allowed in the folder typo3/.

These CGLs are valid for all TYPO3 files and for those user files, which are to be generated or processed by the TYPO3 Core like for example LocalConfiguration.php or AdditionalConfiguration.php.

Extension directory structure:ref:

An extension directory contains the following files and directories:

Name

ext_autoload.php

Description

This file contains an array. This array maps class names to file paths. It gets loaded by the autoloader when the autoloader is initialized.

Name

ext_emconf.php

Description

This is the only mandatory file in the extension. It describes the extension for the rest of TYPO3.

Name

ext_icon.gif or ext_icon.png

Description

This is the icon of the extension. The filename may not be changed.

Name

ext_localconf.php

Description

This file contains hook definitions and plugin configuration. It must not contain a PHP encoding declaration. The filename may not be changed.

Name

ext_tables.php

Description

This file contains table declarations. It must not contain a PHP encoding declaration. For more information about table declarations and definitions see the "TYPO3 Core API" document. The filename may not be changed.

Name

ext_tables.sql

Description

This files contains SQL definitions for extension tables. The filename may not be changed.

The file may contain either a full table definition or a partial table. The full table definition declares extension's tables. It looks like a normal SQL CREATE TABLE statement.

The partial table definition contains a list of the fields that will be added to an existing table. Here is an example:

CREATE TABLE pages (
       tx_myext_field int(11) DEFAULT '0' NOT NULL,
);

Notice the comma after the field. In the full table definition it will be an error, but in the partial table definition it is required. TYPO3 will merge this table definition to the existing table definition when comparing expected and actual table definitions. Partial definitions can also contain indexes and other directives. They can also change existing table fields though that is not recommended, because it may create problems with the TYPO3 core and/or other extensions.

TYPO3 parses ext_tables.sql files. TYPO3 expects that all table definitions in this file look like the ones produced by the mysqldump utility. Incorrect definitions may not be recognized by the TYPO3 SQL parser or may lead to MySQL errors, when TYPO3 tries to apply them.

Name

locallang*.xlf

Description

These files contain localizable labels in standard XLIFF format, one language per file. They can also appear in subdirectories, e.g. inside Resources/.

Name

locallang*.xml

Description

These files contain localizable labels in a custom XML based format, possibly multiple languages per file. They can also appear in subdirectories. Deprecated since TYPO3 4.6; use locallang*.xlf files instead.

Name

doc/

Description

This directory contains the extension manual in OpenOffice format. The filename may not be changed.

Name

doc/manual.sxw

Description

This file contains the extension manual in OpenOffice 1.0 format. The name or format of the file may not be changed. See the extension "doc_template" ("Official Doc Extension Template") on typo3.org for more information about extension manuals. Deprecated, provide your manual in ReST format instead.

Name

Classes/

Description

Directory for the PHP files of the extension, possibly in further subfolders like for example Controller/, Domain/, Plugin, Service/ or View/.

Name

Configuration/

Description

Directory for configuration files, in subfolders like TCA/ or TSconfig/. E.g. the subfolder TCA/ contains files named like tablename.php, which return an array of the configuration of the according table tablename.

Name

Documentation/

Description

This directory contains the extension manual in ReST format. Documentation/ and its subfolders may contain several ReST files, images and other resources.

Name

Documentation/Index.rst

Description

This file contains the cover page of the extension manual in ReST format. The name or format of the file may not be changed. You may include other ReST files as you like. See the "Extension Template" on docs.typo3.org for more information about structure and syntax of extension manuals.

Name

Resources/

Description

Contains the subfolders Public/ and Private/, which contain resources, possibly in further subfolders, e.g. Templates/, CSS/, Images/ or JavaScript/.

This is also the directory for non–TYPO3 files supplied with the extension. TYPO3 is licensed under GPL version 2 or any later version. Any non–TYPO3 code must be compatible with GPL version 2 or any later version.

Name

Tests/

Description

This directory contains tests, e.g. unit tests in the subfolder Unit/.

This directory structure is strongly recommended. Extensions may create their own directories (for example, move all language files into other directories).

For the class names in extension files see the chapter "Class names of user files".

File names:ref:

The file name describes the functionality included in the file. It consists of one or more nouns, written in UpperCamelCase. For example in the frontend system extension there is the file ContentObject/ContentObjectRenderer.php.

It is recommended to use only PHP classes and avoid non-class files.

Files that contain PHP interfaces must have the file name end on "Interface", e.g. FileListEditIconHookInterface.php.

For information on class names for user files, see the according section of this document.

One file can contain only one class or interface.

Extension for PHP files is always php.

Unit test files¶

Unit test files are located in the "Tests/Unit/" folder in the according extension, within a sub-structure matching the structure in the Classes/ folder.

The naming conventions for the files are different from those explained above: "Test" is appended at the end of the name, before ".php".

Example¶

The unit test class file for typo3/sysext/core/Classes/Database/PreparedStatement.php is:

typo3/sysext/core/Tests/Unit/Database/PreparedStatementTest.php

See more about unit testing in the "Unit tests" chapter.

PHP file formatting:ref:

General requirements for PHP files:ref:

PHP tags¶

Each PHP file in TYPO3 must use the full (as opposed to short) opening PHP tag. There must be exactly one opening tag (no closing and opening tags in the middle of the file). Example:

<?php
        // File content goes here

Closing PHP tags (e.g. at the end of the file) are not used.

Line breaks¶

TYPO3 uses Unix line endings (\n, PHP chr(10)). If a developer uses Windows or Mac OS X platform, the editor must be configured to use Unix line endings.

Line length¶

Very long lines of code should be avoided for questions of readability. A line length of about 130 characters (including tabs) is fine. Longer lines should be split into several lines whenever possible. Each line fragment starting from the second must - compared to the first one - be indented with one tab character more. Example:

$rows = $GLOBALS['TYPO3_DB']->exec_SELECTgetRows('uid, title', 'pages',
        'pid=' . $this->fullQuoteStr($this->pid, 'pages') . $this->cObj->enableFields('pages'),
        '', 'title');

or even better for readability:

$rows = $GLOBALS['TYPO3_DB']->exec_SELECTgetRows('uid, title',
        'pages',
        'pid=' . $this->fullQuoteStr($this->pid, 'pages') . $this->cObj->enableFields('pages'),
        '',
        'title'
);

Comment lines should be kept within a limit of about 80 characters (excluding tabs) as it makes them easier to read.

Notes¶

When splitting a line, try to split it at a point that makes as much sense as possible. In the above example, the line is split between two arguments and not in the middle of one. In case of long logical expressions, put the logical operator at the beginning of the next line, e.g.:
```
if (
    $GLOBALS['TYPO3_CONF_VARS']['SYS']['curlUse'] == '1'
    && preg_match('/^(?:http|ftp)s?|s(?:ftp|cp):/', $url)
) {
```

Whitespace and indentation¶

TYPO3 uses tab characters to indent source code. One indentation level is one tab.

There must be no white spaces in the end of a line. This can be done manually or using a text editor that takes care of this.

Spaces must be added:

on both sides of string, arithmetic, assignment and other similar operators (for example ., =, +, -, ?, :, *, etc)
after commas
in single line comments after the comment sign (double slash)
after asterisks in multiline comments
after conditional keywords like if ( and switch (
before conditional keywords if the keyword is not the first character like } elseif {

Character set¶

All TYPO3 source files use the UTF-8 character set without byte order mark (BOM) since version 4.5. Encoding declarations like declare(encoding = 'utf-8'); must not be used. They might lead to problems, especially in ext_tables.php and ext_localconf.php files of extensions, which are merged internally in TYPO3 CMS. Files from third-party libraries may have different encodings.

File structure:ref:

TYPO3 files use the following structure:

Opening PHP tag
Namespace
Copyright notice
Included files
Class information block in phpDoc format
PHP class
Optional module execution code (for example, in eID classes)

The following sections discuss each of these parts.

Namespace¶

The namespace declaration of each PHP file in the TYPO3 Core shows where the file belongs inside TYPO3 CMS. The namespace starts with "TYPO3\CMS\", then the extension name in UpperCamelCase, a backslash and then the name of the subfolder of Classes/, in which the file is located (if any). E.g. the file typo3/sysext/frontend/Classes/ContentObject/ContentObjectRenderer.php with the class ContentObjectRenderer is in the namespace "TYPO3\CMS\Frontend\ContentObject".

use statements can be added to this section.

Copyright notice¶

TYPO3 is released under the terms of GNU General Public License version 2 or any later version. The copyright notice with a reference to the license text must be included at the top of every TYPO3 PHP class file. user_ files must have this copyright notice as well. Example:

<?php
namespace TYPO3\CMS\XXX;

/**
 * This file is part of the TYPO3 CMS project.
 *
 * It is free software; you can redistribute it and/or modify it under
 * the terms of the GNU General Public License, either version 2
 * of the License, or any later version.
 *
 * For the full copy