Merge branch 'master' into 2.5

en/cakephp-overview/where-to-get-help.rst

@@ -76,16 +76,15 @@ donate your brand new sports car.
 
 .. _cakephp-official-communities:
 
-CakePHP Official Communities
-============================
-CakePHP also has it's official group in most popular social networking sites like Facebook, Google Plus. There are
-thousands of people discussing CakePHP projects, helping each other, solving problems, building projects
-and sharing ideas. It can be a great resource for finding archived answers, frequently asked questions, and
-getting answers to immediate problems. Join other CakePHP users in the following communities.
-
--   `CakePHP Google Group <http://groups.google.com/group/cake-php>`_
--   `CakePHP Facebook Group <https://www.facebook.com/groups/cake.community>`_
--   `CakePHP Google Plus Community <https://plus.google.com/communities/108328920558088369819>`_
+Official CakePHP discussion group
+=================================
+`CakePHP Google Group <http://groups.google.com/group/cake-php>`_
+
+CakePHP also has its official discusson group on Google Groups.
+There are thousands of people discussing CakePHP projects, helping each other,
+solving problems, building projects and sharing ideas.
+It can be a great resource for finding archived answers, frequently asked questions, and
+getting answers to immediate problems. Join other CakePHP users and start discussing.
 
 
 Stackoverflow

en/controllers.rst

@@ -809,6 +809,7 @@ More on controllers
 ===================
 
 .. toctree::
+    :maxdepth: 1
 
     controllers/request-response
     controllers/scaffolding

en/controllers/components.rst

@@ -1,21 +1,16 @@
 Components
 ##########
 
-Components are packages of logic that are shared between
-controllers. If you find yourself wanting to copy and paste things
-between controllers, you might consider wrapping some functionality
-in a component.
+Components are packages of logic that are shared between controllers.
+CakePHP comes with a fantastic set of core components you can use to aid in
+various common tasks. You can also create you own components. If you find
+yourself wanting to copy and paste things between controllers, you should
+consider creating your own component to contain the functionality. Creating
+components keeps controller code clean and allows you to reuse code between projects.
 
-CakePHP also comes with a fantastic set of core components you can
-use to aid in:
-
-.. include:: /core-libraries/toc-components.rst
-    :start-line: 7
-
-Each of these core components is detailed in its own chapter.
-For now, we'll show you how to create your own components. Creating
-components keeps controller code clean and allows you to reuse code
-between projects.
+Each of the core components is detailed in its own chapter. See :doc:`/core-libraries/toc-components`.
+This section describes how to configure and use components, and how to create
+your own components.
 
 .. _configuring-components:
 
@@ -150,6 +145,8 @@ Components also offer a few request life-cycle callbacks that allow them
 to augment the request cycle. See the base :ref:`component-api` for
 more information on the callbacks components offer.
 
+.. _creating-a-component:
+
 Creating a Component
 ====================
 

en/controllers/request-response.rst

@@ -486,7 +486,7 @@ to send a file as response::
 
 As shown in the above example, you have to pass the file path to the method.
 CakePHP will send proper content type header if it's a known file type listed in
-:php:attr:`CakeReponse::$_mimeTypes`. You can add new types prior to calling :php:meth:`CakeResponse::file()`
+:php:attr:`CakeResponse::$_mimeTypes`. You can add new types prior to calling :php:meth:`CakeResponse::file()`
 by using the :php:meth:`CakeResponse::type()` method.
 
 If you want you can also force a file to be downloaded instead of being displayed in
@@ -839,4 +839,4 @@ CakeResponse API
 
 .. meta::
     :title lang=en: Request and Response objects
-    :keywords lang=en: request controller,request parameters,array indexes,purpose index,response objects,domain information,request object,request data,interrogating,params,previous versions,introspection,dispatcher,rout,data structures,arrays,ip address,migration,indexes,cakephp
+    :keywords lang=en: request controller,request parameters,array indexes,purpose index,response objects,domain information,request object,request data,interrogating,params,previous versions,introspection,dispatcher,rout,data structures,arrays,ip address,migration,indexes,cakephp

en/core-libraries/components/authentication.rst

