Merge branch 'develop' of https://github.com/bcit-ci/CodeIgniter into fix/housekeeping

10 files changed, 105 insertions, 70 deletions

diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst
index 8f77f368f..ef3d2af39 100644
--- a/user_guide_src/source/changelog.rst
+++ b/user_guide_src/source/changelog.rst
@@ -480,6 +480,7 @@ Release Date: Not Released
 
    -  :doc:`Input Library <libraries/input>` changes include:
 
+      -  Deprecated the ``$config['global_xss_filtering']`` setting.
       -  Added ``method()`` to retrieve ``$_SERVER['REQUEST_METHOD']``.
       -  Added support for arrays and network addresses (e.g. 192.168.1.1/24) for use with the *proxy_ips* setting.
       -  Added method ``input_stream()`` to aid in using **php://input** stream data such as one passed via PUT, DELETE and PATCH requests.
@@ -493,6 +494,7 @@ Release Date: Not Released
       -  Added an option for ``_clean_input_keys()`` to return FALSE instead of terminating the whole script.
       -  Deprecated the ``is_cli_request()`` method, it is now an alias for the new :php:func:`is_cli()` common function.
       -  Added an ``$xss_clean`` parameter to method ``user_agent()`` and removed the ``$user_agent`` property.
+      -  Added property ``$raw_input_stream`` to access **php://input** data.
 
    -  :doc:`Common functions <general/common_functions>` changes include:
 
