Merge branch 'staging' of https://github.com/joomla/joomla-platform i…

…nto staging
aaronschmitz · Mar 25, 2012 · 7d943ef · 7d943ef
2 parents d05f75b + a6915dd
commit 7d943ef
Show file tree

Hide file tree

Showing 71 changed files with 811 additions and 498 deletions.
diff --git a/docs/coding-standards/en-US/chapters/php.xml b/docs/coding-standards/en-US/chapters/php.xml
@@ -1,6 +1,7 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-<!ENTITY % BOOK_ENTITIES SYSTEM "Coding_Standards.ent">
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "../Coding_Standards.ent">
 %BOOK_ENTITIES;
 ]>
 <chapter id="chap-Coding_Standards-PHP">
@@ -38,7 +39,7 @@
       <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>
+        <para><code>require_once JPATH_COMPONENT.’/helpers/helper.php’;</code></para>
       </note>
 
       <para>You should not enclose the filename in parentheses.</para>
@@ -76,7 +77,8 @@
 	echo 'True';
 }
 // Comments can go here.
-else if ($test === false)
+// Note that "elseif" as one word is used.
+elseif ($test === false)
 {
 	echo 'Really false';
 }
@@ -163,7 +165,7 @@ while ($i &lt; 10);</programlisting>
       <para>For example:</para>
 
       <programlisting>&lt;?php
-$ref1  = &amp;$this-&gt;sql;</programlisting>
+$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>
@@ -640,9 +642,140 @@ class JClass extends JObject
   </section>
 
   <section>
-    <title>Error Handling</title>
+    <title>Exception Handling</title>
 
     <para>Exceptions should be used for error handling.</para>
+
+    <para>The follow sections outline how to semantically use SPL exceptions</para>
+
+    <section>
+      <title>Logic Exceptions</title>
+
+      <para>The <exceptionname>LogicException</exceptionname> is used when there is an explicit problem with the way the API is
+      being used. For example:</para>
+
+      <simplelist>
+        <member>A dependancy has failed (you try to operate on an object that has not been loaded yet).</member>
+      </simplelist>
+
+      <para>The following child classes can also be used in appropriate situations.</para>
+
+      <section>
+        <title>BadFunctionCallException</title>
+
+        <para>This exception can be thrown if a callback refers to an undefined function or if some arguments are missing. For
+        example:</para>
+
+        <simplelist>
+          <member><methodname>is_callable</methodname>, or similar, fails on a function.</member>
+        </simplelist>
+      </section>
+
+      <section>
+        <title>BadMethodCallException</title>
+
+        <para>This exception can be thrown if a callback refers to an undefined method or if some arguments are missing. For
+        example:</para>
+
+        <simplelist>
+          <member><methodname>is_callable</methodname>, or similar, fails on a class method.</member>
+
+          <member>There where missing arguments passed to a magic call method.</member>
+        </simplelist>
+      </section>
+
+      <section>
+        <title>InvalidArgumentException</title>
+
+        <para>This exception can be called if there is invalid input.</para>
+      </section>
+
+      <section>
+        <title>DomainException</title>
+
+        <para>This exception is similar to the <exceptionname>InvalidArgumentException</exceptionname> but can be thrown if a
+        value does not adhere to a defined valid data domain. For example:</para>
+
+        <simplelist>
+          <member>Trying to load a database driver of type "mongodb" but that driver is not available in the API.</member>
+        </simplelist>
+      </section>
+
+      <section>
+        <title>LengthException</title>
+
+        <para>This exception can be thrown is a length check on an argument fails. For example:</para>
+
+        <simplelist>
+          <member>A file signature was not a specific number of characters.</member>
+        </simplelist>
+      </section>
+
+      <section>
+        <title>OutOfRangeException</title>
+
+        <para>This exception has few practical applications but can be thrown when an illegal index was requested.</para>
+      </section>
+    </section>
+
+    <section>
+      <title>Runtime Exceptions</title>
+
+      <para>The <exceptionname>RuntimeException</exceptionname> is thrown when some sort of external entity or environment causes
+      a problem that is beyond your control providing the input is valid. This exception is the default case for when the cause of
+      an error can't explicity be determined. For example:</para>
+
+      <simplelist>
+        <member>Tried to connect to a database but the database was not available (server down, etc).</member>
+
+        <member>An SQL query failed.</member>
+      </simplelist>
+
+      <section>
+        <title>UnexpectedValueException</title>
+
+        <para>This type of exception should be used when an unecpected result is encountered. For example:</para>
+
+        <simplelist>
+          <member>A function call returned a string when a boolean was expected.</member>
+        </simplelist>
+      </section>
+
+      <section>
+        <title>OutOfBoundsException</title>
+
+        <para>This exception has few practical applications but may be thrown if a value is not a valid key.</para>
+      </section>
+
+      <section>
+        <title>OverflowException</title>
+
+        <para>This exception has few practical applications but may be thrown when you add an element into a full
+        container.</para>
+      </section>
+
+      <section>
+        <title>RangeException</title>
+
+        <para>This exception has few practical applications but may be thrown to indicate range errors during program execution.
+        Normally this means there was an arithmetic error other than under/overflow. This is the runtime version of
+        DomainException.</para>
+      </section>
+
+      <section>
+        <title>UnderflowException</title>
+
+        <para>This exception has few practical applications but may thrown when you try to remove an element of an empty
+        container.</para>
+      </section>
+    </section>
+
+    <section>
+      <title>Documenting exceptions</title>
+
+      <para>Each function or method must annotate the type of exception that it throws using an @throws tag and any downstream
+      exceptions types that are thrown. Each type of exception need only be annotated once. No description is necessary.</para>
+    </section>
   </section>
 
   <section>