@@ -373,7 +373,7 @@ callback of your model using appropriate password hasher class::
 
     class User extends AppModel {
         public function beforeSave($options = array()) {
-            if (!$this->id) {
+            if (!empty($this->data['User']['password'])) {
                 $passwordHasher = new SimplePasswordHasher();
                 $this->data['User']['password'] = $passwordHasher->hash(
                     $this->data['User']['password']

en/core-libraries/components/security-component.rst

@@ -16,18 +16,16 @@ Like all components it is configured through several configurable parameters.
 All of these properties can be set directly or through setter methods of the
 same name in your controller's beforeFilter.
 
-By using the Security Component you automatically get
-`CSRF <http://en.wikipedia.org/wiki/Cross-site_request_forgery>`_
-and form tampering protection. Hidden token fields will
-automatically be inserted into forms and checked by the Security
-component. Among other things, a form submission will not be
-accepted after a certain period of inactivity, which is controlled by
-the ``csrfExpires`` time.
-
-If you are using Security component's form protection features and
-other components that process form data in their ``startup()``
-callbacks, be sure to place Security Component before those
-components in your ``$components`` array.
+By using the Security Component you automatically get `CSRF
+<http://en.wikipedia.org/wiki/Cross-site_request_forgery>`_ and form tampering
+protection. Hidden token fields will automatically be inserted into forms and
+checked by the Security component. Among other things, a form submission will
+not be accepted after a certain period of inactivity, which is controlled by the
+``csrfExpires`` time.
+
+If you are using Security component's form protection features and other
+components that process form data in their ``startup()`` callbacks, be sure to
+place Security Component before those components in your ``$components`` array.
 
 .. note::
 
@@ -143,11 +141,24 @@ Restricting cross controller communication
 Form tampering prevention
 =========================
 
-By default ``SecurityComponent`` prevents users from tampering with forms. It
-does this by working with FormHelper and tracking which fields are in a form. It
-also keeps track of the values of hidden input elements. All of this data is
-combined and turned into a hash. When a form is submitted, SecurityComponent
-will use the POST data to build the same structure and compare the hash.
+By default ``SecurityComponent`` prevents users from tampering with forms in
+specific ways. The ``SecurityComponent`` will prevent the following things:
+
+* Unknown fields cannot be added to the form.
+* Fields cannot be removed from the form.
+* Values in hidden inputs cannot be modified.
+
+Preventing these forms of tampering is accomplished by working with FormHelper
+and tracking which fields are in a form. The values for hidden fields are
+tracked as well. All of this data is combined and turned into a hash. When
+a form is submitted, SecurityComponent will use the POST data to build the same
+structure and compare the hash.
+
+
+.. note::
+
+    SecurityComponent will **not** prevent select options from being
+    added/changed. Nor will it prevent radio options from being added/changed.
 
 .. php:attr:: unlockedFields
 
@@ -318,12 +329,13 @@ some reason. If you do want to disable this feature, you can set
 components array. By default CSRF protection is enabled, and configured to use
 one-use tokens.
 
-Disabling Security Component For Specific Actions
-=================================================
+Disabling CSRF and Post Data Validation For Specific Actions
+============================================================
 
 There may be cases where you want to disable all security checks for an action (ex. AJAX requests).
 You may "unlock" these actions by listing them in ``$this->Security->unlockedActions`` in your
-``beforeFilter``.
+``beforeFilter``. The ``unlockedActions`` property will **not** effect other
+features of ``SecurityComponent``.
 
 .. versionadded:: 2.3
 

en/core-libraries/events.rst

@@ -451,6 +451,7 @@ Additional Reading
 ==================
 
 .. toctree::
+    :maxdepth: 1
 
     /core-libraries/collections
     /models/behaviors

en/core-libraries/helpers/form.rst

@@ -415,10 +415,10 @@ field. Internally ``input()`` delegates to other methods in FormHelper.
         Try to avoid using `FormHelper::input()` to generate submit buttons. Use
         :php:meth:`FormHelper::submit()` instead.
 
-.. php:method:: inputs(mixed $fields = null, array $blacklist = null)
+.. php:method:: inputs(mixed $fields = null, array $blacklist = null, $options = array())
 
-    Generate a set of inputs for ``$fields``. If $fields is null the current model
-    will be used.
+    Generate a set of inputs for ``$fields``. If ``$fields`` is null all fields,
+    except of those defined in ``$blacklist``, of the current model will be used.
 
     In addition to controller fields output, ``$fields`` can be used to control
     legend and fieldset rendering with the ``fieldset`` and ``legend`` keys.

en/core-libraries/helpers/html.rst

@@ -1085,7 +1085,7 @@ Creating breadcrumb trails with HtmlHelper
 
     :param array $options: An array of :term:`html attributes` for the
         containing ``<ul>`` element. Can also contain the 'separator',
-        'firstClass' and 'lastClass' options.
+        'firstClass', 'lastClass' and 'escape' options.
     :param string|array $startText: The text or element that precedes the ul.
 
     Returns breadcrumbs as a (x)html list.
@@ -1102,6 +1102,9 @@ Creating breadcrumb trails with HtmlHelper
 
     .. versionchanged:: 2.3
         The 'separator', 'firstClass' and 'lastClass' options were added.
+
+    .. versionchanged:: 2.5
+        The 'escape' option was added.
 
 
 .. meta::

en/core-libraries/logging.rst

@@ -50,10 +50,11 @@ When configuring a log stream the ``engine`` parameter is used to
 locate and load the log handler. All of the other configuration
 properties are passed to the log stream's constructor as an array.::
 
-    App::uses('CakeLogInterface', 'Log');
+    App::uses('BaseLog', 'Log');
 
-    class DatabaseLog implements CakeLogInterface {
+    class DatabaseLog extends BaseLog {
         public function __construct($options = array()) {
+            parent::__construct($options);
             // ...
         }
 
@@ -62,12 +63,18 @@ properties are passed to the log stream's constructor as an array.::
         }
     }
 
-CakePHP has no requirements for Log streams other than that they
-must implement a ``write`` method. This write method must take two
-parameters ``$type, $message`` in that order. ``$type`` is the
-string type of the logged message, core values are ``error``,
-``warning``, ``info`` and ``debug``. In addition you can define
-your own types by using them when you call ``CakeLog::write``.
+While CakePHP has no requirements for Log streams other than that they
+must implement a ``write`` method, extending the ``BaseLog`` class has a few
+benefits:
+
+- It automatically handles the scope and type argument casting.
+- It implements the ``config()`` method which is required to make scoped logging
+  work.
+
+Each logger's write method must take two parameters ``$type, $message`` in that
+order. ``$type`` is the string type of the logged message, core values are
+``error``, ``warning``, ``info`` and ``debug``. In addition you can define your
+own types by using them when you call ``CakeLog::write``.
 
 .. _file-log:
 
@@ -76,17 +83,17 @@ your own types by using them when you call ``CakeLog::write``.
 As of 2.4 ``FileLog`` engine takes a few new options:
 
 * ``size`` Used to implement basic log file rotation. If log file size
-   reaches specified size the existing file is renamed by appending timestamp
-   to filename and new log file is created. Can be integer bytes value or
-   human reabable string values like '10MB', '100KB' etc. Defaults to 10MB.
+  reaches specified size the existing file is renamed by appending timestamp
+  to filename and new log file is created. Can be integer bytes value or
+  human reabable string values like '10MB', '100KB' etc. Defaults to 10MB.
 * ``rotate`` Log files are rotated specified times before being removed.
   If value is 0, old versions are removed rather then rotated. Defaults to 10.
 * ``mask`` Set the file permissions for created files. If left empty the default
   permissions are used.
 
 .. warning::
 
-    Prior to 2.4 you had to include the suffix ``Log``` in your configuration
+    Prior to 2.4 you had to include the suffix ``Log`` in your configuration
     (``LoggingPack.DatabaseLog``). This is now not necessary anymore.
     If you have been using a Log engine like ```DatabaseLogger`` that does not follow
     the convention to use a suffix ``Log`` for your class name you have to adjust your
@@ -181,9 +188,7 @@ a completely different storage for your logs.
 Using syslog is pretty much like using the default FileLog engine, you just need
 to specify `Syslog` as the engine to be used for logging. The following
 configuration snippet will replace the default logger with syslog, this should
-be done in the `bootstrap.php` file.
-
-::
+be done in the `bootstrap.php` file::
 
     CakeLog::config('default', array(
         'engine' => 'Syslog'
@@ -276,8 +281,11 @@ message. For example::
     CakeLog::warning('This gets written to both shops and payments streams', 'payments');
     CakeLog::warning('This gets written to both shops and payments streams', 'unknown');
 
-In order for scopes to work correctly, you **must** define the accepted
-``types`` on all loggers you want to use scopes with.
+In order for scopes to work, you **must** do a few things:
+
+#. Define the accepted ``types`` on loggers that use scopes.
+#. Loggers using scopes must implement a ``config()`` method. Extending the
+   ``BaseLog`` class is the easiest way to get a compatible method.
 
 CakeLog API
 ===========

en/development/routing.rst

@@ -180,7 +180,7 @@ When generating URLs, routes are used too. Using
 a url will output /cooks/some_action/5 if the above route is the
 first match found.
 
-By default all named passed and arguments are extracted from URLs matching
+By default all named and passed arguments are extracted from URLs matching
 greedy templates. However, you can configure how and which named arguments are
 parsed using :php:meth:`Router::connectNamed()` if you need to.
 

en/development/testing.rst

@@ -18,10 +18,12 @@ following::
 
     pear upgrade PEAR
     pear config-set auto_discover 1
-    pear install pear.phpunit.de/PHPUnit
+    pear install pear.phpunit.de/PHPUnit-3.7.32
 
 .. note::
 
+    PHPUnit 4 is not compatible with CakePHP's Unit Testing.
+
     Depending on your system's configuration, you may need to run the previous
     commands with ``sudo``
 

en/getting-started.rst

@@ -23,6 +23,7 @@ Additional Reading
 ==================
 
 .. toctree::
+    :maxdepth: 1
 
     getting-started/a-typical-cakephp-request
     getting-started/cakephp-conventions

en/installation.rst

@@ -185,6 +185,7 @@ Advanced Installation and URL Rewriting
 =======================================
 
 .. toctree::
+    :maxdepth: 1
 
     installation/advanced-installation
     installation/url-rewriting

en/models.rst

@@ -116,6 +116,7 @@ More on models
 ==============
 
 .. toctree::
+    :maxdepth: 1
 
     models/associations-linking-models-together
     models/retrieving-your-data

en/models/data-validation.rst

@@ -1270,6 +1270,7 @@ ability to pass off to another validator has been added.
     Also feel free to contribute with your localized validation rules.
 
 .. toctree::
+    :maxdepth: 1
 
     data-validation/validating-data-from-the-controller
 

en/plugins.rst

@@ -72,6 +72,15 @@ Note that all files specified should actually exist in the configured
 plugin(s) or PHP will give warnings for each file it cannot load. This is
 especially important to remember when specifying defaults for all plugins.
 
+CakePHP 2.3.0 added an ``ignoreMissing``` option, that allows you to ignore any
+missing routes and bootstrap files when loading plugins. You can shorten the
+code needed to load all plugins using this::
+
+    // Loads all plugins including any possible routes and bootstrap files
+    CakePlugin::loadAll(array(
+        array('routes' => true, 'bootstrap' => true, 'ignoreMissing' => true)
+    ));
+
 Some plugins additionally need to create one or more tables in your database. In
 those cases, they will often include a schema file which you can
 call from the cake shell like this::

en/tutorials-and-examples/blog-auth-example/auth.rst

@@ -30,6 +30,8 @@ Next step is to create our User model, responsible for finding, saving and
 validating any user data::
 
     // app/Model/User.php
+    App::uses('AppModel', 'Model');
+    
     class User extends AppModel {
         public $validate = array(
             'username' => array(

en/tutorials-and-examples/blog/blog.rst

@@ -192,6 +192,7 @@ to one of the sections below about URL rewriting for your webserver to get
 you up and running:
 
 .. toctree::
+    :maxdepth: 1
 
     /installation/url-rewriting
 

en/views.rst

@@ -808,6 +808,7 @@ More about Views
 ================
 
 .. toctree::
+    :maxdepth: 1
 
     views/themes
     views/media-view