Merge pull request cakephp#1887 from cakephp/3.0-doc-updates

3.0 doc updates

en/controllers.rst

@@ -439,6 +439,7 @@ In your Controller's ``initialize()`` method you can define any components you
 want loaded, and any configuration data for them::
 
     public function intialize() {
+        parent::initialize();
         $this->loadComponent('Csrf');
         $this->loadComponent('Comments', Configure:read('Comments'));
     }
@@ -461,7 +462,6 @@ additional MVC classes::
 
     class RecipesController extends AppController {
         public $helpers = ['Form'];
-        public $components = ['RequestHandler'];
     }
 
 Each of these variables are merged with their inherited values,

en/controllers/components.rst

@@ -130,7 +130,11 @@ and the :php:class:`Cake\\Controller\\Component\\CookieComponent` in your
 controller, you could access them like so::
 
     class PostsController extends AppController {
-        public $components = ['Flash', 'Cookie'];
+        public function intialize() {
+            parent::initialize();
+            $this->loadComponent('Flash');
+            $this->loadComponent('Cookie');
+        }
 
         public function delete() {
             if ($this->Post->delete($this->request->data('Post.id')) {

en/controllers/components/authentication.rst

@@ -69,7 +69,7 @@ authentication by throwing an exception. You will need to catch any
 thrown exceptions, and handle them as needed.
 
 You can configure authentication handlers in your controller's
-``beforeFilter`` or, in the ``$components`` array. You can pass
+``beforeFilter()`` or ``initialize()`` methods. You can pass
 configuration information into each authentication object, using an
 array::
 
@@ -110,27 +110,27 @@ keys.
 - ``contain`` Extra models to contain and return with identified user's info.
 - ``passwordHasher`` Password hasher class. Defaults to ``Default``.
 
-To configure different fields for user in ``$components`` array::
+To configure different fields for user in your ``initialize()`` method::
 
-    // Pass settings in $components array
-    public $components = [
-        'Auth' => [
+    public function initialize() {
+        parent::initialize();
+        $this->loadComponent('Auth', [
             'authenticate' => [
                 'Form' => [
                     'fields' => ['username' => 'email', 'password' => 'passwd']
                 ]
             ]
-        ]
-    ];
+        ]);
+    }
 
 Do not put other ``Auth`` configuration keys (like ``authError``, ``loginAction`` etc)
 within the ``authenticate`` or ``Form`` element. They should be at the same level as
 the authenticate key. The setup above with other Auth configuration
 should look like::
 
-    // Pass settings in $components array
-    public $components = [
-        'Auth' => [
+    public function initialize() {
+        parent::initialize();
+        $this->loadComponent('Auth', [
             'loginAction' => [
                 'controller' => 'Users',
                 'action' => 'login',
@@ -142,8 +142,8 @@ should look like::
                     'fields' => ['username' => 'email']
                 ]
             ]
-        ]
-    ];
+        ]);
+    }
 
 In addition to the common configuration, Basic authentication supports
 the following keys:
@@ -406,17 +406,18 @@ In order to use a different password hasher, you need to create the class in
 Then you are required to configure the AuthComponent to use your own password
 hasher::
 
-    public $components = [
-        'Auth' => [
+    public function initialize() {
+        parent::initialize();
+        $this->loadComponent('Auth', [
             'authenticate' => [
                 'Form' => [
                     'passwordHasher' => [
                         'className' => 'Legacy',
                     ]
                 ]
             ]
-        ]
-    ];
+        ]);
+    }
 
 Supporting legacy systems is a good idea, but it is even better to keep your
 database with the latest security advancements. The following section will
@@ -430,8 +431,9 @@ to another, this is achieved through the ``FallbackPasswordHasher`` class.
 Assuming you are using ``LegacyPasswordHasher`` from the previous example, you
 can configure the AuthComponent as follows::
 
-    public $components = [
-        'Auth' => [
+    public function initialize() {
+        parent::initialize();
+        $this->loadComponent('Auth', [
             'authenticate' => [
                 'Form' => [
                     'passwordHasher' => [
@@ -440,8 +442,8 @@ can configure the AuthComponent as follows::
                     ]
                 ]
             ]
-        ]
-    ];
+        ]);
+    }
 
 The first name appearing in the ``hashers`` key indicates which of the classes
 is the preferred one, but it will fallback to the others in the list if the
@@ -613,7 +615,7 @@ Additionally you can halt all authorization by throwing an exception.
 You will need to catch any thrown exceptions, and handle them.
 
 You can configure authorization handlers in your controller's
-``beforeFilter`` or, in the ``$components`` array. You can pass
+``beforeFilter()`` or ``initialize()`` methods. You can pass
 configuration information into each authorization object, using an
 array::
 
@@ -764,9 +766,13 @@ the request. The callback is passed the active user, so it can be
 checked::
 
     class AppController extends Controller {
-        public $components = [
-            'Auth' => ['authorize' => 'Controller'],
-        ];
+        public function initialize() {
+            parent::initialize();
+            $this->loadComponent('Auth', [
+                'authorize' => 'Controller',
+            ]);
+        }
+
         public function isAuthorized($user = null) {
             // Any registered user can access public functions
             if (empty($this->request->params['prefix'])) {
@@ -791,7 +797,7 @@ Configuration options
 =====================
 
 The following settings can all be defined either in your controller's
-``$components`` array or using ``$this->Auth->config()``:
+``initialize()`` method or using ``$this->Auth->config()`` in your ``beforeFilter()``:
 
 ajaxLogin
     The name of an optional view element to render when an AJAX request is made

en/controllers/components/csrf.rst

@@ -20,11 +20,12 @@ Using the CsrfComponent
 Simply by adding the ``CsrfComponent``` to your components array,
 you can benefit from the CSRF protection it provides::
 
-    public $components = [
-        'Csrf' => [
+    public function initialize() {
+        parent::initialize();
+        $this->loadComponent('Csrc', [
             'secure' => true
-        ]
-    ];
+        ]);
+    }
 
 Settings can be passed into the component through your component's settings.
 The available configuration options are:

en/controllers/components/pagination.rst

@@ -32,30 +32,36 @@ that the order key must be defined in an array structure like below::
 
     class ArticlesController extends AppController {
 
-        public $components = ['Paginator'];
-
         public $paginate = [
             'limit' => 25,
             'order' => [
                 'Articles.title' => 'asc'
             ]
         ];
+
+        public function intialize() {
+            parent::initialize();
+            $this->loadComponent('Paginator');
+        }
     }
 
 You can also include any of the options supported by
 :php:meth:`~Cake\\ORM\\Table::find()`, such as ``fields``::
 
     class ArticlesController extends AppController {
 
-        public $components = ['Paginator'];
-
         public $paginate = [
             'fields' => ['Articles.id', 'Articles.created'],
             'limit' => 25,
             'order' => [
                 'Articles.title' => 'asc'
             ]
         ];
+
+        public function intialize() {
+            parent::initialize();
+            $this->loadComponent('Paginator');
+        }
     }
 
 While you can pass most of the query options from the paginate property it is

en/controllers/components/request-handling.rst

@@ -20,11 +20,14 @@ extension exists, it will be added to the Controllers Helper array.
 Lastly, if XML/JSON data is POST'ed to your Controllers, it will be
 parsed into an array which is assigned to ``$this->request->data``,
 and can then be saved as model data. In order to make use of
-RequestHandler it must be included in your $components array::
+RequestHandler it must be included in your ``initialize()`` method::
 
     class WidgetsController extends AppController {
 
-        public $components = ['RequestHandler'];
+        public function initialize() {
+            parent::initialize();
+            $this->loadComponent('RequestHandler');
+        }
 
         // Rest of controller
     }
@@ -45,7 +48,10 @@ the client and its request.
 
         class ArticlesController extends AppController {
 
-            public $components = ['RequestHandler'];
+            public function initialize() {
+                parent::initialize();
+                $this->loadComponent('RequestHandler');
+            }
 
             public function beforeFilter() {
                 if ($this->RequestHandler->accepts('html')) {
@@ -220,10 +226,12 @@ the client. The response status code is then set to ``304 Not Modified``.
 You can opt-out this automatic checking by setting the ``checkHttpCache``
 setting to ``false``::
 
-    public $components = [
-        'RequestHandler' => [
+    public function initialize() {
+        parent::initialize();
+        $this->loadComponent('RequestHandler', [
             'checkHttpCache' => false
-    ]];
+        ]);
+    }
 
 Using custom ViewClasses
 ========================
@@ -236,14 +244,16 @@ with a custom View class, or add View classes for other types.
 You can map existing and new types to your custom classes. You can also set this
 automatically by using the ``viewClassMap`` setting::
 
-    public $components = [
-        'RequestHandler' => [
+    public function initialize() {
+        parent::initialize();
+        $this->loadComponent(''RequestHandler', [
             'viewClassMap' => [
                 'json' => 'ApiKit.MyJson',
                 'xml' => 'ApiKit.MyXml',
                 'csv' => 'ApiKit.Csv'
             ]
-    ]];
+        ]);
+    }
 
 .. meta::
     :title lang=en: Request Handling

en/controllers/components/security.rst

@@ -22,7 +22,7 @@ Security component.
 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.
+components in your ``initialize()`` method.
 
 .. note::
 
@@ -85,7 +85,7 @@ Restricting Cross Controller Communication
 
 .. php:attr:: allowedControllers
 
-    A list of controllers which can send requests 
+    A list of controllers which can send requests
     to this controller.
     This can be used to control cross controller requests.
 
@@ -146,7 +146,10 @@ want and the Security Component will enforce them on its startup::
 
     class WidgetsController extends AppController {
 
-        public $components = ['Security'];
+        public function initialize() {
+            parent::initialize();
+            $this->loadComponent('Security');
+        }
 
         public function beforeFilter(Event $event) {
             if (isset($this->request->params['admin'])) {
@@ -165,7 +168,10 @@ require secure SSL requests::
 
     class WidgetsController extends AppController {
 
-        public $components = ['Security'];
+        public function initialize() {
+            parent::initialize();
+            $this->loadComponent('Security');
+        }
 
         public function beforeFilter(Event $event) {
             if (isset($this->params['admin'])) {
@@ -211,7 +217,10 @@ There may be cases where you want to disable all security checks for an action
 
     class WidgetController extends AppController {
 
-        public $components = ['Security'];
+        public function initialize() {
+            parent::initialize();
+            $this->loadComponent('Security');
+        }
 
         public function beforeFilter(Event $event) {
              $this->Security->config('unlockedActions', ['edit']);

en/core-libraries/number.rst

@@ -14,7 +14,10 @@ use the ``Number`` class::
 
     class UsersController extends AppController {
 
-        public $components = array('Auth');
+        public function initialize() {
+            parent::initialize();
+            $this->loadComponent('Auth');
+        }
 
         public function afterLogin() {
             $storageUsed = $this->Auth->user('storage_used');

en/core-libraries/string.rst

@@ -18,7 +18,10 @@ of a ``View``, use the ``String`` class::
 
     class UsersController extends AppController {
 
-        public $components = ['Auth'];
+        public function initialize() {
+            parent::initialize();
+            $this->loadComponent('Auth')
+        };
 
         public function afterLogin() {
             $message = $this->Users->find('new_message');

en/core-libraries/time.rst

@@ -12,7 +12,10 @@ use the ``Time`` class::
 
     class UsersController extends AppController {
 
-        public $components = ['Auth'];
+        public function initialize() {
+            parent::initialize();
+            $this->loadComponent('Auth');
+        }
 
         public function afterLogin() {
             $time = new Time($this->Auth->user('date_of_birth'));

en/development/rest.rst

@@ -27,7 +27,10 @@ this::
     // src/Controller/RecipesController.php
     class RecipesController extends AppController {
 
-        public $components = ['RequestHandler'];
+        public function initialize() {
+            parent::initialize();
+            $this->loadComponent('RequestHandler');
+        }
 
         public function index() {
             $recipes = $this->Recipes->find('all');