README

This plugin is full of handly stuff

Installation

You can install this plugin into your CakePHP application using composer.

The recommended way to install composer packages is:

composer require 3xw/cakephp-utils

In src/Application.php

use Cake\Http\BaseApplication;
...

class Application extends BaseApplication {

	...

  public function bootstrap()
  {
    parent::bootstrap();
    this->addPlugin('Trois/Utils', ['routes' => true]);
  }
	..
}

ORM

Behaviors

Sluggable Behavior
Translate Behavior

Rules

IsUniqueTranslationRule

Associations

MinMaxAssocationTrait

namespace App\Model\Table
use Trois\Utils\ORM\Traits\MinMaxAssocationTrait;

class SubscriptionsTable extends Table
{
	use MinMaxAssocationTrait;

	public function initialize(array $config)
	{
		...

		// custom Association
    	$this->belongsToMinMax('MinPeriodes', [
      'type' => 'MIN',
      'field' => 'date',
      'className' => 'Periodes',
      'foreignKey' => 'subscription_id',
      'targetForeignKey' => 'periode_id',
      'joinTable' => 'subscriptions_periodes',
      'joinType' => 'LEFT'
			'joinAlias' => 'SP', // extra stuff: define yourself join alias
      'joinExtraConditions' => ['SP.was_present' => true] // extra stuff: add conditions on join clause
    ]);
	}
}

// OR
namespace App\Model\Table
use Trois\Utils\ORM\Traits\MinMaxAssocationTrait;

class LessonsTable extends Table
{
	use MinMaxAssocationTrait;

	public function initialize(array $config)
	{
		...

		// custom Association
    	$this->hasOneMinMax('MinPeriode', [
      'type' => 'MIN',
      'field' => 'date',
      'className' => 'Periodes',
      'foreignKey' => 'lesson_id',
      'joinType' => 'LEFT'
    ]);
	}
}

Shell

MissingTranslations
Token

MissingTranslations

tu_miss_i18n $model, ...$locales

Token

ut_token username

View

LngSwitchCell

Security

GUARD Component

This component allows you to check constructed request object and clean it if needed...

in your src/Controller/AppController.php add following:

public function initialize()
{
    parent::initialize();

    ...

    // Auth
    $this->loadComponent('Auth', [...]);

    // Guard
    $this->loadComponent('Trois/Utils.Guard',[
      'autoload_configs' => [
        'Guard.requestBody' => 'guard_request_body'
      ]
    ]);

    ...
}

in config/guard_request_body.php

	<?php
	use Cake\Http\ServerRequest;

	return [
	  'Guard.requestBody' => [
	    [
	      'role' => '*',
	      'prefix' => 'Book',
	      'controller' => ['Users','Subscriptions'],
	      'action' => ['register','registerAndBook'],
	      'method' => ['POST','PUT'],
	      'rule' => function($user, $role, ServerRequest $request)
	      {
	        // magic here... manipulate request here
	      }
	    ],
	]];

CORS Middleware

in your src/Application.php add following:

use Trois\Utils\Middleware\CorsMiddleware;
...
public function middleware($middlewareQueue)
{
	$middlewareQueue
	->add(new CorsMiddleware::class)

	/* -- OR  -- */
	->add(new CorsMiddleware([

		// thoses are default options
	    'all' => [
	      'Access-Control-Allow-Origin' => '*',
	      'Access-Control-Allow-Credentials' => 'true',
	      'Access-Control-Expose-Headers' => 'X-Token',
	      'Access-Control-Max-Age' => '86400'
	    ],
	    'options' => [
	      'methods' => 'GET, POST, OPTIONS, PUT, DELETE'
	    ]

  	]))

	...
}

Auth tools

Config example:

config/bootsrap.php

Configure::load('auth', 'default');

src/Controller/Appcontroller.php

$this->loadComponent('Auth', Configure::read('Auth.V2'));

config/auth.php

<?php
use Cake\Core\Configure;

return [
  'Auth.V2' => [

    'loginAction' => false,
    'unauthorizedRedirect' => false,
    'checkAuthIn' => 'Controller.initialize' ,

    // Authenticate
    'authenticate' => [

      // map role
      'all' => ['finder' => 'Auth'],

      // Legacy X-API-TOKEN header token
      'Trois/Utils.LegacyToken' => [
        'key' => Configure::read('Legacy.key'),
        'salt' => Configure::read('Legacy.salt')
      ],

      // with Bearer JWT token
      'Trois\Utils\Auth\JwtBearerAuthenticate' => [
        'duration' => 3600
      ],

      // Basic username + pass
      'Trois\Utils\Auth\BasicToJwtBearerAuthenticate' => [
        'fields' => ['username' => 'username'],
        'passwordHasher' => 'Trois\Utils\Auth\LegacyPasswordHasher',
      ],
    ],

    // Cache Storage Engine
    'storage' => [
      'className' => 'Trois\Utils\Auth\Storage\CacheStorage',
      'cache' => 'token'
    ],

    // Authorize
    'authorize' => [
      'CakeDC/Auth.SimpleRbac' => [
        'autoload_config' => 'permissions',
      ],
    ],
  ]
];

Two factor Auth

