/doc/t3php/t3php-mode.info

Large files files are truncated, but you can click here to view the full file

This is t3php-mode.info, produced by makeinfo version 4.13 from
t3php-mode.texi.

This manual introduces a TYPO3-PHP major mode for Emacs, which is
specialized on editing PHP code in the TYPO3 world.

   Copyright (C) 2009 Joachim Mathes.

     This program is free software; you can redistribute it and/or
     modify it under the terms of the GNU General Public License as
     published by the Free Software Foundation; either version 2 of the
     License, or (at your option) any later version.

     This program is distributed in the hope that it will be useful, but
     WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
     02110-1301, USA.


File: t3php-mode.info,  Node: Top,  Next: Introduction,  Up: (dir)

TYPO3-PHP Mode
**************

This manual introduces a TYPO3-PHP major mode for Emacs, which is
specialized on editing PHP code in the TYPO3 world.

   Copyright (C) 2009 Joachim Mathes.

     This program is free software; you can redistribute it and/or
     modify it under the terms of the GNU General Public License as
     published by the Free Software Foundation; either version 2 of the
     License, or (at your option) any later version.

     This program is distributed in the hope that it will be useful, but
     WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
     02110-1301, USA.

* Menu:

* Introduction:: TYPO3-PHP and Emacs
* Installation:: Prepare Emacs
* Using T3PHP mode:: Features, commands and key bindings
* TYPO3 Coding Guidelines::
* Key Index::
* Variable Index::
* Function Index::


File: t3php-mode.info,  Node: Introduction,  Next: Installation,  Prev: Top,  Up: Top

1 Introduction
**************

This manual describes T3PHP mode, which extends Emacs with functionality
for editing TYPO3-PHP files. Of course, it is also useful for PHP
coding in general.

   GNU Emacs is an extensible, customizable text editor and can be
obtained for free from `http://ftp.gnu.org/pub/gnu/emacs/'. *Note
Preface: (emacs)Top. The code is written and tested on GNU Emacs
version 23.1.1.


File: t3php-mode.info,  Node: Installation,  Next: Using T3PHP mode,  Prev: Introduction,  Up: Top

2 Installation
**************

To install T3PHP Mode just drop file `t3php-mode.el' into a directory
on your load-path. If you are the administrator of the system you are
working on, a possible directory could be
`/usr/share/emacs/site-lisp/t3php-mode', for example. You might
byte-compile it for better performance. *Note Byte Compilation:
(elisp)Byte Compilation.

   To set up Emacs to automatically edit files ending in `.php' using
