Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Merge remote-tracking branch 'upstream/master' into behavior

  • Loading branch information...
commit 3b81e68c4be5d956af5397449adeb86ab2542db7 2 parents 456c817 + 7840802
@realityking realityking authored
Showing with 23,495 additions and 781 deletions.
  1. +1 −0  build/.gitignore
  2. +216 −0 build/changelog.php
  3. +9 −9 build/phpcs/Joomla/Sniffs/Commenting/ClassCommentSniff.php
  4. +9 −9 build/phpcs/Joomla/Sniffs/Commenting/FileCommentSniff.php
  5. +1 −1  build/phpcs/Joomla/Sniffs/Commenting/FunctionCommentSniff.php
  6. +2 −2 build/phpcs/Joomla/Sniffs/ControlStructures/MultiLineConditionSniff.php
  7. +13 −0 docs/build.xml
  8. +11 −13 docs/coding-standards/book.xml
  9. +20 −29 docs/coding-standards/chapters/basic-guidelines.xml
  10. +598 −322 docs/coding-standards/chapters/php.xml
  11. +17 −22 docs/coding-standards/chapters/preface.xml
  12. +22 −29 docs/coding-standards/chapters/source-code-management.xml
  13. +103 −101 docs/manual/appendices/analysis.xml
  14. +1,032 −231 docs/manual/appendices/changelog.xml
  15. +9 −11 docs/manual/book.xml
  16. +4 −2 docs/manual/chapters/preface.xml
  17. +115 −0 docs/xsl/VERSION
  18. +1,229 −0 docs/xsl/common/af.xml
  19. +1,229 −0 docs/xsl/common/am.xml
  20. +1,229 −0 docs/xsl/common/ar.xml
  21. +660 −0 docs/xsl/common/as.xml
  22. +660 −0 docs/xsl/common/ast.xml
  23. +44 −0 docs/xsl/common/autoidx-kimber.xsl
  24. +154 −0 docs/xsl/common/autoidx-kosek.xsl
  25. +672 −0 docs/xsl/common/az.xml
  26. +724 −0 docs/xsl/common/bg.xml
  27. +1,229 −0 docs/xsl/common/bn.xml
  28. +660 −0 docs/xsl/common/bn_in.xml
  29. +662 −0 docs/xsl/common/bs.xml
  30. +660 −0 docs/xsl/common/ca.xml
  31. +185 −0 docs/xsl/common/charmap.xml
  32. +221 −0 docs/xsl/common/charmap.xsl
  33. +622 −0 docs/xsl/common/common.xml
  34. +2,039 −0 docs/xsl/common/common.xsl
  35. +700 −0 docs/xsl/common/cs.xml
  36. +1,245 −0 docs/xsl/common/cy.xml
  37. +664 −0 docs/xsl/common/da.xml
  38. +666 −0 docs/xsl/common/de.xml
  39. +729 −0 docs/xsl/common/el.xml
  40. +1,229 −0 docs/xsl/common/en.xml
  41. +67 −0 docs/xsl/common/entities.ent
  42. +1,229 −0 docs/xsl/common/eo.xml
  43. +676 −0 docs/xsl/common/es.xml
  44. +1,229 −0 docs/xsl/common/et.xml
