Download the PHP package ali1/cakephp-json-tools without Composer

CakePHP Json Tools Plugin

A CakePHP plugin to assist with creating Json responses from controllers.

Json Tools has been created to be used by traditional CakePHP projects which are mostly browser-based, but have a few AJAX or API methods. The Json Tools component makes creating these a breeze.

Features

• A component that quickly lets you set up ajax methods.
• Works with CakePHP's JsonView so you don't have to
• Can be used in methods that sometimes output Html and other times Json depending on request headers, just like normal CakePHP behavior
• Adds optional debug context to JSON errors for authenticated Cake session users

Requirements

• Composer
• CakePHP 5.0+
• PHP 8.2+

Upgrading to 6.0.0 (breaking changes)

6.0.0 contains no new features. It applies the full coding standard to the published API. Two sniffs that were previously excluded because satisfying them breaks backward compatibility are now enforced, so the trait name and five method signatures below have changed.

1. The Route trait is now RouteTrait

JsonTools\Model\Entity\Traits\Route has been renamed to JsonTools\Model\Entity\Traits\RouteTrait, and its file moved from src/Model/Entity/Traits/Route.php to src/Model/Entity/Traits/RouteTrait.php. Behaviour is unchanged. Any entity that uses the trait must update its import, or it will fatal with "Trait not found".

Before:

After:

If you aliased the import (use ... Route as SomethingElse;) only the imported class name changes; the alias can stay.

2. Five JsonComponent methods now have native parameter types

These methods were previously untyped, with the accepted types documented only in their @param docblocks. The native types are now declared, so passing anything outside them throws a TypeError instead of failing later (or silently) inside the method.

EntityInterface is \Cake\Datasource\EntityInterface and Form is \Cake\Form\Form.

What now throws TypeError that previously did not:

• redirect() — anything that is not an array, string, or null. Router::url() was already the effective constraint, so this mostly surfaces bad input earlier.
• sendContent() — a non-string, non-null template, such as an object without __toString() or an array.
• set() — a $name that is neither a string nor an array.
• entityErrorVars() — anything that is not an entity or a Form, including a plain array. generateErrorMessage() accepts arrays but entityErrorVars() never did: it called $entity->getErrors() unconditionally, so an array previously failed with "Call to a member function getErrors() on array". That failure is now a TypeError at the call boundary.
• generateErrorMessage() — see the behaviour change below.

Scalar coercion follows PHP's normal rule: strictness is decided by the file making the call, not by this plugin. If your calling file does not declare strict_types=1, passing 42 to sendContent() or set() still coerces to '42' as before. If it does, that call now throws. Objects, arrays, and null where the type does not allow them throw either way.

3. generateErrorMessage() no longer returns '' for unsupported input

In 5.x, generateErrorMessage() ended with an else branch that returned an empty string for any argument that was not an array, an EntityInterface, or a Form — so generateErrorMessage(null), generateErrorMessage('oops') or generateErrorMessage($someRandomObject) quietly produced '' and the caller carried on.

With the parameter typed as EntityInterface|Form|array, that input is rejected at the call boundary with a TypeError and the branch became unreachable, so it has been removed. If your code relied on passing loosely-typed input and getting an empty string back, guard the call yourself:

An entity or form with no errors still returns '', and an empty array still returns '', exactly as before. Only genuinely unsupported types changed.

Installation

In your CakePHP root directory: run the following command:

Then in your Application.php in your project root, add the following snippet:

or you can use the following shell command to enable to plugin in your bootstrap.php automatically:

Now add it to your src/AppController.php or to specific controllers

Usage (in controller methods that may need to output Json)

Understanding the boiler plate Json output

This component primes JsonView to output something that looks like this:

Which corresponds to a json output of:

Your controller method can then override these keys or add new ones easily using this component.

Priming the method with boiler-plate Json output

Setting the JSON output

Boiler plate output keys (see above) could be overwritten later in your method using one of these methods

Example controller

Example AJAX form

This is an example form that corresponds to the ajaxUpdateUser method above.

templates/Users/edit.php

webroot/ajax_submit.js