Joomla! Documentation - User contributions [en]

Unit Testing

2010-10-19T17:46:55Z

Paladin: Corrected unit test file naming convention

{{cookiejar}}
== News and Updates ==
2009 10 06: Tests now depend on the SVN version of PHPUnit 3.4.1.

2008 06 24: Update to reflect move of PHPUnit code from branch to trunk (former trunk now in /branches/old_simpletest).

2008 06 22: Add information on limiting tests by version.

2008 06 21: Added --class-exclude, --sequence-exclude, and --test-exclude options.

2008 06 21: PHPUnit has been updated to version 3.2.21 with SVN rev 10436. Please update.

== Unit Testing ==
Unit testing is not only an essential part of a good Quality Control program, it is an aid to development as well. Writing new tests before writing code helps focus the developer on the problem at hand. The practice also encourages writing smaller, more loosely coupled, more reusable, and more maintainable code units and these benefits often outweigh the benefits gained by treating unit tests solely as a QC tool. When used in this manner correctness becomes more a by-product of the process than the goal.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with [http://seleniumhq.org/ Selenium], a browser based test automation tool. Writing a functional test using Selenium is documented [http://docs.joomla.org/Functional_Testing#Writing_Functional_Tests here].

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests.

The SVN repository contains code under the /testing path. /testing/trunk used to contain code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

The PHPUnit tests are found in '''/tests/unit''' in the development trunk. See [http://docs.joomla.org/Running_Automated_Tests_for_Version_1.6 Running Automated Tests for Version 1.6] for instructions on setting up unit testing in your IDE.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.

==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-Test.php, for example JObject-0000-class-Test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.
* The custom test runner is no longer needed. The current tests will run with the latest SVN version of PHPUnit 3.4. This code will eventually become PHPUnit 3.4.1. Thanks to Sebastian Bergmann for his excellent work on an excellent project!

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]], [[Unit_Testing_--_UI_Example|UI Example]].

==== Running Unit Tests ====
Test files follow the form classnameTest.php, for example JObjectTest.php. For tests that are not class based, use the name of the file being tested.

Joomla unit tests use the standard PHPUnit test runner. See http://www.phpunit.de for documentation.

== How to Get it Running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation. Since you will be using SVN to check out the testing project, you don't want to check out the Joomla! with SVN. Instead, simply unpack a normal Joomla! archive. If you are using Eclipse, you can create a folder in your Eclipse workspace for the Joomla! installation, but don't create an Eclipse project yet.
* In the root checkout (or export) the latest version of the unit test code from SVN ''"/testing/trunk/1.5/unittest"'' or ''"/testing/trunk/1.6/unittest"'' to your installation base. This will create a ''"/unittest"'' sub-folder under your joomla installation. If you are using Eclipse, Import the project from the SVN and use the same folder in your Eclipse workspace you used above.
* From the command line, change to the unittest directory.
* Run the unit test from the command prompt using the following command: <code>phpunit tests</code>

The unit test will the run, and the results are rendered. You will see a series of dots for each passed test and other letters for failed tests.

See http://www.phpunit.de/manual/current/en/textui.html for help using the --filter switch to run only certain tests. There are also many other command line switches you can use to get results in various formats.

== Troubleshooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like below, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

== Frequently Asked Questions ==
'''Why can't I use "phpunit ''testname.php''" to run my tests?'''

The test facility has to do some work to be able to load the "Joomla!" framework and to be able to inject mock classes. It's difficult to do this from the PHPUnit test runner, so we built our own. Also, the Joomla test runner has specific options designed to make it easy to select specific tests. Over time we will add more functionality to the test runner so it has many of the capabilities of the phpunit command.

==See also==
[http://www.phpunit.de/manual/current/en/ PHPUnit Manual]

[[Category:Bug Squad]]
[[Category:Development]]
[[Category:Testing]]
[[Category:Automated Testing]]

Coding style and standards

2010-09-29T22:25:50Z

Paladin: added reference to the Joomla CodeSniffer page

{{review}}
{{RightTOC}}
remark: The following information has been copied from the old WIKI archive has not yet been reviewed.
See: http://dev.joomla.org/component/option,com_jd-wiki/Itemid,/id,standards:coding/

Good coding standards are important in any development project, but particularly when multiple developers are working on the same project. Having coding standards helps ensure that the code is of high quality, has fewer bugs, and is easily maintained.

First rule, if in doubt, ask. There is [[Joomla_CodeSniffer|a tool available]] to help your code conform to the standards.

== File Format ==
All files contributed to Joomla must:

* Be stored as ASCII text
* Use UTF-8 character encoding
* Be Unix formatted
** Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.

New files will normally be added to the code base using Subversion (SVN). All SVN files should have the SVN property set "eol-style=LF". Also, most Joomla! files will have "$Id" tags in the "@version" line of the Doc block. These require the SVN property "keywords=Id". See [[Subversion File Properties]] for more information about how to set SVN properties.

== Coding Standards ==

=== Spelling ===

Spelling of class, function, variable and constant names should generally be in accordance with British English rules (en_GB). However, some exceptions are permitted, for example where common programming names are used that align with the PHP API such as <code>$color</code>.

=== E_STRICT-compatible code ===

As of version 1.6, all new code that is suggested for inclusion into Joomla must be E_STRICT-compatible. This means that it must not produce any warnings or errors when PHP's error reporting level is set to E_ALL | E_STRICT.

=== Indenting and Line Length ===

Use tabs to indent, not spaces. Make sure that the tab-stops are set to only 4 spaces in length.

There is no set limit for line length. Use your judgment based on the nature of the line and readability.

=== Control Structures ===

These include if, for, while, switch, etc. Here is an example of an if statement, as it is the most complicated of the control structures:

<source lang="php">
<?php
if ((condition1) || (condition2)) {
action1();
} else if ((condition3) && (condition4)) {
action2();
} else {
defaultAction();
anotherAction();
}

// optional formatting if it improves readability
if ((condition1) || (condition2)) {
action1();
} else if ((condition3) && (condition4)) {
action2();
} else {
defaultAction();
anotherAction();
}
</source>

Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

In '''layouts''', the alternative named notation should be used:

<source lang="php">
<?php
if ((condition1) OR (condition2)) :
action1();
elseif ((condition3) AND (condition4)) :
action2();
else :
defaultAction();
anotherAction();
endif;

foreach ($array as $element) :
echo $element;
endforeach;
</source>

Logical operators in condition statements should use uppercase words (<code>AND</code>, <code>OR</code>, etc) rather than programmatic notation (<code>&&</code>, <code>||</code>, etc).

With the exception of <code>case</code> statements, curly braces must always be included even though they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

For switch statements:

<source lang="php">
<?php
switch (condition) {
case 1:
doAction1();
break;
case 2:
doAction2();
break;
default:
doDefaultAction();
break;
}
</source>

Use indenting and line-breaks rather than curly braces in the <code>case</code> statements to increase readability. There should be no space between the condition and the colon in the <code>case</code> statement.

=== Function Calls ===

Functions should be called with no spaces between the function name and the opening parenthesis, and no space between this and the first parameter; a space after the comma between each parameter (if they are present), and no space between the last parameter and the closing parenthesis, and the semicolon. Here's an example:

<source lang="php">
<?php
$var = foo($bar, $baz, $quux);
</source>

As displayed above, there should be space before and one space after the equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, tabs (not spaces) may be inserted to promote readability:

<source lang="php">
<?php
$short = foo($bar);
$long_variable = foo($baz);
</source>

=== Function Definitions ===

Class and function declarations follow this convention:

<source lang="php">
<?php
function fooFunction($arg1, $arg2 = '')
{
if (condition) {
statement;
}
return $val;
}

class fooClass
{
function fooMethod($arg1)
{
if ($arg) {
$result = true;
} else {
$result = false;
}
return $result;
}
}
</source>

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example:

<source lang="php">
<?php
function connect(&$dsn, $persistent = false)
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}

if (!$dsninfo OR !$dsninfo['phptype']) {
return $this->raiseError();
}

return true;
}
</source>

=== Comments ===

Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: http://www.phpdoc.org/

See also [[Adding phpDocumentor comments]]

Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.