Sorry, we could not display the entire diff because too many files (310) changed.
View
1  build/.gitignore
@@ -3,3 +3,4 @@
/pdepend
/code-browser
/api
+/docs
View
216 build/changelog.php
@@ -0,0 +1,216 @@
+#!/usr/bin/php
+<?php
+/**
+ * @package Joomla.Build
+ *
+ * @copyright Copyright (C) 2005 - 2011 Open Source Matters, Inc. All rights reserved.
+ * @license GNU General Public License version 2 or later; see LICENSE
+ */
+
+// We are a valid Joomla entry point.
+define('_JEXEC', 1);
+
+// Setup the path related constants.
+define('JPATH_BASE', dirname(__FILE__));
+
+// Bootstrap the application.
+require '../libraries/import.php';
+
+jimport('joomla.application.cli');
+
+/**
+ * The command line application.
+ *
+ * @package NewLifeInIT
+ * @subpackage cron
+ */
+class Changelog extends JCli
+{
+ /**
+ * Execute the application.
+ *
+ * @return void
+ *
+ * @since 11.3
+ */
+ public function execute()
+ {
+ // Import dependancies.
+ jimport('joomla.client.http');
+
+ try
+ {
+ // Get a list of the merged pull requests.
+ $merged = $this->getMergedPulls();
+
+ $doc = new XMLWriter;
+ $doc->openMemory();
+ $doc->setIndent(true);
+ $doc->setIndentString("\t");
+ $doc->startDocument('1.0', 'utf-8');
+
+ $doc->startElement('appendix');
+ $doc->writeAttribute('version', '5.0');
+ $doc->writeAttribute('xmlns', 'http://docbook.org/ns/docbook');
+ $doc->writeAttribute('xml:id', 'preface');
+ $doc->writeAttribute('xmlns:ns', 'http://docbook.org/ns/docbook');
+ $doc->writeAttribute('xmlns:ns2', 'http://www.w3.org/1999/xlink');
+ $doc->writeAttribute('xmlns:ns3', 'http://www.w3.org/1998/Math/MathML');
+ $doc->writeAttribute('xmlns:ns4', 'http://www.w3.org/2000/svg');
+ $doc->writeAttribute('xmlns:ns5', 'http://www.w3.org/1999/xhtml');
+
+ $doc->startElement('section');
+
+ $cutoff = 10;
+ $page = 1;
+
+ while ($cutoff--)
+ {
+ // Get a page of issues.
+ $issues = $this->getIssues($page++);
+
+ // Check if we've gone past the last page.
+ if (empty($issues))
+ {
+ break;
+ }
+
+ $doc->startElement('itemizedlist');
+
+ // Loop through each pull.
+ foreach ($issues as $issue)
+ {
+ // Check if the issue has been merged.
+ if (empty($issue->pull_request->html_url))
+ {
+ continue;
+ }
+
+ // Check if the pull has been merged.
+ if (!in_array($issue->number, $merged))
+ {
+ continue;
+ }
+
+ $doc->startElement('listitem');
+
+ $doc->startElement('para');
+
+ // Prepare the link to the pull.
+ $doc->text('[');
+ $doc->startElement('link');
+ $doc->writeAttribute('ns2:href', $issue->url);
+ $doc->writeAttribute('ns2:title', 'Closed '.$issue->closed_at);
+ $doc->text('#'.$issue->number);
+ $doc->endElement(); // ulink
+ $doc->text('] '.$issue->title.' (');
+
+ // Prepare the link to the author.
+ $doc->startElement('link');
+ $doc->writeAttribute('ns2:href', $issue->user->url);
+ $doc->text($issue->user->login);
+ $doc->endElement(); // ulink
+ $doc->text(')');
+
+ $doc->endElement(); // para
+
+ if (trim($issue->body))
+ {
+ $doc->startElement('para');
+ $doc->text($issue->body);
+ $doc->endElement(); // para
+ }
+
+ $doc->endElement(); // listitem
+ }
+
+ $doc->endElement(); // itemizedlist
+ }
+
+ $doc->endElement(); // section
+ $doc->endElement(); // appendix
+
+ // Write the file.
+ if (!is_dir('./docs'))
+ {
+ mkdir('./docs');
+ }
+
+ file_put_contents('./docs/changelog.xml', $doc->outputMemory());
+ }
+ catch (Exception $e)
+ {
+ $this->out($e->getMessage());
+ $this->close($e->getCode());
+ }
+
+ // Close normally.
+ $this->close();
+ }
+
+ /**
+ * Get a page of issue data.
+ *
+ * @param integer The page number.
+ *
+ * @return array
+ *
+ * @since 11.3
+ */
+ protected function getIssues($page)
+ {
+ $http = new JHttp;
+ $r = $http->get(
+ 'https://api.github.com/repos/joomla/joomla-platform/issues?state=closed&sort=updated&direction=desc&page='.$page.'&per_page=100'
+ );
+
+ return json_decode($r->body);
+ }
+
+ /**
+ * Gets a list of the merged pull numbers.
+ *
+ * @param integer The pull/issue number.
+ *
+ * @return array
+ *
+ * @since 11.3
+ */
+ protected function getMergedPulls()
+ {
+ $cutoff = 10;
+ $page = 1;
+ $merged = array();
+
+ while ($cutoff--)
+ {
+ $http = new JHttp;
+
+ $r = $http->get(
+ 'https://api.github.com/repos/joomla/joomla-platform/pulls?state=closed&page='.$page++.'&per_page=100'
+ );
+
+ $pulls = json_decode($r->body);
+
+ // Check if we've gone past the last page.
+ if (empty($pulls))
+ {
+ break;
+ }
+
+ // Loop through each of the pull requests.
+ foreach ($pulls as $pull)
+ {
+ // If merged, add to the white list.
+ if ($pull->merged_at)
+ {
+ $merged[] = $pull->number;
+ }
+ }
+ }
+
+ return $merged;
+ }
+}
+
+JCli::getInstance('Changelog')->execute();
View
18 build/phpcs/Joomla/Sniffs/Commenting/ClassCommentSniff.php
@@ -65,17 +65,17 @@ class Joomla_Sniffs_Commenting_ClassCommentSniff extends Joomla_Sniffs_Commentin
'category' => array(
'required' => false,
'allow_multiple' => false,
- 'order_text' => 'follow @version (if used)',
+ 'order_text' => 'must follow @version (if used)',
),
'package' => array(
'required' => true,
'allow_multiple' => false,
- 'order_text' => 'follows @category',
+ 'order_text' => 'must follow @category (if used)',
),
'subpackage' => array(
'required' => false,
'allow_multiple' => false,
- 'order_text' => 'follows @package',
+ 'order_text' => 'must follow @package',
),
'author' => array(
'required' => false,
@@ -85,32 +85,32 @@ class Joomla_Sniffs_Commenting_ClassCommentSniff extends Joomla_Sniffs_Commentin
'copyright' => array(
'required' => false,
'allow_multiple' => true,
- 'order_text' => 'follows @author (if used) or @subpackage (if used) or @package',
+ 'order_text' => 'must follow @author (if used) or @subpackage (if used) or @package',
),
'license' => array(
'required' => false,
'allow_multiple' => false,
- 'order_text' => 'follows @copyright',
+ 'order_text' => 'must follow @copyright (if used)',
),
'link' => array(
'required' => false,
'allow_multiple' => true,
- 'order_text' => 'follows @version',
+ 'order_text' => 'must follow @version (if used)',
),
'see' => array(
'required' => false,
'allow_multiple' => true,
- 'order_text' => 'follows @link',
+ 'order_text' => 'must follow @link (if used)',
),
'since' => array(
'required' => true,
'allow_multiple' => false,
- 'order_text' => 'follows @see (if used) or @link',
+ 'order_text' => 'must follow @see (if used) or @link (if used)',
),
'deprecated' => array(
'required' => false,
'allow_multiple' => false,
- 'order_text' => 'follows @since (if used) or @see (if used) or @link',
+ 'order_text' => 'must follow @since (if used) or @see (if used) or @link (if used)',
),
);
View
18 build/phpcs/Joomla/Sniffs/Commenting/FileCommentSniff.php
@@ -79,47 +79,47 @@ class Joomla_Sniffs_Commenting_FileCommentSniff implements PHP_CodeSniffer_Sniff
'package' => array(
'required' => true,
'allow_multiple' => false,
- 'order_text' => 'follows, if used, @category',
+ 'order_text' => 'must follows @category (if used)',
),
'subpackage' => array(
'required' => false,
'allow_multiple' => false,
- 'order_text' => 'follows @package',
+ 'order_text' => 'must follow @package',
),
'author' => array(
'required' => false,
'allow_multiple' => true,
- 'order_text' => 'follows, if used, @subpackage or @package',
+ 'order_text' => 'must follow @subpackage (if used) or @package',
),
'copyright' => array(
'required' => true,
'allow_multiple' => true,
- 'order_text' => 'follows, if used, @author, @subpackage or @package',
+ 'order_text' => 'must follow @author (if used), @subpackage (if used) or @package',
),
'license' => array(
'required' => true,
'allow_multiple' => false,
- 'order_text' => 'follows @copyright',
+ 'order_text' => 'must follow @copyright',
),
'link' => array(
'required' => false,
'allow_multiple' => true,
- 'order_text' => 'follows @license',
+ 'order_text' => 'must follow @license',
),
'see' => array(
'required' => false,
'allow_multiple' => true,
- 'order_text' => 'follows, if used, @link or @license',
+ 'order_text' => 'must follow @link (if used) or @license',
),
'since' => array(
'required' => false,
'allow_multiple' => false,
- 'order_text' => 'follows, if used, @see, @link (if used) or @license',
+ 'order_text' => 'must follows @see (if used), @link (if used) or @license',
),
'deprecated' => array(
'required' => false,
'allow_multiple' => false,
- 'order_text' => 'follows, if used, @since, @see, @link or @license',
+ 'order_text' => 'must follow @since (if used), @see (if used), @link (if used) or @license',
),
);
View
2  build/phpcs/Joomla/Sniffs/Commenting/FunctionCommentSniff.php
@@ -348,7 +348,7 @@ protected function processParams($commentStart)
$errorPos = ($param->getLine() + $commentStart);
// Make sure that there is only one space before the var type.
- // Joomla change: 3 spaces to make it line up with e @return tag with a 2 space gap.
+ // Joomla change: 3 spaces to make it line up with the @return tag with a 2 space gap.
if ($param->getWhitespaceBeforeType() !== ' ') {
$error = 'Expected 3 spaces before variable type';
$this->currentFile->addError($error, $errorPos, 'BeforeParamType');
View
4 build/phpcs/Joomla/Sniffs/ControlStructures/MultiLineConditionSniff.php
@@ -83,14 +83,14 @@ public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
// Closing bracket is on the same line as a condition.
$error = 'Closing parenthesis of a multi-line IF statement must be on a new line';
$phpcsFile->addError($error, $i, 'CloseBracketNewLine');
- $expectedIndent = ($statementIndent + 4);
+ $expectedIndent = ($statementIndent + 1);
} else {
// Closing brace needs to be indented to the same level
// as the function.
$expectedIndent = $statementIndent;
}
} else {
- $expectedIndent = ($statementIndent + 4);
+ $expectedIndent = ($statementIndent + 1);
}
// We changed lines, so this should be a whitespace indent token.
View
13 docs/build.xml
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<project name="joomla-platform-manual" default="docs" basedir=".">
+
+ <target name="docs">
+ <exec
+ command="xsltproc --xinclude xsl/xhtml/docbook.xsl manual/book.xml > ../build/docs/joomla-platform-manual.html" />
+
+ <exec
+ command="xsltproc --xinclude xsl/xhtml/docbook.xsl coding-standards/book.xml > ../build/docs/joomla-platform-coding-standards.html" />
+ </target>
+
+</project>
View
24 docs/coding-standards/book.xml
@@ -1,16 +1,14 @@
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="UTF-8"?>
+<book version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:ns4="http://www.w3.org/1998/Math/MathML"
+ xmlns:ns3="http://www.w3.org/2000/svg" xmlns:ns2="http://www.w3.org/1999/xlink" xmlns:ns="http://docbook.org/ns/docbook">
+ <title>The Joomla! Platform Coding Standards</title>
-<!DOCTYPE book [
-<!ENTITY pref SYSTEM "chapters/preface.xml">
-<!ENTITY chap1 SYSTEM "chapters/source-code-management.xml">
-<!ENTITY chap2 SYSTEM "chapters/basic-guidelines.xml">
-<!ENTITY chap3 SYSTEM "chapters/php.xml">
-]>
+ <xi:include href="chapters/preface.xml" />
-<book xmlns="http://docbook.org/ns/docbook" version="5.0">
- <title>Joomla! Platform Coding Standards</title>
-&pref;
-&chap1;
-&chap2;
-&chap3;
+ <xi:include href="chapters/source-code-management.xml" />
+
+ <xi:include href="chapters/basic-guidelines.xml" />
+
+ <xi:include href="chapters/php.xml" />
</book>
View
49 docs/coding-standards/chapters/basic-guidelines.xml
@@ -1,62 +1,53 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter xml:id="ch2">
+<chapter version="5.0" xml:id="ch2" xmlns="http://docbook.org/ns/docbook" xmlns:ns5="http://www.w3.org/1999/xhtml"
+ xmlns:ns4="http://www.w3.org/1998/Math/MathML" xmlns:ns3="http://www.w3.org/2000/svg"
+ xmlns:ns2="http://www.w3.org/1999/xlink" xmlns:ns="http://docbook.org/ns/docbook">
<title>Basic Guidelines</title>
<section>
<title></title>
- <para>This chapter outlines the basic guidelines that cover and
- files.</para>
+ <para>This chapter outlines the basic guidelines that cover and files.</para>
</section>
<section>
<title>File Format</title>
- <para>All files contributed to Joomla must be stored as ASCII text, use
- UTF-8 character encoding and ne 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.</para>
+ <para>All files contributed to Joomla must be stored as ASCII text, use UTF-8 character encoding and ne 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.</para>
</section>
<section>
<title>Spelling</title>
- <para>The spelling of words and terms used in code comments and in the
- naming of class, functions, variables and constant 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 or other established conven-tions such as for
- “color” where is it common practice to maintain US English
- spelling.</para>
+ <para>The spelling of words and terms used in code comments and in the naming of class, functions, variables and constant
+ 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 or other established conventions such as for “color” where
+ is it common practice to maintain US English spelling.</para>
</section>
<section>
<title>Indenting</title>
- <para>Tabs are used for indenting code (not spaces as required by the PEAR
- standard). Source code editors or Integrated Development Environments
- (IDE’s) such as Eclipse must have the tab-stops for indenting measuring
- four (4) spaces in length.</para>
+ <para>Tabs are used for indenting code (not spaces as required by the PEAR standard). Source code editors or Integrated
+ Development Environments (IDE’s) such as Eclipse must have the tab-stops for indenting measuring four (4) spaces in
+ length.</para>
</section>
<section>
<title>Line Length</title>
- <para>There is no maximum limit for line lengths in files, however, a
- notional value of about 150 characters is recommend to achieve a good
- level of readability without horizontal scrolling. Longer lines are
- permitted if the nature of the code for individual lines requires it and
- line breaks would have an adverse affect on the final output (such as for
- mixed PHP/HTML layout files).</para>
+ <para>There is no maximum limit for line lengths in files, however, a notional value of about 150 characters is recommend to
+ achieve a good level of readability without horizontal scrolling. Longer lines are permitted if the nature of the code for
+ individual lines requires it and line breaks would have an adverse affect on the final output (such as for mixed PHP/HTML
+ layout files).</para>
</section>
<section>
<title>Best Practices</title>
- <para>TODO Any words of wisdom about PHP best practice, maybe even
- references for design patterns? Can/should we link out to the JRD, Doc
- wiki and Developer site for additional resources?</para>
+ <para>TODO Any words of wisdom about PHP best practice, maybe even references for design patterns? Can/should we link out to
+ the JRD, Doc wiki and Developer site for additional resources?</para>
</section>
</chapter>
View
920 docs/coding-standards/chapters/php.xml
@@ -1,153 +1,131 @@
<?xml version="1.0" encoding="UTF-8"?>
+<chapter version="5.0" xml:id="ch3" xmlns="http://docbook.org/ns/docbook" xmlns:ns5="http://www.w3.org/1999/xhtml"
+ xmlns:ns4="http://www.w3.org/1998/Math/MathML" xmlns:ns3="http://www.w3.org/2000/svg"
+ xmlns:ns2="http://www.w3.org/1999/xlink" xmlns:ns="http://docbook.org/ns/docbook">
+ <title>PHP</title>
-<chapter xml:id="ch3">
- <title>PHP</title>
-
- <sect1>
- <title></title>
-
- <para>This chapter is about</para>
- </sect1>
-
- <sect1>
- <title>Language Constructs</title>
-
- <sect1>
- <title>PHP Code Tags</title>
-
- <para>Always use the full &lt;?php ?&gt; to delimit PHP code, not the &lt;? ?&gt; shorthand. This
- is the most portable way to include PHP code on differing operating systems and setups.
- </para>
-
- <para>For files that contain only PHP code, the closing tag (?&gt;) should not be included. It is
- not required by PHP. Leaving this out prevents trailing white space from being accidentally
- injected into the output that can introduce errors in the Joomla session (see the PHP manual on
- instruction separation at http://php.net/basic-syntax.instruction-separation).
- </para>
-
- <para>TODO Example</para>
- </sect1>
-
- <sect1>
- <title>Including Code</title>
-
- <para>Anywhere you are unconditionally including a file, use require_once. Anywhere you are
- conditionally including a file (for example, factory methods), use include_once. Either of these
- will ensure that 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 require_once will not be included again by
- include_once.
- </para>
-
- <note>
- <para>include_once and require_once are PHP language statements, not functions. The correct
- formatting is:
- </para>
-
- <para>require_once JPATH_COMPONENT.’/helpers/helper.php’;</para>
- </note>
-
- <para>You should not enclose the filename in parentheses. </para>
- </sect1>
-
- <sect1>
- <title>E_STRICT Compatible PHP Code</title>
-
- <para>As of Joomla version 1.6 and for all versions of the Joomla Platform, adhering to object
- oriented programming practice as supported by PHP 5.2 is required. Joomla is commit-ted to
- progressively making the source code E_STRICT.
- </para>
- </sect1>
- </sect1>
-
- <sect1>
- <title>GLobal Variables</title>
-
- <para>TODO Usage should be kept to a minimum. Use OOP and factory patterns instead.</para>
- </sect1>
-
- <sect1>
- <title>Control Structures</title>
-
- <para>For all control structures, there is a space between the keyword and an opening
- parenthe-sis, then no space either after the opening parenthesis or before the closing bracket.
- This is done to distinguish control keywords from function names. All control structures must
- contain their logic within braces.
- </para>
- <para>Where the control structure is an if, the if and else keywords are put on newlines and the
- control logic is indented. The opening brace is included on the same line as the if or else and
- the closing brace is on a new line.
- </para>
- <para>For all other control structures, such as do, for, foreach, try, catch, switch and while,
- both the keyword starts a newline and the opening and closing braces are each put on a new line.
- </para>
- <sect2>
- <title>An if-else Example</title>
- <programlisting><![CDATA[
-if ($test) {
+ <para>This chapter is about ...</para>
+
+ <sect1>
+ <title>Language Constructs</title>
+
+ <sect2>
+ <title>PHP Code Tags</title>
+
+ <para>Always use the full &lt;?php ?&gt; to delimit PHP code, not the &lt;? ?&gt; shorthand. This is the most portable way
+ to include PHP code on differing operating systems and setups.</para>
+
+ <para>For files that contain only PHP code, the closing tag (?&gt;) should not be included. It is not required by PHP.
+ Leaving this out prevents trailing white space from being accidentally injected into the output that can introduce errors in
+ the Joomla session (see the PHP manual on instruction separation at
+ http://php.net/basic-syntax.instruction-separation).</para>
+
+ <para>TODO Example</para>
+ </sect2>
+
+ <sect2>
+ <title>Including Code</title>
+
+ <para>Anywhere you are unconditionally including a file, use require_once. Anywhere you are conditionally including a file
+ (for example, factory methods), use include_once. Either of these will ensure that 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 require_once will not be included
+ again by include_once.</para>
+
+ <note>
+ <para>include_once and require_once are PHP language statements, not functions. The correct formatting is:</para>
+
+ <para>require_once JPATH_COMPONENT.’/helpers/helper.php’;</para>
+ </note>
+
+ <para>You should not enclose the filename in parentheses.</para>
+ </sect2>
+
+ <sect2>
+ <title>E_STRICT Compatible PHP Code</title>
+
+ <para>As of Joomla version 1.6 and for all versions of the Joomla Platform, adhering to object oriented programming practice
+ as supported by PHP 5.2 is required. Joomla is committed to progressively making the source code E_STRICT.</para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Global Variables</title>
+
+ <para>TODO Usage should be kept to a minimum. Use OOP and factory patterns instead.</para>
+ </sect1>
+
+ <sect1>
+ <title>Control Structures</title>
+
+ <para>For all control structures there is a space between the keyword and an opening parenthesis, then no space either after
+ the opening parenthesis or before the closing bracket. This is done to distinguish control keywords from function names. All
+ control structures must contain their logic within braces.</para>
+
+ <para>For all all control structures, such as if, else, do, for, foreach, try, catch, switch and while, both the keyword
+ starts a newline and the opening and closing braces are each put on a new line.</para>
+
+ <sect2>
+ <title>An if-else Example</title>
+
+ <programlisting>if ($test)
+{
echo 'True';
}
// Comments can go here.
-else if ($test === false) {
+else if ($test === false)
+{
echo 'Really false';
-else {
- echo 'A white lie';
}
- ]]>
- </programlisting>
- </sect2>
-
- <sect2>
- <title>A do-while Example</title>
- <programlisting><![CDATA[
-do
+else
+{
+ echo 'A white lie';
+}</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>A do-while Example</title>
+
+ <programlisting>do
{
$i++;
}
-while ($i < 10);
- ]]>
- </programlisting>
- </sect2>
-
- <sect2>
- <title>A for Example</title>
- <programlisting><![CDATA[
-for ($i = 0; $i < $n; $i++)
+while ($i &lt; 10);</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>A for Example</title>
+
+ <programlisting>for ($i = 0; $i &lt; $n; $i++)
{
echo 'Increment = '.$i;
-}
- ]]>
- </programlisting>
- </sect2>
-
- <sect2>
- <title>A foreach Example</title>
- <programlisting><![CDATA[
-foreach ($rows as $index => $row)
+}</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>A foreach Example</title>
+
+ <programlisting>foreach ($rows as $index =&gt; $row)
{
echo 'Index = '.$id.', Value = '.$row;
-}
- ]]>
- </programlisting>
- </sect2>
-
- <sect2>
- <title>A while Example</title>
- <programlisting><![CDATA[
-while (!$done)
+}</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>A while Example</title>
+
+ <programlisting>while (!$done)
{
$done = true;
-}
- ]]>
- </programlisting>
- </sect2>
-
- <sect2>
- <title>A switch example</title>
- <para>When using a switch statement, the case keywords are indented. The break statement starts
- on a newline assuming the indent of the code within the case.
- </para>
- <programlisting><![CDATA[
-switch ($value)
+}</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>A switch example</title>
+
+ <para>When using a switch statement, the case keywords are indented. The break statement starts on a newline assuming the
+ indent of the code within the case.</para>
+
+ <programlisting>switch ($value)
{
case 'a':
echo 'A';
@@ -156,218 +134,516 @@ switch ($value)
default:
echo 'I give up';
break;
-}
- ]]>
- </programlisting>
- </sect2>
-
- <sect2>
- <title>References</title>
- <para>When using references, there should be a space before the reference operator and no space
- between it and the function or variable name.
- </para>
- <para>For example:</para>
- <programlisting><![CDATA[
-<?php
-$ref1 = &$this->_sql;
- ]]>
- </programlisting>
- <note>
- <para>In PHP 5, reference operators are not required for objects. All objects are handled by
- reference.
- </para>
- </note>
- </sect2>
-
- <sect2>
- <title>Arrays</title>
- <para>Assignments (the =&gt; operator) in arrays may be aligned with tabs. When splitting array
- definitions onto several lines, the last value may also have a trailing comma. This is val-id
- PHP syntax and helps to keep code diffs minimal.
- </para>
- <para>For example:</para>
- <programlisting><![CDATA[
-$options = array(
- 'foo' => 'foo',
- 'spam' => 'spam',
-);
- ]]>
- </programlisting>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Code Commenting</title>
-
- <para>Inline comments to explain code follow the convention for C (/* … */) and C++ single line
- (// ...) comments. C-style blocks are generally restricted to documentation headers for files,
- classes and functions. The C++ style is generally used for making code notes. Code notes are
- strongly encouraged to help other people, including your future-self, follow the purpose of the
- code. Always provide notes where the code is performing particularly complex operations.
- </para>
- <para>Perl/shell style comments (#) are not permitted in PHP files but are permitted in INI
- language files.
- </para>
- <para>Blocks of code may, of course, be commented out for debugging purposes using any appropriate
- format, but should be removed before submitting patches for contribution back to the core code.
- </para>
- <para>For example, do not include feature submissions like:</para>
- <programlisting><![CDATA[
-<?php
+}</programlisting>
+ </sect2>
+
+ <sect2>
+ <title>References</title>
+
+ <para>When using references, there should be a space before the reference operator and no space between it and the function
+ or variable name.</para>
+
+ <para>For example:</para>
+
+ <programlisting>&lt;?php
+$ref1 = &amp;$this-&gt;sql;</programlisting>
+
+ <note>
+ <para>In PHP 5, reference operators are not required for objects. All objects are handled by reference.</para>
+ </note>
+ </sect2>
+
+ <sect2>
+ <title>Arrays</title>
+
+ <para>Assignments (the =&gt; operator) in arrays may be aligned with tabs. When splitting array definitions onto several
+ lines, the last value may also have a trailing comma. This is valid PHP syntax and helps to keep code diffs minimal.</para>
+
+ <para>For example:</para>
+
+ <programlisting>$options = array(
+ 'foo' =&gt; 'foo',
+ 'spam' =&gt; 'spam',
+);</programlisting>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Code Commenting</title>
+
+ <para>Inline comments to explain code follow the convention for C (/* … */) and C++ single line (// ...) comments. C-style
+ blocks are generally restricted to documentation headers for files, classes and functions. The C++ style is generally used for
+ making code notes. Code notes are strongly encouraged to help other people, including your future-self, follow the purpose of
+ the code. Always provide notes where the code is performing particularly complex operations.</para>
+
+ <para>Perl/shell style comments (#) are not permitted in PHP files but are permitted in INI language files.</para>
+
+ <para>Blocks of code may, of course, be commented out for debugging purposes using any appropriate format, but should be
+ removed before submitting patches for contribution back to the core code.</para>
+
+ <para>For example, do not include feature submissions like:</para>
+
+ <programlisting>&lt;?php
// Must fix this code up one day.
-//$code = broken($fixme);
- ]]>
- </programlisting>
-
- <sect2>
- <title>Comment Docblocks</title>
-
- <para>Documentation headers for PHP and Javascript code in files, classes, class properties,
- methods and functions, called the docblocks, follow a convention similar to JavaDoc or phpDOC.
- </para>
- <para>These &quot;DocBlocks&quot; borrow from the PEAR standard but have some variations specific
- for
- Joomla and the Joomla Platform.
- </para>
- <para>Whereas normal code indenting uses real tabs, all whitespace in a Docblock uses real
- spaces. This provides better readability in source code browsers. The minimum whitespace between
- any text elements, such as tags, variable types, variable names and tag descriptions, is two
- real spaces. Variable types and tag descriptions should be aligned according to the longest
- Docblock tag and type-plus-variable respectively.
- </para>
- <para>If the @package tag is used, it will be &quot;Joomla.Platform&quot;.</para>
- <para>If the @subpackage tag is used, it is the name of the top level folder under the /joomla/
- folder. For example: Application, Database, Html, and so on.
- </para>
- <para>Code contributed to the Joomla project that will become the copyright of the project is not
- allowed to include @author tags. You should update the contribution log in CREDITS.php.
- Joomla's
- philosophy is that the code is written "all together" and there is no notion of any one
- person
- &quot;owning&quot; any section of code. The @author tags are permitted in third-party
- libraries
- that are included in the core libraries.
- </para>
- <para>Files included from third party sources must leave DocBlocks intact. Layout files use the
- same DocBlocks as other PHP files.</para>
- </sect2>
-
- <sect2>
- <title>File DocBlock Headers</title>
-
- <para>The file header DocBlock consists of the following required and optional elements in the
- following order:</para>
-
- <itemizedlist>
- <listitem>
- <para>Short description (optional unless the file contains more than two classes or functions),
- followed by a blank line).</para>
- </listitem>
- <listitem>
- <para>Long description (optional, followed by a blank line).</para>
- </listitem>
- <listitem>
- <para>@category (optional and rarely used)</para>
- </listitem>
- <listitem>
- <para>@package (generally optional but required when files contain only procedural code)</para>
- </listitem>
- <listitem>
- <para>@subpackage (optional)</para>
- </listitem>
- <listitem>
- <para>@author (optional but only permitted in non-Joomla source files, for example, included
- third-party libraries like Geshi)</para>
- </listitem>
- <listitem>
- <para>@copyright (required)</para>
- </listitem>
- <listitem>
- <para>@license (required and must be compatible with the Joomla license)</para>
- </listitem>
- <listitem>
- <para>@deprecated (optional)</para>
- </listitem>
- <listitem>
- <para>@link (optional)</para>
- </listitem>
- <listitem>
- <para>@see (optional)</para>
- </listitem>
- <listitem>
- <para>@since (generally optional but required when files contain only procedural code)</para>
- </listitem>
- </itemizedlist>
-
- <example>
- <title>Example Joomla Platform file header </title>
- <programlisting><![CDATA[
-<?php
+//$code = broken($fixme);</programlisting>
+
+ <sect2>
+ <title>Comment Docblocks</title>
+
+ <para>Documentation headers for PHP and Javascript code in files, classes, class properties, methods and functions, called
+ the docblocks, follow a convention similar to JavaDoc or phpDOC.</para>
+
+ <para>These "DocBlocks" borrow from the PEAR standard but have some variations specific for Joomla and the Joomla
+ Platform.</para>
+
+ <para>Whereas normal code indenting uses real tabs, all whitespace in a Docblock uses real spaces. This provides better
+ readability in source code browsers. The minimum whitespace between any text elements, such as tags, variable types,
+ variable names and tag descriptions, is two real spaces. Variable types and tag descriptions should be aligned according to
+ the longest Docblock tag and type-plus-variable respectively.</para>
+
+ <para>If the @package tag is used, it will be "Joomla.Platform".</para>
+
+ <para>If the @subpackage tag is used, it is the name of the top level folder under the /joomla/ folder. For example:
+ Application, Database, Html, and so on.</para>
+
+ <para>Code contributed to the Joomla project that will become the copyright of the project is not allowed to include @author
+ tags. You should update the contribution log in CREDITS.php. 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. The @author tags are permitted in third-party
+ libraries that are included in the core libraries.</para>
+
+ <para>Files included from third party sources must leave DocBlocks intact. Layout files use the same DocBlocks as other PHP
+ files.</para>
+ </sect2>
+
+ <sect2>
+ <title>File DocBlock Headers</title>
+
+ <para>The file header DocBlock consists of the following required and optional elements in the following order:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Short description (optional unless the file contains more than two classes or functions), followed by a blank
+ line).</para>
+ </listitem>
+
+ <listitem>
+ <para>Long description (optional, followed by a blank line).</para>
+ </listitem>
+
+ <listitem>
+ <para>@category (optional and rarely used)</para>
+ </listitem>
+
+ <listitem>
+ <para>@package (generally optional but required when files contain only procedural code)</para>
+ </listitem>
+
+ <listitem>
+ <para>@subpackage (optional)</para>
+ </listitem>
+
+ <listitem>
+ <para>@author (optional but only permitted in non-Joomla source files, for example, included third-party libraries like
+ Geshi)</para>
+ </listitem>
+
+ <listitem>
+ <para>@copyright (required)</para>
+ </listitem>
+
+ <listitem>
+ <para>@license (required and must be compatible with the Joomla license)</para>
+ </listitem>
+
+ <listitem>
+ <para>@deprecated (optional)</para>
+ </listitem>
+
+ <listitem>
+ <para>@link (optional)</para>
+ </listitem>
+
+ <listitem>
+ <para>@see (optional)</para>
+ </listitem>
+
+ <listitem>
+ <para>@since (generally optional but required when files contain only procedural code)</para>
+ </listitem>
+ </itemizedlist>
+
+ <example>
+ <title>Example Joomla Platform file header</title>
+
+ <programlisting>&lt;?php
/**
* @package Joomla.Platform
* @subpackage Database
* @copyright Copyright 2005 - 2010 Open Source Matters. All rights re-served.
* @license GNU General Public License version 2 or later; see LICENSE.txt
- */
- ]]>
- </programlisting>
-
- </example>
- </sect2>
+ */</programlisting>
+ </example>
+ </sect2>
+ </sect1>
+ <sect1>
+ <title>Function Calls</title>
- </sect1>
+ <para>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. There should be space before and exactly one space after the equals sign. Tab
+ alignment over multiple lines is permitted.</para>
- <sect1>
- <title>Function Calls</title>
+ <example>
+ <title>Example function call</title>
- <para>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. There should be space before and exactly one space after the equals sign. Tab alignment over multiple lines is permitted.</para>
- <example>
- <title>Example function call</title>
- <programlisting><![CDATA[
-<?php
+ <programlisting>&lt;?php
// An isolated function call.
$foo = bar($var1, $var2);
// Multiple aligned function calls.
$short = bar('short');
$medium = bar('medium');
-$long = bar('long');
- ]]>
- </programlisting>
- </example>
+$long = bar('long');</programlisting>
+ </example>
+
+ <para></para>
+ </sect1>
+
+ <sect1>
+ <title>Function Definitions</title>
+
+ <para>Function definitions start on a new line and the opening and closing braces are also placed on new lines. An empty line
+ should precede lines specifying the return value.</para>
+
+ <para>Function definitions must include a documentation comment in accordance with the Commenting section of this document.
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Short description (required, followed by a blank line)</para>
+ </listitem>
+
+ <listitem>
+ <para>Long description (optional, followed by a blank line)</para>
+ </listitem>
+
+ <listitem>
+ <para>@param (required if there are method or function arguments, the last @param tag is followed by a blank line)</para>
+ </listitem>
+
+ <listitem>
+ <para>@return (required, followed by a blank line)</para>
+ </listitem>
+
+ <listitem>
+ <para>All other tags in alphabetical order, however @since is always required.</para>
+ </listitem>
+ </itemizedlist>
+
+ <example>
+ <title>Example function definition with docblock</title>
+
+ <para><programlisting>&lt;?php
+/**
+ * A utility class.
+ *
+ * @package Joomla.Framework
+ * @subpackage XBase
+ *
+ * @param string $path The library path in dot notation.
+ *
+ * @return void
+ * @since 1.6
+ */
+public function jimport($path)
+{
+ // Body of method.
+}</programlisting></para>
+ </example>
+ </sect1>
+
+ <sect1>
+ <title>Class Definitions</title>
+
+ <para>Class definitions start on a new line and the opening and closing braces are also placed on new lines. Class methods
+ must follow the guidelines for Function Definitions. Properties and methods must follow OOP standards and be declared
+ appropriately (using public, protected, private and static as applicable). </para>
+
+ <para>Class definitions, properties and methods must each be provided with a DocBlock in accordance with the following
+ sections. </para>
+
+ <sect2>
+ <title>Class DocBlock Headers</title>
+
+ <para>The class Docblock consists of the following required and optional elements in the fol-lowing order.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Short description (required, unless the file contains more than two classes or functions), followed by a blank
+ line).</para>
+ </listitem>
+
+ <listitem>
+ <para>Long description (optional, followed by a blank line).</para>
+ </listitem>
+
+ <listitem>
+ <para>@category (optional and rarely used)</para>
+ </listitem>
+
+ <listitem>
+ <para>@package (required)</para>
+ </listitem>
+
+ <listitem>
+ <para>@subpackage (optional)</para>
+ </listitem>
+
+ <listitem>
+ <para>@author (optional but only permitted in non-Joomla source files, for example, included third-party libraries like
+ Geshi)</para>
+ </listitem>
+
+ <listitem>
+ <para>@copyright (optional unless different from the file Docblock)</para>
+ </listitem>
+
+ <listitem>
+ <para>@license (optional unless different from the file Docblock)</para>
+ </listitem>
+
+ <listitem>
+ <para>@deprecated (optional)</para>
+ </listitem>
+
+ <listitem>
+ <para>@link (optional)</para>
+ </listitem>
+
+ <listitem>
+ <para>@see (optional)</para>
+ </listitem>
+
+ <listitem>
+ <para>@since (required, being the version of the software the class was introduced)</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Class Property DocBlocks</title>
+
+ <para>The class property Docblock consists of the following required and optional elements in the following order.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Short description (required, followed by a blank line)</para>
+ </listitem>
+
+ <listitem>
+ <para>@var (required, followed by the property type)</para>
+ </listitem>
+
+ <listitem>
+ <para>@deprecated (optional)</para>
+ </listitem>
+
+ <listitem>
+ <para>@since (required)</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Class Method DocBlocks</title>
+
+ <para>The DocBlock for class methods follows the same convention as for PHP functions (see above).</para>
+
+ <example>
+ <title>Example class definition</title>
+
+ <programlisting>&lt;?php
+/**
+ * A utility class.
+ *
+ * @package Joomla.Framework
+ * @subpackage XBase
+ * @since 1.6
+ */
+class JClass extends JObject
+{
+ /**
+ * Human readable name
+ *
+ * @var string
+ * @since 1.6
+ */
+ public $name;
+
+ /**
+ * Method to get the name of the class.
+ *
+ * @param string $case Optionally return in upper/lower case.
+ *
+ * @return boolean True if successfully loaded, false otherwise.
+ *
+ * @since 1.6
+ */
+ public function getName($case = null)
+ {
+ // Body of method.
+
+ return $this-&gt;name;
+ }
+}</programlisting>
+ </example>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Naming Conventions</title>
+
+ <sect2>
+ <title>Classes</title>
+
+ <para>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.</para>
+
+ <para>For example:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>JHtmlHelper</para>
+ </listitem>
+
+ <listitem>
+ <para>JXmlParser</para>
+ </listitem>
+
+ <listitem>
+ <para>JModel</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Functions and Methods</title>
+
+ <para>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 let-ter that starts a new "word" is capitalized. Function in
+ the Joomla framework must begin with a lowercase 'j'.</para>
+
+ <para>For example:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>connect();</para>
+ </listitem>
+
+ <listitem>
+ <para>getData();</para>
+ </listitem>
+
+ <listitem>
+ <para>buildSomeWidget();</para>
+ </listitem>
+
+ <listitem>
+ <para>jImport();</para>
+ </listitem>
+
+ <listitem>
+ <para>jDoSomething();</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>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.</para>
+
+ <para>For example:</para>
+
+ <example>
+ <title>Example class with private properties (DocBlocks excluded for clarity)</title>
+
+ <programlisting>class JFooHelper
+{
+ private $_status = null;
+
+ protected $field_name = null;
+
+ protected function sort()
+ {
+ }
+}</programlisting>
+ </example>
+
+ <note>
+ <para>Private class methods, and properties, should be avoided unless absolutely necessary as they present difficulties
+ when writing unit tests.</para>
+ </note>
+ </sect2>
+
+ <sect2>
+ <title>Constants</title>
+
+ <para>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_".</para>
+ </sect2>
+
+ <sect2>
+ <title>Global Variables</title>
+
+ <para>Do not use global variables. Use static class properties or constants instead of globals.</para>
+ </sect2>
+
+ <sect2>
+ <title>Regular Variables and Class Properties</title>
+
+ <para>Regular variables, follow the same conventions as function.</para>
+
+ <para>Class variables should be set to null or some other appropriate default value.</para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Error Handling</title>
+ <para>Exceptions should be used for error handling.</para>
+ </sect1>
- <para></para>
- <para></para>
- <para></para>
- <para></para>
- <para></para>
- <para></para>
- <para></para>
- </sect1>
+ <sect1>
+ <title>SQL Queries</title>
- <sect1>
- <title></title>
+ <para>SQL keywords are to be written in uppercase, while all other identifiers (which the ex-ception of quoted text obviously)
+ is to be in lowercase.</para>
- <para></para>
- </sect1>
+ <para>All table names should use the #__ prefix rather than jos_ to access Joomla contents and allow for the user defined
+ database prefix to be applied. Queries should also use the JDatabaseQuery API.</para>
- <sect1>
- <title></title>
+ <example>
+ <title>Example query</title>
- <para></para>
- </sect1>
+ <programlisting>// Get the database connector.
+$db = JFactory::getDBO();
- <sect1>
- <title></title>
+// Get the query from the database connector.
+$query = $db-&gt;getQuery(true);
- <para></para>
- </sect1>
+// Build the query programatically (using chaining if desired).
+$query-&gt;select('u.*')
+ // Use the qn alias for the quoteName method to quote table names.
+ -&gt;from($db-&gt;qn('#__users').' AS u'));
- <sect1>
- <title></title>
+// Tell the database connector what query to run.
+$db-&gt;setQuery($query);
- <para></para>
- </sect1>
+// Invoke the query or data retrieval helper.
+$users = $db-&gt;loadObjectList();</programlisting>
+ </example>
+ </sect1>
</chapter>
View
39 docs/coding-standards/chapters/preface.xml
@@ -1,27 +1,22 @@
-<?xml version="1.0" encoding="utf-8"?>
-<preface xml:id="preface">
+<?xml version="1.0" encoding="UTF-8"?>
+<preface version="5.0" xml:id="preface" xmlns="http://docbook.org/ns/docbook" xmlns:ns5="http://www.w3.org/1999/xhtml"
+ xmlns:ns4="http://www.w3.org/1998/Math/MathML" xmlns:ns3="http://www.w3.org/2000/svg"
+ xmlns:ns2="http://www.w3.org/1999/xlink" xmlns:ns="http://docbook.org/ns/docbook">
<title>Preface</title>
- <para>One of the things that sets good software apart from great software is
- not the features or the actual function the software performs, but it more
- often than not balances on the quality of the source code. In order to
- perform in the highly competitive Open Source and propriety software
- industries, the source code not only needs to be beautifully de-signed, it
- also needs to be beautiful and elegant to look at.</para>
+ <para>One of the things that sets good software apart from great software is not the features or the actual function the
+ software performs, but the quality of the source code. In order to perform in the highly competitive Open Source and propriety
+ software industries, the source code not only needs to be beautifully designed, it also needs to be beautiful and elegant to
+ look at.</para>
- <para>Readable code is maintainable code and the compass guides us in
- achieving that goal is by developing and adhering to a set of well thought
- out coding standards for the different software languages that are employed
- in a software project. Joomla has a solid heritage of striving to support a
- great looking product with great looking code. This document compiles the
- collective wisdom of past and present contributors to the project to form
- the definitive standard for coding in Joomla, whether that is for the core
- Joomla Platform or an extension that forms part of the stack of the Joomla
- CMS. It also serves as a lighthouse to the Joomla developer community, to
- safely guide developers around the pitfalls of becoming lackadaisical with
- respect to writing clean, beautiful code.</para>
+ <para>Readable code is maintainable code and the compass that guides us in achieving that goal is a set of well thought out
+ coding standards for the different software languages that are employed in our software project. Joomla has a solid heritage of
+ striving to support a great looking product with great looking code. This document compiles the collective wisdom of past and
+ present contributors to the project to form the definitive standard for coding in Joomla, whether that is for the core Joomla
+ Platform or an extension that forms part of the stack of the Joomla CMS. It also serves as a lighthouse to the Joomla developer
+ community, to safely guide developers around the pitfalls of becoming lackadaisical with respect to writing clean, beautiful
+ code.</para>
- <para>The Joomla Coding Standards borrows heavily from the PEAR coding
- standard for PHP files, augmenting and diverging where it is deemed sensible
- to do so</para>
+ <para>The Joomla Coding Standards borrows heavily from the PEAR coding standard for PHP files, augmenting and diverging where it
+ is deemed sensible to do so</para>
</preface>
View
51 docs/coding-standards/chapters/source-code-management.xml
@@ -1,47 +1,40 @@
<?xml version="1.0" encoding="UTF-8"?>
-<chapter xml:id="ch1">
+<chapter version="5.0" xml:id="ch1" xmlns="http://docbook.org/ns/docbook" xmlns:ns5="http://www.w3.org/1999/xhtml"
+ xmlns:ns4="http://www.w3.org/1998/Math/MathML" xmlns:ns3="http://www.w3.org/2000/svg"
+ xmlns:ns2="http://www.w3.org/1999/xlink" xmlns:ns="http://docbook.org/ns/docbook">
<title>Source Code Management</title>
<section>
<title></title>
- <para>Before we start talking about what code should look list, it is
- appropriate to look at how and where the source code is stored. All
- serious software projects, whether driven by an Open Source community or
- developed within a company for proprietary purposes will manage the source
- code is some sort of source or version management system. Joomla currently
- employs two different systems. One system is for the files that form the
- product distributed as the Joomla CMS, and the other is for the files that
- are distributed as the Joomla Platform. Each system is described
- below.</para>
+ <para>Before we start talking about what code should look like, it is appropriate to look at how and where the source code is
+ stored. All serious software projects, whether driven by an Open Source community or developed within a company for
+ proprietary purposes will manage the source code is some sort of source or version management system. Joomla currently employs
+ two different systems. One system is for the files that form the product distributed as the Joomla CMS, and the other is for
+ the files that are distributed as the Joomla Platform. Each system is described below.</para>
</section>
<section>
<title>The Joomla Platform</title>
- <para>In April 2011 the Joomla project decided to formally split off the
- core engine that drives the Joomla CMS into a separate project with a
- separate development path called the Joomla Platform. The Joomla Platform
- is a PHP framework that is designed to serve as a foundation for not only
- web applications (like a CMS) but other types of software such as command
- line applications. The files that form the Joomla Platform are stored in a
- Distributed Version Control System (DVCS) called Mercurial hosted at
- bitbucket.org</para>
-
- <para>You can learn about how to get the Joomla Platform source code from
- the Mercurial repository from the following page: &lt;permalink to
- developer.joomla.org staging page&gt;</para>
-
- <para>Because Mercurial treats the concepts of file revision numbers
- differently than Subversion, the repository revision number is not
- required in files (that is, the @version tag is not necessary).</para>
+ <para>In April 2011 the Joomla project decided to formally split off the core engine that drives the Joomla CMS into a
+ separate project with a separate development path called the Joomla Platform. The Joomla Platform is a PHP framework that is
+ designed to serve as a foundation for not only web applications (like a CMS) but other types of software such as command line
+ applications. The files that form the Joomla Platform are stored in a Distributed Version Control System (DVCS) called Git
+ hosted at github.org</para>
+
+ <para>You can learn about how to get the Joomla Platform source code from the Git repository from the following page:
+ &lt;permalink to developer.joomla.org staging page&gt;</para>
+
+ <para>Because Git treats the concepts of file revision numbers differently than Subversion, the repository revision number is
+ not required in files (that is, the @version tag is not necessary).</para>
</section>
<section>
<title>Compliance Tool</title>
- <para>TODO Mention something about CodeSniffer and the custom Joomla sniff
- standard for PHP files. The Sniff is based on the standard outlined in
- this document.</para>
+ <para>TODO Mention something about CodeSniffer and the custom Joomla sniff standard for PHP files. The Sniff is based on the
+ standard outlined in this document. For more information about how code standards are enforced see the analysis appendix of
+ the manual.</para>
</section>
</chapter>
View
204 docs/manual/appendices/analysis.xml
@@ -1,102 +1,104 @@
-<?xml version="1.0" encoding="utf-8"?>
-<appendix xml:id="app1">
- <title>Configuring Code Analysis Tools</title>
-
- <sect1>
- <title>Running Unit Tests</title>
-
- <para>Before code gets pulled into the master repository, the unit testing suite is run to
- ensure that the change candidates to not leave trunk in an unstable state (i.e. all tests
- should pass at all times). In order to make the process of getting your code accepted it
- is helpful to run these tests locally to prevent any unexpected surprises.</para>
-
- <para>The Joomla Platform unit tests are developed for use with PHPUnit 3.5, which is the
- latest stable version as of August 2011. Please see the
- <link href="http://www.phpunit.de/manual/3.5/en/installation.html">PHPUnit Manual</link> for
- information on installing PHPUnit on your system.</para>
-
- <sect2>
- <title>Configuring Your Environment</title>
-
- <para>At this point in time you will get a bunch of failed unit tests if you attempt to execute
- them without first creating a database, populating it, and configuring the unit tests to be able
- to locate the correct database using the correct user.</para>
-
- <para>To do this, perform the following steps:</para>
-
- <itemizedlist>
- <listitem>
- <para>Create a database and a database user with full access to the database.</para>
- </listitem>
-
- <listitem>
- <para>Populate the database by executing the ddl.sql file found in the tests directory.</para>
- </listitem>
-
- <listitem>
- <para>Copy the config.php-dist file to config.php (in the tests directory) and edit the host, user,
- password and db values as appropriate (this step can be skipped if your database is on localhost,
- is named joomla_ut, your user is named utuser and the password is ut1234.</para>
- </listitem>
-
- </itemizedlist>
-
- </sect2>
-
- <sect2>
- <title>Running the Tests</title>
-
- <para>You can run the tests by going to the platform root directory and executing <command>phpunit</command></para>
-
- </sect2>
-
- <sect2>
- <title>Known Issues</title>
-
- <itemizedlist>
- <listitem>
- <para>There is currently a cache test that will fail the first time you run the tests. If you run the tests a
- second time it should pass.</para>
- </listitem>
-
- </itemizedlist>
-
- </sect2>
-
- </sect1>
-
- <sect1>
- <title>Coding Standards Analysis</title>
-
- <para>In order to improve the consistency and readability of the source code, we run a coding style analysis tool everytime
- changes are pushed in the repo. For new contributions we are going to be encorcing coding standards to ensure that the coding
- style in the source code is consistent. Ensuring that your code meets these standards will make the process of code contribution
- smoother.</para>
-
- <para>The Joomla Platform sniffer rules are written to be used with a tool called PHP_CodeSniffer. Please see the
- <link href="http://pear.php.net/package/PHP_CodeSniffer">PHP_CodeSniffer Pear Page</link> for
- information on installing PHP_CodeSniffer on your system.</para>
-
- <sect2>
- <title>Configuring Your Environment</title>
-
- <para>The Joomla project has written custom code sniffer rules for use with PHP_CodeSniffer. Unfortunately, these is a
- limitation in PHP_CodeSniffer which means that in order to use the custom rules they either have to be symlinked or copied into
- the PEAR directory.</para>
-
- <para>The build/phpcs/Joomla directory must be copied into CodeSniffer standards directory. On Ubuntu 11.04 this directory is
- <filename>/usr/share/php/PHP/CodeSniffer/Standards</filename>. On Macports this directory is
- <filename>/opt/local/lib/php/PHP/CodeSniffer/Standards</filename>. Other systems and configurations will vary.</para>
-
- </sect2>
-
- <sect2>
- <title>Running CodeSniffer</title>
-
- <para>You can run CodeSniffer by going to the platform root directory and executing
- <command>phpcs --report=checkstyle --report-file=build/logs/checkstyle.xml --standard=Joomla /path/to/platform</command></para>
-
- </sect2>
-
- </sect1>
+<?xml version="1.0" encoding="UTF-8"?>
+<appendix version="5.0" xml:id="app2" xmlns="http://docbook.org/ns/docbook" xmlns:ns5="http://www.w3.org/1999/xhtml"
+ xmlns:ns4="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1998/Math/MathML"
+ xmlns:ns2="http://www.w3.org/1999/xlink" xmlns:ns="http://docbook.org/ns/docbook">
+ <title>Configuring Code Analysis Tools</title>
+
+ <sect1>
+ <title>Running Unit Tests</title>
+
+ <para>Before code gets pulled into the master repository, the unit testing suite is run to ensure that the change candidates
+ to not leave trunk in an unstable state (i.e. all tests should pass at all times). In order to make the process of getting
+ your code accepted it is helpful to run these tests locally to prevent any unexpected surprises.</para>
+
+ <para>The Joomla Platform unit tests are developed for use with PHPUnit 3.5, which is the latest stable version as of August
+ 2011. Please see the <link ns2:href="http://www.phpunit.de/manual/3.5/en/installation.html">PHPUnit Manual</link> for information
+ on installing PHPUnit on your system.</para>
+
+ <sect2>
+ <title>Configuring Your Environment</title>
+
+ <para>At this point in time you will get a bunch of failed unit tests if you attempt to execute them without first creating
+ a database, populating it, and configuring the unit tests to be able to locate the correct database using the correct
+ user.</para>
+
+ <para>To do this, perform the following steps:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Create a database and a database user with full access to the database.</para>
+ </listitem>
+
+ <listitem>
+ <para>Populate the database by executing the ddl.sql file found in the tests directory.</para>
+ </listitem>
+
+ <listitem>
+ <para>Copy the config.php-dist file to config.php (in the tests directory) and edit the host, user, password and db
+ values as appropriate (this step can be skipped if your database is on localhost, is named joomla_ut, your user is named
+ utuser and the password is ut1234.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Running the Tests</title>
+
+ <para>You can run the tests by going to the platform root directory and executing <command>phpunit</command></para>
+ </sect2>
+
+ <sect2>
+ <title>Known Issues</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>There is currently a cache test that will fail the first time you run the tests. If you run the tests a second
+ time it should pass.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Coding Standards Analysis</title>
+
+ <para>In order to improve the consistency and readability of the source code, we run a coding style analysis tool everytime
+ changes are pushed in the repo. For new contributions we are going to be encorcing coding standards to ensure that the coding
+ style in the source code is consistent. Ensuring that your code meets these standards will make the process of code
+ contribution smoother.</para>
+
+ <para>The Joomla Platform sniffer rules are written to be used with a tool called PHP_CodeSniffer. Please see the <link
+ ns2:href="http://pear.php.net/package/PHP_CodeSniffer">PHP_CodeSniffer Pear Page</link> for information on installing
+ PHP_CodeSniffer on your system.</para>
+
+ <sect2>
+ <title>Configuring Your Environment</title>
+
+ <para>The Joomla project has written custom code sniffer rules for use with PHP_CodeSniffer. Unfortunately, these is a
+ limitation in PHP_CodeSniffer which means that in order to use the custom rules they either have to be symlinked or copied
+ into the PEAR directory.</para>
+
+ <para>The build/phpcs/Joomla directory must be copied into CodeSniffer standards directory. On Ubuntu 11.04 this directory
+ is <filename>/usr/share/php/PHP/CodeSniffer/Standards</filename>. On Macports this directory is
+ <filename>/opt/local/lib/php/PHP/CodeSniffer/Standards</filename>. Other systems and configurations will vary.</para>
+ </sect2>
+
+ <sect2>
+ <title>Running CodeSniffer</title>
+
+ <para>You can run CodeSniffer by going to the platform root directory and executing <command>phpcs --report=checkstyle
+ --report-file=build/logs/checkstyle.xml --standard=Joomla /path/to/platform</command></para>
+ </sect2>
+
+ <sect2>
+ <title>Known Issues</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>There is currently an issue with running the Code Sniffer on the Simplepie library. Running from inside the Joomla
+ folder will avoid this issue.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
</appendix>
View
1,263 docs/manual/appendices/changelog.xml
@@ -1,341 +1,1142 @@
-<?xml version="1.0" encoding="utf-8"?>
-<appendix xml:id="app1">
- <title>Changelog</title>
+<?xml version="1.0" encoding="UTF-8"?>
+<appendix version="5.0" xml:id="app1" xmlns="http://docbook.org/ns/docbook" xmlns:ns5="http://www.w3.org/1999/xhtml"
+ xmlns:ns4="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1998/Math/MathML"
+ xmlns:ns2="http://www.w3.org/1999/xlink" xmlns:ns="http://docbook.org/ns/docbook">
+ <title>Changelog</title>
- <sect1>
- <title>Version 11.3</title>
+ <sect1>
+ <title>Version 11.3</title>
- <para>Version 11.3 is currently under development.</para>
-
- <itemizedlist>
+ <para>Version 11.3 is currently under development.</para>
+ <itemizedlist>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/263" ns2:title="Closed 2011-08-20T04:16:41Z">#263</link>
+] Fixes code style issues. ( <link ns2:href="https://api.github.com/users/elinw">elinw</link>
+)</para>
+ <para>Doc block work mainly in html/parameter</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/266" ns2:title="Closed 2011-08-20T17:43:46Z">#266</link>
+] Fixes typographical errors in docbook files. ( <link ns2:href="https://api.github.com/users/elinw">elinw</link>
+)</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/271" ns2:title="Closed 2011-08-21T13:44:48Z">#271</link>
+] Fixes code style issues. ( <link ns2:href="https://api.github.com/users/elinw">elinw</link>
+)</para>
+ <para>Continued work on cleaning up doc blocs.</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/262" ns2:title="Closed 2011-08-22T06:45:10Z">#262</link>
+] Adds a JString::increment method and fixes bugs in JHtmlString::truncate. ( <link ns2:href="https://api.github.com/users/eddieajau">eddieajau</link>
+)</para>
+ <para>Adds a JString::increment method to allow for easier incrementing of title/label strings such as &quot;Title (2)&quot; that are used in copying routines within an application.&#13;
+&#13;
+This method can be used to replace duplicate code in the CMS: CategoryModelCategory, MenusModelItem, ModulesModelMouldes and TemplatesModelStyle.&#13;
+&#13;
+Updates JModelAdmin to use the new method in generateNewTitle.&#13;
+&#13;
+Code coverage and code cleaning also included.&#13;
+&#13;
+Fixes bugs in JHtmlString::truncate where tags are not being properly closed.&#13;
+&#13;
+Adds unit tests for JHtmlString.&#13;
+</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/272" ns2:title="Closed 2011-08-21T21:41:34Z">#272</link>
+] Fixes DocBlocks in JTree and JParameter elements. ( <link ns2:href="https://api.github.com/users/elinw">elinw</link>
+)</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/257" ns2:title="Closed 2011-08-20T10:22:26Z">#257</link>
+] Adds JArrayHelper::pivot, improves JArrayHelper::sortObjects and provides full code coverage. ( <link ns2:href="https://api.github.com/users/eddieajau">eddieajau</link>
+)</para>
+ <para>Alphabetised methods in JArrayHelperTest and adds test for arrayUnique method.&#13;
+&#13;
+Refactored unreachable code in _fromObject (arrays cannot be processed without the recurse argument being true. Added test case to verify).&#13;
+&#13;
+Changed testSortObjects to do most of the tests on a mac (ignoring only those that cause problems).&#13;
+&#13;
+Refactors sortObjects method to use internal static variables for sort properties, instead of some arbitrary [bad practice] global variable.&#13;
+&#13;
+Added JArrayHelper::pivot which allows you to create pure reverse lookups on an array of scalar, array or object elements, or lookups based on collections of common values or the designated array/object key.&#13;
+&#13;
+</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/232" ns2:title="Closed 2011-08-20T08:46:34Z">#232</link>
+] Joomla CMS [#25957] wrong behaviour of libraries/joomla/application/module/JModuleHelper:moduleCache() ( <link ns2:href="https://api.github.com/users/elinw">elinw</link>
+)</para>
+ <para>Based on code proposed here: http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&amp;tracker_item_id=25957 This issue has been in the tracker since May.</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/260" ns2:title="Closed 2011-08-20T00:39:03Z">#260</link>
+] Joomla CMS [#26612] Contacts Component sets Reply-To incorrectly in 1.7 ( <link ns2:href="https://api.github.com/users/infograf768">infograf768</link>
+)</para>
+ <para>Fixes platform issues related to http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&amp;tracker_item_id=26612&#13;
+&#13;
+</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/229" ns2:title="Closed 2011-08-20T00:30:21Z">#229</link>
+] Joomla CMS [#25962] APC lock method seems to be returning the wrong thing ( <link ns2:href="https://api.github.com/users/elinw">elinw</link>
+)</para>
+ <para>Fixes incorrect return value in docblocks.&#13;
+&#13;
+http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&amp;tracker_item_id=25962</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/214" ns2:title="Closed 2011-08-19T04:37:02Z">#214</link>
+] Adds universal mocks for testing and JDate::getInstance. ( <link ns2:href="https://api.github.com/users/eddieajau">eddieajau</link>
+)</para>
+ <para>Added support for getting universal mock objects in JoomlaTestCase providing getters for JApplication, JConfig, JDatabase and JSession mocks.&#13;
+&#13;
+Converted JDatabaseQuery test to use the universal database mock.&#13;
+&#13;
+Improved setup and teardown of rules field test in JForm.&#13;
+&#13;
+Added tests for JDate (tests involving language are incomplete because of tight coupling to the CMS).&#13;
+&#13;
+Added static getInstance method to JDate as an alias for new JDate.</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/255" ns2:title="Closed 2011-08-17T22:09:51Z">#255</link>
+] Added JLog dependency to JError and JException ( <link ns2:href="https://api.github.com/users/elinw">elinw</link>
+)</para>
+ <para>Add JLog for JError and JException since both are deprecated and deprecation logging was causing an infinite loop.</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/256" ns2:title="Closed 2011-08-18T10:18:47Z">#256</link>
+] Fixes login and module display issues in the CMS ( <link ns2:href="https://api.github.com/users/eddieajau">eddieajau</link>
+)</para>
+ <para>Using database magic calls (qn and q) causes problems in the session database class, so these have been replaced with the fully qualified names.&#13;
+A small glitch in the module display was fixed.&#13;
+JAuthentication::authenticate was still being defined as static which caused problems with the plugins.</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/254" ns2:title="Closed 2011-08-17T21:40:05Z">#254</link>
+] Fixes comments in sniff and docblocks in JError ( <link ns2:href="https://api.github.com/users/elinw">elinw</link>
+)</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/252" ns2:title="Closed 2011-08-16T21:54:43Z">#252</link>
+] Turn JAuthentication back from static class and updated tests accordingly ( <link ns2:href="https://api.github.com/users/pasamio">pasamio</link>
+)</para>
+ <para>This fixes an issue with syncing the CMS where the CMS breaks because the plugins aren't loaded properly. This restores the pre-11.2 behaviour of not using a static class. Also a minor update to fix spaces used instead of tabs in the test.</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/247" ns2:title="Closed 2011-08-16T21:25:54Z">#247</link>
+] Check if module properly is set ( <link ns2:href="https://api.github.com/users/elinw">elinw</link>
+)</para>
+ <para>In testing the JBs found a regression in that in getModule the module helper is now not setting $module-&gt;user to 0 for all modules any more. I did some digging and this seems to be a legacy property from 1.0 and seemed to possible check if you were a super user for menu modules. As far as I can tell it has no use at all in the current CMS. (Looking at the 1.0 module code explains a lot about some other parts of the module helper.)</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/248" ns2:title="Closed 2011-08-15T14:40:26Z">#248</link>
+] Added a command line application to automatically generate the changelog from closed pull requests. ( <link ns2:href="https://api.github.com/users/eddieajau">eddieajau</link>
+)</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/236" ns2:title="Closed 2011-08-14T18:27:10Z">#236</link>
+] Add a unit test for JFormRuleColor and fix the rule. ( <link ns2:href="https://api.github.com/users/realityking">realityking</link>
+)</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/209" ns2:title="Closed 2011-08-13T20:52:17Z">#209</link>
+] Updated changelog ( <link ns2:href="https://api.github.com/users/nikosdion">nikosdion</link>
+)</para>
+ <para>Updated change log with the proposed change, as per Andrew's request at https://github.com/joomla/joomla-platform/pull/201#issuecomment-1776347</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/222" ns2:title="Closed 2011-08-13T07:16:59Z">#222</link>
+] Fixing checkstyle errors for JPagination. ( <link ns2:href="https://api.github.com/users/LouisLandry">LouisLandry</link>
+)</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/221" ns2:title="Closed 2011-08-13T06:59:09Z">#221</link>
+] Fixing up some checkstyle issues. ( <link ns2:href="https://api.github.com/users/LouisLandry">LouisLandry</link>
+)</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/220" ns2:title="Closed 2011-08-13T06:30:36Z">#220</link>
+] Fixed missing J prefix when registering JDatabaseException. ( <link ns2:href="https://api.github.com/users/eddieajau">eddieajau</link>
+)</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/212" ns2:title="Closed 2011-08-13T06:13:01Z">#212</link>
+] Fix login routine to display error message generated by authentication pl ( <link ns2:href="https://api.github.com/users/roland-d">roland-d</link>
+)</para>
+ <para>Fix login routine to display error message generated by authentication plugin.</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/219" ns2:title="Closed 2011-08-13T06:08:38Z">#219</link>
+] Merge with CMS trunk change. ( <link ns2:href="https://api.github.com/users/LouisLandry">LouisLandry</link>
+)</para>
+ <para>Closes #197.&#13;
+&#13;
+and&#13;
+&#13;
+Closes #172.</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/218" ns2:title="Closed 2011-08-13T05:33:01Z">#218</link>
+] Fix up specification of abstract JDatabase::getTableColumns. ( <link ns2:href="https://api.github.com/users/eddieajau">eddieajau</link>
+)</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/215" ns2:title="Closed 2011-08-12T21:14:43Z">#215</link>
+] Description for pull request 212 ( <link ns2:href="https://api.github.com/users/roland-d">roland-d</link>
+)</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/213" ns2:title="Closed 2011-08-12T21:14:07Z">#213</link>
+] Fix annoying typo. ( <link ns2:href="https://api.github.com/users/elinw">elinw</link>
+)</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/211" ns2:title="Closed 2011-08-11T21:34:28Z">#211</link>
+] CodeSniffer Cleanup on JForm library ( <link ns2:href="https://api.github.com/users/mbabker">mbabker</link>
+)</para>
+ <para>Used the CodeSniffer to do a cleanup on the JForm library. With these changes, no further messages appear in the report.</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/208" ns2:title="Closed 2011-08-10T20:27:43Z">#208</link>
+] Changing access to JDatabase::replacePrefix() back to public ( <link ns2:href="https://api.github.com/users/elkuku">elkuku</link>
+)</para>
+ <para>As suggested on [Gooogle groups](http://groups.google.com/group/joomla-dev-framework/browse_thread/thread/77dd8810690a9f4f) and reported on the CMS Tracker [#26596](http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&amp;tracker_item_id=26596) and [#26617](http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&amp;tracker_item_id=26617)</para>
+ </listitem>
<listitem>
- <para>Fixed the login routine to return the error message set by authentication plugin.</para>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/201" ns2:title="Closed 2011-08-08T22:38:13Z">#201</link>
+] Fixed a typo in JHttp (stream_set_timeout vs stream_settimeout) as it cau ( <link ns2:href="https://api.github.com/users/nikosdion">nikosdion</link>
+)</para>
+ <para>Fixed a typo in JHttp (stream_set_timeout vs stream_settimeout) as it caused a fatal error when using the class. Hopefully, this time I got the pull request against the correct branch.</para>
</listitem>
<listitem>
- <para>Moved JString from Utilites package to String package.
- Added JStringNormalize.
- Renamed DatabaseException to JDatabaseException.
- Fixed several instances of database exceptions being thrown without error
- messages or codes.
- Removed old CHANGELOG.</para>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/207" ns2:title="Closed 2011-08-10T16:44:06Z">#207</link>
+] Docblocks ( <link ns2:href="https://api.github.com/users/elinw">elinw</link>
+)</para>
</listitem>
<listitem>
- <para>This manual was added.</para>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/205" ns2:title="Closed 2011-08-10T03:34:38Z">#205</link>
+] Added missing jimport ( <link ns2:href="https://api.github.com/users/ianmacl">ianmacl</link>
+)</para>
+ <para>Let's try this again. *sigh*</para>
</listitem>
<listitem>
- <para>The coding standards document was added.</para>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/204" ns2:title="Closed 2011-08-10T02:20:51Z">#204</link>
+] Code style work ( <link ns2:href="https://api.github.com/users/elinw">elinw</link>
+)</para>
+ <para>Easy wins</para>
</listitem>
<listitem>
- <para>Numerous DocBlock and coding standard improvements.</para>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/193" ns2:title="Closed 2011-08-09T21:01:17Z">#193</link>
+] Call to a member function qn() on a non-object ( <link ns2:href="https://api.github.com/users/jonnsl">jonnsl</link>
+)</para>
</listitem>
<listitem>
- <para>The Joomla codesniffer was added to the tree and the build process.</para>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/195" ns2:title="Closed 2011-08-09T20:06:20Z">#195</link>
+] More doc block work ( <link ns2:href="https://api.github.com/users/elinw">elinw</link>
+)</para>
+ <para>Code style</para>
</listitem>
<listitem>
- <para>Fixed bug where $offset would not be honoured in the sub-call to utf8_strrpos.</para>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/203" ns2:title="Closed 2011-08-09T20:03:48Z">#203</link>
+] Fixed function name mentioned in deprecated warning. ( <link ns2:href="https://api.github.com/users/jlleblanc">jlleblanc</link>
+)</para>
+ <para>Deprecated JDatabase::loadResultArray() logged a warning with the incorrect replacement function name. This patch changes it from getColumn() to loadColumn().</para>
</listitem>
<listitem>
- <para>Implemented a color field for JForm. This uses the native color picker in Opera 11 and
- falls back to MooRainbow in all other browsers. Also adds the corresponding JFormRule for
- validation.</para>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/191" ns2:title="Closed 2011-08-07T14:22:29Z">#191</link>
+] Namespace more of Joomla's JavaScript functions and deprecate the old one ( <link ns2:href="https://api.github.com/users/realityking">realityking</link>
+)</para>
+ <para>Namespace more of Joomla's JavaScript functions and deprecate the old ones.</para>
</listitem>
<listitem>
- <para>Implemented graceful failure when update manifest is not available</para>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/198" ns2:title="Closed 2011-08-08T16:48:17Z">#198</link>
+] Various fixes ( <link ns2:href="https://api.github.com/users/realityking">realityking</link>
+)</para>
+ <para>Again a couple of smaller fixes. (Take 2)</para>
</listitem>
<listitem>
- <para>Allow components to remove the admin menu entry in their postflight script, and not
- throw errors during uninstall if the menu entries are not there.</para>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/194" ns2:title="Closed 2011-08-07T20:30:31Z">#194</link>
+] Adding test execution instructions ( <link ns2:href="https://api.github.com/users/ianmacl">ianmacl</link>
+)</para>
+ <para>Basic instructions on running phpunit and phpcs.</para>
</listitem>
<listitem>
- <para>Implemented fluid interface for setter and mutator methods in document package.
- JDocument: parse(), addScript(), addScriptDeclaration(), addStyleSheet(),
- addStyleDeclaration(), setBase(), setBuffer(), setCharset(), setDescription(),
- setDirection(), setGenerator(), setLanguage(), setLineEnd(), setLink(), setMetaData(),
- setMimeEncoding(), setModifiedDate(), setTab(), setTitle(), setType().
- JDocumentFeed: addItem(), setEnclosure().
- JDocumentHTML: addCustomTag(), addFavicon(), addHeadLink(), mergeHeadData(),
- setBuffer(), setHeadData(), _fetchTemplate(), _parseTemplate().
- JDocumentJSON: setName().
- JDocumentOpensearch: addImage(), addUrl(), setShortName().
- JDocumentXml: setName().</para>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/192" ns2:title="Closed 2011-08-07T06:19:56Z">#192</link>
+] Mising @since tags ( <link ns2:href="https://api.github.com/users/elinw">elinw</link>
+)</para>
</listitem>
<listitem>
- <para>Fixed 'Call to a member function qn() on a non-object in
- libraries/joomla/form/fields/rules.php on line 304'.</para>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/189" ns2:title="Closed 2011-08-06T23:56:35Z">#189</link>
+] Sync changes to the media folder from Joomla 1.7. ( <link ns2:href="https://api.github.com/users/realityking">realityking</link>
+)</para>
+ <para>I made this against staging just to be sure, but for the future should we also make the pull requests against staging when no PHP code is involved?</para>
</listitem>
<listitem>
- <para>Fixed bug in JHtml: stream_set_timeout was misspelled as stream_settimeout, throwing a Fatal Error each time the class was used</para>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/188" ns2:title="Closed 2011-08-06T19:39:26Z">#188</link>
+] Various little fixes. ( <link ns2:href="https://api.github.com/users/realityking">realityking</link>
+)</para>
</listitem>
<listitem>
- <para></para>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/186" ns2:title="Closed 2011-08-06T01:24:35Z">#186</link>
+] Utfail ( <link ns2:href="https://api.github.com/users/ianmacl">ianmacl</link>
+)</para>
+ <para>Fixed unit test. The test for parse verified that the method returned null. The method now returns a JDocument object. Test changed to reflect that.</para>
</listitem>
<listitem>
- <para></para>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/185" ns2:title="Closed 2011-08-05T19:47:57Z">#185</link>
+] JDocument fluent interface - reprise ( <link ns2:href="https://api.github.com/users/WebMechanic">WebMechanic</link>
+)</para>
+ <para>- changed setters and mutators to return $this instead of &quot;void&quot;.&#13;
+- cleanup of duplicate jimport('joomla.document.document')&#13;
+- whitespace and indents</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/184" ns2:title="Closed 2011-08-05T19:40:05Z">#184</link>
+] Code cleaning. ( <link ns2:href="https://api.github.com/users/LouisLandry">LouisLandry</link>
+)</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/182" ns2:title="Closed 2011-08-05T09:14:37Z">#182</link>
+] Code cleaning ( <link ns2:href="https://api.github.com/users/eddieajau">eddieajau</link>
+)</para>
+ <para>Fixing up the HTML package.</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/180" ns2:title="Closed 2011-08-04T14:38:38Z">#180</link>
+] Allow removal of admin menu entries ( <link ns2:href="https://api.github.com/users/rvsjoen">rvsjoen</link>
+)</para>
+ <para>This will allow developers to remove the backend entry in the components menu using for example the postflight() hook in the installer without throwing errors about missing menu entries when the component is uninstalled.</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/179" ns2:title="Closed 2011-08-04T05:47:44Z">#179</link>
+] Added String package, updated changelog ( <link ns2:href="https://api.github.com/users/robschley">robschley</link>
+)</para>
+ <para>Moved JString from Utilites package to String package.&#13;
+Added JStringNormalize.&#13;
+Removed old CHANGELOG.</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/178" ns2:title="Closed 2011-08-04T05:47:33Z">#178</link>
+] Code cleaning. ( <link ns2:href="https://api.github.com/users/eddieajau">eddieajau</link>
+)</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/174" ns2:title="Closed 2011-08-04T04:09:32Z">#174</link>
+] Graceful return when update manifest cannot be parsed ( <link ns2:href="https://api.github.com/users/rvsjoen">rvsjoen</link>
+)</para>
+ <para>Instead of just dying when the update manifest cannot be parsed, give a warning and move on.</para>
+ </listitem>
+ <listitem>
+ <para>[ <link ns2:href="https://api.github.com/repos/joomla/joomla-platform/issues/173" ns2:title="Closed 2011-08-04T04:07:54Z">#173</link>
+] Test ( <