mirko-pagliai/cakephp-essentials

cakephp-essentials

1.0.23 2026-02-18 18:59 UTC

Requires

• php: >=8.4
• axllent/jquery: ~3.7
• cakephp/cakephp: ^5.2
• friendsofcake/bootstrap-ui: ^5.1.1
• symfony/filesystem: ^7.3
• twbs/bootstrap: ~5.3
• twbs/bootstrap-icons: ^1.11

Requires (Dev)

• cakedc/cakephp-phpstan: ^4.0
• cakephp/authentication: ^3.2
• cakephp/authorization: ^3.0
• cakephp/cakephp-codesniffer: ^5.0
• mockery/mockery: ^1.6
• phpunit/phpunit: ^12.5.8 || ^13.0

MIT

• Mirko Pagliai

README

Various classes and useful utilities for various CakePHP projects.

• Global functions
• Request detectors
• Extends the View
• Using Tooltips and Popovers
• How to use Bake templates

Global functions

rtr()

rtr() is an acronym for "relative to root."

Returns a path relative to ROOT, useful for some output (e.g., commands).

For example:

rtr(ROOT . 'webroot/assets')

returns webroot/assets.

The function preserves any trailing slashes and throws exceptions for invalid paths (e.g. not relative to ROOT or not absolute).

toDate() and toDateTime()

These two functions ensure they always return a valid Date or DateTime instance.

They are useful when a variable may already be a valid instance or an argument to create an instance and allow you to avoid this:

if (!$dateTime instanceof DateTime) {
    $dateTime = new DateTime($dateTime);
}

//or

$date = $date instanceof Date ? $date : new Date($date);

simply by doing this:

$dateTime = toDateTime($dateTime);

//or

$date = toDate($date);

Request detectors

This plugin provides several very useful request detectors.

is('action') detector

Checks if $action matches the current action.

The $action argument can be a string or an array of strings. In the second case, it is enough that the action matches one of those.

Example:

$this->getRequest()->is('action', 'delete')

returns true if the current action is delete, otherwise false.

Example:

$this->getRequest()->isAction('action', 'edit', 'delete')

returns true if the current action is edit or delete, otherwise false.

Other "action detectors": is('add'), is('edit'), is('view'), is('index'), is('delete')

These are quick aliases for is('action') detectors.

Example:

$this->getRequest()->is('delete')

returns true if the current action is delete, otherwise false.

is('ip') detector

Checks whether the current client IP matches the IP or one of the IPs passed as an argument.

Example:

$this->getRequest()->is('ip', '99.99.99.99')

returns true if the current client IP is 99.99.99.99, otherwise false.

Example:

$this->getRequest()->isAction('ip', ['99.99.99.99', '11.11.11.11']);

returns true if the current client IP is 99.99.99.99 or 11.11.11.11, otherwise false.

is('localhost') detector

This is a quick alias for is('ip') detector.

Returns true if the current client IP matches localhost.

is('trustedClient') detector

This is a quick alias for is('ip') detector.

Returns true if it is a trusted client.

Before using this detector, you should write trusted clients into the configuration.

For example, in your bootstrap.php file,

Configure::write('trustedIpAddress', ['45.46.47.48', '192.168.0.100']);

At this point,

$this->getRequest()->isAction('trustedClient')

returns true if the current client IP matches one of these.

Extends the View

use Cake\Essentials\View\View;

class AppView extends View
{
}

If necessary, you can rewrite the default helpers by implementing the initialize() method and calling parent::initialize() before adding your own helpers.

class AppView extends View
    public function initialize(): void
    {
        parent::initialize();
    
        /**
         * These override any helpers defined by the parent.
         */
        $this->addHelper('Html');
        $this->addHelper('Form');
    }
}

Using Tooltips and Popovers

Several helper methods support tooltips and popovers and can generate them automatically.

Please refer to the Bootstrap documentation before using them (here and here).

Keep in mind that:

1. both depend on the third-party library Popper, which you need to include, or you can use bootstrap.bundle.min.js which contains Popper;
2. you will need to initialize both, as indicated in the documentation.
   You can include webroot/js/enable-popovers.js and webroot/js/enable-tooltips.js files in yourt layout, which will do it automatically:

echo $this->Html->script('/cake/essentials/js/enable-popovers.js');
echo $this->Html->script('/cake/essentials/js/enable-tooltips.js');

How to use Bake templates

In your config/bootstrap.php file:

Configure::write('Bake.theme', 'Cake/Essentials');

Or you can use the --theme option (or --t) with Cake/Essentials value.
Example:

bin/cake bake template ServiceStops -t Cake/Essentials -f

See also CakePHP Bake 2.x Cookbook.