C style comments (<tt>/* */</tt>) and standard C++ comments (<tt>//</tt>) are both satisfactory. Use of Perl/shell style comments (<tt>#</tt>) is not permitted.

Please note - commented code is not to be committed to trunk or release repositories.

=== Including Code ===

Anywhere you are unconditionally including a class file, use <code>require_once</code>. Anywhere you are conditionally including a class file (for example, factory methods), use <code>include_once</code>. Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them -- a file included with <code>require_once</code> will not be included again by </code>include_once</code>.

;Note: [[php:include_once|include_once]] and [[php:require_once|require_once]] are PHP ''language statements'', not functions. You don't need parentheses around the filename to be included.

=== PHP Code Tags ===

Always use <tt><?php ?></tt> to delimit PHP code, not the <tt><? ?></tt> shorthand. This is the most portable way to include PHP code on differing operating systems and setups.

For files that contain only PHP code, the closing tag (<tt>?></tt>) is never permitted. It is not required by PHP. Not including it prevents trailing white space from being accidentally injected into the output (see PHP manual on [http://au.php.net/basic-syntax.instruction-separation instruction separation]).

=== SQL Queries ===

SQL keywords are to be written in uppercase, while all other identifiers (which the exception of quoted text obviously) is to be in lowercase. Carriage returns should not be used as [[JDatabase]]::getQuery provides for formatted output. However, indenting with spaces to improve readability is desireable.

Queries should be wrapped in single quotes (as these text blocks are parsed faster by php).

All quoted strings must use the ''Quote'' method to facilitate future compatibility with other database engines.

All table names should use the '''<tt>#_</tt>''' prefix rather than <tt>jos_</tt> to access Joomla! contents and allow for the [[screen.config.15#Database_Settings|user defined database prefix]] to be applied.

All expected integer or floating-point variable must be [http://php.net/manual/language.types.type-juggling.php cast] with <tt>(int)</tt>, <tt>(float)</tt> or <tt>(double)</tt> as appropriate.

<source lang="php">
$state = 1;
$name = 'bill';
$db = &JFactory::getDBO();
$query = 'SELECT COUNT( c.id ) AS num_articles, u.id, u.username'.
' FROM #__content AS c'.
' LEFT JOIN #__users AS u ON u.id = c.created_by'.
' WHERE c.state = '.(int) $state
' AND u.id IS NOT NULL'.
' AND u.username <> '.$db->Quote( $name ).
' GROUP BY u.id'.
' HAVING COUNT( c.id ) > 0';
$db->setQuery();
// Output formated query if joomla debug is active:
if (JDEBUG) {
echo $db->getQuery();
}
$stats = $db->loadObjectList();
</source>

=== Doc Blocks ===

All source code files in the core Joomla distribution must contain the following comment block as the header:

<source lang="php">
<?php
/**
* Short description of file
*
* Longer description of file is optional, but should be included if the file contains multiple classes or non-class material.
*
* PHP version 5.2.4 (put in the minimum version of PHP expected for the code here to run)
*
* @version $Id$
* @package Joomla
* @copyright Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license GNU/GPL, see LICENSE.php
*/
</source>

The <code>@package</code> in the header is not required for class-only files.

Classes, functions, constants, class properties and class methods should all be supplied with appropriate DocBlocks.

<source lang="php">
/**
* Short description for class
*
* Long description for class (if any)...
*
* @package PackageName
* @subpackage SubPackageName
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since Class available since Release 1.2.0
* @deprecated Class deprecated in Release 2.0.0
*/
class JFooBar
{
/**
* @var int $id Primary key
*/
public $id = null;
}
</source>

The following package names are to be used in the core stack:

* Joomla.Administrator - all files that belong only to the administrator or backend application
* Joomla.Installation - all files that belong to the installation application
* Joomla.Plugin - all plugin files
* Joomla.Site - all files that pertain only to the site or frontend application
* Joomla.XML-RPC - all files that belong to the XML-RPC server application

The sub-package name will vary according to the extension type:

* Components - the component folder, eg <code>com_content</code>
* Modules - the module folder, eg <code>mod_latest_news</code>
* Plugins - the folder.element, eg <code>content.pagebreak</code>
* Templates - the template folder, eg <code>rhuk_milkyway</code>
* Framework - nothing for top level files (such as <code>factory.php</code>), the first level folder or the first.second level folders as appropriate, eg <code>utilities</code> for <code>joomla/utilities/date.php</code>, <code>html.html</code> for <code>joomla/html/html/email.php</code>

Please note that code contributed to the Joomla stack that will become the copyright of the project is not allowed to include <code>@author</code> tags. You should update the contribution log in <tt>CREDITS.php</tt>. Joomla's philosophy is that the code is written "all together" and there is no notion of any one person 'owning' any section of code.

Files included from third party sources must leave DocBlocks intact. Layout files use the same DocBlocks as other PHP files.

Note that the "@version $Id" line uses the SVN "keywords=Id" property. See [[Subversion File Properties]] for information about setting this property.

== Naming Conventions ==

=== Classes ===

Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with an uppercase letter and be written in CamelCase even if using traditionally uppercase acronyms (such as XML, HTML). One exception is for Joomla framework classes which must begin with an uppercase 'J' with the next letter also being uppercase. For example:

* JHtmlHelper
* JXmlParser
* JModel

Third-party developers are advised to namespace their functions with a unique prefix.

=== Functions and Methods ===

Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). The initial letter of the name is lowercase, and each letter that starts a new "word" is capitalized. Function in the Joomla framework must begin with a lowercase 'j'. Some examples:

<source lang="php">
connect();
getData();
buildSomeWidget();
jImport();
jDoSomething();
</source>

Private class members (meaning class members that are intended to be used only from within the same class in which they are declared; are preceded by a single underscore. Properties are to be written in underscore format (that is, logical words separated by underscores) and should be all lowercase. For example:

<source lang="php">
class JFooBar
{
// Joomla 1.5 and earlier format
var $_status = null;

function _sort()
{
}

// Joomla 1.6 format
private $_status = null;

protected $field_name = null;

protected function _sort()
{
}
}
</source>

=== Constants ===

Constants should always be all-uppercase, with underscores to separate words. Prefix constant names with the uppercase name of the class/package they are used in. For example, the constants used by the [[JError]] class all begin with "JERROR_".

=== Global Variables ===

If your package needs to define global variables, their name should start with a single underscore followed by the uppercase class/package name and another underscore. For example, the JError class uses a global variable called $_JERROR_LEVELS.

With PHP5 and later you may use static class properties or constants instead of globals.
<source lang="php">
<?php
class JWhatever
{
public static $instance = null;
const SUCCESS = 1;
const FAILURE = 0;
// Methods...
}
</source>

=== Regular and Class Variables ===

Regular variables, follow the same conventions as function.

Class variables should be set to null or some other appropriate default value. Lining up the default values with tabs should only be used if particularly warranted for readability.

=== References ===

When using references, there should be a space before the reference operator and no space between it and the function or variable name. For example:

<source lang="php">
<?php
$ref1 = &$this->_sql;
$db = &JFactory::getDBO();
</source>

=== Language Keys ===

NOTE: This part has to be rewritten for 1.6 (JM)

Except for the most common of words, such as "Yes", "No", "Show", "Hide" all language keys should be namespaced to reflect the type of string they represent. Always consider that if two extensions use the same key, the one loaded last will be the one that displays. Namespacing should generally relate to the extension displaying the text. For example:

<source lang="php"><?php
echo JText::_('Weblink Link');
echo JText::_('Weblink Title');
echo JText::_('Weblink Description');

echo JText::_('Exception An error occurred while saving');
?></source>

TODO: Link to page with "common" strings that can be used for typical actions in components, such a "Save"

Where the same English word is used in two different locations, two different language keys should be used to allow for cases where the translation results in different words or phrases.

<source lang="php">
// A table column title
<th><?php echo JText::_('Weblink Column Title');?></th>
<th><?php echo JText::_('Weblink Column Link');?></th>

// In the form
<?php echo JText::_('Weblink Title');?><input name="title" />
<?php echo JText::_('Weblink Link');?><input name="link" />
</source>

Toolbar and Linkbar text should be prefixed Toolbar and Linkbar respectively.

The language keys should be written as naturally as possible with spaces, not underscores separating words. Long phrases can be condensed to reduce keys to a sensible length. For example, tooltips for an edit field can be written like this:

<source lang="php">
<?php echo JText::_('Weblink Title');?><input name="title" title="<?php echo JText::_('Weblink Title Desc');?>" />
</source>

The convention used should be governed by common sense, but must be consistent. In general consider how the language file will look with all keys sorted alphabetically. Prefixes should be used to group text within a common context (such as column headings). Suffixes should be used to group elements that logically go together (such as a field name and its description).

Phrases must never be assembled by string concatenation. Each phrase must be represented by a single language key, using sprintf as appropriate to replace dynamic words in the phrase. Where replacements are made, the word used should be as descriptive as possible and all-uppercase. This assists the translators to determine the context of the replacement.

<source lang="php"><?php
// Not permitted
echo JText::_('Deleted ').$n.JText::_(' items');

// Permitted
echo JText::sprintf('Message Deleted NUMBER items', $n);
?></source>

The reference in the language file would look like this:

<source lang="php">MESSAGE DELETED NUMBER ITEMS=Deleted %d Item(s)</source>

If more than one dynamic string is used in a phrase, the printf markers should employ order placement as other languages might change the position of the strings. This is done via %[number]$[printf_type] as follows:

Left to right language:

<source lang="php">PAGE X OF Y=Page %1$d of %2$d</source>

Right to left language:

<source lang="php">PAGE X OF Y=%2$d of %1$d egaP</source>

=== Controllers ===

For single controller components, the naming convention is ''[Name]Controller''.

<source lang="php">
<?php
/**
* Content Controller
* @package Joomla
*/
class ContentController extends JController
{
// Methods
}
</source>
The file name will generally be ''controller.php'' and is located in the component folder.
<source lang="text">
com_content
/ controller.php
</source>

For a multi-controller components, such as the Banners in the Administrator, the convention is ''[Component]Controller[Name]''.

<source lang="php">
<?php
/**
* Banner Client Controller
* @package Joomla
*/
class BannerControllerClient extends JController
{
// Methods
}
</source>

The files will be located in a <tt>/controllers/</tt> folder under the component folder. The file names will reflect the name of the controller.
<source lang="text">
com_banner
/controllers/
/ banner.php
/ client.php
</source>

=== Models===

The naming convention is ''[Component]Model[Name]''.

<source lang="php">
<?php
/**
* Banner Client Model
* @package Joomla
*/
class BannerModelClient extends JModel
{
// Methods
}
</source>

The files will be located in a <tt>/models/</tt> folder under the component folder. The file names will reflect the name of the model.

<source lang="text">
com_banner
/models/
/ banner.php
/ client.php
</source>

=== Views ===
The naming convention is ''[Component]View[Name]''.
<source lang="php">
<?php
/**
* Contact Category View
* @package Joomla
*/
class ContactViewCategory extends JView
{
// Methods
}
</source>
The files will be located in a <tt>/view/</tt> folder under the component folder. The subfolder names will reflect the name of a View.

com_contact
/views/
/''view name 1''/
/ view.html.php
/''view name 2''/
/ view.html.php

Multi-view components such as com_content may provide an optional "master" view class the specialised views extend from. It is located in the component folder and typically called ''view.php''. The naming convention is ''[Component]View''.

com_content
/views/
<span style="color:#999">/archive/</span>
/ view.html.php
<span style="color:#999">/article/</span>
/ view.php

<source lang="php">
view.php
<?php
/**
* Content View
* @package Joomla
*/
class ContentView extends JView
{
// Helper Methods
}

views/archive/view.html.php
<?php
/**
* Content Archive View
* @package Joomla
*/
class ContactViewArchive extends ContentView
{
// Methods
}

</source>

=== Plugins ===

The naming convention is ''plg[Folder][Element]'' as pointed out in [[How to create a content plugin|the relative HowTo page]].

<source lang="php">
class plgContentPagebreak extends JPlugin
{
// Methods
}
</source>

=== Layouts ===
Components may support different Layouts to render the data supplied by a [[#Views|View]] and its [[#Models|Models]]. A Layout file usually contains markup and some PHP code for ''display logic only'': no functions, no classes.

A Layout consists of at least one .php file and an equally named [[Creating a basic layout.xml file|.xml manifest file]] located in the <tt>/tmpl/</tt> folder of a View, both reflect the internal name of the Layout. The standard Layout is called ''default''.

<span style="color:#999">com_content
/views/
/article/</span><span style="color:#000">
/tmpl/
/ default.php
/ default.xml
/ form.php
/ form.xml
/ pagebreak.php
/ pagebreak.xml </span>

The Layout may use supplemental .php files to provide more granule control in order to render individual parts or repetitive items of the data.

Users may customize the Layout output via [[#Template Layout Overrides|Template Layout Overrides]].

=== Templates ===

=== Template Layout Overrides ===

Joomla CodeSniffer

2010-09-29T22:21:12Z

Paladin: /* A Nose For Joomla */

(This page needs expanded installation instructions, especially for Windows-based systems.)

== A Nose For Joomla ==

This is a custom coding standard for the PHP CodeSniffer that attempts to codify and enforce the Joomla coding standards.

==Why?==

The reasons seem obvious, but one look at reality shows they aren't, so I'll enumerate some of them here:

- Coherent and consisting coding practice makes the files look more professional. Conflicting styles in the same project (or worse, the same file) not only look sloppy, they encourage further sloppiness.

- When all code complies with the same standard, bad code is easier for everyone to spot.

- It makes it easier for someone new to a particular file in the project to find and fix errors, or extend functionality.

- If there is no consistent standard maintained, the sometimes developers will reformat the code to suit themselves. This causes a wide range of changes in the code repository, and if there is a later problem, a significant change could be lost in the chaff produced by a diff.

==Installation==

First you'll need to install phpcs (http://pear.php.net/package/PHP_CodeSniffer/download/). This set of files is intended to work with phpcs version 1.3, so behavior with any other version is undefined.

Then download and unzip the [http://joomlacode.org/gf/project/jcodesniffer/ Joomla CodeSniffer], and copy the contents of it into /path/to/PHP_CodeSniffer/Standards/Joomla. (The path on some systems is /usr/lib/php/PHP/PHP_CodeSniffer but this varies from system to system. Use

<code>pear config-get php_dir</code>

to find out where the PEAR directory is on your system, then add "/PHP/PHP_CodeSniffer" to it.)

You invoke the custom standard by

<code>phpcs --standard=Joomla --tab-width=4 file/to/sniff</code>

Further documentation on the use of phpcs can be found at: [http://pear.php.net/package/PHP_CodeSniffer/docs]

Joomla CodeSniffer

2010-09-29T22:19:32Z

Paladin: /* A Nose For Joomla */ fixed == error

== A Nose For Joomla ==

This is a custom coding standard for the PHP CodeSniffer that attempts to codify and enforce the Joomla coding standards.

==Why?==

The reasons seem obvious, but one look at reality shows they aren't, so I'll enumerate some of them here:

- Coherent and consisting coding practice makes the files look more professional. Conflicting styles in the same project (or worse, the same file) not only look sloppy, they encourage further sloppiness.

- When all code complies with the same standard, bad code is easier for everyone to spot.

- It makes it easier for someone new to a particular file in the project to find and fix errors, or extend functionality.

- If there is no consistent standard maintained, the sometimes developers will reformat the code to suit themselves. This causes a wide range of changes in the code repository, and if there is a later problem, a significant change could be lost in the chaff produced by a diff.

==Installation==

First you'll need to install phpcs (http://pear.php.net/package/PHP_CodeSniffer/download/). This set of files is intended to work with phpcs version 1.3, so behavior with any other version is undefined.

Then download and unzip the [http://joomlacode.org/gf/project/jcodesniffer/ Joomla CodeSniffer], and copy the contents of it into /path/to/PHP_CodeSniffer/Standards/Joomla. (The path on some systems is /usr/lib/php/PHP/PHP_CodeSniffer but this varies from system to system. Use

<code>pear config-get php_dir</code>

to find out where the PEAR directory is on your system, then add "/PHP/PHP_CodeSniffer" to it.)

You invoke the custom standard by

<code>phpcs --standard=Joomla --tab-width=4 file/to/sniff</code>

Further documentation on the use of phpcs can be found at: [http://pear.php.net/package/PHP_CodeSniffer/docs]

Joomla CodeSniffer

2010-09-29T22:19:06Z

Paladin: New page: == A Nose For Joomla == This is a custom coding standard for the PHP CodeSniffer that attempts to codify and enforce the Joomla coding standards. ==Why?-- The reasons seem obvious, bu...

== A Nose For Joomla ==

This is a custom coding standard for the PHP CodeSniffer that attempts to codify and enforce the Joomla coding standards.

==Why?--

The reasons seem obvious, but one look at reality shows they aren't, so I'll enumerate some of them here:

- Coherent and consisting coding practice makes the files look more professional. Conflicting styles in the same project (or worse, the same file) not only look sloppy, they encourage further sloppiness.

- When all code complies with the same standard, bad code is easier for everyone to spot.

- It makes it easier for someone new to a particular file in the project to find and fix errors, or extend functionality.

- If there is no consistent standard maintained, the sometimes developers will reformat the code to suit themselves. This causes a wide range of changes in the code repository, and if there is a later problem, a significant change could be lost in the chaff produced by a diff.

==Installation==

First you'll need to install phpcs (http://pear.php.net/package/PHP_CodeSniffer/download/). This set of files is intended to work with phpcs version 1.3, so behavior with any other version is undefined.

Then download and unzip the [http://joomlacode.org/gf/project/jcodesniffer/ Joomla CodeSniffer], and copy the contents of it into /path/to/PHP_CodeSniffer/Standards/Joomla. (The path on some systems is /usr/lib/php/PHP/PHP_CodeSniffer but this varies from system to system. Use

<code>pear config-get php_dir</code>

to find out where the PEAR directory is on your system, then add "/PHP/PHP_CodeSniffer" to it.)

You invoke the custom standard by

<code>phpcs --standard=Joomla --tab-width=4 file/to/sniff</code>

Further documentation on the use of phpcs can be found at: [http://pear.php.net/package/PHP_CodeSniffer/docs]

Coding style and standards

2010-09-29T22:07:28Z

Paladin: /* Function Definitions */ The exemplar is *not* the "one true brace" convention, which specifies the opening brace be at the end of the function line, not on a new line

{{review}}
{{RightTOC}}
remark: The following information has been copied from the old WIKI archive has not yet been reviewed.
See: http://dev.joomla.org/component/option,com_jd-wiki/Itemid,/id,standards:coding/

Good coding standards are important in any development project, but particularly when multiple developers are working on the same project. Having coding standards helps ensure that the code is of high quality, has fewer bugs, and is easily maintained.

First rule, if in doubt, ask.

== File Format ==
All files contributed to Joomla must:

* Be stored as ASCII text
* Use UTF-8 character encoding
* Be Unix formatted
** Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.

New files will normally be added to the code base using Subversion (SVN). All SVN files should have the SVN property set "eol-style=LF". Also, most Joomla! files will have "$Id" tags in the "@version" line of the Doc block. These require the SVN property "keywords=Id". See [[Subversion File Properties]] for more information about how to set SVN properties.

== Coding Standards ==

=== Spelling ===

Spelling of class, function, variable and constant names should generally be in accordance with British English rules (en_GB). However, some exceptions are permitted, for example where common programming names are used that align with the PHP API such as <code>$color</code>.

=== E_STRICT-compatible code ===

As of version 1.6, all new code that is suggested for inclusion into Joomla must be E_STRICT-compatible. This means that it must not produce any warnings or errors when PHP's error reporting level is set to E_ALL | E_STRICT.

=== Indenting and Line Length ===

Use tabs to indent, not spaces. Make sure that the tab-stops are set to only 4 spaces in length.

There is no set limit for line length. Use your judgment based on the nature of the line and readability.

=== Control Structures ===

These include if, for, while, switch, etc. Here is an example of an if statement, as it is the most complicated of the control structures:

<source lang="php">
<?php
if ((condition1) || (condition2)) {
action1();
} else if ((condition3) && (condition4)) {
action2();
} else {
defaultAction();
anotherAction();
}

// optional formatting if it improves readability
if ((condition1) || (condition2)) {
action1();
} else if ((condition3) && (condition4)) {
action2();
} else {
defaultAction();
anotherAction();
}
</source>

Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

In '''layouts''', the alternative named notation should be used:

<source lang="php">
<?php
if ((condition1) OR (condition2)) :
action1();
elseif ((condition3) AND (condition4)) :
action2();
else :
defaultAction();
anotherAction();
endif;

foreach ($array as $element) :
echo $element;
endforeach;
</source>

Logical operators in condition statements should use uppercase words (<code>AND</code>, <code>OR</code>, etc) rather than programmatic notation (<code>&&</code>, <code>||</code>, etc).

With the exception of <code>case</code> statements, curly braces must always be included even though they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

For switch statements:

<source lang="php">
<?php
switch (condition) {
case 1:
doAction1();
break;
case 2:
doAction2();
break;
default:
doDefaultAction();
break;
}
</source>

Use indenting and line-breaks rather than curly braces in the <code>case</code> statements to increase readability. There should be no space between the condition and the colon in the <code>case</code> statement.

=== Function Calls ===

Functions should be called with no spaces between the function name and the opening parenthesis, and no space between this and the first parameter; a space after the comma between each parameter (if they are present), and no space between the last parameter and the closing parenthesis, and the semicolon. Here's an example:

<source lang="php">
<?php
$var = foo($bar, $baz, $quux);
</source>

As displayed above, there should be space before and one space after the equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, tabs (not spaces) may be inserted to promote readability:

<source lang="php">
<?php
$short = foo($bar);
$long_variable = foo($baz);
</source>

=== Function Definitions ===

Class and function declarations follow this convention:

<source lang="php">
<?php
function fooFunction($arg1, $arg2 = '')
{
if (condition) {
statement;
}
return $val;
}

class fooClass
{
function fooMethod($arg1)
{
if ($arg) {
$result = true;
} else {
$result = false;
}
return $result;
}
}
</source>

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example:

<source lang="php">
<?php
function connect(&$dsn, $persistent = false)
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}

if (!$dsninfo OR !$dsninfo['phptype']) {
return $this->raiseError();
}

return true;
}
</source>

=== Comments ===

Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: http://www.phpdoc.org/

See also [[Adding phpDocumentor comments]]

Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.

C style comments (<tt>/* */</tt>) and standard C++ comments (<tt>//</tt>) are both satisfactory. Use of Perl/shell style comments (<tt>#</tt>) is not permitted.

Please note - commented code is not to be committed to trunk or release repositories.

=== Including Code ===

Anywhere you are unconditionally including a class file, use <code>require_once</code>. Anywhere you are conditionally including a class file (for example, factory methods), use <code>include_once</code>. Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them -- a file included with <code>require_once</code> will not be included again by </code>include_once</code>.

;Note: [[php:include_once|include_once]] and [[php:require_once|require_once]] are PHP ''language statements'', not functions. You don't need parentheses around the filename to be included.

=== PHP Code Tags ===

Always use <tt><?php ?></tt> to delimit PHP code, not the <tt><? ?></tt> shorthand. This is the most portable way to include PHP code on differing operating systems and setups.

For files that contain only PHP code, the closing tag (<tt>?></tt>) is never permitted. It is not required by PHP. Not including it prevents trailing white space from being accidentally injected into the output (see PHP manual on [http://au.php.net/basic-syntax.instruction-separation instruction separation]).

=== SQL Queries ===

SQL keywords are to be written in uppercase, while all other identifiers (which the exception of quoted text obviously) is to be in lowercase. Carriage returns should not be used as [[JDatabase]]::getQuery provides for formatted output. However, indenting with spaces to improve readability is desireable.

Queries should be wrapped in single quotes (as these text blocks are parsed faster by php).

All quoted strings must use the ''Quote'' method to facilitate future compatibility with other database engines.

All table names should use the '''<tt>#_</tt>''' prefix rather than <tt>jos_</tt> to access Joomla! contents and allow for the [[screen.config.15#Database_Settings|user defined database prefix]] to be applied.

All expected integer or floating-point variable must be [http://php.net/manual/language.types.type-juggling.php cast] with <tt>(int)</tt>, <tt>(float)</tt> or <tt>(double)</tt> as appropriate.

<source lang="php">
$state = 1;
$name = 'bill';
$db = &JFactory::getDBO();
$query = 'SELECT COUNT( c.id ) AS num_articles, u.id, u.username'.
' FROM #__content AS c'.
' LEFT JOIN #__users AS u ON u.id = c.created_by'.
' WHERE c.state = '.(int) $state
' AND u.id IS NOT NULL'.
' AND u.username <> '.$db->Quote( $name ).
' GROUP BY u.id'.
' HAVING COUNT( c.id ) > 0';
$db->setQuery();
// Output formated query if joomla debug is active:
if (JDEBUG) {
echo $db->getQuery();
}
$stats = $db->loadObjectList();
</source>

=== Doc Blocks ===

All source code files in the core Joomla distribution must contain the following comment block as the header:

<source lang="php">
<?php
/**
* Short description of file
*
* Longer description of file is optional, but should be included if the file contains multiple classes or non-class material.
*
* PHP version 5.2.4 (put in the minimum version of PHP expected for the code here to run)
*
* @version $Id$
* @package Joomla
* @copyright Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license GNU/GPL, see LICENSE.php
*/
</source>

The <code>@package</code> in the header is not required for class-only files.

Classes, functions, constants, class properties and class methods should all be supplied with appropriate DocBlocks.

<source lang="php">
/**
* Short description for class
*
* Long description for class (if any)...
*
* @package PackageName
* @subpackage SubPackageName
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since Class available since Release 1.2.0
* @deprecated Class deprecated in Release 2.0.0
*/
class JFooBar
{
/**
* @var int $id Primary key
*/
public $id = null;
}
</source>

The following package names are to be used in the core stack:

* Joomla.Administrator - all files that belong only to the administrator or backend application
* Joomla.Installation - all files that belong to the installation application
* Joomla.Plugin - all plugin files
* Joomla.Site - all files that pertain only to the site or frontend application
* Joomla.XML-RPC - all files that belong to the XML-RPC server application

The sub-package name will vary according to the extension type:

* Components - the component folder, eg <code>com_content</code>
* Modules - the module folder, eg <code>mod_latest_news</code>
* Plugins - the folder.element, eg <code>content.pagebreak</code>
* Templates - the template folder, eg <code>rhuk_milkyway</code>
* Framework - nothing for top level files (such as <code>factory.php</code>), the first level folder or the first.second level folders as appropriate, eg <code>utilities</code> for <code>joomla/utilities/date.php</code>, <code>html.html</code> for <code>joomla/html/html/email.php</code>

Please note that code contributed to the Joomla stack that will become the copyright of the project is not allowed to include <code>@author</code> tags. You should update the contribution log in <tt>CREDITS.php</tt>. Joomla's philosophy is that the code is written "all together" and there is no notion of any one person 'owning' any section of code.

Files included from third party sources must leave DocBlocks intact. Layout files use the same DocBlocks as other PHP files.

Note that the "@version $Id" line uses the SVN "keywords=Id" property. See [[Subversion File Properties]] for information about setting this property.

== Naming Conventions ==

=== Classes ===

Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with an uppercase letter and be written in CamelCase even if using traditionally uppercase acronyms (such as XML, HTML). One exception is for Joomla framework classes which must begin with an uppercase 'J' with the next letter also being uppercase. For example:

* JHtmlHelper
* JXmlParser
* JModel

Third-party developers are advised to namespace their functions with a unique prefix.

=== Functions and Methods ===

Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). The initial letter of the name is lowercase, and each letter that starts a new "word" is capitalized. Function in the Joomla framework must begin with a lowercase 'j'. Some examples:

<source lang="php">
connect();
getData();
buildSomeWidget();
jImport();
jDoSomething();
</source>

Private class members (meaning class members that are intended to be used only from within the same class in which they are declared; are preceded by a single underscore. Properties are to be written in underscore format (that is, logical words separated by underscores) and should be all lowercase. For example:

<source lang="php">
class JFooBar
{
// Joomla 1.5 and earlier format
var $_status = null;

function _sort()
{
}

// Joomla 1.6 format
private $_status = null;

protected $field_name = null;

protected function _sort()
{
}
}
</source>

=== Constants ===

Constants should always be all-uppercase, with underscores to separate words. Prefix constant names with the uppercase name of the class/package they are used in. For example, the constants used by the [[JError]] class all begin with "JERROR_".

=== Global Variables ===

If your package needs to define global variables, their name should start with a single underscore followed by the uppercase class/package name and another underscore. For example, the JError class uses a global variable called $_JERROR_LEVELS.

With PHP5 and later you may use static class properties or constants instead of globals.
<source lang="php">
<?php
class JWhatever
{
public static $instance = null;
const SUCCESS = 1;
const FAILURE = 0;
// Methods...
}
</source>

=== Regular and Class Variables ===

Regular variables, follow the same conventions as function.

Class variables should be set to null or some other appropriate default value. Lining up the default values with tabs should only be used if particularly warranted for readability.

=== References ===

When using references, there should be a space before the reference operator and no space between it and the function or variable name. For example:

<source lang="php">
<?php
$ref1 = &$this->_sql;
$db = &JFactory::getDBO();
</source>

=== Language Keys ===

NOTE: This part has to be rewritten for 1.6 (JM)

Except for the most common of words, such as "Yes", "No", "Show", "Hide" all language keys should be namespaced to reflect the type of string they represent. Always consider that if two extensions use the same key, the one loaded last will be the one that displays. Namespacing should generally relate to the extension displaying the text. For example:

<source lang="php"><?php
echo JText::_('Weblink Link');
echo JText::_('Weblink Title');
echo JText::_('Weblink Description');

echo JText::_('Exception An error occurred while saving');
?></source>

TODO: Link to page with "common" strings that can be used for typical actions in components, such a "Save"

Where the same English word is used in two different locations, two different language keys should be used to allow for cases where the translation results in different words or phrases.

<source lang="php">
// A table column title
<th><?php echo JText::_('Weblink Column Title');?></th>
<th><?php echo JText::_('Weblink Column Link');?></th>

// In the form
<?php echo JText::_('Weblink Title');?><input name="title" />
<?php echo JText::_('Weblink Link');?><input name="link" />
</source>

Toolbar and Linkbar text should be prefixed Toolbar and Linkbar respectively.

The language keys should be written as naturally as possible with spaces, not underscores separating words. Long phrases can be condensed to reduce keys to a sensible length. For example, tooltips for an edit field can be written like this:

<source lang="php">
<?php echo JText::_('Weblink Title');?><input name="title" title="<?php echo JText::_('Weblink Title Desc');?>" />
</source>

The convention used should be governed by common sense, but must be consistent. In general consider how the language file will look with all keys sorted alphabetically. Prefixes should be used to group text within a common context (such as column headings). Suffixes should be used to group elements that logically go together (such as a field name and its description).

Phrases must never be assembled by string concatenation. Each phrase must be represented by a single language key, using sprintf as appropriate to replace dynamic words in the phrase. Where replacements are made, the word used should be as descriptive as possible and all-uppercase. This assists the translators to determine the context of the replacement.

<source lang="php"><?php
// Not permitted
echo JText::_('Deleted ').$n.JText::_(' items');

// Permitted
echo JText::sprintf('Message Deleted NUMBER items', $n);
?></source>

The reference in the language file would look like this:

<source lang="php">MESSAGE DELETED NUMBER ITEMS=Deleted %d Item(s)</source>

If more than one dynamic string is used in a phrase, the printf markers should employ order placement as other languages might change the position of the strings. This is done via %[number]$[printf_type] as follows:

Left to right language:

<source lang="php">PAGE X OF Y=Page %1$d of %2$d</source>

Right to left language:

<source lang="php">PAGE X OF Y=%2$d of %1$d egaP</source>

=== Controllers ===

For single controller components, the naming convention is ''[Name]Controller''.

<source lang="php">
<?php
/**
* Content Controller
* @package Joomla
*/
class ContentController extends JController
{
// Methods
}
</source>
The file name will generally be ''controller.php'' and is located in the component folder.
<source lang="text">
com_content
/ controller.php
</source>

For a multi-controller components, such as the Banners in the Administrator, the convention is ''[Component]Controller[Name]''.

<source lang="php">
<?php
/**
* Banner Client Controller
* @package Joomla
*/
class BannerControllerClient extends JController
{
// Methods
}
</source>

The files will be located in a <tt>/controllers/</tt> folder under the component folder. The file names will reflect the name of the controller.
<source lang="text">
com_banner
/controllers/
/ banner.php
/ client.php
</source>

=== Models===

The naming convention is ''[Component]Model[Name]''.

<source lang="php">
<?php
/**
* Banner Client Model
* @package Joomla
*/
class BannerModelClient extends JModel
{
// Methods
}
</source>

The files will be located in a <tt>/models/</tt> folder under the component folder. The file names will reflect the name of the model.

<source lang="text">
com_banner
/models/
/ banner.php
/ client.php
</source>

=== Views ===
The naming convention is ''[Component]View[Name]''.
<source lang="php">
<?php
/**
* Contact Category View
* @package Joomla
*/
class ContactViewCategory extends JView
{
// Methods
}
</source>
The files will be located in a <tt>/view/</tt> folder under the component folder. The subfolder names will reflect the name of a View.

com_contact
/views/
/''view name 1''/
/ view.html.php
/''view name 2''/
/ view.html.php

Multi-view components such as com_content may provide an optional "master" view class the specialised views extend from. It is located in the component folder and typically called ''view.php''. The naming convention is ''[Component]View''.

com_content
/views/
<span style="color:#999">/archive/</span>
/ view.html.php
<span style="color:#999">/article/</span>
/ view.php

<source lang="php">
view.php
<?php
/**
* Content View
* @package Joomla
*/
class ContentView extends JView
{
// Helper Methods
}

views/archive/view.html.php
<?php
/**
* Content Archive View
* @package Joomla
*/
class ContactViewArchive extends ContentView
{
// Methods
}

</source>

=== Plugins ===

The naming convention is ''plg[Folder][Element]'' as pointed out in [[How to create a content plugin|the relative HowTo page]].

<source lang="php">
class plgContentPagebreak extends JPlugin
{
// Methods
}
</source>

=== Layouts ===
Components may support different Layouts to render the data supplied by a [[#Views|View]] and its [[#Models|Models]]. A Layout file usually contains markup and some PHP code for ''display logic only'': no functions, no classes.

A Layout consists of at least one .php file and an equally named [[Creating a basic layout.xml file|.xml manifest file]] located in the <tt>/tmpl/</tt> folder of a View, both reflect the internal name of the Layout. The standard Layout is called ''default''.

<span style="color:#999">com_content
/views/
/article/</span><span style="color:#000">
/tmpl/
/ default.php
/ default.xml
/ form.php
/ form.xml
/ pagebreak.php
/ pagebreak.xml </span>

The Layout may use supplemental .php files to provide more granule control in order to render individual parts or repetitive items of the data.

Users may customize the Layout output via [[#Template Layout Overrides|Template Layout Overrides]].

=== Templates ===

=== Template Layout Overrides ===

Coding style and standards

2010-09-29T22:00:05Z

Paladin: /* Control Structures */ Edited slightly again to conform with earlier discussions.

{{review}}
{{RightTOC}}
remark: The following information has been copied from the old WIKI archive has not yet been reviewed.
See: http://dev.joomla.org/component/option,com_jd-wiki/Itemid,/id,standards:coding/

Good coding standards are important in any development project, but particularly when multiple developers are working on the same project. Having coding standards helps ensure that the code is of high quality, has fewer bugs, and is easily maintained.

First rule, if in doubt, ask.

== File Format ==
All files contributed to Joomla must:

* Be stored as ASCII text
* Use UTF-8 character encoding
* Be Unix formatted
** Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.

New files will normally be added to the code base using Subversion (SVN). All SVN files should have the SVN property set "eol-style=LF". Also, most Joomla! files will have "$Id" tags in the "@version" line of the Doc block. These require the SVN property "keywords=Id". See [[Subversion File Properties]] for more information about how to set SVN properties.

== Coding Standards ==

=== Spelling ===

Spelling of class, function, variable and constant names should generally be in accordance with British English rules (en_GB). However, some exceptions are permitted, for example where common programming names are used that align with the PHP API such as <code>$color</code>.

=== E_STRICT-compatible code ===

As of version 1.6, all new code that is suggested for inclusion into Joomla must be E_STRICT-compatible. This means that it must not produce any warnings or errors when PHP's error reporting level is set to E_ALL | E_STRICT.

=== Indenting and Line Length ===

Use tabs to indent, not spaces. Make sure that the tab-stops are set to only 4 spaces in length.

There is no set limit for line length. Use your judgment based on the nature of the line and readability.

=== Control Structures ===

These include if, for, while, switch, etc. Here is an example of an if statement, as it is the most complicated of the control structures:

<source lang="php">
<?php
if ((condition1) || (condition2)) {
action1();
} else if ((condition3) && (condition4)) {
action2();
} else {
defaultAction();
anotherAction();
}

// optional formatting if it improves readability
if ((condition1) || (condition2)) {
action1();
} else if ((condition3) && (condition4)) {
action2();
} else {
defaultAction();
anotherAction();
}
</source>

Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

In '''layouts''', the alternative named notation should be used:

<source lang="php">
<?php
if ((condition1) OR (condition2)) :
action1();
elseif ((condition3) AND (condition4)) :
action2();
else :
defaultAction();
anotherAction();
endif;

foreach ($array as $element) :
echo $element;
endforeach;
</source>

Logical operators in condition statements should use uppercase words (<code>AND</code>, <code>OR</code>, etc) rather than programmatic notation (<code>&&</code>, <code>||</code>, etc).

With the exception of <code>case</code> statements, curly braces must always be included even though they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

For switch statements:

<source lang="php">
<?php
switch (condition) {
case 1:
doAction1();
break;
case 2:
doAction2();
break;
default:
doDefaultAction();
break;
}
</source>

Use indenting and line-breaks rather than curly braces in the <code>case</code> statements to increase readability. There should be no space between the condition and the colon in the <code>case</code> statement.

=== Function Calls ===

Functions should be called with no spaces between the function name and the opening parenthesis, and no space between this and the first parameter; a space after the comma between each parameter (if they are present), and no space between the last parameter and the closing parenthesis, and the semicolon. Here's an example:

<source lang="php">
<?php
$var = foo($bar, $baz, $quux);
</source>

As displayed above, there should be space before and one space after the equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, tabs (not spaces) may be inserted to promote readability:

<source lang="php">
<?php
$short = foo($bar);
$long_variable = foo($baz);
</source>

=== Function Definitions ===

Class and function declarations follow the "one true brace" convention:

<source lang="php">
<?php
function fooFunction($arg1, $arg2 = '')
{
if (condition) {
statement;
}
return $val;
}

class fooClass
{
function fooMethod($arg1)
{
if ($arg) {
$result = true;
} else {
$result = false;
}
return $result;
}
}
</source>

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example:

<source lang="php">
<?php
function connect(&$dsn, $persistent = false)
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}

if (!$dsninfo OR !$dsninfo['phptype']) {
return $this->raiseError();
}

return true;
}
</source>

=== Comments ===

Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: http://www.phpdoc.org/

See also [[Adding phpDocumentor comments]]

Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.

C style comments (<tt>/* */</tt>) and standard C++ comments (<tt>//</tt>) are both satisfactory. Use of Perl/shell style comments (<tt>#</tt>) is not permitted.

Please note - commented code is not to be committed to trunk or release repositories.

=== Including Code ===

Anywhere you are unconditionally including a class file, use <code>require_once</code>. Anywhere you are conditionally including a class file (for example, factory methods), use <code>include_once</code>. Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them -- a file included with <code>require_once</code> will not be included again by </code>include_once</code>.

;Note: [[php:include_once|include_once]] and [[php:require_once|require_once]] are PHP ''language statements'', not functions. You don't need parentheses around the filename to be included.

=== PHP Code Tags ===

Always use <tt><?php ?></tt> to delimit PHP code, not the <tt><? ?></tt> shorthand. This is the most portable way to include PHP code on differing operating systems and setups.

For files that contain only PHP code, the closing tag (<tt>?></tt>) is never permitted. It is not required by PHP. Not including it prevents trailing white space from being accidentally injected into the output (see PHP manual on [http://au.php.net/basic-syntax.instruction-separation instruction separation]).

=== SQL Queries ===

SQL keywords are to be written in uppercase, while all other identifiers (which the exception of quoted text obviously) is to be in lowercase. Carriage returns should not be used as [[JDatabase]]::getQuery provides for formatted output. However, indenting with spaces to improve readability is desireable.

Queries should be wrapped in single quotes (as these text blocks are parsed faster by php).

All quoted strings must use the ''Quote'' method to facilitate future compatibility with other database engines.

All table names should use the '''<tt>#_</tt>''' prefix rather than <tt>jos_</tt> to access Joomla! contents and allow for the [[screen.config.15#Database_Settings|user defined database prefix]] to be applied.

All expected integer or floating-point variable must be [http://php.net/manual/language.types.type-juggling.php cast] with <tt>(int)</tt>, <tt>(float)</tt> or <tt>(double)</tt> as appropriate.

<source lang="php">
$state = 1;
$name = 'bill';
$db = &JFactory::getDBO();
$query = 'SELECT COUNT( c.id ) AS num_articles, u.id, u.username'.
' FROM #__content AS c'.
' LEFT JOIN #__users AS u ON u.id = c.created_by'.
' WHERE c.state = '.(int) $state
' AND u.id IS NOT NULL'.
' AND u.username <> '.$db->Quote( $name ).
' GROUP BY u.id'.
' HAVING COUNT( c.id ) > 0';
$db->setQuery();
// Output formated query if joomla debug is active:
if (JDEBUG) {
echo $db->getQuery();
}
$stats = $db->loadObjectList();
</source>

=== Doc Blocks ===

All source code files in the core Joomla distribution must contain the following comment block as the header:

<source lang="php">
<?php
/**
* Short description of file
*
* Longer description of file is optional, but should be included if the file contains multiple classes or non-class material.
*
* PHP version 5.2.4 (put in the minimum version of PHP expected for the code here to run)
*
* @version $Id$
* @package Joomla
* @copyright Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license GNU/GPL, see LICENSE.php
*/
</source>

The <code>@package</code> in the header is not required for class-only files.

Classes, functions, constants, class properties and class methods should all be supplied with appropriate DocBlocks.

<source lang="php">
/**
* Short description for class
*
* Long description for class (if any)...
*
* @package PackageName
* @subpackage SubPackageName
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since Class available since Release 1.2.0
* @deprecated Class deprecated in Release 2.0.0
*/
class JFooBar
{
/**
* @var int $id Primary key
*/
public $id = null;
}
</source>

The following package names are to be used in the core stack:

* Joomla.Administrator - all files that belong only to the administrator or backend application
* Joomla.Installation - all files that belong to the installation application
* Joomla.Plugin - all plugin files
* Joomla.Site - all files that pertain only to the site or frontend application
* Joomla.XML-RPC - all files that belong to the XML-RPC server application

The sub-package name will vary according to the extension type:

* Components - the component folder, eg <code>com_content</code>
* Modules - the module folder, eg <code>mod_latest_news</code>
* Plugins - the folder.element, eg <code>content.pagebreak</code>
* Templates - the template folder, eg <code>rhuk_milkyway</code>
* Framework - nothing for top level files (such as <code>factory.php</code>), the first level folder or the first.second level folders as appropriate, eg <code>utilities</code> for <code>joomla/utilities/date.php</code>, <code>html.html</code> for <code>joomla/html/html/email.php</code>

Please note that code contributed to the Joomla stack that will become the copyright of the project is not allowed to include <code>@author</code> tags. You should update the contribution log in <tt>CREDITS.php</tt>. Joomla's philosophy is that the code is written "all together" and there is no notion of any one person 'owning' any section of code.

Files included from third party sources must leave DocBlocks intact. Layout files use the same DocBlocks as other PHP files.

Note that the "@version $Id" line uses the SVN "keywords=Id" property. See [[Subversion File Properties]] for information about setting this property.

== Naming Conventions ==

=== Classes ===

Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with an uppercase letter and be written in CamelCase even if using traditionally uppercase acronyms (such as XML, HTML). One exception is for Joomla framework classes which must begin with an uppercase 'J' with the next letter also being uppercase. For example:

* JHtmlHelper
* JXmlParser
* JModel

Third-party developers are advised to namespace their functions with a unique prefix.

=== Functions and Methods ===

Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). The initial letter of the name is lowercase, and each letter that starts a new "word" is capitalized. Function in the Joomla framework must begin with a lowercase 'j'. Some examples:

<source lang="php">
connect();
getData();
buildSomeWidget();
jImport();
jDoSomething();
</source>

Private class members (meaning class members that are intended to be used only from within the same class in which they are declared; are preceded by a single underscore. Properties are to be written in underscore format (that is, logical words separated by underscores) and should be all lowercase. For example:

<source lang="php">
class JFooBar
{
// Joomla 1.5 and earlier format
var $_status = null;

function _sort()
{
}

// Joomla 1.6 format
private $_status = null;

protected $field_name = null;

protected function _sort()
{
}
}
</source>

=== Constants ===

Constants should always be all-uppercase, with underscores to separate words. Prefix constant names with the uppercase name of the class/package they are used in. For example, the constants used by the [[JError]] class all begin with "JERROR_".

=== Global Variables ===

If your package needs to define global variables, their name should start with a single underscore followed by the uppercase class/package name and another underscore. For example, the JError class uses a global variable called $_JERROR_LEVELS.

With PHP5 and later you may use static class properties or constants instead of globals.
<source lang="php">
<?php
class JWhatever
{
public static $instance = null;
const SUCCESS = 1;
const FAILURE = 0;
// Methods...
}
</source>

=== Regular and Class Variables ===

Regular variables, follow the same conventions as function.

Class variables should be set to null or some other appropriate default value. Lining up the default values with tabs should only be used if particularly warranted for readability.

=== References ===

When using references, there should be a space before the reference operator and no space between it and the function or variable name. For example:

<source lang="php">
<?php
$ref1 = &$this->_sql;
$db = &JFactory::getDBO();
</source>

=== Language Keys ===

NOTE: This part has to be rewritten for 1.6 (JM)

Except for the most common of words, such as "Yes", "No", "Show", "Hide" all language keys should be namespaced to reflect the type of string they represent. Always consider that if two extensions use the same key, the one loaded last will be the one that displays. Namespacing should generally relate to the extension displaying the text. For example:

<source lang="php"><?php
echo JText::_('Weblink Link');
echo JText::_('Weblink Title');
echo JText::_('Weblink Description');

echo JText::_('Exception An error occurred while saving');
?></source>

TODO: Link to page with "common" strings that can be used for typical actions in components, such a "Save"

Where the same English word is used in two different locations, two different language keys should be used to allow for cases where the translation results in different words or phrases.

<source lang="php">
// A table column title
<th><?php echo JText::_('Weblink Column Title');?></th>
<th><?php echo JText::_('Weblink Column Link');?></th>

// In the form
<?php echo JText::_('Weblink Title');?><input name="title" />
<?php echo JText::_('Weblink Link');?><input name="link" />
</source>

Toolbar and Linkbar text should be prefixed Toolbar and Linkbar respectively.

The language keys should be written as naturally as possible with spaces, not underscores separating words. Long phrases can be condensed to reduce keys to a sensible length. For example, tooltips for an edit field can be written like this:

<source lang="php">
<?php echo JText::_('Weblink Title');?><input name="title" title="<?php echo JText::_('Weblink Title Desc');?>" />
</source>

The convention used should be governed by common sense, but must be consistent. In general consider how the language file will look with all keys sorted alphabetically. Prefixes should be used to group text within a common context (such as column headings). Suffixes should be used to group elements that logically go together (such as a field name and its description).

Phrases must never be assembled by string concatenation. Each phrase must be represented by a single language key, using sprintf as appropriate to replace dynamic words in the phrase. Where replacements are made, the word used should be as descriptive as possible and all-uppercase. This assists the translators to determine the context of the replacement.

<source lang="php"><?php
// Not permitted
echo JText::_('Deleted ').$n.JText::_(' items');

// Permitted
echo JText::sprintf('Message Deleted NUMBER items', $n);
?></source>

The reference in the language file would look like this:

<source lang="php">MESSAGE DELETED NUMBER ITEMS=Deleted %d Item(s)</source>

If more than one dynamic string is used in a phrase, the printf markers should employ order placement as other languages might change the position of the strings. This is done via %[number]$[printf_type] as follows:

Left to right language:

<source lang="php">PAGE X OF Y=Page %1$d of %2$d</source>

Right to left language:

<source lang="php">PAGE X OF Y=%2$d of %1$d egaP</source>

=== Controllers ===

For single controller components, the naming convention is ''[Name]Controller''.

<source lang="php">
<?php
/**
* Content Controller
* @package Joomla
*/
class ContentController extends JController
{
// Methods
}
</source>
The file name will generally be ''controller.php'' and is located in the component folder.
<source lang="text">
com_content
/ controller.php
</source>

For a multi-controller components, such as the Banners in the Administrator, the convention is ''[Component]Controller[Name]''.

<source lang="php">
<?php
/**
* Banner Client Controller
* @package Joomla
*/
class BannerControllerClient extends JController
{
// Methods
}
</source>

The files will be located in a <tt>/controllers/</tt> folder under the component folder. The file names will reflect the name of the controller.
<source lang="text">
com_banner
/controllers/
/ banner.php
/ client.php
</source>

=== Models===

The naming convention is ''[Component]Model[Name]''.

<source lang="php">
<?php
/**
* Banner Client Model
* @package Joomla
*/
class BannerModelClient extends JModel
{
// Methods
}
</source>

The files will be located in a <tt>/models/</tt> folder under the component folder. The file names will reflect the name of the model.

<source lang="text">
com_banner
/models/
/ banner.php
/ client.php
</source>

=== Views ===
The naming convention is ''[Component]View[Name]''.
<source lang="php">
<?php
/**
* Contact Category View
* @package Joomla
*/
class ContactViewCategory extends JView
{
// Methods
}
</source>
The files will be located in a <tt>/view/</tt> folder under the component folder. The subfolder names will reflect the name of a View.

com_contact
/views/
/''view name 1''/
/ view.html.php
/''view name 2''/
/ view.html.php

Multi-view components such as com_content may provide an optional "master" view class the specialised views extend from. It is located in the component folder and typically called ''view.php''. The naming convention is ''[Component]View''.

com_content
/views/
<span style="color:#999">/archive/</span>
/ view.html.php
<span style="color:#999">/article/</span>
/ view.php

<source lang="php">
view.php
<?php
/**
* Content View
* @package Joomla
*/
class ContentView extends JView
{
// Helper Methods
}

views/archive/view.html.php
<?php
/**
* Content Archive View
* @package Joomla
*/
class ContactViewArchive extends ContentView
{
// Methods
}

</source>

=== Plugins ===

The naming convention is ''plg[Folder][Element]'' as pointed out in [[How to create a content plugin|the relative HowTo page]].

<source lang="php">
class plgContentPagebreak extends JPlugin
{
// Methods
}
</source>

=== Layouts ===
Components may support different Layouts to render the data supplied by a [[#Views|View]] and its [[#Models|Models]]. A Layout file usually contains markup and some PHP code for ''display logic only'': no functions, no classes.

A Layout consists of at least one .php file and an equally named [[Creating a basic layout.xml file|.xml manifest file]] located in the <tt>/tmpl/</tt> folder of a View, both reflect the internal name of the Layout. The standard Layout is called ''default''.

<span style="color:#999">com_content
/views/
/article/</span><span style="color:#000">
/tmpl/
/ default.php
/ default.xml
/ form.php
/ form.xml
/ pagebreak.php
/ pagebreak.xml </span>

The Layout may use supplemental .php files to provide more granule control in order to render individual parts or repetitive items of the data.

Users may customize the Layout output via [[#Template Layout Overrides|Template Layout Overrides]].

=== Templates ===

=== Template Layout Overrides ===

Talk:Coding style and standards

2010-09-29T21:56:51Z

Paladin: /* Studly caps exception? */

Shouldn't the JText not have spaces?

== Studly caps exception? ==

jImport() is given as an example. But the entire codebase is littered with jimport(), as well as lots of 3PD extensions. Do you mean to designate jImport() as the new canonical name for this method, or should we carry this as an exception?

Talk:Coding style and standards

2010-09-29T21:56:35Z

Paladin: /* Studly caps exception? */ new section

Shouldn't the JText not have spaces?

== Studly caps exception? ==

jImport() is given as an example. But the entire codebase is lettered with jimport(), as well as lots of 3PD extensions. Do you mean to designate jImport() as the new canonical name for this method, or should we carry this as an exception?

Coding style and standards

2010-09-29T21:52:54Z

Paladin: /* Doc Blocks */ Updated to reflect additional comments and their purpose.

{{review}}
{{RightTOC}}
remark: The following information has been copied from the old WIKI archive has not yet been reviewed.
See: http://dev.joomla.org/component/option,com_jd-wiki/Itemid,/id,standards:coding/

Good coding standards are important in any development project, but particularly when multiple developers are working on the same project. Having coding standards helps ensure that the code is of high quality, has fewer bugs, and is easily maintained.

First rule, if in doubt, ask.

== File Format ==
All files contributed to Joomla must:

* Be stored as ASCII text
* Use UTF-8 character encoding
* Be Unix formatted
** Lines must end only with a line feed (LF). Line feeds are represented as ordinal 10, octal 012 and hex 0A. Do not use carriage returns (CR) like Macintosh computers do or the carriage return/line feed combination (CRLF) like Windows computers do.

New files will normally be added to the code base using Subversion (SVN). All SVN files should have the SVN property set "eol-style=LF". Also, most Joomla! files will have "$Id" tags in the "@version" line of the Doc block. These require the SVN property "keywords=Id". See [[Subversion File Properties]] for more information about how to set SVN properties.

== Coding Standards ==

=== Spelling ===

Spelling of class, function, variable and constant names should generally be in accordance with British English rules (en_GB). However, some exceptions are permitted, for example where common programming names are used that align with the PHP API such as <code>$color</code>.

=== E_STRICT-compatible code ===

As of version 1.6, all new code that is suggested for inclusion into Joomla must be E_STRICT-compatible. This means that it must not produce any warnings or errors when PHP's error reporting level is set to E_ALL | E_STRICT.

=== Indenting and Line Length ===

Use tabs to indent, not spaces. Make sure that the tab-stops are set to only 4 spaces in length.

There is no set limit for line length. Use your judgment based on the nature of the line and readability.

=== Control Structures ===

These include if, for, while, switch, etc. Here is an example of an if statement, as it is the most complicated of the control structures:

<source lang="php">
<?php
if ((condition1) || (condition2)) {
action1();
} else if ((condition3) && (condition4)) {
action2();
} else
{
// Use one true brace in control structures
// when the block is longer than one line
defaultAction();
anotherAction();
}

// optional formatting if it improves readability
if ((condition1) || (condition2)) {
action1();
}
else if ((condition3) && (condition4)) {
action2();
}
else {
defaultAction();
anotherAction();
}
</source>

Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

In '''layouts''', the alternative named notation should be used:

<source lang="php">
<?php
if ((condition1) OR (condition2)) :
action1();
elseif ((condition3) AND (condition4)) :
action2();
else :
defaultAction();
anotherAction();
endif;

foreach ($array as $element) :
echo $element;
endforeach;
</source>

Logical operators in condition statements should use uppercase words (<code>AND</code>, <code>OR</code>, etc) rather than programmatic notation (<code>&&</code>, <code>||</code>, etc).

With the exception of <code>case</code> statements, curly braces must always be included even though they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

For switch statements:

<source lang="php">
<?php
switch (condition)
{
case 1:
doAction1();
break;

case 2:
doAction2();
break;

default:
doDefaultAction();
break;
}
</source>

Use indenting and line-breaks rather than curly braces in the <code>case</code> statements to increase readability. There should be no space between the condition and the colon in the <code>case</code> statement.

=== Function Calls ===

Functions should be called with no spaces between the function name and the opening parenthesis, and no space between this and the first parameter; a space after the comma between each parameter (if they are present), and no space between the last parameter and the closing parenthesis, and the semicolon. Here's an example:

<source lang="php">
<?php
$var = foo($bar, $baz, $quux);
</source>

As displayed above, there should be space before and one space after the equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, tabs (not spaces) may be inserted to promote readability:

<source lang="php">
<?php
$short = foo($bar);
$long_variable = foo($baz);
</source>

=== Function Definitions ===

Class and function declarations follow the "one true brace" convention:

<source lang="php">
<?php
function fooFunction($arg1, $arg2 = '')
{
if (condition) {
statement;
}
return $val;
}

class fooClass
{
function fooMethod($arg1)
{
if ($arg) {
$result = true;
} else {
$result = false;
}
return $result;
}
}
</source>

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example:

<source lang="php">
<?php
function connect(&$dsn, $persistent = false)
{
if (is_array($dsn)) {
$dsninfo = &$dsn;
} else {
$dsninfo = DB::parseDSN($dsn);
}

if (!$dsninfo OR !$dsninfo['phptype']) {
return $this->raiseError();
}

return true;
}
</source>

=== Comments ===

Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: http://www.phpdoc.org/

See also [[Adding phpDocumentor comments]]

Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.

C style comments (<tt>/* */</tt>) and standard C++ comments (<tt>//</tt>) are both satisfactory. Use of Perl/shell style comments (<tt>#</tt>) is not permitted.

Please note - commented code is not to be committed to trunk or release repositories.

=== Including Code ===

Anywhere you are unconditionally including a class file, use <code>require_once</code>. Anywhere you are conditionally including a class file (for example, factory methods), use <code>include_once</code>. Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them -- a file included with <code>require_once</code> will not be included again by </code>include_once</code>.

;Note: [[php:include_once|include_once]] and [[php:require_once|require_once]] are PHP ''language statements'', not functions. You don't need parentheses around the filename to be included.

=== PHP Code Tags ===

Always use <tt><?php ?></tt> to delimit PHP code, not the <tt><? ?></tt> shorthand. This is the most portable way to include PHP code on differing operating systems and setups.

For files that contain only PHP code, the closing tag (<tt>?></tt>) is never permitted. It is not required by PHP. Not including it prevents trailing white space from being accidentally injected into the output (see PHP manual on [http://au.php.net/basic-syntax.instruction-separation instruction separation]).

=== SQL Queries ===

SQL keywords are to be written in uppercase, while all other identifiers (which the exception of quoted text obviously) is to be in lowercase. Carriage returns should not be used as [[JDatabase]]::getQuery provides for formatted output. However, indenting with spaces to improve readability is desireable.

Queries should be wrapped in single quotes (as these text blocks are parsed faster by php).

All quoted strings must use the ''Quote'' method to facilitate future compatibility with other database engines.

All table names should use the '''<tt>#_</tt>''' prefix rather than <tt>jos_</tt> to access Joomla! contents and allow for the [[screen.config.15#Database_Settings|user defined database prefix]] to be applied.

All expected integer or floating-point variable must be [http://php.net/manual/language.types.type-juggling.php cast] with <tt>(int)</tt>, <tt>(float)</tt> or <tt>(double)</tt> as appropriate.

<source lang="php">
$state = 1;
$name = 'bill';
$db = &JFactory::getDBO();
$query = 'SELECT COUNT( c.id ) AS num_articles, u.id, u.username'.
' FROM #__content AS c'.
' LEFT JOIN #__users AS u ON u.id = c.created_by'.
' WHERE c.state = '.(int) $state
' AND u.id IS NOT NULL'.
' AND u.username <> '.$db->Quote( $name ).
' GROUP BY u.id'.
' HAVING COUNT( c.id ) > 0';
$db->setQuery();
// Output formated query if joomla debug is active:
if (JDEBUG) {
echo $db->getQuery();
}
$stats = $db->loadObjectList();
</source>

=== Doc Blocks ===

All source code files in the core Joomla distribution must contain the following comment block as the header:

<source lang="php">
<?php
/**
* Short description of file
*
* Longer description of file is optional, but should be included if the file contains multiple classes or non-class material.
*
* PHP version 5.2.4 (put in the minimum version of PHP expected for the code here to run)
*
* @version $Id$
* @package Joomla
* @copyright Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license GNU/GPL, see LICENSE.php
*/
</source>

The <code>@package</code> in the header is not required for class-only files.

Classes, functions, constants, class properties and class methods should all be supplied with appropriate DocBlocks.

<source lang="php">
/**
* Short description for class
*
* Long description for class (if any)...
*
* @package PackageName
* @subpackage SubPackageName
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since Class available since Release 1.2.0
* @deprecated Class deprecated in Release 2.0.0
*/
class JFooBar
{
/**
* @var int $id Primary key
*/
public $id = null;
}
</source>

The following package names are to be used in the core stack:

* Joomla.Administrator - all files that belong only to the administrator or backend application
* Joomla.Installation - all files that belong to the installation application
* Joomla.Plugin - all plugin files
* Joomla.Site - all files that pertain only to the site or frontend application
* Joomla.XML-RPC - all files that belong to the XML-RPC server application

The sub-package name will vary according to the extension type:

* Components - the component folder, eg <code>com_content</code>
* Modules - the module folder, eg <code>mod_latest_news</code>
* Plugins - the folder.element, eg <code>content.pagebreak</code>
* Templates - the template folder, eg <code>rhuk_milkyway</code>
* Framework - nothing for top level files (such as <code>factory.php</code>), the first level folder or the first.second level folders as appropriate, eg <code>utilities</code> for <code>joomla/utilities/date.php</code>, <code>html.html</code> for <code>joomla/html/html/email.php</code>

Please note that code contributed to the Joomla stack that will become the copyright of the project is not allowed to include <code>@author</code> tags. You should update the contribution log in <tt>CREDITS.php</tt>. Joomla's philosophy is that the code is written "all together" and there is no notion of any one person 'owning' any section of code.

Files included from third party sources must leave DocBlocks intact. Layout files use the same DocBlocks as other PHP files.

Note that the "@version $Id" line uses the SVN "keywords=Id" property. See [[Subversion File Properties]] for information about setting this property.

== Naming Conventions ==

=== Classes ===

Classes should be given descriptive names. Avoid using abbreviations where possible. Class names should always begin with an uppercase letter and be written in CamelCase even if using traditionally uppercase acronyms (such as XML, HTML). One exception is for Joomla framework classes which must begin with an uppercase 'J' with the next letter also being uppercase. For example:

* JHtmlHelper
* JXmlParser
* JModel

Third-party developers are advised to namespace their functions with a unique prefix.

=== Functions and Methods ===

Functions and methods should be named using the "studly caps" style (also referred to as "bumpy case" or "camel caps"). The initial letter of the name is lowercase, and each letter that starts a new "word" is capitalized. Function in the Joomla framework must begin with a lowercase 'j'. Some examples:

<source lang="php">
connect();
getData();
buildSomeWidget();
jImport();
jDoSomething();
</source>

Private class members (meaning class members that are intended to be used only from within the same class in which they are declared; are preceded by a single underscore. Properties are to be written in underscore format (that is, logical words separated by underscores) and should be all lowercase. For example:

<source lang="php">
class JFooBar
{
// Joomla 1.5 and earlier format
var $_status = null;

function _sort()
{
}

// Joomla 1.6 format
private $_status = null;

protected $field_name = null;

protected function _sort()
{
}
}
</source>

=== Constants ===

Constants should always be all-uppercase, with underscores to separate words. Prefix constant names with the uppercase name of the class/package they are used in. For example, the constants used by the [[JError]] class all begin with "JERROR_".

=== Global Variables ===

If your package needs to define global variables, their name should start with a single underscore followed by the uppercase class/package name and another underscore. For example, the JError class uses a global variable called $_JERROR_LEVELS.

With PHP5 and later you may use static class properties or constants instead of globals.
<source lang="php">
<?php
class JWhatever
{
public static $instance = null;
const SUCCESS = 1;
const FAILURE = 0;
// Methods...
}
</source>

=== Regular and Class Variables ===

Regular variables, follow the same conventions as function.

Class variables should be set to null or some other appropriate default value. Lining up the default values with tabs should only be used if particularly warranted for readability.

=== References ===

When using references, there should be a space before the reference operator and no space between it and the function or variable name. For example:

<source lang="php">
<?php
$ref1 = &$this->_sql;
$db = &JFactory::getDBO();
</source>

=== Language Keys ===

NOTE: This part has to be rewritten for 1.6 (JM)

Except for the most common of words, such as "Yes", "No", "Show", "Hide" all language keys should be namespaced to reflect the type of string they represent. Always consider that if two extensions use the same key, the one loaded last will be the one that displays. Namespacing should generally relate to the extension displaying the text. For example:

<source lang="php"><?php
echo JText::_('Weblink Link');
echo JText::_('Weblink Title');
echo JText::_('Weblink Description');

echo JText::_('Exception An error occurred while saving');
?></source>

TODO: Link to page with "common" strings that can be used for typical actions in components, such a "Save"

Where the same English word is used in two different locations, two different language keys should be used to allow for cases where the translation results in different words or phrases.

<source lang="php">
// A table column title
<th><?php echo JText::_('Weblink Column Title');?></th>
<th><?php echo JText::_('Weblink Column Link');?></th>

// In the form
<?php echo JText::_('Weblink Title');?><input name="title" />
<?php echo JText::_('Weblink Link');?><input name="link" />
</source>

Toolbar and Linkbar text should be prefixed Toolbar and Linkbar respectively.

The language keys should be written as naturally as possible with spaces, not underscores separating words. Long phrases can be condensed to reduce keys to a sensible length. For example, tooltips for an edit field can be written like this:

<source lang="php">
<?php echo JText::_('Weblink Title');?><input name="title" title="<?php echo JText::_('Weblink Title Desc');?>" />
</source>

The convention used should be governed by common sense, but must be consistent. In general consider how the language file will look with all keys sorted alphabetically. Prefixes should be used to group text within a common context (such as column headings). Suffixes should be used to group elements that logically go together (such as a field name and its description).

Phrases must never be assembled by string concatenation. Each phrase must be represented by a single language key, using sprintf as appropriate to replace dynamic words in the phrase. Where replacements are made, the word used should be as descriptive as possible and all-uppercase. This assists the translators to determine the context of the replacement.

<source lang="php"><?php
// Not permitted
echo JText::_('Deleted ').$n.JText::_(' items');

// Permitted
echo JText::sprintf('Message Deleted NUMBER items', $n);
?></source>

The reference in the language file would look like this:

<source lang="php">MESSAGE DELETED NUMBER ITEMS=Deleted %d Item(s)</source>

If more than one dynamic string is used in a phrase, the printf markers should employ order placement as other languages might change the position of the strings. This is done via %[number]$[printf_type] as follows:

Left to right language:

<source lang="php">PAGE X OF Y=Page %1$d of %2$d</source>

Right to left language:

<source lang="php">PAGE X OF Y=%2$d of %1$d egaP</source>

=== Controllers ===

For single controller components, the naming convention is ''[Name]Controller''.

<source lang="php">
<?php
/**
* Content Controller
* @package Joomla
*/
class ContentController extends JController
{
// Methods
}
</source>
The file name will generally be ''controller.php'' and is located in the component folder.
<source lang="text">
com_content
/ controller.php
</source>

For a multi-controller components, such as the Banners in the Administrator, the convention is ''[Component]Controller[Name]''.

<source lang="php">
<?php
/**
* Banner Client Controller
* @package Joomla
*/
class BannerControllerClient extends JController
{
// Methods
}
</source>

The files will be located in a <tt>/controllers/</tt> folder under the component folder. The file names will reflect the name of the controller.
<source lang="text">
com_banner
/controllers/
/ banner.php
/ client.php
</source>

=== Models===

The naming convention is ''[Component]Model[Name]''.

<source lang="php">
<?php
/**
* Banner Client Model
* @package Joomla
*/
class BannerModelClient extends JModel
{
// Methods
}
</source>

The files will be located in a <tt>/models/</tt> folder under the component folder. The file names will reflect the name of the model.

<source lang="text">
com_banner
/models/
/ banner.php
/ client.php
</source>

=== Views ===
The naming convention is ''[Component]View[Name]''.
<source lang="php">
<?php
/**
* Contact Category View
* @package Joomla
*/
class ContactViewCategory extends JView
{
// Methods
}
</source>
The files will be located in a <tt>/view/</tt> folder under the component folder. The subfolder names will reflect the name of a View.

com_contact
/views/
/''view name 1''/
/ view.html.php
/''view name 2''/
/ view.html.php

Multi-view components such as com_content may provide an optional "master" view class the specialised views extend from. It is located in the component folder and typically called ''view.php''. The naming convention is ''[Component]View''.

com_content
/views/
<span style="color:#999">/archive/</span>
/ view.html.php
<span style="color:#999">/article/</span>
/ view.php

<source lang="php">
view.php
<?php
/**
* Content View
* @package Joomla
*/
class ContentView extends JView
{
// Helper Methods
}

views/archive/view.html.php
<?php
/**
* Content Archive View
* @package Joomla
*/
class ContactViewArchive extends ContentView
{
// Methods
}

</source>

=== Plugins ===

The naming convention is ''plg[Folder][Element]'' as pointed out in [[How to create a content plugin|the relative HowTo page]].

<source lang="php">
class plgContentPagebreak extends JPlugin
{
// Methods
}
</source>

=== Layouts ===
Components may support different Layouts to render the data supplied by a [[#Views|View]] and its [[#Models|Models]]. A Layout file usually contains markup and some PHP code for ''display logic only'': no functions, no classes.

A Layout consists of at least one .php file and an equally named [[Creating a basic layout.xml file|.xml manifest file]] located in the <tt>/tmpl/</tt> folder of a View, both reflect the internal name of the Layout. The standard Layout is called ''default''.

<span style="color:#999">com_content
/views/
/article/</span><span style="color:#000">
/tmpl/
/ default.php
/ default.xml
/ form.php
/ form.xml
/ pagebreak.php
/ pagebreak.xml </span>

The Layout may use supplemental .php files to provide more granule control in order to render individual parts or repetitive items of the data.

Users may customize the Layout output via [[#Template Layout Overrides|Template Layout Overrides]].

=== Templates ===

=== Template Layout Overrides ===

Unit Testing

2010-09-25T16:42:36Z

Paladin: /* Unit Testing in Joomla! */

{{cookiejar}}
== News and Updates ==
2009 10 06: Tests now depend on the SVN version of PHPUnit 3.4.1.

2008 06 24: Update to reflect move of PHPUnit code from branch to trunk (former trunk now in /branches/old_simpletest).

2008 06 22: Add information on limiting tests by version.

2008 06 21: Added --class-exclude, --sequence-exclude, and --test-exclude options.

2008 06 21: PHPUnit has been updated to version 3.2.21 with SVN rev 10436. Please update.

== Unit Testing ==
Unit testing is not only an essential part of a good Quality Control program, it is an aid to development as well. Writing new tests before writing code helps focus the developer on the problem at hand. The practice also encourages writing smaller, more loosely coupled, more reusable, and more maintainable code units and these benefits often outweigh the benefits gained by treating unit tests solely as a QC tool. When used in this manner correctness becomes more a by-product of the process than the goal.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with [http://seleniumhq.org/ Selenium], a browser based test automation tool. Writing a functional test using Selenium is documented [http://docs.joomla.org/Functional_Testing#Writing_Functional_Tests here].

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests.

The SVN repository contains code under the /testing path. /testing/trunk used to contain code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

The PHPUnit tests are found in '''/tests/unit''' in the development trunk. See [http://docs.joomla.org/Running_Automated_Tests_for_Version_1.6 Running Automated Tests for Version 1.6] for instructions on setting up unit testing in your IDE.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.

==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-Test.php, for example JObject-0000-class-Test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.
* The custom test runner is no longer needed. The current tests will run with the latest SVN version of PHPUnit 3.4. This code will eventually become PHPUnit 3.4.1. Thanks to Sebastian Bergmann for his excellent work on an excellent project!

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]], [[Unit_Testing_--_UI_Example|UI Example]].

==== Running Unit Tests ====
Test files follow the form class-sequence-type-Test.php, for example JObject-0000-class-Test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-Test.php.

Joomla unit tests use the standard PHPUnit test runner. See http://www.phpunit.de for documentation.

== How to Get it Running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation. Since you will be using SVN to check out the testing project, you don't want to check out the Joomla! with SVN. Instead, simply unpack a normal Joomla! archive. If you are using Eclipse, you can create a folder in your Eclipse workspace for the Joomla! installation, but don't create an Eclipse project yet.
* In the root checkout (or export) the latest version of the unit test code from SVN ''"/testing/trunk/1.5/unittest"'' or ''"/testing/trunk/1.6/unittest"'' to your installation base. This will create a ''"/unittest"'' sub-folder under your joomla installation. If you are using Eclipse, Import the project from the SVN and use the same folder in your Eclipse workspace you used above.
* From the command line, change to the unittest directory.
* Run the unit test from the command prompt using the following command: <code>phpunit tests</code>

The unit test will the run, and the results are rendered. You will see a series of dots for each passed test and other letters for failed tests.

See http://www.phpunit.de/manual/current/en/textui.html for help using the --filter switch to run only certain tests. There are also many other command line switches you can use to get results in various formats.

== Troubleshooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like below, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

== Frequently Asked Questions ==
'''Why can't I use "phpunit ''testname.php''" to run my tests?'''

The test facility has to do some work to be able to load the "Joomla!" framework and to be able to inject mock classes. It's difficult to do this from the PHPUnit test runner, so we built our own. Also, the Joomla test runner has specific options designed to make it easy to select specific tests. Over time we will add more functionality to the test runner so it has many of the capabilities of the phpunit command.

==See also==
[http://www.phpunit.de/manual/current/en/ PHPUnit Manual]

[[Category:Bug Squad]]
[[Category:Development]]
[[Category:Testing]]
[[Category:Automated Testing]]

Unit Testing

2010-09-25T16:29:36Z

Paladin: /* Unit Testing */

{{cookiejar}}
== News and Updates ==
2009 10 06: Tests now depend on the SVN version of PHPUnit 3.4.1.

2008 06 24: Update to reflect move of PHPUnit code from branch to trunk (former trunk now in /branches/old_simpletest).

2008 06 22: Add information on limiting tests by version.

2008 06 21: Added --class-exclude, --sequence-exclude, and --test-exclude options.

2008 06 21: PHPUnit has been updated to version 3.2.21 with SVN rev 10436. Please update.

== Unit Testing ==
Unit testing is not only an essential part of a good Quality Control program, it is an aid to development as well. Writing new tests before writing code helps focus the developer on the problem at hand. The practice also encourages writing smaller, more loosely coupled, more reusable, and more maintainable code units and these benefits often outweigh the benefits gained by treating unit tests solely as a QC tool. When used in this manner correctness becomes more a by-product of the process than the goal.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with [http://seleniumhq.org/ Selenium], a browser based test automation tool. Writing a functional test using Selenium is documented [http://docs.joomla.org/Functional_Testing#Writing_Functional_Tests here].

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests.

The SVN repository contains code under the /testing path. /testing/trunk used to contain code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

The PHPUnit tests are available from '''/testing/trunk'''. Some new tests have been added, any remaining tests from the SimpleTest days are completely broken. See /testing/branches/old-simpletest if you need to run something from that suite.

The unit tests are located in two places:
* /testing/trunk/1.5/unittest - these are tests for Joomla! 1.5 (/development/releases/1.5)
* /testing/trunk/1.6/unittest - there are tests for Joomla! 1.6 (/development/trunk)

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.

==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-Test.php, for example JObject-0000-class-Test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.
* The custom test runner is no longer needed. The current tests will run with the latest SVN version of PHPUnit 3.4. This code will eventually become PHPUnit 3.4.1. Thanks to Sebastian Bergmann for his excellent work on an excellent project!

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]], [[Unit_Testing_--_UI_Example|UI Example]].

==== Running Unit Tests ====
Test files follow the form class-sequence-type-Test.php, for example JObject-0000-class-Test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-Test.php.

Joomla unit tests use the standard PHPUnit test runner. See http://www.phpunit.de for documentation.

== How to Get it Running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation. Since you will be using SVN to check out the testing project, you don't want to check out the Joomla! with SVN. Instead, simply unpack a normal Joomla! archive. If you are using Eclipse, you can create a folder in your Eclipse workspace for the Joomla! installation, but don't create an Eclipse project yet.
* In the root checkout (or export) the latest version of the unit test code from SVN ''"/testing/trunk/1.5/unittest"'' or ''"/testing/trunk/1.6/unittest"'' to your installation base. This will create a ''"/unittest"'' sub-folder under your joomla installation. If you are using Eclipse, Import the project from the SVN and use the same folder in your Eclipse workspace you used above.
* From the command line, change to the unittest directory.
* Run the unit test from the command prompt using the following command: <code>phpunit tests</code>

The unit test will the run, and the results are rendered. You will see a series of dots for each passed test and other letters for failed tests.

See http://www.phpunit.de/manual/current/en/textui.html for help using the --filter switch to run only certain tests. There are also many other command line switches you can use to get results in various formats.

== Troubleshooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like below, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

== Frequently Asked Questions ==
'''Why can't I use "phpunit ''testname.php''" to run my tests?'''

The test facility has to do some work to be able to load the "Joomla!" framework and to be able to inject mock classes. It's difficult to do this from the PHPUnit test runner, so we built our own. Also, the Joomla test runner has specific options designed to make it easy to select specific tests. Over time we will add more functionality to the test runner so it has many of the capabilities of the phpunit command.

==See also==
[http://www.phpunit.de/manual/current/en/ PHPUnit Manual]

[[Category:Bug Squad]]
[[Category:Development]]
[[Category:Testing]]
[[Category:Automated Testing]]

Talk:Unit Testing

2010-09-25T15:59:09Z

Paladin: Is this still relevant?

The information in this page is completely out of date, but another question is:

Is it relevant, given some of the other documentation on j1.6 unit testing?

If it's still judged relevant, I'll be happy to tackle editing the page, but I don't want to waste my time if the page is just going to be deleted in the end, in favor of other pages.