diff --git a/docs/manual/en-US/appendices/analysis.xml b/docs/manual/en-US/appendices/analysis.xml
@@ -20,25 +20,29 @@
     <section>
       <title>Configuring Your Environment: The Database</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>Standard unit tests run against a <ulink url="http://www.sqlite.org/quickstart.html">Sqlite</ulink> in memory 
+      database for ease of setup and performance. Other than <ulink url="http://www.sqlite.org/quickstart.html">installing Sqlite</ulink>  
+      no manual intervention or set up is required. The database is built at runtime and deleted when finished.      	
+      </para>
 
-      <para>To do this, perform the following steps:</para>
+      <para>To run the specific database tests:</para>
 
       <itemizedlist>
-        <listitem>
-          <para>Create a database and a database user with full access to the database.</para>
+          <para>Create your database and use the appropriate database-specific DDL located in 
+          tests/suites/database/stubs to create the database tables required.</para>
         </listitem>
+
+        <listitem>
+          <para>In the root directory, copy the file named phpunit.xml.dist, leaving it in the same
+          folder and naming it phpunit.xml.</para>
+        </listitem>          
 
         <listitem>
-          <para>Populate the database by executing the ddl.sql file found in the tests directory.</para>
+          <para>Uncomment the php block and include the const line(s) related to the database(s) you will be testing.</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>
+          <para>Set up the database configuration values for your specific environment.</para>
         </listitem>
       </itemizedlist>
     </section>

