Merge branch 'master' of github.com:joomla/joomla-platform into 23882

README.markdown

@@ -15,7 +15,8 @@ A guide for contributing to the Joomla Platform can be found at: https://github.
 Requirements
 ------------
 
-* PHP 5.3+
+* PHP 5.2.4+ for Platform versions 11.x
+* PHP 5.3+ for Platform versions 12.x  
 
 
 Installation

build.xml

@@ -83,7 +83,7 @@
    <arg value="--report=checkstyle" />
    <arg value="--report-file=${basedir}/build/logs/checkstyle.xml" />
    <arg value="--standard=${basedir}/build/phpcs/Joomla" />
-   <arg value="--ignore=${source}/phpmailer,${source}/phputf8,${source}/simplepie/${source}/config.example.php" />
+   <arg value="--ignore=${source}/phpmailer,${source}/phputf8,${source}/simplepie/,${source}/config.example.php" />
    <arg path="${source}" />
   </exec>
  </target>

build/phpcs/Joomla/Sniffs/Commenting/FileCommentSniff.php

@@ -484,7 +484,7 @@ protected function processTags($commentStart, $commentEnd)
             // Joomla change: allow for 2 space gap.
                 && $indentInfo['space'] !== ($longestTag + 2)
             ) {
-                $expected = (($longestTag - strlen($indentInfo['tag'])) + 1);
+                $expected = (($longestTag - strlen($indentInfo['tag'])) + 2);
                 $space    = ($indentInfo['space'] - strlen($indentInfo['tag']));
                 $error    = '@%s tag comment indented incorrectly; expected %s spaces but found %s';
                 $data     = array(

build/phpcs/Joomla/Sniffs/Functions/FunctionCallSignatureSniff.php

@@ -234,13 +234,18 @@ public function processMultiLineCall(PHP_CodeSniffer_File $phpcsFile, $stackPtr,
             }
         }//end for
 
-        if ($tokens[($openBracket + 1)]['content'] !== $phpcsFile->eolChar) {
+        if ($tokens[($openBracket + 1)]['content'] !== $phpcsFile->eolChar
+        && T_CONSTANT_ENCAPSED_STRING != $tokens[($openBracket + 1)]['code'])// allow a '"'
+        {
             $error = 'Opening parenthesis of a multi-line function call must be the last content on the line';
             $phpcsFile->addError($error, $stackPtr, 'ContentAfterOpenBracket');
         }
 
         $prev = $phpcsFile->findPrevious(T_WHITESPACE, ($closeBracket - 1), null, true);
-        if ($tokens[$prev]['line'] === $tokens[$closeBracket]['line']) {
+
+        if ($tokens[$prev]['line'] === $tokens[$closeBracket]['line']
+        && T_CONSTANT_ENCAPSED_STRING != $tokens[$prev]['code'])// allow a '"'
+        {
             $error = 'Closing parenthesis of a multi-line function call must be on a line by itself';
             $phpcsFile->addError($error, $closeBracket, 'CloseBracketLine');
         }

build/phpcs/Joomla/Sniffs/WhiteSpace/OperatorSpacingSniff.php

@@ -0,0 +1,258 @@
+<?php
+/**
+ * Sniffs_Squiz_WhiteSpace_OperatorSpacingSniff.
+ *
+ * PHP version 5
+ *
+ * @category  PHP
+ * @package   PHP_CodeSniffer
+ * @author    Greg Sherwood <gsherwood@squiz.net>
+ * @author    Marc McIntyre <mmcintyre@squiz.net>
+ * @copyright 2006 Squiz Pty Ltd (ABN 77 084 670 600)
+ * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
+ * @version   CVS: $Id: OperatorSpacingSniff.php 8 2010-11-06 00:40:23Z elkuku $
+ * @link      http://pear.php.net/package/PHP_CodeSniffer
+ */
+
+/**
+ * Verifies that operators have valid spacing surrounding them.
+ *
+ * Example:
+ * <b class="bad">$a=$b+$c;</b>
+ * <b class="good">$a = $b + $c;</b>
+ *
+ * @category  PHP
+ * @package   PHP_CodeSniffer
+ * @author    Greg Sherwood <gsherwood@squiz.net>
+ * @author    Marc McIntyre <mmcintyre@squiz.net>
+ * @copyright 2006 Squiz Pty Ltd (ABN 77 084 670 600)
+ * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
+ * @version   Release: 1.3.0RC1
+ * @link      http://pear.php.net/package/PHP_CodeSniffer
+ */
+class Joomla_Sniffs_WhiteSpace_OperatorSpacingSniff implements PHP_CodeSniffer_Sniff
+{
+    /**
+     * A list of tokenizers this sniff supports.
+     *
+     * @var array
+     */
+    public $supportedTokenizers = array(
+                                   'PHP',
+                                   'JS',
+    );
+
+    /**
+     * Returns an array of tokens this test wants to listen for.
+     *
+     * @return array
+     */
+    public function register()
+    {
+        $comparison = PHP_CodeSniffer_Tokens::$comparisonTokens;
+        $operators  = PHP_CodeSniffer_Tokens::$operators;
+        $assignment = PHP_CodeSniffer_Tokens::$assignmentTokens;
+
+        return array_unique(array_merge($comparison, $operators, $assignment));
+    }//function
+
+    /**
+     * Processes this sniff, when one of its tokens is encountered.
+     *
+     * @param PHP_CodeSniffer_File $phpcsFile The current file being checked.
+     * @param integer                  $stackPtr  The position of the current token in the
+     *                                        stack passed in $tokens.
+     *
+     * @return void
+     */
+    public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
+    {
+        $tokens = $phpcsFile->getTokens();
+
+        // Skip default values in function declarations.
+        if($tokens[$stackPtr]['code'] === T_EQUAL
+        || $tokens[$stackPtr]['code'] === T_MINUS
+        )
+        {
+            if(isset($tokens[$stackPtr]['nested_parenthesis']) === true)
+            {
+                $bracket = end($tokens[$stackPtr]['nested_parenthesis']);
+
+                if(isset($tokens[$bracket]['parenthesis_owner']) === true)
+                {
+                    $function = $tokens[$bracket]['parenthesis_owner'];
+
+                    if($tokens[$function]['code'] === T_FUNCTION)
+                    {
+                        return;
+                    }
+                }
+            }
+        }
+
+        if($tokens[$stackPtr]['code'] === T_EQUAL)
+        {
+            // Skip for '=&' case.
+            if(isset($tokens[($stackPtr + 1)]) === true
+            && $tokens[($stackPtr + 1)]['code'] === T_BITWISE_AND
+            || $tokens[($stackPtr + 1)]['code'] === T_OPEN_PARENTHESIS)
+            {
+                return;
+            }
+        }
+
+        if($tokens[$stackPtr]['code'] === T_EQUAL
+        || $tokens[$stackPtr]['content'] === '.='
+        || $tokens[$stackPtr]['content'] === '+=')
+        {
+            // Skip for '=(' case.
+            // Skip also '.=('
+            if(isset($tokens[($stackPtr + 1)]) === true
+            && $tokens[($stackPtr + 1)]['code'] === T_OPEN_PARENTHESIS)
+            {
+                return;
+            }
+        }
+
+        if($tokens[$stackPtr]['code'] === T_BITWISE_AND)
+        {
+            // If its not a reference, then we expect one space either side of the
+            // bitwise operator.
+            if($phpcsFile->isReference($stackPtr) === false)
+            {
+                // Check there is one space before the & operator.
+                if($tokens[($stackPtr - 1)]['code'] !== T_WHITESPACE)
+                {
+                    $error = 'Expected 1 space before "&" operator; 0 found';
+                    $phpcsFile->addError($error, $stackPtr, 'NoSpaceBeforeAmp');
+                }
+                else
+                {
+                    if(strlen($tokens[($stackPtr - 1)]['content']) !== 1)
+                    {
+                        $found = strlen($tokens[($stackPtr - 1)]['content']);
+                        $error = sprintf('Expected 1 space before "&" operator; %s found'
+                        , $found);
+
+                        $phpcsFile->addError($error, $stackPtr, 'SpacingBeforeAmp');
+                    }
+                }
+
+                // Check there is one space after the & operator.
+                if($tokens[($stackPtr + 1)]['code'] !== T_WHITESPACE)
+                {
+                    $error = 'Expected 1 space after "&" operator; 0 found';
+                    $phpcsFile->addError($error, $stackPtr, 'NoSpaceAfterAmp');
+                }
+                else
+                {
+                    if(strlen($tokens[($stackPtr + 1)]['content']) !== 1)
+                    {
+                        $found = strlen($tokens[($stackPtr + 1)]['content']);
+                        $error = sprintf('Expected 1 space after "&" operator; %s found'
+                        , $found);
+
+                        $phpcsFile->addError($error, $stackPtr, 'SpacingAfterAmp');
+                    }
+                }
+            }
+        }
+        else
+        {
+            if($tokens[$stackPtr]['code'] === T_MINUS
+            || $tokens[$stackPtr]['code'] === T_PLUS)
+            {
+                // Check minus spacing, but make sure we aren't just assigning
+                // a minus value or returning one.
+                $prev = $phpcsFile->findPrevious(T_WHITESPACE, ($stackPtr - 1), null, true);
+
+                if($tokens[$prev]['code'] === T_RETURN)
+                {
+                    // Just returning a negative value; eg. return -1.
+                    return;
+                }
+
+                if(in_array($tokens[$prev]['code'], PHP_CodeSniffer_Tokens::$operators) === true)
+                {
+                    // Just trying to operate on a negative value; eg. ($var * -1).
+                    return;
+                }
+
+                if(in_array($tokens[$prev]['code'], PHP_CodeSniffer_Tokens::$comparisonTokens) === true)
+                {
+                    // Just trying to compare a negative value; eg. ($var === -1).
+                    return;
+                }
+
+                // A list of tokens that indicate that the token is not
+                // part of an arithmetic operation.
+                $invalidTokens = array(
+                T_COMMA,
+                T_OPEN_PARENTHESIS,
+                T_OPEN_SQUARE_BRACKET,
+                T_DOUBLE_ARROW,
+                T_COLON,
+                T_INLINE_THEN, // the ternary "?"
+                );
+
+                if(in_array($tokens[$prev]['code'], $invalidTokens) === true)
+                {
+                    // Just trying to use a negative value; eg. myFunction($var, -2).
+                    return;
+                }
+
+                $number = $phpcsFile->findNext(T_WHITESPACE, ($stackPtr + 1), null, true);
+
+                if(in_array($tokens[$number]['code'], array(T_LNUMBER, T_VARIABLE)) === true)
+                {
+                    $semi = $phpcsFile->findNext(T_WHITESPACE, ($number + 1), null, true);
+
+                    if($tokens[$semi]['code'] === T_SEMICOLON)
+                    {
+                        if($prev !== false
+                        && (in_array($tokens[$prev]['code'], PHP_CodeSniffer_Tokens::$assignmentTokens) === true))
+                        {
+                            // This is a negative assignment.
+                            return;
+                        }
+                    }
+                }
+            }
+
+            $operator = $tokens[$stackPtr]['content'];
+
+            if($tokens[($stackPtr - 1)]['code'] !== T_WHITESPACE)
+            {
+                $error = "Expected 1 space before \"$operator\"; 0 found";
+                $phpcsFile->addError($error, $stackPtr, 'NoSpaceBefore');
+            }
+            else if(strlen($tokens[($stackPtr - 1)]['content']) !== 1)
+            {
+                // Don't throw an error for assignments, because other standards allow
+                // multiple spaces there to align multiple assignments.
+                if(in_array($tokens[$stackPtr]['code'], PHP_CodeSniffer_Tokens::$assignmentTokens) === false)
+                {
+                    $found = strlen($tokens[($stackPtr - 1)]['content']);
+                    $error = sprintf('Expected 1 space before "%s"; %s found'
+                    , $operator, $found);
+
+                    $phpcsFile->addError($error, $stackPtr, 'SpacingBefore');
+                }
+            }
+
+            if($tokens[($stackPtr + 1)]['code'] !== T_WHITESPACE)
+            {
+                $error = "Expected 1 space after \"$operator\"; 0 found";
+                $phpcsFile->addError($error, $stackPtr, 'NoSpaceAfter');
+            }
+            else if(strlen($tokens[($stackPtr + 1)]['content']) !== 1)
+            {
+                $found = strlen($tokens[($stackPtr + 1)]['content']);
+                $error = sprintf('Expected 1 space after "%s"; %s found'
+                , $operator, $found);
+
+                $phpcsFile->addError($error, $stackPtr, 'SpacingAfter');
+            }
+        }
+    }//function
+}//class

docs/coding-standards/en-US/Preface.xml

@@ -7,7 +7,7 @@
   <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 the quality of the source code. In order to perform in the highly competitive Open Source and propriety
+  software performs, but the quality of the source code. In order to perform in the highly competitive Open Source and proprietary
   software industries, the source code not only needs to be beautifully designed, it also needs to be beautiful and elegant to
   look at.</para>
 

docs/coding-standards/en-US/chapters/basic-guidelines.xml

@@ -11,7 +11,7 @@
   <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
+    <para>All files contributed to Joomla must be stored as ASCII text, use UTF-8 character encoding and 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.</para>
   </section>
@@ -36,7 +36,7 @@
   <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
+    <para>There is no maximum limit for line lengths in files, however, a notional value of about 150 characters is recommended 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>

docs/coding-standards/en-US/chapters/php.xml

@@ -361,12 +361,13 @@ $long    = bar('long');</programlisting>
 /**
  * A utility class.
  *
- * @package     Joomla.Framework
+ * @package     Joomla.Platform
  * @subpackage  XBase
  *
  * @param       string  $path  The library path in dot notation.
  *
  * @return      void
+ *
  * @since       1.6
  */
 function jimport($path)
@@ -493,7 +494,7 @@ function jimport($path)
 /**
  * A utility class.
  *
- * @package     Joomla.Framework
+ * @package     Joomla.Platform
  * @subpackage  XBase
  * @since       1.6
  */
@@ -510,11 +511,11 @@ class JClass extends JObject
     /**
      * Method to get the name of the class.
      *
-     * @param      string  $case  Optionally return in upper/lower case.
+     * @param   string  $case  Optionally return in upper/lower case.
      *
-     * @return     boolean  True if successfully loaded, false otherwise.
+     * @return  boolean  True if successfully loaded, false otherwise.
      *
-     * @since      1.6
+     * @since   1.6
      */
     public function getName($case = null)
     {
@@ -559,7 +560,7 @@ class JClass extends JObject
       <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
+      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'.</para>
 
       <para>For example:</para>

docs/manual/en-US/Developer_Manual.xml

@@ -6,6 +6,7 @@
 <book>
 	<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="chapters/preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+	<xi:include href="chapters/jlog.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="chapters/github.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="chapters/testing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="appendices/analysis.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />