Merge branch 'master' into 3.0

Conflicts: en/contributing/cakephp-coding-conventions.rst en/core-libraries/behaviors/containable.rst en/core-libraries/components/access-control-lists.rst en/core-libraries/helpers/text.rst en/core-libraries/logging.rst en/core-utility-libraries/app.rst en/development/configuration.rst en/development/routing.rst en/installation/advanced-installation.rst en/models/data-validation.rst en/models/retrieving-your-data.rst en/models/saving-your-data.rst en/models/virtual-fields.rst en/views/helpers.rst en/views/themes.rst fr/contributing/cakephp-coding-conventions.rst fr/core-libraries/behaviors/containable.rst fr/core-libraries/helpers/form.rst fr/core-libraries/helpers/html.rst fr/core-libraries/logging.rst fr/core-utility-libraries/httpsocket.rst fr/core-utility-libraries/string.rst fr/development/configuration.rst fr/development/routing.rst fr/installation/advanced-installation.rst fr/models/retrieving-your-data.rst fr/models/saving-your-data.rst fr/models/virtual-fields.rst
tuffz · Jun 17, 2014 · a078f74 · a078f74
2 parents c3d91d8 + b2dd79f
commit a078f74
Show file tree

Hide file tree

Showing 37 changed files with 698 additions and 84 deletions.
diff --git a/README.mdown b/README.mdown
@@ -23,10 +23,10 @@ You can install the phpdomain using:
 
 *To run the easy_install command, the setuptools package must be previously installed.*
 
-Building the documentation
+Building the Documentation
 --------------------------
 
-After installing the required packages, you can build the documentation using `Make`.
+After installing the required packages, you can build the documentation using `make`.
 
 	# Create all the HTML docs. Including all the languages.
 	make html