set up Auth:

  'Trois\Utils\Auth\TwoFactorAuthenticate' => [
    'userModel' => 'ExtranetUsers',
    'passwordHasher' => 'App\Auth\NoHasher',
    'fields' => [
      'username' => 'CLIENT_ID',
      'password' => 'Password'
    ],
    'transmitter' => [
      'class' => '\Trois\Utils\Auth\TwoFactor\EmailCodeTransmitter', // any child of Trois\Utils\Auth\TwoFactor\AbstractCodeTransmitter
      'config' => [
        'messages' => [
          'success' => 'Un email avec un code vous a été envoyé',
          'error' => 'L\'application n\'a pas pu vous envoyer de mail. Veuillez essayer à nouveau.'
        ],
        'email' => [
          'field' => 'Email',
          'profile' => 'default',
          'from' => ['info@xxx' => 'Site xxx'],
          'subject' => 'Votre code personnel',
          'emailFormat' => 'both',
          'template' => 'Trois/Utils.default',
          'layout' => 'default',
        ]
      ]
    ],
    'verifyAction' => [
      'prefix' => 'extranet',
      'controller' => 'ExtranetUsers',
      'action' => 'verify',
      'plugin' => false
    ],
  ],

Cache

cache settings

in config folder create a cache.php file with as exemple:

<?php
return [
	'Trois.cache.settings' => [
		'default' => 'default', // default cache config to use if not set in rules...
	],
	'Trois.cache.rules' => [

		// cache request
		[
		  'cache' => 'html', // default: 'default', can be a fct($request)
		  'skip' => false, // default: false, can be a fct($request)
		  'clear' => false, // default: false, can be a fct($request)
		  'compress' => true, // default: false, can be a fct($request)
		  //'key' => 'whatEver',// default is fct($request) => return $request->here()
		  'method' => ['GET'],
		  'code' => '200', // must be set or '*' !!!!!
		  'prefix' => '*',
		  'plugin' => '*',
		  'controller' => '*',
		  'action' => '*',
		  'extension' => '*'
		],

		// clear request
		[
		  'cache' => 'html', // default: 'default'
		  'skip' => false, // default: false
		  'clear' => true, // default: false,
		  'key' => '*', // * => Cache::clear(false, cache) (Will clear all keys), 'whatEver' => Cache::delete('whatEver', cache), null => Cache::delete($request->here(), cache)
		  'method' => ['POST','PUT','DELETE'],
		  'code' => ['200','201','202'],
		  'prefix' => '*',
		  'plugin' => '*',
		  'controller' => ['Users','Pages'],
		  'action' => '*',
		  'extension' => '*'
		],
  	]
];

Cache as your last middleware

in your src/Application.php file add the middleware as last chain block. This will create or delete view renders as cache ( html/json /etc...)

<?php
namespace App;
...
use Trois\Utils\Middleware\ResponseCacheMiddleware;

class Application extends BaseApplication
{
    public function middleware($middleware)
    {
        $middleware
			...
            // Apply Response caching
            ->add(ResponseCacheMiddleware::class);

        return $middleware;
    }
}

Retrieve cache via ActionCacheComponent

in your AppController load the component AFTER Auth!!

$this->loadComponent('Awallef/Cache.ActionCache');

Retrieve cache via Nginx

First install nginx redis extension. Then set your cache config to store in redis. You can use my plugin...

composer require awallef/cakephp-redis

Configure the engine in app.php like follow:

'Cache' => [
	...
	'redis' => [
		'className' => 'Trois/Utils.Redis',
		'prefix' => 'hello.com:',
		'duration' => '+24 hours',
		'serialize' => true
	],
	...
]

Configure cache.php like follow:

return [
		'Trois.cache.settings' => [
			'default' => 'redis', // default cache config to use if not set in rules...
		],
	'Trois.cache.rules' => [

		// cache request
		[
			'skip' => false, // default: false, can be a fct($request)
			'clear' => false, // default: false, can be a fct($request)
			'compress' => true, // default: false, can be a fct($request)
			//'key' => 'whatEver',// default is fct($request) => return $request->here()
			'method' => ['GET'],
			'code' => '200', // must be set or '*' !!!!!
			'prefix' => '*',
			'plugin' => '*',
			'controller' => '*',
			'action' => '*',
			'extension' => '*'
		],

		// clear request
		[
	      'clear' => true,
	      'key' => '*',
	      'method' => ['POST','PUT','DELETE'],
		  'code' => ['200','201','202','302'], // 302 is often triggered by cakephp in case of success crud operation...
		  'prefix' => '*',
		  'plugin' => '*',
		  'controller' => '*',
		  'action' => '*',
		  'extension' => '*'
		],
	]
];

Configure Nginx too:

map $http_accept $hello_com_response_header {
	default   "text/html; charset=UTF-8";
	"~*json"  "application/json; charset=UTF-8";
}
server {
	listen 443;
	server_name hello.com;

	ssl on;
	...

	# redis key
	set $redis_key  "hello.com:$request_uri";
	if ($args) {
		set $redis_key  "hello.com:$request_uri?$args";
	}

	location / {
		redis_pass 127.0.0.1:6379;
		error_page 404 405 502 504 = @fallback;
		more_set_headers "Content-Type: $hello_com_response_header";
	}

	#default cake handling
	location @fallback {
		try_files $uri $uri/ /index.php?$args;
	}

	location ~ \.php$ {
		try_files $uri =404;
		include /etc/nginx/fastcgi_params;
		fastcgi_intercept_errors on;
		fastcgi_pass unix:/var/run/php/php7.1-fpm.sock;
		fastcgi_index   index.php;
		fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
	}

}

Redis caching

This plugin provides a very little bit different redis engine based on cakephp's RedisEngine. differences are:

Engine config comes with a bool 'serialize' option ( default is true )
Read and wirte fct use config 'serialize' option
Keys are stored/read/deleted in order to uses : and :* redis skills!