Merge branch '2.7' into master.

2.7 has been released, so the docs should be updated now.

en/appendices.rst

@@ -4,6 +4,14 @@ Appendices
 Appendices contain information regarding the new features
 introduced in 2.x, and the migration path from 1.3 to 2.0.
 
+2.7 Migration Guide
+===================
+
+.. toctree::
+    :maxdepth: 1
+
+    appendices/2-7-migration-guide
+
 2.6 Migration Guide
 ===================
 

en/appendices/2-7-migration-guide.rst

@@ -0,0 +1,114 @@
+2.7 Migration Guide
+###################
+
+CakePHP 2.7 is a fully API compatible upgrade from 2.6. This page outlines
+the changes and improvements made in 2.7.
+
+Console
+=======
+
+- Plugin shells that share a name with their plugin can now be called without
+  the plugin prefix. For example ``Console/cake MyPlugin.my_plugin`` can now
+  be called with ``Console/cake my_plugin``.
+- ``Shell::param()`` was backported from 3.0 into 2.7. This method provides
+  a notice error free way to read CLI options.
+
+Core
+====
+
+Configure
+---------
+
+- :php:meth:`Configure::consume()` has been added to read and delete from
+  Configure in a single step.
+
+Datasource
+==========
+
+- SQL datasources will now cast ``''`` and ``null`` into ``''`` when columns are
+  not nullable and rows are being created or updated.
+
+CakeSession
+-----------
+
+- :php:meth:`CakeSession::consume()` has been added to read and delete from
+  session in a single step.
+- Argument `$renew` has been added to :php:meth:`CakeSession::clear()` to allow
+  emptying the session without forcing a new id and renewing the session. It
+  defaults to ``true``.
+
+Model
+=====
+
+TreeBehavior
+------------
+
+- New setting `level` is now available. You can use it to specify field name in
+  which the depth of tree nodes will be stored.
+- New method ``TreeBehavior::getLevel()`` has been added which fetches depth of
+  a node.
+- The formatting of ``TreeBehavior::generateTreeList()`` has been extracted into
+  an own method ``TreeBehavior::formatTreeList()``.
+
+Network
+=======
+
+CakeEmail
+---------
+
+- CakeEmail will now use the 'default' config set when creating instances that
+  do not specify a configuration set to use. For example ``$email = new
+  CakeEmail();`` will now use the 'default' config set.
+
+Utility
+=======
+
+CakeText
+--------
+
+The class ``String`` has been renamed to ``CakeText``. This resolves some
+conflicts around HHVM compatibility as well as possibly PHP7+. There is
+a ``String`` class provided as well for compatibility reasons.
+
+Validation
+----------
+
+- ``Validation::notEmpty()`` has been renamed to ``Validation::notBlank()``.
+  This aims to avoid confusion around the PHP `notEmpty()` function and that the
+  validation rule accepts ``0`` as valid input.
+
+Controller
+==========
+
+SessionComponent
+----------------
+
+- :php:meth:`SessionComponent::consume()` has been added to read and delete
+  from session in a single step.
+- :php:meth:`SessionComponent::setFlash()` has been deprecated. You should use
+  :php:class:`FlashComponent` instead.
+
+RequestHandlerComponent
+-----------------------
+
+- The ``text/plain`` Accept header is no longer automatically mapped to the
+  ``csv`` response type. This is a backport from 3.0
+
+View
+====
+
+SessionHelper
+-------------
+
+- :php:meth:`SessionHelper::consume()` has been added to read and delete from
+  session in a single step.
+- :php:meth:`SessionHelper::flash()` has been deprecated. You should use
+  :php:class:`FlashHelper` instead.
+
+TestSuite
+=========
+
+ControllerTestCase
+------------------
+
+- :php:meth:`ControllerTestCase::testAction()` now supports an array as URL.

en/appendices/new-features-in-cakephp-2-1.rst

@@ -160,7 +160,7 @@ CPU cycles and memory. ::
         public $components = array('RequestHandler');
 
         public function view($id) {
-            $article = $this->Article->read(null, $id);
+            $article = $this->Article->findById($id);
             $this->response->modified($article['Article']['modified']);
             $this->set(compact('article'));
         }

en/console-and-shells.rst

@@ -184,7 +184,7 @@ and see your name printed out. Any public method not prefixed by an ``_`` is all
 called from the command line. In our ``hey_there`` method we also used ``$this->args``, this
 property contains an array of all the positional arguments provided to a command. You can
 also use switches or options on shell applications, these are available at ``$this->params``,
