Components¶

Configuring Components¶

Many of the core components require configuration. One example would be the Form Protection Component. Configuration for these components, and for components in general, is usually done via loadComponent() in your Controller’s initialize() method or via the $components array:

class PostsController extends AppController
{
    public function initialize(): void
    {
        parent::initialize();
        $this->loadComponent('FormProtection', [
            'unlockedActions' => ['index'],
        ]);
        $this->loadComponent('Flash');
    }
}

You can configure components at runtime using the setConfig() method. Often, this is done in your controller’s beforeFilter() method. The above could also be expressed as:

public function beforeFilter(EventInterface $event)
{
    $this->FormProtection->setConfig('unlockedActions', ['index']);
}

Like helpers, components implement getConfig() and setConfig() methods to read and write configuration data:

// Read config data.
$this->FormProtection->getConfig('unlockedActions');

// Set config
$this->Flash->setConfig('key', 'myFlash');

As with helpers, components will automatically merge their $_defaultConfig property with constructor configuration to create the $_config property which is accessible with getConfig() and setConfig().

// src/Controller/PostsController.php
class PostsController extends AppController
{
    public function initialize(): void
    {
        $this->loadComponent('Flash', [
            'className' => 'MyFlash',
        ]);
    }
}

// src/Controller/Component/MyFlashComponent.php
use Cake\Controller\Component\FlashComponent;

class MyFlashComponent extends FlashComponent
{
    // Add your code to override the core FlashComponent
}

// In a controller action
$this->loadComponent('OneTimer');
$time = $this->OneTimer->getTime();

Using Components¶

Once you’ve included some components in your controller, using them is pretty simple. Each component you use is exposed as a property on your controller. If you had loaded up the Cake\Controller\Component\FlashComponent in your controller, you could access it like so:

class PostsController extends AppController
{
    public function initialize(): void
    {
        parent::initialize();
        $this->loadComponent('Flash');
    }

    public function delete()
    {
        if ($this->Post->delete($this->request->getData('Post.id')) {
            $this->Flash->success('Post deleted.');

            return $this->redirect(['action' => 'index']);
        }
    }

Creating a Component¶

Suppose our application needs to perform a complex mathematical operation in many different parts of the application. We could create a component to house this shared logic for use in many different controllers.

The first step is to create a new component file and class. Create the file in src/Controller/Component/MathComponent.php. The basic structure for the component would look something like this:

namespace App\Controller\Component;

use Cake\Controller\Component;

class MathComponent extends Component
{
    public function doComplexOperation($amount1, $amount2)
    {
        return $amount1 + $amount2;
    }
}

Components can use Dependency Injection to receive services as constructor parameters:

namespace App\Controller\Component;

use Cake\Controller\Component;
use App\Service\UserService;

class SsoComponent extends Component
{
    public function __construct(
        ComponentRegistry $registry,
        array $config = [],
        UserService $users
    ) {
        parent::__construct($registry, $config);
        $this->users = $users;
    }
}

// In a controller
// Make the new component available at $this->Math,
// as well as the standard $this->Flash
public function initialize(): void
{
    parent::initialize();
    $this->loadComponent('Math');
    $this->loadComponent('Flash');
}

// In your controller.
public function initialize(): void
{
    parent::initialize();
    $this->loadComponent('Math', [
        'precision' => 2,
        'randomGenerator' => 'srand',
    ]);
    $this->loadComponent('Flash');
}

// src/Controller/Component/CustomComponent.php
namespace App\Controller\Component;

use Cake\Controller\Component;

class CustomComponent extends Component
{
    // The other component your component uses
    protected array $components = ['Existing'];

    // Execute any other additional setup for your component.
    public function initialize(array $config): void
    {
        $this->Existing->foo();
    }

    public function bar()
    {
        // ...
    }
}

// src/Controller/Component/ExistingComponent.php
namespace App\Controller\Component;

use Cake\Controller\Component;

class ExistingComponent extends Component
{
    public function foo()
    {
        // ...
    }
}

$controller = $this->getController();

Component Callbacks¶

Components also offer a few request life-cycle callbacks that allow them to augment the request cycle.

beforeFilter(EventInterface $event)¶

Is called before the controller’s beforeFilter() method, but after the controller’s initialize() method.

startup(EventInterface $event)¶

Is called after the controller’s beforeFilter() method but before the controller executes the current action handler.

beforeRender(EventInterface $event)¶

Is called after the controller executes the requested action’s logic, but before the controller renders views and layout.

afterFilter(EventInterface $event)¶

Is called during the Controller.shutdown event, before output is sent to the browser.

beforeRedirect(EventInterface $event, $url, Response $response)¶

Is invoked when the controller’s redirect method is called but before any further action. If this method returns false the controller will not continue on to redirect the request. The $url, and $response parameters allow you to inspect and modify the location or any other headers in the response.

Using Redirects in Component Events¶

To redirect from within a component callback method you can use the following:

public function beforeFilter(EventInterface $event)
{
    $event->stopPropagation();

    return $this->getController()->redirect('/');
}

By stopping the event you let CakePHP know that you don’t want any other component callbacks to run, and that the controller should not handle the action any further. As of 4.1.0 you can raise a RedirectException to signal a redirect:

use Cake\Http\Exception\RedirectException;
use Cake\Routing\Router;

public function beforeFilter(EventInterface $event)
{
    throw new RedirectException(Router::url('/'))
}

Raising an exception will halt all other event listeners and create a new response that doesn’t retain or inherit any of the current response’s headers. When raising a RedirectException you can include additional headers:

throw new RedirectException(Router::url('/'), 302, [
    'Header-Key' => 'value',
]);