diff --git a/libraries/joomla/application/component/controlleradmin.php b/libraries/joomla/application/component/controlleradmin.php
@@ -117,7 +117,7 @@ public function delete()
 
 		if (!is_array($cid) || count($cid) < 1)
 		{
-			JError::raiseWarning(500, JText::_($this->text_prefix . '_NO_ITEM_SELECTED'));
+			JLog::add(JText::_($this->text_prefix . '_NO_ITEM_SELECTED'), JLog::WARNING, 'jerror');
 		}
 		else
 		{
@@ -177,7 +177,7 @@ public function publish()
 
 		if (empty($cid))
 		{
-			JError::raiseWarning(500, JText::_($this->text_prefix . '_NO_ITEM_SELECTED'));
+			JLog::add(JText::_($this->text_prefix . '_NO_ITEM_SELECTED'), JLog::WARNING, 'jerror');
 		}
 		else
 		{
@@ -190,7 +190,7 @@ public function publish()
 			// Publish the items.
 			if (!$model->publish($cid, $value))
 			{
-				JError::raiseWarning(500, $model->getError());
+				JLog::add($model->getError(), JLog::WARNING, 'jerror');
 			}
 			else
 			{

diff --git a/libraries/joomla/application/component/controllerform.php b/libraries/joomla/application/component/controllerform.php
@@ -139,7 +139,7 @@ public function __construct($config = array())
 	/**
 	 * Method to add a new record.
 	 *
-	 * @return  mixed  True if the record can be added, a JError object if not.
+	 * @return  mixed  True if the record can be added, a error object if not.
 	 *
 	 * @since   11.1
 	 */

diff --git a/libraries/joomla/application/component/helper.php b/libraries/joomla/application/component/helper.php
@@ -333,7 +333,7 @@ public static function renderComponent($option, $params = array())
 		// If component is disabled throw error
 		if (!self::isEnabled($option) || !file_exists($path))
 		{
-			throw new Exception(404, JText::_('JLIB_APPLICATION_ERROR_COMPONENT_NOT_FOUND'), 404);
+			throw new Exception(JText::_('JLIB_APPLICATION_ERROR_COMPONENT_NOT_FOUND'), 404);
 		}
 
 		$task = JRequest::getString('task');
@@ -399,7 +399,7 @@ protected static function _load($option)
 		if ($error = $db->getErrorMsg() || empty(self::$components[$option]))
 		{
 			// Fatal error.
-			JError::raiseWarning(500, JText::sprintf('JLIB_APPLICATION_ERROR_COMPONENT_NOT_LOADING', $option, $error));
+			JLog::add(JText::sprintf('JLIB_APPLICATION_ERROR_COMPONENT_NOT_LOADING', $option, $error), JLog::WARNING, 'jerror');
 			return false;
 		}
 

diff --git a/libraries/joomla/application/component/model.php b/libraries/joomla/application/component/model.php
@@ -205,7 +205,7 @@ public static function getInstance($type, $prefix = '', $config = array())
 
 				if (!class_exists($modelClass))
 				{
-					JError::raiseWarning(0, JText::sprintf('JLIB_APPLICATION_ERROR_MODELCLASS_NOT_FOUND', $modelClass));
+					JLog::add(JText::sprintf('JLIB_APPLICATION_ERROR_MODELCLASS_NOT_FOUND', $modelClass), JLog::WARNING, 'jerror');
 					return false;
 				}
 			}
@@ -235,7 +235,7 @@ public function __construct($config = array())
 
 			if (!preg_match('/(.*)Model/i', get_class($this), $r))
 			{
-				throw new Exception(500, JText::_('JLIB_APPLICATION_ERROR_MODEL_GET_NAME'), 500);
+				throw new Exception(JText::_('JLIB_APPLICATION_ERROR_MODEL_GET_NAME'), 500);
 			}
 
 			$this->option = 'com_' . strtolower($r[1]);

diff --git a/libraries/joomla/application/component/modeladmin.php b/libraries/joomla/application/component/modeladmin.php
@@ -683,12 +683,12 @@ public function delete(&$pks)
 					$error = $this->getError();
 					if ($error)
 					{
-						JError::raiseWarning(500, $error);
+						JLog::add($error, JLog::WARNING, 'jerror');
 						return false;
 					}
 					else
 					{
-						JError::raiseWarning(403, JText::_('JLIB_APPLICATION_ERROR_DELETE_NOT_PERMITTED'));
+						JLog::add(JText::_('JLIB_APPLICATION_ERROR_DELETE_NOT_PERMITTED'), JLog::WARNING, 'jerror');
 						return false;
 					}
 				}
@@ -855,7 +855,7 @@ public function publish(&$pks, $value = 1)
 				{
 					// Prune items that you can't change.
 					unset($pks[$i]);
-					JError::raiseWarning(403, JText::_('JLIB_APPLICATION_ERROR_EDITSTATE_NOT_PERMITTED'));
+					JLog::add(JText::_('JLIB_APPLICATION_ERROR_EDITSTATE_NOT_PERMITTED'), JLog::WARNING, 'jerror');
 					return false;
 				}
 			}