@@ -43,16 +43,16 @@ After installing the required packages, you can build the documentation using `M
 	# Populate the search index
 	make populate-index
 
-This will generate all the documentation in an html form.  Other output such as 'htmlhelp' are not fully complete at this time.
+This will generate all the documentation in an HTML form.  Other output such as 'htmlhelp' are not fully complete at this time.
 
-After making changes to the documentation, you can build the html version of the docs by using `make html` again.  This will build only the html files that have had changes made to them.
+After making changes to the documentation, you can build the HTML version of the docs by using `make html` again.  This will build only the HTML files that have had changes made to them.
 
 Building the PDF
 ----------------
 
 Building the PDF is a non-trivial task.
 
-1. Install Latex - This varies by distribution/OS so refer to your package manager. You should install the full LaTeX package. The basic one requires many additional packages to be installed with `tlmgr`
+1. Install LaTeX - This varies by distribution/OS so refer to your package manager. You should install the full LaTeX package. The basic one requires many additional packages to be installed with `tlmgr`
 2. Run `make latex-en`.
 3. Run `make pdf-en`.
 
@@ -68,27 +68,27 @@ There are currently a number of outstanding issues that need to be addressed.  W
 
 	todo_include_todos = True
 
-After rebuilding the html content, you should see a list of existing todo items at the bottom of the table of contents.
+After rebuilding the HTML content, you should see a list of existing todo items at the bottom of the table of contents.
 
-You are also welcome to make and suggestions for new content as commits in a github fork.  Please make any totally new sections in a separate branch.  This makes changes far easier to integrate later on.
+You are also welcome to make and suggestions for new content as commits in a GitHub fork.  Please make any totally new sections in a separate branch.  This makes changes far easier to integrate later on.
 
 Translations
 ------------
 
 Contributing translations requires that you make a new directory using the two letter name for your language.  As content is translated, directories mirroring the english content should be created with localized content.
 
 
-Generating Meta tags
+Generating Meta Tags
 --------------------
 
-If you are providing translations and want to automatically generate meta tags for the resulting html files, a MetatagShell is provided in
+If you are providing translations and want to automatically generate meta tags for the resulting HTML files, a MetatagShell is provided in
 the `scripts` folder of this repo. In order to use it, copy it into any CakePHP 2.0 empty application inside `app/Console/Command`, execute
 `Console/cake metatag` and follow the instructions.
 
 The script will process all the files under one of the translation folders and generate the possible description terms using an external API, 
 it is a good idea to go over the generated terms and clean-up whatever noise it might have generated.
 
-Making search work locally
+Making Search Work Locally
 --------------------------
 
 * Install elasticsearch.  This varies based on your platform, but most

diff --git a/config/all.py b/config/all.py
@@ -118,7 +118,7 @@
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.

diff --git a/en/contributing.rst b/en/contributing.rst
@@ -11,6 +11,7 @@ cover the various ways you can contribute to CakePHP:
     contributing/tickets
     contributing/code
     contributing/cakephp-coding-conventions
+    contributing/backwards-compatibility
 
 
 

diff --git a/en/contributing/backwards-compatibility.rst b/en/contributing/backwards-compatibility.rst
@@ -0,0 +1,166 @@
+Backwards Compatibility Guide
+#############################
+
+Ensuring that you can upgrade your applications easily and smoothly is important
+to us. That's why we only break compatibility at major release milestones.
+You might be familiar with `semantic versioning <http://semver.org/>`_, which is
+the general guideline we use on all CakePHP projects. In short, semantic
+versioning means that only major releases (such as 2.0, 3.0, 4.0) can break
+backwards compatibility. Minor releases (such as 2.1, 3.1, 3.2) may introduce new
+features, but are not allowed to break compatibility. Bug fix releases (such as 2.1.2,
+3.0.1) do not add new features, but fix bugs or enhance performance only.
+
+.. note::
+
+    CakePHP started following semantic versioning in 2.0.0. These
+    rules do not apply to 1.x.
+
+To clarify what changes you can expect in each release tier we have more
+detailed information for developers using CakePHP, and for developers working on
+CakePHP that helps set expectations of what can be done in minor releases. Major
+releases can have as many breaking changes as required.
+
+Migration Guides
+================
+
+For each major and minor release, the CakePHP team will provide a migration
+guide. These guides explain the new features and any breaking changes that are
+in each release. They can be found in the :doc:`/appendices` section of the
+cookbook.
+
+Using CakePHP
+=============
+
+If you are building your application with CakePHP, the following guidelines
+explain the stability you can expect.
+
+Interfaces
+----------
+
+Outside of major releases, interfaces provided by CakePHP will **not** have any
+existing methods changed. New methods may be added, but no existing methods will
+be changed.
+
+Classes
+-------
+
+Classes provided by CakePHP can be constructed and have their public methods and
+properties used by application code and outside of major releases backwards
+compatibility is ensured.
+
+.. note::
+
+    Some classes in CakePHP are marked with the ``@internal`` API doc tag. These
+    classes are **not** stable and do not have any backwards compatibility
+    promises.
+
+In minor releases, new methods may be added to classes, and existing methods may
+have new arguments added. Any new arguments will have default values, but if
+you've overidden methods with a differing signature you may see fatal errors.
+Methods that have new arguments added will be documented in the migration guide
+for that release.
+
+The following table outlines several use cases and what compatibility you can
+expect from CakePHP:
+
++-------------------------------+--------------------------+
+| If you...                     | Backwards compatibility? |
++===============================+==========================+
+| Typehint against the class    | Yes                      |
++-------------------------------+--------------------------+
+| Create a new instance         | Yes                      |
++-------------------------------+--------------------------+
+| Extend the class              | Yes                      |
++-------------------------------+--------------------------+
+| Access a public property      | Yes                      |
++-------------------------------+--------------------------+
+| Call a public method          | Yes                      |
++-------------------------------+--------------------------+
+| **Extend a class and...**                                |
++-------------------------------+--------------------------+
+| Override a public property    | Yes                      |
++-------------------------------+--------------------------+
+| Access a protected property   | No [1]_                  |
++-------------------------------+--------------------------+
+| Override a protected property | No [1]_                  |
++-------------------------------+--------------------------+
+| Override a protected method   | No [1]_                  |
++-------------------------------+--------------------------+
+| Call a protected method       | No [1]_                  |
++-------------------------------+--------------------------+
+| Add a public property         | No                       |
++-------------------------------+--------------------------+
+| Add a public method           | No                       |
++-------------------------------+--------------------------+
+| Add an argument               | No [1]_                  |
+| to an overridden method       |                          |
++-------------------------------+--------------------------+
+| Add a default argument        | Yes                      |
+| to an existing method         |                          |
++-------------------------------+--------------------------+
+
+Working on CakePHP
+==================
+
+If you are helping make CakePHP even better please keep the following guidelines
+in mind when adding/changing functionality: 
+
+In a minor release you can:
+
++-------------------------------+--------------------------+
+| In a minor release can you...                            |
++===============================+==========================+
+| **Classes**                                              |
++-------------------------------+--------------------------+
+| Remove a class                | No                       |
++-------------------------------+--------------------------+
+| Remove an interface           | No                       |
++-------------------------------+--------------------------+
+| Remove a trait                | No                       |
++-------------------------------+--------------------------+
+| Make final                    | No                       |
++-------------------------------+--------------------------+
+| Make abstract                 | No                       |
++-------------------------------+--------------------------+
+| Change name                   | Yes [2]_                 |
++-------------------------------+--------------------------+
+| **Properties**                                           |
++-------------------------------+--------------------------+
+| Add a public property         | Yes                      |
++-------------------------------+--------------------------+
+| Remove a public property      | No                       |
++-------------------------------+--------------------------+
+| Add a protected property      | Yes                      |
++-------------------------------+--------------------------+
+| Remove a protected property   | Yes [3]_                 |
++-------------------------------+--------------------------+
+| **Methods**                                              |
++-------------------------------+--------------------------+
+| Add a public method           | Yes                      |
++-------------------------------+--------------------------+
+| Remove a public method        | No                       |
++-------------------------------+--------------------------+
+| Add a protected method        | Yes                      |
++-------------------------------+--------------------------+
+| Move to parent class          | Yes                      |
++-------------------------------+--------------------------+
+| Remove a protected method     | Yes [3]_                 |
++-------------------------------+--------------------------+
+| Reduce visibility             | No                       |
++-------------------------------+--------------------------+
+| Change method name            | Yes [2]_                 |
++-------------------------------+--------------------------+
+| Add argument with             | Yes                      |
+| default value                 |                          |
++-------------------------------+--------------------------+
+| Add required argument         | No                       |
++-------------------------------+--------------------------+
+
+
+.. [1] Your code *may* be broken by minor releases. Check the migration guide
+       for details.
+.. [2] You can change a class/method name as long as the old name remains available.
+       This is generally avoided unless renaming has significant benefit.
+.. [3] Avoid whenever possible. Any removals need to be documented in
+       the migration guide.
+
diff --git a/en/controllers/components.rst b/en/controllers/components.rst
@@ -3,7 +3,7 @@ Components
 
 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