T3PHP Mode, add the following lines to your `~/.emacs' file (GNU Emacs)
or `~/.xemacs/init.el' file (XEmacs):
     (setq auto-mode-alist (cons '("\\.php$" . t3php-mode) auto-mode-alist))
     (autoload 't3php-mode "t3php-mode" "TYPO3-PHP input file editing mode." t)
   If you just want to test T3PHP Mode or are not eager to modify your
`~/.emacs' file, type `M-x load-file', load the `t3php-mode.el' file
and finally apply the mode to the current buffer by typing `M-x
t3php-mode'.


File: t3php-mode.info,  Node: Using T3PHP mode,  Next: TYPO3 Coding Guidelines,  Prev: Installation,  Up: Top

3 Using T3PHP mode
******************

TYPO3 Mode supports different display and editing features, which will
be described in the following sections.

* Menu:

* Customization::
* Syntax highlighting::
* Line indentation::
* Inserting code templates::
* Inserting classes::
* Buffer outline::


File: t3php-mode.info,  Node: Customization,  Next: Syntax highlighting,  Up: Using T3PHP mode

3.1 Customization
=================

T3PHP Mode defines a customization group in Emacs, which is a member of
the Emacs standard customization group `Languages', whose parent Emacs
group is `Programming'. Use `M-x customize' to browse through the full
list of customization groups or `M-x customize-group' with parameter
`t3php' to enter the T3PHP Mode customization group directly

The following user-customizable variables are provided.

 -- Variable: string t3php-developer
     The current developer or author of the PHP code. The value of this
     variable is used in the php-doc comments.

     Default: `Lisa Fremont <lisa@fremont.de>'

 -- Variable: string t3php-typo3-extension-directory
     The path to the TYPO3 extensions' directory relative to the TYPO3
     root directory.

     Default: `ext/'

 -- Variable: string t3php-path-to-typo3-extension-directory
     The path to the TYPO3 extensions directory relative to the TYPO3
     root directory.

     Default: `typo3conf/'

 -- Variable: string t3php-date-format
     The date format which is used for php-doc comments.

     Default: `%Y-%m-%d'

 -- Variable: string t3php-year-format
     The year format which is used in php-doc comments.

     Default: `%Y'

 -- Variable: integer t3php-block-indentation
     The indentation relative to a predecessing line which begins a new
     code block.

     Default: `4'

 -- Variable: choice t3php-newline-function
     This variable decides which function to call upon pressing
     `<RET>'. Depending on the chosen option, line indentation will be
     processed automatically. The following options are available for
     CHOICE:
    `newline'
          This command just inserts newlines into the current buffer
          before point.

    `newline-and-indent'
          This function inserts a newline(1), then indents the new line
          (the one following the newline just inserted) according to
          T3PHP Mode's internal indentation strategies.

    `reindent-then-newline-and-indent'
          This command reindents the current line, inserts a newline at
          point, and then indents the new line (the one following the
          newline just inserted).

     Default: `newline'.

 -- Variable: boolean t3php-php-doc-align
     Determines whether the PHPDoc parameters are aligned after a
     method or class is inserted with `t3php-insert-method' or
     `t3php-insert-class' respectively. See *note Inserting methods::
     and *note Inserting classes::, for more information.

     Aligned parameters:
     1  /**
     2   * Define foobar
     3   *
     4   * @param   $foo
     5   * @param   $bar
     6   * @return
     7   * @author  Lisa Fremont <lisa@fremont.de>
     8   * @since   2009-12-02
     9   */
     10 public function foobar($foo, $bar) {
     11
     12 }

     Unaligned parameters:
     1  /**
     2   * Define foobar
     3   *
     4   * @param $foo
     5   * @param $bar
     6   * @return
     7   * @author Lisa Fremont <lisa@fremont.de>
     8   * @since 2009-12-02
     9   */
     10 public function foobar($foo, $bar) {
     11
     12 }

     Default: `t'

 -- Variable: string t3php-php-manual-url
     URL at which to find PHP manual. You can replace `en' with your ISO
     language code.

     Default: `http://www.php.net/manual/en/'

 -- Variable: string t3php-php-search-url
     URL at which to search for documentation on a word, e.g. a PHP
     function.

     Default: `http://www.php.net/manual/en/'

 -- Variable: boolean t3php-outline-keep-other-windows
     When the outline is viewed, the boolean value of this variable
     decides if the currently selected T3PHP Mode buffer will be
     deleted. If the variable is set to true (`t') the current window is
     split and the outline is displayed in the newly created window.
     When `nil', all other windows except the selected one will be
     deleted, so that the outline window fills an adjustable (*note
     t3php-outline-split-windows-fraction: x-stswf.) amount of the
     frame.

     Default: `t'.

 -- Variable: boolean t3php-outline-split-windows-horizontally
     This variable determines the splitting mode, if the outline is
     displayed. If true, split the current window horizontally.
     Otherwise split the window vertically.

     Default: `nil'.

     I must admit, that sometimes I get confused. So if it is not for
     your orientation, at least it is for mine. :-)

     �[image src="images/split_v.png" alt="Splitting a window vertically" text="+-------+         +-------+
     |       |         |       |
     |       |  split  |       |
     |       |  -----> +-------+
     |       |    v    |       |
     |       |         |       |
     +-------+         +-------+
     "�]
     Figure 3.1: Splitting a window _vertically_.

     �[image src="images/split_h.png" alt="Splitting a window horizontally" text="+-------+         +---+---+
     |       |         |   |   |
     |       |  split  |   |   |
     |       |  -----> |   |   |
     |       |    h    |   |   |
     |       |         |   |   |
     +-------+         +---+---+
     "�]
     Figure 3.2: Splitting a window _horizontally_.


 -- Variable: number t3php-outline-split-windows-fraction
     This variable describes the fraction of the width or height of the
     window, which is used for the outline.

     Default: `.3'.

 -- Variable: boolean t3php-outline-follow-mode
     If true, point in outline buffer will make T3PHP window to follow.
     It will show the corresponding part of the document. This flag can
     be toggled from within the outline buffer with the `f' key.

     Default: `nil'.

 -- Variable: color t3php-outline-hl-line-color
     The color used to highlight the background of the horizontal line
     which marks the current line of the outline buffer and the
     corresponding line in the T3PHP buffer when follow mode is active.

     Default: `DarkSlateBlue'.

 -- Variable: color t3php-outline-method-name-color
     The color used to highlight the lines in the outline, which refer
     to the corresponding method.

     Default: `sea green'.

   ---------- Footnotes ----------

   (1) Note the different meanings of _newline_ and _new line_, that
goes with their different spellings. _newline_ refers to the code
representation of a new line, while _new line_ means its interpretation
as a visible new line in the editor after pressing `<RET>'.


File: t3php-mode.info,  Node: Syntax highlighting,  Next: Line indentation,  Prev: Customization,  Up: Using T3PHP mode

3.2 Syntax highlighting
=======================

Syntax highlighting is a convenient feature of an editor to improve the
appearance hence the readability of code. TYPO3 Mode supports the
highlighting of single line and multiline comments, keywords and several
syntactic structures.

   In XEmacs syntax highlighting should be enabled automatically. In GNU
Emacs you may have to add these lines to your `~/.emacs' file:
     (global-font-lock-mode t)
     (setq font-lock-maximum-decoration t)


File: t3php-mode.info,  Node: Line indentation,  Next: Inserting code templates,  Prev: Syntax highlighting,  Up: Using T3PHP mode

3.3 Line indentation
====================

A PHP code line is indented automatically when the <TAB> key is pressed
while point is on the according line. The indentation takes place with
respect to the indentation of previous lines. *Note Customization::,
for details. The default width is `4'.

   Depending on the current value of the customizable variable
T3PHP-NEWLINE-FUNCTION, line indentation might be executed
automatically after pressing `<RET>'. *Note Customization::, for
details.


File: t3php-mode.info,  Node: Inserting code templates,  Prev: Line indentation,  Up: Using T3PHP mode

3.4 Inserting code templates
============================

The following sections describe functions and their respective key
bindings to insert templates for methods and classes.

* Menu:

* Inserting methods::
* Inserting classes::


File: t3php-mode.info,  Node: Inserting methods,  Next: Inserting classes,  Up: Inserting code templates

3.4.1 Inserting methods
-----------------------

 -- Interactive Command: t3php-insert-method
     Insert the rudimentary method framework code with respect to TYPO3
     coding standards. The function asks interactively for the method
     name, an auto-completed modifier (`public', `protected',
     `private') and method arguments until an empty string is provided.
     The inserted code consists of
        * a class header comment in PHPdoc style which contains
             - empty lines for method descriptions

             - `@param' and variable name

             - `@return'

             - `@author' (default: `t3php-developer')

             - `@since' (default: `t3php-date-format')

        * the method signature

     Key binding: `C-c C-if'.
The following example was inserted with parameters
   * Method name: `foobar'

   * Modifier: `public'

   * Parameter: `foo'

   * Parameter: `bar'

1  /**
2   *
3   *
4   * @param $foo
5   * @param $bar
6   * @return
7   * @author Lisa Fremont <lisa@fremont.de>
8   * @since 2009-12-02
9   */
10 public function foobar($foo, $bar) {
11
12 }


File: t3php-mode.info,  Node: Inserting classes,  Next: Buffer outline,  Prev: Inserting methods,  Up: Inserting code templates

3.4.2 Inserting classes
-----------------------

 -- Interactive Command: t3php-insert-class
     Insert the rudimentary class framework code with respect to TYPO3
     coding standards. The inserted code consists of
        * PHP tags

        * a copyright notice where date and author are inserted
          automatically with respect to customizable variables
          `t3php-year-format' and `t3php-developer'. See *note
          t3php-year-format: x-t3php-year-format. and *note
          x-t3php-developer: x-t3php-developer, for more information.

        * a marker comment for the class and function index which can
          be inserted by TYPO3 extension _extdeval_. The following
          empty lines might be filled with required files.

        * a class header comment in PHPdoc style which contains
             - `@author' (default: `t3php-developer')

             - `@package' (default: `TYPO3')

             - `@subpackage' (default: empty)

             - `@since' (default: `t3php-date-format')

        * the class definition

        * a TYPO3 XCLASS inclusion code snippet for class extension
          and/or overriding. The associative array `TYPO3_CONF_VARS'
          has a key which refers to the current class path and file
          name, which is inserted dynamically. The information is
          extracted from the customizable variables
          `t3php-path-to-typo3-extension-directory' and the buffer file
          name. See *note t3php-typo3-extension-directory:
          x-t3php-typo3-extension-directory, for more information.

     Key binding: `C-c C-ic'.
The following code example was inserted in an empty file named
`class.bar.php':
1  <?php
2  /***************************************************************
3   *  Copyright notice
4   *
5   *  (c) 2009 Lisa Fremont <lisa@fremont.de>
6   *  All rights reserved
7   *
8   *  This script is part of the TYPO3 project. The TYPO3 project is
9   *  free software; you can redistribute it and/or modify
10  *  it under the terms of the GNU General Public License as published by
11  *  the Free Software Foundation; either version 2 of the License, or
12  *  (at your option) any later version.
13  *
14  *  The GNU General Public License can be found at
15  *  http://www.gnu.org/copyleft/gpl.html.
16  *
17  *  This script is distributed in the hope that it will be useful,
18  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
19  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
20  *  GNU General Public License for more details.
21  *
22  *  This copyright notice MUST APPEAR in all copies of the script!
23  ***************************************************************/
24 /**
25  * [CLASS/FUNCTION INDEX of SCRIPT]
26  *
27  * Hint: use extdeveval to insert/update function index above.
28  */
29
30
31
32
33
34 /**
35  *
36  *
37  * @author     Lisa Fremont <lisa@fremont.de>
38  * @package    TYPO3
39  * @subpackage
40  * @since      2009-12-02
41  */
42 class tslib_content {
43
44 }
45
46
47 /*******************************************************************************
48  * TYPO3 XCLASS INCLUSION (for class extension/overriding)
49  ******************************************************************************/
50 if (defined('TYPO3_MODE') && $TYPO3_CONF_VARS[TYPO3_MODE]['XCLASS']['ext/foo/class.bar.php']) {
51     include_once($TYPO3_CONF_VARS[TYPO3_MODE]['XCLASS']['ext/foo/class.bar.php']);
52 }
53 ?>


File: t3php-mode.info,  Node: Buffer outline,  Prev: Inserting classes,  Up: Using T3PHP mode

3.5 Buffer outline
==================

The outline buffer summarizes the methods of the PHP buffer and provides
comfortable navigation through the PHP buffer. The first three lines are
intangible and show the file name of the current PHP input file and the
shortcuts of the most important commands.

   Each method in the current PHP buffer is referred to by its name. The
maximally displayed line width of a method name is limited to 40
characters. Thus, a longer name is chopped to a length of 40 characters
and ellipse characters (`...') are concatenated. When you move the
mouse cursor over a method name the complete name is displayed
nevertheless. On graphical displays, it is displayed as a _tooltip_ or
_balloon help_ as it is called sometimes. On some systems, it is shown
in the echo area. On text-only terminals, Emacs can't follow the mouse,
and therefore is not able to show the complete name on mouse-over.

   The character and color of the leftmost column indicates the type of
method modifier:
`private'
     `[-]' (color: `firebrick')

`protected'
     `[#]' (color: `goldenrod')

`public'
     `[+]' (color: `forest green')

   The rightmost column presents the line numbers, which delimit the
region of the respective measurement block.
TABLE OF CONTENTS of ~/public_html/typo3/t3lib/class.t3lib_extmgm.php
SPC=view TAB=goto RET=goto+kill [f]ollow [r]escan  [k]ill [?]Help
-----------------------------------------------------------------------
[P] isLoaded                                      [  131-136  ]
[P] extPath                                       [  147-155  ]
[P] extRelPath                                    [  165-172  ]
[P] siteRelPath                                   [  182-185  ]
[P] getCN                                         [  194-197  ]
[P] addTCAcolumns                                 [  227-235  ]
[P] addToAllTCAtypes                              [  251-304  ]
[P] allowTableOnStandardPages                     [  315-320  ]
[P] addModule                                     [  332-378  ]
[P] addModulePath                                 [  390-395  ]
[P] insertModuleFunction                          [  412-421  ]
[P] addPageTSConfig                               [  431-435  ]
[P] addUserTSConfig                               [  445-449  ]
[P] addLLrefForTCAdescr                           [  460-472  ]

 -- Interactive Command: t3php-outline rescan
     This command shows the outline of the current PHP buffer. If
     RESCAN is true, the PHP buffer will be rescanned before the ouline
     buffer is displayed.

     Key binding `C-ct'.

The outline buffer is a read-only buffer with few dedicated key
bindings:
`n'
     Move to the next selectable item.

`<RIGHT>'
     Move to the next selectable item.

`<DOWN>'
     Move to the next selectable item.

`p'
     Move to the previous selectable item.

`<LEFT>'
     Move to the previous selectable item.

`<UP>'
     Move to the previous selectable item.

`C-<HOME>'
     Move to the beginning of the outline buffer.

`C-<END>'
     Move to the end of the outline buffer.

`<SPC>'
     Show the corresponding location of the TYPO3 buffer.

`<TAB>'
     Go to the corresponding location of the TYPO3 buffer and keep the
     outline window.

`<RET>'
     Go to the corresponding location of the TYPO3 buffer and hide the
     outline window.

`f'
     Toggle follow mode.

`r'
     Re-parse the TYPO3 buffer.

`k'
     Kill the outline buffer.

`?'
     Show a help buffer.


File: t3php-mode.info,  Node: TYPO3 Coding Guidelines,  Next: Key Index,  Prev: Using T3PHP mode,  Up: Top

Appendix A TYPO3 Coding Guidelines
**********************************

This appendix refers to the section _PHP file formatting_ of the manual
`TYPO3 Coding Guidelines' by the _TYPO3 Core Development Team_. I
decided to append this documentation to have a reference nearby,
whenever I think of extending any T3PHP Mode features.

* Menu:

* General requirements::
* File structure::
* PHP syntax formatting::
* Using phpDoc::
* The ChangeLog file::


File: t3php-mode.info,  Node: General requirements,  Next: File structure,  Up: TYPO3 Coding Guidelines

A.1 General requirements
========================

* Menu:

* PHP tags::
* Line breaks::
* Line length::
* Whitespace and indentation::
* Character set::


File: t3php-mode.info,  Node: PHP tags,  Next: Line breaks,  Up: General requirements

A.1.1 PHP Tags
--------------

Each PHP file in TYPO3 must use full PHP tags. There must be exactly one
pair of opening and closing tags (no closing and opening tags in the
middle of the file). Example:
<?php
    // File content goes here
?>
   There must be no empty lines after the closing PHP tag. Empty lines
after closing tags break output compression in PHP and/or result in AJAX
errors.


File: t3php-mode.info,  Node: Line breaks,  Next: Line length,  Prev: PHP tags,  Up: General requirements

A.1.2 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.


File: t3php-mode.info,  Node: Line length,  Next: Whitespace and indentation,  Prev: Line breaks,  Up: General requirements

A.1.3 Line length
-----------------

Line length is limited to 80 characters. Longer lines should be split to
several lines. Each line fragment starting from the second must be
indented with one or more tab characters. Example:
       $rows = $GLOBALS['TYPO3_DB']->exec_SELECTgetRows('uid, title', 'pages',
                    'pid=' . $this->fullQuoteStr($this->pid, 'pages') .
                    $this->cObj->enableFields('pages'), '', 'title');
   In certain cases splitting lines exactly at 80 characters is not
feasible. In this case lines can be longer but such practice is
discouraged.


File: t3php-mode.info,  Node: Whitespace and indentation,  Next: Character set,  Prev: Line length,  Up: General requirements

A.1.4 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


File: t3php-mode.info,  Node: Character set,  Prev: Whitespace and indentation,  Up: General requirements

A.1.5 Character set
-------------------

TYPO3 PHP files use iso-8859-1 character set.

All XML files use UTF-8 character set.


File: t3php-mode.info,  Node: File structure,  Next: PHP syntax formatting,  Prev: General requirements,  Up: TYPO3 Coding Guidelines

A.2 File structure
==================

TYPO3 files use the following structure:
  1. Opening PHP tag

  2. Copyright notice

  3. File information block (with optional function index) in phpDoc
     format

  4. Included files

  5. Class information block in phpDoc format

  6. PHP class

  7. XCLASS declaration

  8. Optional module execution code (for example, in eID classes)
        The following sections discuss each of these parts.

* Menu:

* Copyright notice::
* File information block::
* Included files::
* Class information block::
* PHP class::
* XCLASS declaration::
* Optional module execution code::


File: t3php-mode.info,  Node: Copyright notice,  Next: File information block,  Up: File structure

A.2.1 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 GPL
must be included at the top of every TYPO3 PHP class file. `user_'
files must have this copyright notice as well. Example:
<?php
/***************************************************************
 *  Copyright notice
 *
 *  (c) YYYY Your name here (your@email.here)
 *  All rights reserved
 *
 *  This script is part of the TYPO3 project. The TYPO3 project is
 *  free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  The GNU General Public License can be found at
 *  http://www.gnu.org/copyleft/gpl.html.
 *  A copy is found in the textfile GPL.txt and important notices to the license
 *  from the author is found in LICENSE.txt distributed with these scripts.
 *
 *
 *  This script is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  This copyright notice MUST APPEAR in all copies of the script!
 ***************************************************************/

This notice may not be altered except for the year, author name and
author e-mail.


File: t3php-mode.info,  Node: File information block,  Next: Included files,  Prev: Copyright notice,  Up: File structure

A.2.2 File information block
----------------------------

File information block follows the copyright statement and provides
basic information about the file. It should include file name,
description of the file and information about the author (or authors).
Example:
/**
 * class.tx_myext_pi1.php
 *
 * Provides XYZ plugin implementation.
 *
 * $Id: class.tx_myext_pi1.php 9514 2008-07-23 17:06:12Z john_doe $
 *
 * @author John Doe <john.doe@example.com>
 */
 The example above uses SVN $Id$ meta keyword. SVN will expand it to a
full version string when the file is committed.  The file information
block can also contain the optional function index. This index is
created and updated by the extdeveval extension.


File: t3php-mode.info,  Node: Included files,  Next: Class information block,  Prev: File information block,  Up: File structure

A.2.3 Included files
--------------------

Files are included using `require_once' function. All TYPO3 files must
use absolute paths in calls to `require_once'. There are two ways to
obtain the path to the included file:

  1. Use one of the predefined TYPO3 constants: `PATH_tslib',
     `PATH_t3lib', `PATH_typo3', `PATH_site'. The first three contain
     absolute paths to the corresponding TYPO3 directories. The last
     constant contains absolute path to the TYPO3 root directory.
     Example: require_once(PATH_tslib . 'class.tslib_pibase.php');

  2. Use `t3lib_extMgm::extPath()' function. This function accepts two
     arguments: extension key and path to the included file. The second
     argument is optional but recommended to use. Examples: require_once(t3lib_extMgm::extPath('lang', 'lang.php'));
     require_once(t3lib_extMgm::extPath('lang') . 'lang.php');
        Always use one of these two ways to include files. This is
required to include files even from the current directory. Some
installations do not have the current directory in the PHP include path
and `require_once' without a proper path will result in fatal PHP error.


File: t3php-mode.info,  Node: Class information block,  Next: PHP class,  Prev: Included files,  Up: File structure

A.2.4 Class information block
-----------------------------

Class information block is similar to the file information block and
describes the class in the file. Example:
/**
 * This class provides XYZ plugin implementation.
 *
 * @author John Doe <john.doe@example.com>
 * @author Jane Doe <jane.doe@example.com>
 */


File: t3php-mode.info,  Node: PHP class,  Next: XCLASS declaration,  Prev: Class information block,  Up: File structure

A.2.5 PHP class
---------------

PHP class follows the Class information block. PHP code must be
formatted as described in *note PHP syntax formatting::.  The class name
is expected to follow some conventions. The namespace and path parts are
all lowercase and separated by underscores (`_'). At the end comes the
"true" class name which must be written in upper camel case.  Taking
again the example of file
`class.t3lib_cache_backend_abstractbackend.php', the PHP class
declaration will look like:
class t3lib_cache_backend_AbstractBackend {
    ...
}


File: t3php-mode.info,  Node: XCLASS declaration,  Next: Optional module execution code,  Prev: PHP class,  Up: File structure

A.2.6 XCLASS declaration
------------------------

The XCLASS declaration must follow the PHP class. The format of the
XCLASS is very important. No spaces can be added or removed, no
reformatting can be done to the declaration. If the formatting is
changed, the TYPO3 Extension Manager will complain about a missing
XCLASS declaration.

   The XCLASS declaration must include proper path to the current class
file. The following example assumes that extension key is `myext', file
name is `class.tx_myext_pi1.php' and file is located in the `pi1'
subdirectory of the extension:
if (defined('TYPO3_MODE') && $TYPO3_CONF_VARS[TYPO3_MODE]['XCLASS']['ext/myext/pi1/class.tx_myext_pi1.php'])    {
    include_once($TYPO3_CONF_VARS[TYPO3_MODE]['XCLASS']['ext/myext/pi1/class.tx_myext_pi1.php']);
}


File: t3php-mode.info,  Node: Optional module execution code,  Prev: XCLASS declaration,  Up: File structure

A.2.7 Optional module execution code
------------------------------------

Module execution code instantiates the class and runs its method(s).
Typically this code can be found in eID scripts and old Backend
modules. Here is how it may look like:
$controller = t3lib_div::makeInstance('tx_myext_ajaxcontroller');
$controller->main();
 This code must appear _after_ the XCLASS declaration. `$SOBE' is
traditional but not required name.


File: t3php-mode.info,  Node: PHP syntax formatting,  Next: Using phpDoc,  Prev: File structure,  Up: TYPO3 Coding Guidelines

A.3 PHP syntax formatting
=========================

* Menu:

* Identifiers::
* Comments::
* Debug output::
* Curly braces::
* Conditions::
* Switch::
* Loops::
* Strings::
* Booleans::
* PHP5 features::
* Global variables::
* Functions::


File: t3php-mode.info,  Node: Identifiers,  Next: Comments,  Up: PHP syntax formatting

A.3.1 Identifiers
-----------------

All identifiers must use camelCase and start with a lower case letter.
Underscore characters are not allowed.  Abbreviations should be
avoided. Examples of good identifiers:
$goodName
$anotherGoodName
   Examples of bad identifiers:
$BAD_name
$unreasonablyLongNamesAreBadToo
$noAbbrAlwd
   Identifier names must be descriptive. However it is allowed to use
traditional integer variables like `$i', `$j', `$k' in for loops. If
such variables are used, their meaning must be absolutely clear from
the context where they are used.  The same rules apply to functions and
class methods. Examples:
protected function getFeedbackForm()
public function processSubmission()
   Class constants should be clear about what they define. Correct:
const USERLEVEL_MEMBER = 1;
   Incorrect:
const UL_MEMBER = 1;
   Variables on the global scope may use upper case and underscore
characters.  Examples:
$TYPO3_CONF_VARS
$TYPO3_DB


File: t3php-mode.info,  Node: Comments,  Next: Debug output,  Prev: Identifiers,  Up: PHP syntax formatting

A.3.2 Comments
--------------

Comments in the code are highly welcome and recommended. Inline comments
must precede the commented line and be indented by one tab. Example:
protected function processSubmission() {
              // Check if user is logged in
       if ($GLOBALS['TSFE']->fe_user->user['uid']) {
              ...
       }
}
   Class constants and variable comments should follow PHP doc style and
precede the variable. Variable type must be specified for non–trivial
types and optional for trivial types. Example:
       /** Number of images submitted by user */
       protected $numberOfImages;
       /**
         * Local instance of tslib_cObj class
         *
         * @var tslib_cObj
         */
       protected $localCobj;
   Single line comments are allowed when there is no type declaration
for the class variable or constant. If a variable can hold values of
different types, use `mixed' as type.


File: t3php-mode.info,  Node: Debug output,  Next: Curly braces,  Prev: Comments,  Up: PHP syntax formatting

A.3.3 Debug output
------------------

During development it is allowed to use `debug()' or
`t3lib_div::debug()' function calls to produce debug output. However
all debug statements must be removed (removed, not commented!) before
committing the code to the Subversion repository.


File: t3php-mode.info,  Node: Curly braces,  Next: Conditions,  Prev: Debug output,  Up: PHP syntax formatting

A.3.4 Curly braces
------------------

Usage of opening and closing curly braces is mandatory in all cases
where they can be used according to PHP syntax (except `case'
statements).

   The opening curly brace is always on the same line as the preceding
construction. There must be a space (not a tab!) before the opening
brace. The opening brace is always followed by a new line.

   The closing curly brace must start on a new line and be indented to
the same level as the construct with the opening brace. Example:
protected function getForm() {
       if ($this->extendedForm) {
             // generate extended form here
       } else {
             // generate simple form here
       }
}
The following is not allowed:
protected function getForm()
{
       if ($this->extendedForm) { // generate extended form here
       } else {
             // generate simple form here
       }
}


File: t3php-mode.info,  Node: Conditions,  Next: Switch,  Prev: Curly braces,  Up: PHP syntax formatting

A.3.5 Conditions
----------------

Conditions consist from `if', `elseif' and `else' keywords. TYPO3 code
must not use the `else if' construct.


The following is the correct layout for conditions:
        if ($this->processSubmission) {
              // Process submission here
        } elseif ($this->internalError) {
              // Handle internal error
        } else {
              // Something else here
        }
   Here is an example of the incorrect layout:
        if ($this->processSubmission) {
              // Process submission here
        }
        elseif ($this->internalError) {
              // Handle internal error
        } else { // Something else here
   It is recommended to create conditions so that shortest block goes
first. For example:
        if (!$this->processSubmission) {
              // Generate error message, 2 lines
        } else {
              // Process submission, 30 lines
        }
   If the condition is long, it must be split into several lines. Each
condition on the line starting from the second should be indented with a
two or more indents relative to the first line of the condition:
        if ($this->getSomeCodition($this->getSomeValiarble()) &&
                     $this->getAnotherCondition()) {
              // Code follows here
        }
   Ternary conditional operator must be used only if it has two
outcomes. Example:
$result = ($useComma ? ',' : '.');
   Wrong usage of ternary conditional operator:
$result = ($useComma ? ',' : $useDot ? '.' : ';');
   Assignment in conditions should be avoided. However if it makes
sense to do assignment in condition, it should be surrounded by the
extra pair of brackets. Example:
        if (($fields = $GLOBALS['TYPO3_DB']->sql_fetch_result($res))) {
              // Do something
        }
   The following is allowed but not recommended:
        if (false !== ($fields = $GLOBALS['TYPO3_DB']->sql_fetch_result($res))) {
              // Do something
        }
   The following is not allowed (missing the extra pair of brackets):
        while ($fields = $GLOBALS['TYPO3_DB']->sql_fetch_result($res)) {
              // Do something
        }


File: t3php-mode.info,  Node: Switch,  Next: Loops,  Prev: Conditions,  Up: PHP syntax formatting

A.3.6 Switch
------------

`case' statements are indented with a single indent (tab) inside the
`switch' statement. The code inside the `case' statements is further
indented with a single indent. The `break' statement is aligned with
the code. Only one `break' statement is allowed per `case'.

   The `default' statement must be the last in the `switch' and must
not have a `break' statement.

   If one `case' block has to pass control into another `case' block
without having a `break', there must be a comment about it in the code.

Examples:
switch ($useType) {
      case 'extended':
            $content .= $this->extendedUse();
            // Fall through
      case 'basic':
            $content .= $this->basicUse();
            break;
      default:
            $content .= $this->errorUse();
}


File: t3php-mode.info,  Node: Loops,  Next: Strings,  Prev: Switch,  Up: PHP syntax formatting

A.3.7 Loops
-----------

The following loops can be used:
   * `do'

   * `while'

   * `for'

   * `foreach'
   The use of each is not allowed in loops.

   `for' loops must contain only variables inside (no function calls).
The following is correct:
      $size = count($dataArray);
      for ($element = 0; $element < $size; $element++) {
            // Process element here
      }
   The following is not allowed:
      for ($element = 0; $element < count($dataArray); $element++) {
            // Process element here
      }
   `do' and `while' loops must use extra brackets if assignment happens
in the loop:
      while (($fields = $GLOBALS['TYPO3_DB']->sql_fetch_result($res))) {
            // Do something
      }


File: t3php-mode.info,  Node: Strings,  Next: Booleans,  Prev: Loops,  Up: PHP syntax formatting

A.3.8 Strings
-------------

All strings must use single quotes. Double quotes are allowed only to
create the new line character ("`\n'").  String concatenation operator
must be surrounded by spaces. Example:
        $content = 'Hello ' . 'world!';
   However the space after the concatenation operator must not be
present if the operator is the last construction on the line. *Note
Whitespace and indentation::, for more information.

Variables must not be embedded into strings. Correct:
        $content = 'Hello ' . $userName;
   Incorrect:
        $content = “Hello $userName”;
   Multiline string concatenations are allowed. Line concatenation
operator must be at the end of the line. Lines starting from the second
must be indented relative to the first line. It is recommended to
indent lines one level from the start of the string on the first level:
        $content = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. ' .
                          'Donec varius libero non nisi. Proin eros.';


File: t3php-mode.info,  Node: Booleans,  Next: PHP5 features,  Prev: Strings,  Up: PHP syntax formatting

A.3.9 Booleans
--------------

Booleans must use PHP's language constructs and not explicit integer
values like 0 or 1. Furthermore they should be written in uppercase,
i.e. `TRUE' and `FALSE'.


File: t3php-mode.info,  Node: PHP5 features,  Next: Global variables,  Prev: Booleans,  Up: PHP syntax formatting

A.3.10 PHP5 features
--------------------

The use of PHP5 features is strongly recommended for extensions and
mandatory for the TYPO3 core versions 4.2 or greater.

   Class functions must have access type specifier: `public',
`protected' or `private'. Notice that private may prevent XCLASSing of
the class. Therefore private can be used only if it is absolutely
necessary.

Class variables must use access specifier instead of `var' keyword.

Type hinting must be used when function expects array or an instance of
a certain class. Example:
       protected function executeAction(tx_myext_action& $action, array $extraParameters) {
             // Do something
       }
   Static functions must use `static' keyword. This keyword must be the
first keyword in the function definition:
       static public function executeAction(tx_myext_action& $action, array $extraParameters) {
             // Do something
       }
   `abstract' keyword also must be on the first position in the
function declaration:
       abstract protected function render();


File: t3php-mode.info,  Node: Global variables,  Next: Functions,  Prev: PHP5 features,  Up: PHP syntax formatting

A.3.11 Global variables
-----------------------

Use of `global' is not recommended. Always use `$GLOBALS['variable']'.


File: t3php-mode.info,  Node: Functions,  Prev: Global variables,  Up: PHP syntax formatting

A.3.12 Functions
----------------

If a function returns a value, it must always return it. The following
is not allowed:
function extendedUse($enabled) {
       if ($enabled) {
              return 'Extended use';
       }
}
   The following is the correct behavior:
function extendedUse($enabled) {
       $content = '';
       if ($enabled) {
              $content = 'Extended use';
       }
       return $content;
}
   In general there should be a single return statement in the function
(see the preceding example). However a function can return during
parameter validation before it starts its main logic. Example:
function extendedUse($enabled, tx_myext_useparameters $useParameters) {
       // Validation
       if (count($useParameters->urlParts) < 5) {
              return 'Parameter validation failed';
       }
       // Main functionality
       $content = '';
       if ($enabled) {
              $content = 'Extended use';
       } else {
              $content = 'Only basic use is available to you!';
       }
       return $content;
}
   Functions should not be long. "Long" is not defined in terms of
lines. General rule is that function should fit into 2/3 of the screen.
This rule allows small changes in the function without splitting the
function further.


File: t3php-mode.info,  Node: Using phpDoc,  Next: The ChangeLog file,  Prev: PHP syntax formatting,  Up: TYPO3 Coding Guidelines

A.4 Using phpDoc
================

phpDoc is used for documenting source code. Typically TYPO3 code uses
the following phpDoc keywords:
   * @author

   * @access

   * @global

   * @param

   * @package

   * @return

   * @see

   * @subpackage

   * @var
   For more information on phpDoc see the phpDoc web site at
`http://www.phpdoc.org/' TYPO3 requires that each class, function and
method is documented with phpDoc. For information on phpDoc with use in
classes see *note Class information block::. Note that the @author tag
should *not* be used in function or method phpDoc comment blocks --
only at class level -- because it is too liable to change frequently
and authors would accumulate indefinitely. `svn blame' is enough for
tracking changes.  Functions should have parameters and return type
documented. Example:
/**
  * Initializes the plugin. Checks the configuration and substitutes defaults for missing values.
  * @param   array $conf Plugin configuration from TypoScript
  * @return void
  * @see     tx_myext_class:anotherFunc()
  */
protected function initialize(array $conf) {
       // Do something
}
   Notice the use of `void' when function does not return a value.


File: t3php-mode.info,  Node: The ChangeLog file,  Prev: Using phpDoc,  Up: TYPO3 Coding Guidelines

A.5 The ChangeLog file
======================

TYPO3 core has a `ChangeLog' file where all changes are recorded. This
file is committed to the SVN together with the change.

Each entry in the ChangeLog file has the following format:
   * Information about the date of the change (YYYY-mm-dd), author name
     and author's e-mail address. These three pieces of information are
     separated strictly by two spaces (no tabs!)

   * Empty line

   * One or more lines describing the change. Each such line is
     indented by a single tab

   * Empty line

   * Line that describes the change consists from the following parts:

   * Asterisk character

   * Type of the change ("Fixed bug" or "Added feature")

   * Bug tracker issue id ("#12345")

   * A colon

   * Bug tracker issue title or, if needed, a more meaningful title that
     describes the change ("great feature for TYPO3")

   * Optional “thanks to” message of the patch was submitted by the
     contributor
   In some cases the line can have free format. This applies to
non–functional changes, like "Formatting change" or "Fixed copyright
dates").

Here is an example of the ChangeLog entry:
2009-01-06   John Doe   <john@doe.com>
      * Fixed bug #12345: typolink does not take XYZ into account
      * Added feature #12345: Google sitemap in the TYPO3 core (thanks to Jane Doe)
   `ChangeLog' file updates are mandatory for every change in the TYPO3
core. Extension authors are strongly recommended to use such file with
the same format in their extensions.


File: t3php-mode.info,  Node: Key Index,  Next: Variable Index,  Prev: TYPO3 Coding Guidelines,  Up: Top

Key Index
*********

�[index�]
* Menu:

* <DOWN>:                                Buffer outline.        (line 6)
* <LEFT>:                                Buffer outline.        (line 6)
* <RET>:                                 Buffer outline.        (line 6)
* <RIGHT>:                               Buffer outline.        (line 6)
* <SPC>:                                 Buffer outline.        (line 6)
* <TAB>:                                 Buffer outline.        (line 6)
* <UP>:                                  Buffer outline.        (line 6)
* ?:                                     Buffer outline.        (line 6)
* C-<END>:                               Buffer outline.        (line 6)
* C-<HOME>:                              Buffer outline.        (line 6)
* C-c C-t:                               Buffer outline.        (line 6)
* f:                                     Buffer outline.        (line 6)
* k:                                     Buffer outline.        (line 6)
* n:                                     Buffer outline.        (line 6)
* p:                                     Buffer outline.        (line 6)
* r:                                     Buffer outline.        (line 6)


File: t3php-mode.info,  Node: Variable Index,  Next: Function Index,  Prev: Key Index,  Up: Top

Variable Index
**************

�[index�]
* Menu:

* t3php-block-indentation:               Customization.       (line  43)
* t3php-date-format:                     Customization.       (line  33)
* t3php-developer:                       Customization.       (line  15)
* t3php-newline-function:                Customization.       (line  49)
* t3php-outline-follow-mode:             Customization.       (line 167)
* t3php-outline-hl-line-color:           Customization.       (line 174)
* t3php-outline-keep-other-windows:      Customization.       (line 118)
* t3php-outline-method-name-color:       Customization.       (line 181)
* t3php-outline-split-windows-fraction:  Customization.       (line 161)
* t3php-outline-split-windows-horizontally: Customization.    (line 130)
* t3php-path-to-typo3-extension-directory: Customization.     (line  27)
* t3php-php-doc-align:                   Customization.       (line  70)
* t3php-php-manual-url:                  Customization.       (line 106)
* t3php-php-search-url:                  Customization.       (line 112)
* t3php-typo3-extension-directory:       Customization.       (line  21)
* t3php-year-format:                     Customization.       (line  38)


File: t3php-mode.info,  Node: Function Index,  Prev: Variable Index,  Up: Top

Function Index
**************

�[index�]
* Menu:

* t3php-insert-class:                    Inserting classes.    (line  7)
* t3php-insert-method:                   Inserting methods.    (line  7)
* t3php-outline:                         Buffer outline.       (line 53)



Tag Table:
Node: Top982
Node: Introduction2198
Node: Installation2692
Node: Using T3PHP mode3716
Node: Customization4123
Ref: x-t3php-developer4660
Ref: x-t3php-typo3-extension-directory4865
Ref: x-t3php-path-to-typo3-extension-directory5033
Ref: x-t3php-year-format5337
Ref: fig:split_v8663
Ref: fig:split_h9031
Ref: x-stswf9404
Ref: Customization-Footnote-110390
Node: Syntax highlighting10658
Node: Line indentation11275
Node: Inserting code templates11901
Node: Inserting methods12242
Node: Inserting classes13457
Node: Buffer outline17053
Node: TYPO3 Coding Guidelines20636
Node: General requirements21196
Node: PHP tags21458
Node: Line breaks21942
Node: Line length22247
Node: Whitespace and indentation22969
Node: Character set23669
Node: File structure23906
Node: Copyright notice24663
Node: File information block26284
Node: Included files27129
Node: Class information block28418
Node: PHP class28857
Node: XCLASS declaration29535…

Large files files are truncated, but you can click here to view the full file