-but we'll cover that in a bit.
+and through the ``param()`` method, but we'll cover that in a bit.
 
 When using a ``main()`` method you won't be able to use the positional arguments
 or parameters. This is because the first positional argument or option is
@@ -625,6 +625,11 @@ checks for boolean flags::
         // do something
     }
 
+    // as of 2.7
+    if ($this->param('verbose')) {
+        // do something
+    }
+
 Since the boolean options are always defined as ``true`` or
 ``false`` you can omit additional check methods.
 
@@ -840,6 +845,13 @@ Shell API
 
     Clears the current output being displayed.
 
+.. php:method:: param($name)
+
+    Get the value of an option/parameter. Will return null if the parameter does
+    not exist.
+
+    .. versionadded:: 2.7
+
 .. php:method:: createFile($path, $contents)
 
     :param string $path: Absolute path to the file you want to create.

en/core-libraries/behaviors/tree.rst

@@ -453,6 +453,30 @@ are a few more tree-orientated permutations at your disposal.
           [5] =>  "_Extreme fishing"
       )
 
+    .. php:method:: formatTreeList($results, $options=array())
+
+    .. versionadded:: 2.7
+
+    :param $results: Results of a find('all') call.
+    :param $options: Options to pass into.
+
+    This method will return data similar to
+    :ref:`model-find-list` but with a nested prefix that is specified
+    in the ``spacer`` option to show the structure of your data.
+
+    Supported options are:
+
+    * ``keyPath``: A string path to the key, i.e. "{n}.Post.id".
+    * ``valuePath``: A string path to the value, i.e. "{n}.Post.title".
+    * ``spacer``: The character or characters which will be repeated.
+
+    An example would be::
+
+        $results = $this->Category->find('all');
+        $results = $this->Category->formatTreeList($results, array(
+            'spacer' => '--'
+        ));
+
     .. php:method:: getParentNode()
 
     This convenience function will, as the name suggests, return the
@@ -771,6 +795,25 @@ Example output::
             )
     )
 
+Node Level (Depth)
+==================
+
+.. versionadded:: 2.7
+
+Knowing the depth of tree nodes can be useful when you want to retrieve nodes
+only upto a certain level for e.g. when generating menus. You can use the
+``level`` option to specify the field that will save level of each node.
+
+    public $actAs = array('Tree' => array(
+        'level' => 'level', // Defaults to null, i.e. no level saving
+    ));
+
+.. php:method:: getLevel($id)
+
+.. versionadded:: 2.7
+
+If you are not caching the level of nodes using the ``level`` option in settings,
+you can use this method to get level of a particular node.
 
 .. meta::
     :title lang=en: Tree

en/core-libraries/components/authentication.rst

@@ -440,6 +440,8 @@ digest authentication with any other authentication strategies, it's also
 recommended that you store the digest password in a separate column,
 from the normal password hash::
 