+various common tasks. You can also create your 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.

diff --git a/en/core-libraries/components/authentication.rst b/en/core-libraries/components/authentication.rst
@@ -11,6 +11,16 @@ ways of identifying and checking user authorization.
 
 .. _authentication-objects:
 
+Suggested Reading Before Continuing
+===================================
+
+Configuring authentication requires several steps including defining
+a users table, creating a model, controller & views, etc.
+
+This is all covered step by step in the
+:doc:`Blog Tutorial </tutorials-and-examples/blog-auth-example/auth>`.
+
+
 Authentication
 ==============
 

diff --git a/en/core-libraries/helpers/form.rst b/en/core-libraries/helpers/form.rst
@@ -786,7 +786,7 @@ Creating Input Elements
     * ``$attributes['disabled']`` Setting this to ``true`` or ``'disabled'``
       will disable all of the generated radio buttons.
 
-    * ``$attributes['legend']`` Radio elements are wrapped with a label and
+    * ``$attributes['legend']`` Radio elements are wrapped with a legend and
       fieldset by default. Set ``$attributes['legend']`` to false to remove
       them.::
 

diff --git a/en/core-libraries/helpers/text.rst b/en/core-libraries/helpers/text.rst
@@ -6,7 +6,7 @@ TextHelper
 The TextHelper contains methods to make text more usable and
 friendly in your views. It aids in enabling links, formatting URLs,
 creating excerpts of text around chosen words or phrases,
-highlighting key words in blocks of text, and to gracefully
+highlighting key words in blocks of text, and gracefully
 truncating long stretches of text.
 
 .. php:method:: autoLinkEmails(string $text, array $options=[])
@@ -35,7 +35,7 @@ truncating long stretches of text.
     :param string $text: The text to convert.
     :param array $htmlOptions: An array :term:`html attributes` for the generated links
 
-    Same as in ``autoLinkEmails()``, only this method searches for
+    Same as ``autoLinkEmails()``, only this method searches for
     strings that start with https, http, ftp, or nntp and links them
     appropriately.
 