@@ -768,7 +770,7 @@ Bug fixes for 3.0
 -  Fixed a bug (#3161) - :doc:`Cache Library <libraries/caching>` methods `increment()`, `decrement()` didn't auto-create non-existent items when using redis and/or file storage.
 -  Fixed a bug (#3189) - :doc:`Parser Library <libraries/parser>` used double replacement on ``key->value`` pairs, exposing a potential template injection vulnerability.
 -  Fixed a bug (#3573) - :doc:`Email Library <libraries/email>` violated `RFC5321 <https://tools.ietf.org/rfc/rfc5321.txt>`_ by sending 'localhost.localdomain' as a hostname.
--  Fixed a bug (#3572) - :doc:`CI_Security::_remove_evil_attributes()` failed for large-sized inputs due to *pcre.backtrack_limit* and didn't properly match HTML tags.
+-  Fixed a bug (#3572) - ``CI_Security::_remove_evil_attributes()`` failed for large-sized inputs due to *pcre.backtrack_limit* and didn't properly match HTML tags.
 
 Version 2.2.1
 =============
diff --git a/user_guide_src/source/database/query_builder.rst b/user_guide_src/source/database/query_builder.rst
index fa1e90353..9b4694710 100644
--- a/user_guide_src/source/database/query_builder.rst
+++ b/user_guide_src/source/database/query_builder.rst
@@ -1221,7 +1221,7 @@ Class Reference
 
 		:param	string	$key: The field to search
 		:param	array	$values: The values searched on
-		:param	boolean	$escape: Whether to escape values and identifiers
+		:param	boolean	$escape: Whether to escape identifiers
 		:returns:	DB_query_builder instance
 		:rtype:	object
 
@@ -1232,7 +1232,7 @@ Class Reference
 
 		:param	string	$key: The field to search
 		:param	array	$values: The values searched on
-		:param	boolean	$escape: Whether to escape values and identifiers
+		:param	boolean	$escape: Whether to escape identifiers
 		:returns:	DB_query_builder instance
 		:rtype:	object
 
@@ -1243,7 +1243,7 @@ Class Reference
 
 		:param	string	$key: Name of field to examine
 		:param	array	$values: Array of target values
-		:param	boolean	$escape: Whether to escape values and identifiers
+		:param	boolean	$escape: Whether to escape identifiers
 		:returns:	DB_query_builder instance
 		:rtype:	object
 
@@ -1254,7 +1254,7 @@ Class Reference
 
 		:param	string	$key: Name of field to examine
 		:param	array	$values: Array of target values
-		:param	boolean	$escape: Whether to escape values and identifiers
+		:param	boolean	$escape: Whether to escape identifiers
 		:returns:	DB_query_builder instance
 		:rtype:	object
 
diff --git a/user_guide_src/source/database/results.rst b/user_guide_src/source/database/results.rst
index a22c2e8c3..ac44566d3 100644
--- a/user_guide_src/source/database/results.rst
+++ b/user_guide_src/source/database/results.rst
@@ -102,7 +102,7 @@ You can also add a second String parameter, which is the name of a class
 to instantiate the row with::
 
 	$query = $this->db->query("SELECT * FROM users LIMIT 1;");
-	$query->row(0, 'User');
+	$row = $query->row(0, 'User');
 	
 	echo $row->name; // access attributes
 	echo $row->reverse_name(); // or methods defined on the 'User' class
@@ -431,4 +431,4 @@ Class Reference
 		:rtype:	array
 
 		Returns an array containing the field names in the
-		result set.
\ No newline at end of file
+		result set.
diff --git a/user_guide_src/source/general/security.rst b/user_guide_src/source/general/security.rst
index 0c58f96b4..efc821f2b 100644
--- a/user_guide_src/source/general/security.rst
+++ b/user_guide_src/source/general/security.rst
@@ -133,6 +133,10 @@ with that. Please read below.
    provides them for you as long as you're running at least PHP version
    5.3.7 (and if you don't meet that requirement - please, upgrade).
 
+   If you're one of the really unlucky people who can't even upgrade to a
+   more recent PHP version, use `hash_pbkdf() <http://php.net/hash_pbkdf2>`,
+   which we also provide in our compatibility layer.
+
 -  DO NOT ever display or send a password in plain-text format!
 
    Even to the password's owner, if you need a "Forgotten password"
diff --git a/user_guide_src/source/installation/upgrade_300.rst b/user_guide_src/source/installation/upgrade_300.rst
index 73ed0f4c3..2f806cccf 100644
--- a/user_guide_src/source/installation/upgrade_300.rst
+++ b/user_guide_src/source/installation/upgrade_300.rst
@@ -1,5 +1,5 @@
 #############################
-Upgrading from 2.2.1 to 3.0.0
+Upgrading from 2.2.x to 3.0.0
 #############################
 
 .. note:: These upgrade notes are for a version that is yet to be released.
@@ -551,6 +551,22 @@ PHP's native ``hash()`` function. It is deprecated and scheduled for removal in
 .. note:: This function is still available, but you're strongly encouraged to remove its usage sooner
 	rather than later.
 
+The $config['global_xss_filtering'] setting
+===========================================
+
+As already explained above, XSS filtering should not be done on input data,
+but on output instead. Therefore, the ``$config['global_xss_filtering']``,
+which automatically filters *input* data, is considered a bad practice and
+is now deprecated.
+
+Instead, you should manually escape any user-provided data via the
+:php:func:`xss_clean()` function when you need to output it, or use a
+library like `HTML Purifier <http://htmlpurifier.org/>`_ that does that
+for you.
+
+.. note:: The setting is still available, but you're strongly encouraged to
+	remove its usage sooner rather than later.
+
 File helper read_file()
 =======================
 
@@ -795,7 +811,7 @@ It is now deprecated and scheduled for removal in CodeIgniter 3.1+.
 	sooner rather than later.
 
 ***********************************************************
-Step 18: Check your usage of Text helper highlight_phrase()
+Step 20: Check your usage of Text helper highlight_phrase()
 ***********************************************************
 
 The default HTML tag used by :doc:`Text Helper <../helpers/text_helper>` function
diff --git a/user_guide_src/source/installation/upgrading.rst b/user_guide_src/source/installation/upgrading.rst
index ab36e9bfd..89e90e714 100644
--- a/user_guide_src/source/installation/upgrading.rst
+++ b/user_guide_src/source/installation/upgrading.rst
@@ -8,7 +8,7 @@ upgrading from.
 .. toctree::
 	:titlesonly:
 
-	Upgrading from 2.2.1 to 3.0.0 <upgrade_300>
+	Upgrading from 2.2.x to 3.0.0 <upgrade_300>
 	Upgrading from 2.2.0 to 2.2.1 <upgrade_221>
 	Upgrading from 2.1.4 to 2.2.0 <upgrade_220>
 	Upgrading from 2.1.3 to 2.1.4 <upgrade_214>
diff --git a/user_guide_src/source/libraries/input.rst b/user_guide_src/source/libraries/input.rst
index 967f69d13..d9c6c2dd1 100644
--- a/user_guide_src/source/libraries/input.rst
+++ b/user_guide_src/source/libraries/input.rst
@@ -53,6 +53,10 @@ this::
 Please refer to the :doc:`Security class <security>` documentation for
 information on using XSS Filtering in your application.
 
+.. important:: The 'global_xss_filtering' setting is DEPRECATED and kept
+	solely for backwards-compatibility purposes. XSS escaping should
+	be performed on *output*, not *input*!
+
 *******************
 Accessing form data
 *******************
@@ -91,8 +95,14 @@ the ``$_POST`` array, because it will always exist and you can try
 and access multiple variables without caring that you might only have
 one shot at all of the POST data.
 
-CodeIgniter will take care of that for you, and you can access data
-from the **php://input** stream at any time, just by calling the
+CodeIgniter will take care of that for you, and you can read the data
+from the **php://input** stream at any time, just by using the
+``$raw_input_stream`` property::
+
+	$this->input->raw_input_stream;
+
+Additionally if the input stream is form-encoded like $_POST you can 
+access its values by calling the
 ``input_stream()`` method::
 
 	$this->input->input_stream('key');
@@ -114,6 +124,12 @@ Class Reference
 
 .. php:class:: CI_Input
 
+	.. attribute:: $raw_input_stream
+		
+		Read only property that will return php://input data as is.
+		
+		The property can be read multiple times.
+
 	.. php:method:: post([$index = NULL[, $xss_clean = NULL]])
 
 		:param	mixed	$index: POST parameter name
diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst
index 5a1b90537..51ecc03bd 100644
--- a/user_guide_src/source/libraries/sessions.rst
+++ b/user_guide_src/source/libraries/sessions.rst
@@ -632,8 +632,7 @@ Redis Driver
 
 .. note:: Since Redis doesn't have a locking mechanism exposed, locks for
 	this driver are emulated by a separate value that is kept for up
-	to 5 seconds. You may experience issues if your page loads take
-	longer than that!
+	to 300 seconds.
 
 Redis is a storage engine typically used for caching and popular because
 of its high performance, which is also probably your reason to use the
@@ -670,8 +669,7 @@ Memcached Driver
 
 .. note:: Since Memcache doesn't have a locking mechanism exposed, locks
 	for this driver are emulated by a separate value that is kept for
-	up to 5 seconds. You may experience issues if your page loads take
-	longer than that!
+	up to 300 seconds.
 
 The 'memcached' driver is very similar to the 'redis' one in all of its
 properties, except perhaps for availability, because PHP's `Memcached
diff --git a/user_guide_src/source/tutorial/news_section.rst b/user_guide_src/source/tutorial/news_section.rst
index 80938de32..f436b2510 100644
--- a/user_guide_src/source/tutorial/news_section.rst
+++ b/user_guide_src/source/tutorial/news_section.rst
@@ -151,7 +151,7 @@ and add the next piece of code.
 		<div class="main">
 			<?php echo $news_item['text'] ?>
 		</div>
-		<p><a href="news/<?php echo $news_item['slug'] ?>">View article</a></p>
+		<p><a href="<?php echo $news_item['slug'] ?>">View article</a></p>
 
 	<?php endforeach ?>
 
diff --git a/user_guide_src/source/tutorial/static_pages.rst b/user_guide_src/source/tutorial/static_pages.rst
index 8ba0486c1..53f286473 100644
--- a/user_guide_src/source/tutorial/static_pages.rst
+++ b/user_guide_src/source/tutorial/static_pages.rst
@@ -11,12 +11,16 @@ static pages. A controller is simply a class that helps delegate work.
 It is the glue of your web application.
 
 For example, when a call is made to:
-``http://example.com/news/latest/10`` We might imagine that there is a
-controller named "news". The method being called on news would be
-"latest". The news method's job could be to grab 10 news items, and
-render them on the page. Very often in MVC, you'll see URL patterns that
-match:
-``http://example.com/[controller-class]/[controller-method]/[arguments]``
+
+	http://example.com/news/latest/10
+
+We might imagine that there is a controller named "news". The method
+being called on news would be "latest". The news method's job could be to
+grab 10 news items, and render them on the page. Very often in MVC,
+you'll see URL patterns that match:
+
+	http://example.com/[controller-class]/[controller-method]/[arguments]
+
 As URL schemes become more complex, this may change. But for now, this
 is all we will need to know.
 
@@ -25,15 +29,13 @@ code.
 
 ::
 
-    <?php 
-    class Pages extends CI_Controller { 
+	<?php 
+	class Pages extends CI_Controller { 
 
-        public function view($page = 'home') 
-        {
-	
-        }
-		 
-    }
+		public function view($page = 'home') 
+		{
+	        }
+	}
 
 You have created a class named "pages", with a view method that accepts
 one argument named $page. The pages class is extending the
@@ -56,13 +58,13 @@ following code.
 
 ::
 
-    <html>
-        <head>
-            <title>CodeIgniter Tutorial</title>
-        </head>
-        <body>
+	<html>
+		<head>
+			<title>CodeIgniter Tutorial</title>
+		</head>
+		<body>
 
-            <h1>CodeIgniter Tutorial</h1>
+			<h1>CodeIgniter Tutorial</h1>
 
 The header contains the basic HTML code that you'll want to display
 before loading the main view, together with a heading. It will also
@@ -72,16 +74,16 @@ includes the following code:
 
 ::
 
-            <em>&copy; 2014</em>
-        </body>
-    </html>
+			<em>&copy; 2014</em>
+		</body>
+	</html>
 
 Adding logic to the controller
 ------------------------------
 
-Earlier you set up a controller with a view() method. The method accepts
-one parameter, which is the name of the page to be loaded. The static
-page templates will be located in the application/views/pages/
+Earlier you set up a controller with a ``view()`` method. The method
+accepts one parameter, which is the name of the page to be loaded. The
+static page templates will be located in the application/views/pages/
 directory.
 
 In that directory, create two files named home.php and about.php. Within
@@ -93,43 +95,40 @@ page actually exists:
 
 ::
 
-    <?php 
-    public function view($page = 'home')
-    {
-                
-        if ( ! file_exists(APPPATH.'/views/pages/'.$page.'.php'))
-        {
-            // Whoops, we don't have a page for that!
-            show_404();
-        }
-        
-        $data['title'] = ucfirst($page); // Capitalize the first letter
-        
-        $this->load->view('templates/header', $data);
-        $this->load->view('pages/'.$page, $data);
-        $this->load->view('templates/footer', $data);
-
-    }
+	public function view($page = 'home')
+	{
+	        if ( ! file_exists(APPPATH.'/views/pages/'.$page.'.php'))
+		{
+			// Whoops, we don't have a page for that!
+			show_404();
+		}
+
+		$data['title'] = ucfirst($page); // Capitalize the first letter
+
+		$this->load->view('templates/header', $data);
+		$this->load->view('pages/'.$page, $data);
+		$this->load->view('templates/footer', $data);
+	}
 
 Now, when the page does exist, it is loaded, including the header and
 footer, and displayed to the user. If the page doesn't exist, a "404
 Page not found" error is shown.
 
 The first line in this method checks whether the page actually exists.
-PHP's native file\_exists() function is used to check whether the file
-is where it's expected to be. show\_404() is a built-in CodeIgniter
+PHP's native ``file_exists()`` function is used to check whether the file
+is where it's expected to be. ``show_404()`` is a built-in CodeIgniter
 function that renders the default error page.
 
-In the header template, the $title variable was used to customize the
+In the header template, the ``$title`` variable was used to customize the
 page title. The value of title is defined in this method, but instead of
 assigning the value to a variable, it is assigned to the title element
 in the $data array.
 
 The last thing that has to be done is loading the views in the order
-they should be displayed. The second parameter in the view() method is
-used to pass values to the view. Each value in the $data array is
+they should be displayed. The second parameter in the ``view()`` method is
+used to pass values to the view. Each value in the ``$data`` array is
 assigned to a variable with the name of its key. So the value of
-$data['title'] in the controller is equivalent to $title in the view.
+``$data['title']`` in the controller is equivalent to $title in the view.
 
 Routing
 -------
@@ -149,8 +148,8 @@ all other code that sets any element in the $route array.
 
 ::
 
-    $route['default_controller'] = 'pages/view';
-    $route['(:any)'] = 'pages/view/$1';
+	$route['default_controller'] = 'pages/view';
+	$route['(:any)'] = 'pages/view/$1';
 
 CodeIgniter reads its routing rules from top to bottom and routes the
 request to the first matching rule. Each rule is a regular expression
@@ -163,8 +162,8 @@ More information about routing can be found in the URI Routing
 `documentation <../general/routing.html>`_.
 
 Here, the second rule in the $routes array matches **any** request using
-the wildcard string (:any). and passes the parameter to the view()
+the wildcard string (:any). and passes the parameter to the ``view()``
 method of the pages class.
 
-Now visit index.php/about. Did it get routed correctly to the view()
+Now visit index.php/about. Did it get routed correctly to the ``view()``
 method in the pages controller? Awesome!