+    App::uses('DigestAuthenticate', 'Controller/Component/Auth');
+    
     class User extends AppModel {
         public function beforeSave($options = array()) {
             // make a password for digest auth.

en/core-libraries/components/flash.rst

@@ -0,0 +1,81 @@
+Flash
+#####
+
+.. php:class:: FlashComponent(ComponentCollection $collection, array $config = array())
+
+FlashComponent provides a way to set one-time notification messages to be
+displayed after processing a form or acknowledging data. CakePHP refers to these
+messages as "flash messages". FlashComponent writes flash messages to
+``$_SESSION``, to be rendered in a View using
+:doc:`FlashHelper </core-libraries/helpers/flash>`.
+
+The FlashComponent replaces the ``setFlash()`` method on ``SessionComponent``
+and should be used instead of that method.
+
+Setting Flash Messages
+======================
+
+FlashComponent provides two ways to set flash messages: its ``__call`` magic
+method and its ``set()`` method.  To furnish your application with verbosity,
+FlashComponent's ``__call`` magic method allows you use a method name that maps
+to an element located under the ``app/View/Elements/Flash`` directory. By
+convention, camelcased methods will map to the lowercased and underscored
+element name::
+
+    // Uses app/View/Elements/Flash/success.ctp
+    $this->Flash->success('This was successful');
+
+    // Uses app/View/Elements/Flash/great_success.ctp
+    $this->Flash->greatSuccess('This was greatly successful');
+
+Alternatively, to set a plain-text message without rendering an element, you can
+use the ``set()`` method::
+
+    $this->Flash->set('This is a message');
+
+FlashComponent's ``__call`` and ``set()`` methods optionally take a second
+parameter, an array of options:
+
+* ``key`` Defaults to 'flash'. The array key found under the 'Flash' key in
+  the session.
+* ``element`` Defaults to null, but will automatically be set when using the
+  ``__call()`` magic method. The element name to use for rendering.
+* ``params`` An optional array of keys/values to make available as variables
+  within an element.
+
+An example of using these options::
+
+    // In your Controller
+    $this->Flash->success('The user has been saved', array(
+        'key' => 'positive',
+        'params' => array(
+            'name' => $user['User']['name'],
+            'email' => $user['User']['email']
+        )
+    ));
+
+    // In your View
+    <?php echo $this->Flash->render('positive') ?>
+
+    <!-- In app/View/Elements/Flash/success.ctp -->
+    <div id="flash-<?php echo h($key) ?>" class="message-info success">
+        <?php echo h($message) ?>: <?php echo h($params['name']) ?>, <?php echo h($params['email']) ?>.
+    </div>
+
+If you are using the ``__call()`` magic method, the ``element`` option will
+always be replaced. In order to retrieve a specific element from a plugin, you
+should set the ``plugin`` parameter. For example::
+
+    // In your Controller
+    $this->Flash->warning('My message', array('plugin' => 'PluginName'));
+
+The code above will use the warning.ctp element under ``plugins/PluginName/View/Elements/Flash``
+for rendering the flash message.
+
+.. note::
+    By default, CakePHP does not escape the HTML in flash messages. If you
+    are using any request or user data in your flash messages, you should
+    escape it with :php:func:`h` when formatting your messages.
+
+For more information about rendering your flash messages, please refer to the
+:doc:`FlashHelper </core-libraries/helpers/flash>` section.

en/core-libraries/components/sessions.rst

@@ -51,6 +51,11 @@ all Session component methods wherever a name/key is used.
     Retrieve the value Green from the session. Reading data that does not exist
     will return null.
 
+.. php:method:: consume($name)
+
+    Read and delete a value from the Session. This is useful when you want to
+    combine reading and deleting values in a single operation.
+
 .. php:method:: check($name)
 
     Used to check if a Session variable has been set. Returns true on
@@ -84,7 +89,9 @@ Creating notification messages
 
 .. php:method:: setFlash(string $message, string $element = 'default', array $params = array(), string $key = 'flash')
 
-    :rtype: void
+    .. deprecated:: 2.7.0
+        You should use :doc:`/core-libraries/components/flash` to
+        create flash messages. The setFlash() method will be removed in 3.0.0.
 
     Often in web applications, you will need to display a one-time notification
     message to the user after processing a form or acknowledging data.

en/core-libraries/helpers/flash.rst

@@ -0,0 +1,49 @@
+Flash
+#####
+
+.. php:class:: FlashHelper(View $view, array $config = array())
+
+FlashHelper provides a way to render flash messages that were set in
+``$_SESSION`` by :doc:`FlashComponent </core-libraries/components/flash>`.
+:doc:`FlashComponent </core-libraries/components/flash>` and FlashHelper
+primarily use elements to render flash messages.  Flash elements are found under
+the ``app/View/Elements/Flash`` directory.  You'll notice that CakePHP's App
+template comes with two flash elements: ``success.ctp`` and ``error.ctp``.
+
+The FlashHelper replaces the ``flash()`` method on ``SessionHelper``
+and should be used instead of that method.
+
+Rendering Flash Messages
+========================
+
+To render a flash message, you can simply use FlashHelper's ``render()``
+method::
+
+    <?php echo $this->Flash->render() ?>
+
+By default, CakePHP uses a "flash" key for flash messages in a session.  But, if
+you've specified a key when setting the flash message in
+:doc:`FlashComponent </core-libraries/components/flash>`, you can specify which
+flash key to render::
+
+    <?php echo $this->Flash->render('other') ?>
+
+You can also override any of the options that were set in FlashComponent::
+
+    // In your Controller
+    $this->Flash->set('The user has been saved.', array(
+        'element' => 'success'
+    ));
+
+    // In your View: Will use great_success.ctp instead of success.ctp
+    <?php echo $this->Flash->render('flash', array(
+        'element' => 'great_success'
+    ));
+
+.. note::
+    By default, CakePHP does not escape the HTML in flash messages. If you are using
+    any request or user data in your flash messages, you should escape it
+    with :php:func:`h` when formatting your messages.
+
+For more information about the available array options, please refer to the
+:doc:`FlashComponent </core-libraries/components/flash>` section.