@@ -58,7 +58,7 @@ truncating long stretches of text.
 
     :param string $text: The text to convert.
 
-    Adds proper <p> around text where double-line returns and <br> where single-line returns
+    Adds proper <p> around text where double-line returns are found, and <br> where single-line returns
     are found.::
 
         $myText = 'For more information

diff --git a/en/core-utility-libraries/hash.rst b/en/core-utility-libraries/hash.rst
@@ -591,7 +591,15 @@ Attribute Matching Types
 
     Creates a new array, by extracting $path, and mapping $function
     across the results. You can use both expression and matching elements with
-    this method.
+    this method::
+    
+        //call the noop function $this->noop() on every element of $data
+        $result = Hash::map($data, "{n}", array($this, 'noop'));
+        
+        function noop($array) {
+         //do stuff to array and return the result
+         return $array;
+        }
 
 .. php:staticmethod:: reduce(array $data, $path, $function)
 

diff --git a/en/core-utility-libraries/inflector.rst b/en/core-utility-libraries/inflector.rst
@@ -8,6 +8,8 @@ word variations such as pluralizations or camelizing and is
 normally accessed statically. Example:
 ``Inflector::pluralize('example')`` returns "examples".
 
+You can try out the inflections online at `inflector.cakephp.org <http://inflector.cakephp.org/>`_.
+
 .. php:staticmethod:: pluralize($singular)
 
     * **Input:** Apple, Orange, Person, Man

diff --git a/en/core-utility-libraries/string.rst b/en/core-utility-libraries/string.rst
@@ -142,13 +142,13 @@ use the ``String`` class::
 .. php:method:: truncate(string $text, int $length = 100, array $options)
 
     :param string $text: The text to truncate.
-    :param int $length:  The length to trim to.
+    :param int $length:  The length, in characters, beyond which the text should be truncated.
     :param array $options: An array of options to use.
 
-    Cuts a string to the ``$length`` and adds a suffix with
-    ``'ellipsis'`` if the text is longer than ``$length``. If ``'exact'``
-    is passed as ``false``, the truncation will occur after the next
-    word ending. If ``'html'`` is passed as ``true``, HTML tags will be
+    If ``$text`` is longer than ``$length``, this method truncates it at ``$length`` and adds a prefix
+    consisting of ``'ellipsis'``, if defined. If ``'exact'``
+    is passed as ``false``, the truncation will occur at the first whitespace after the
+    point at which ``$length`` is exceeded. If ``'html'`` is passed as ``true``, HTML tags will be
     respected and will not be cut off.
 
     ``$options`` is used to pass all extra parameters, and has the
@@ -191,13 +191,14 @@ use the ``String`` class::
 .. php:method:: tail(string $text, int $length = 100, array $options)
 
     :param string $text: The text to truncate.
-    :param int $length:  The length to trim to.
+    :param int $length:  The length, in characters, beyond which the text should be truncated.
     :param array $options: An array of options to use.
 
-    Cuts a string to the ``$length`` and adds a prefix with
-    ``'ellipsis'`` if the text is longer than ``$length``. If ``'exact'``
-    is passed as ``false``, the truncation will occur before the next
-    word ending.
+    If ``$text`` is longer than ``$length``, this method removes an initial substring with length
+    consisting of the difference and prepends a suffix
+    consisting of ``'ellipsis'``, if defined. If ``'exact'``
+    is passed as ``false``, the truncation will occur at the first whitespace prior to the
+    point at which truncation would otherwise take place.
 
     ``$options`` is used to pass all extra parameters, and has the
     following possible keys by default, all of which are optional::

diff --git a/en/installation.rst b/en/installation.rst
@@ -100,6 +100,15 @@ process makes ``tmp`` and it's subfolders globally writeable to get things up
 and running quickly but you can update the permissions for better security and
 keep them writable only for the webserver user.
 
+One common issue is that the app/tmp directories and subdirectories must be writable both by the web server and the command line user.
+On a UNIX system, if your web server user is different from your command line user,
+you can run the following commands just once in your project to ensure that
+permissions will be setup properly::
+
+   HTTPDUSER=`ps aux | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`
+   setfacl -R -m u:${HTTPDUSER}:rwx app/tmp
+   setfacl -R -d -m u:${HTTPDUSER}:rwx app/tmp
+
 Setup
 =====