@@ -919,7 +919,7 @@ public function reorder($pks, $delta = 0)
 					// Prune items that you can't change.
 					unset($pks[$i]);
 					$this->checkin($pk);
-					JError::raiseWarning(403, JText::_('JLIB_APPLICATION_ERROR_EDITSTATE_NOT_PERMITTED'));
+					JLog::add(JText::_('JLIB_APPLICATION_ERROR_EDITSTATE_NOT_PERMITTED'), JLog::WARNING, 'jerror');
 					$allowed = false;
 					continue;
 				}
@@ -1076,7 +1076,7 @@ public function saveorder($pks = null, $order = null)
 			{
 				// Prune items that you can't change.
 				unset($pks[$i]);
-				JError::raiseWarning(403, JText::_('JLIB_APPLICATION_ERROR_EDITSTATE_NOT_PERMITTED'));
+				JLog::add(JText::_('JLIB_APPLICATION_ERROR_EDITSTATE_NOT_PERMITTED'), JLog::WARNING, 'jerror');
 			}
 			elseif ($table->ordering != $order[$i])
 			{

diff --git a/libraries/joomla/application/component/view.php b/libraries/joomla/application/component/view.php
@@ -291,7 +291,7 @@ public function __construct($config = array())
 	 *
 	 * @param   string  $tpl  The name of the template file to parse; automatically searches through the template paths.
 	 *
-	 * @return  mixed  A string if successful, otherwise a JError object.
+	 * @return  mixed  A string if successful, otherwise a Error object.
 	 *
 	 * @see     fetch()
 	 * @since   11.1
@@ -551,7 +551,7 @@ public function getName()
 			}
 			if (strpos($r[3], "view"))
 			{
-				JError::raiseWarning('SOME_ERROR_CODE', JText::_('JLIB_APPLICATION_ERROR_VIEW_GET_NAME_SUBSTRING'));
+				JLog::add(JText::_('JLIB_APPLICATION_ERROR_VIEW_GET_NAME_SUBSTRING'), JLog::WARNING, 'jerror');
 			}
 			$this->name = strtolower($r[3]);
 		}

diff --git a/libraries/joomla/application/module/helper.php b/libraries/joomla/application/module/helper.php
@@ -334,7 +334,7 @@ protected static function &_load()
 
 		if ($db->getErrorNum())
 		{
-			JError::raiseWarning(500, JText::sprintf('JLIB_APPLICATION_ERROR_MODULE_LOAD', $db->getErrorMsg()));
+			JLog::add(JText::sprintf('JLIB_APPLICATION_ERROR_MODULE_LOAD', $db->getErrorMsg()), JLog::WARNING, 'jerror');
 			return $clean;
 		}
 

diff --git a/libraries/joomla/archive/archive.php b/libraries/joomla/archive/archive.php
@@ -149,7 +149,7 @@ public static function extract($archivename, $extractdir)
 				break;
 
 			default:
-				JError::raiseWarning(10, JText::_('JLIB_FILESYSTEM_UNKNOWNARCHIVETYPE'));
+				JLog::add(JText::_('JLIB_FILESYSTEM_UNKNOWNARCHIVETYPE'), JLog::WARNING, 'jerror');
 				return false;
 				break;
 		}