CakeDC Blog

TIPS, INSIGHTS AND THE LATEST FROM THE EXPERTS BEHIND CAKEPHP

Introduction to CakeDC Api plugin

Written by Yevgeny on March 30, 2020
12228 VIEWS

 

The CakeDC API plugin was created with the goal to prepare abstract solutions that solve generic tasks -in case of creating a rest API. It provides such features like automatic rest API generation based on db schema, support nested routes. It also allows the use of different formats like json or xml, and easily adds their own custom format. It helps to solve generic tasks appearing in development of any API, like pagination, data validation, adding common data to response, or building metadata, about data objects.

Dependencies

The CakeDC API plugin hardly depends on the CakeDC Users Plugin. For authentication it is highly recommended to use CakePHP Authentication plugin configured as middleware.

Installation

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

The recommended way to install composer packages is:

composer require cakedc/cakephp-api

 

 Load the Plugin

Ensure  The CakeDC API Plugin is loaded in your src/Aplication.php in bootstrap method.

php

    $this->addPlugin(\CakeDC\Users\Plugin::class);

    $this->addPlugin(\CakeDC\Api\Plugin::class, ['bootstrap' => true, 'routes' => true]);

Configuration

Minimal configuration to allow non authorized requests require you to copy file: ./vendor/cakedc/cakephp-api/config/api_permissions.php.default to ./config/api_permissions.php

Examples

Lets bake table blogs with two fields id and name.

After that, the next requests would be possible to perform to api. Requests would be performed using curl.

Request:

curl http://localhost:8765/api/blogs

Response:

{

    "status": "success",

    "data": [

        {

            "id": 1,

            "name": "blog001"

        }

    ],

    "pagination": {

        "page": 1,

        "limit": 20,

        "pages": 1,

        "count": 1

    },

    "links": [

        {

            "name": "self",

            "href": "http:\/\/localhost:8765\/api\/blogs",

            "rel": "\/api\/blogs",

            "method": "GET"

        },

        {

            "name": "blogs:add",

            "href": "http:\/\/localhost:8765\/api\/blogs",

            "rel": "\/api\/blogs",

            "method": "POST"

        }

    ]

}

Request:

curl -d "name=blog001" -H "Content-Type: application/x-www-form-urlencoded" -X POST http://localhost:8765/api/blogs

Response:

{

    "status": "success",

    "data": {

        "name": "blog001",

        "id": 1

    },

    "links": []

}

Request:

curl -d "name=blog002" -H "Content-Type: application/x-www-form-urlencoded" -X PUT http://localhost:8765/api/blogs/1

Response:

{

    "status": "success",

    "data": {

        "id": 1,

        "name": "blog002"

    },

    "links": []

}

Request:

curl -X DELETE http://localhost:8765/api/blogs/1

Response:

{

    "status": "success",

    "data": true,

    "links": []

}

For more complex features about plugin initialization and configuration based on routes middlewares, we plan to create an additional article.

Services and Actions

In the REST recommendations documents names defined as a noun. Here, services come into play.

It describes business entities. From other side actions define the verbs that describe the operations that should be performed on the actions.

Common and difference between controller classes and services.

The common part is the service is the managing the choosing action to execute.

The primary difference is that service could be nested, if this is defined by request url.

Common and difference between controller actions and service actions.

The common part is the action defined logic of the request.

The primary is that each service’s action is defined as a separate class.

This means that generic actions could be defined as common class and reused in many services.

From the other side, an action class is able to extend if the system has slightly different actions.

This way it is possible to build actions hierarchy.

Both service and actions define an event during this execution flow. 

Main service events:

* Service.beforeDispatch

* Service.beforeProcess

* Service.afterDispatch

Main action events:

* Action.beforeProcess

* Action.onAuth

* Action.beforeValidate

* Action.beforeValidateStopped

* Action.validationFailed

* Action.beforeExecute

* Action.beforeExecuteStopped

* Action.afterProcess

Crud actions define events that depend on the type of action, and more details could be checked in documentation.

* Action.Crud.onPatchEntity

* Action.Crud.onFindEntities

* Action.Crud.afterFindEntities 

* Action.Crud.onFindEntity

Nested services

Consider we have request with method POST /blogs/1/posts with data like {"title": "...", "body": "..."}

As it is possible to see there is nothing in the given data about the blog_id to which the newly created post should belong to.

In the case of controllers we should define custom logic to parse a route, and to consume the blog_id from url.

For nested service all checks and records updates are automatically executed. This will happen for any crud operations, when detected by the route parent service. So for example: GET /blogs/1/posts, will return only posts for the blog with id 1.

Logical checks are also performed, so for request: DELETE /blogs/1/posts/2, a user gets an error if the post with id 2 belongs to the blog with id 2.

Action inheritance

As each action can be defined as a separate class, it is possible to use class inheritance to define common logic. For example:  Add and Edit actions.

Extending services and actions with shared functionality

The alternative way for defining common logic actions is using action extensions. Action extension is a more powerful feature and could be used for global tasks like search or pagination.

It is also possible to create service level extensions. Those extensions work on the top level of the execution process, and could be used for things like adding cors feature, or to append some counter into response.

Add service actions from service::initialize

This is a recommended way to register non crud actions. The mapAction uses the Router class syntax for parsing routes. So on any special use cases well described in cakephp core.

    public function initialize()

    {

        parent::initialize();

        $this->mapAction('view_edit', ViewEditAction::class, [

            'method' => ['GET'],

            'path' => 'view_edit/:id'

        ]);

    }

Configure actions using action class map.

Each action class uses $_actionsClassMap for defining a map between crud (and non crud) actions on the name of the action class.

Non crud actions should be additionally mapped, which is described in the previous step.

use App\Service\Protocols\IndexAction;

class ProtocolsService extends AppFallbackService

{

    /**

     * Actions classes map.

     *

     * @var array

     */

    protected $_actionsClassMap = [

        'index' => IndexAction::class,

    ];

} 

Configure service and action in config file

Service options are defined in the config/api.php in Api.Service section.

Let's consider configuration options for ArticlesService.

Configuration are hierarchical in the next sense: 

  • define default options for any service within the application in the Api.Service.default.options section.
  • define options for any service within the application in Api.Service.articles.options section.

All defined options are overridden from up to down in described order.

This allows common service settings, and the ability to overwrite them in bottom level.

  •  Api.Service.classMap - defines name map, that allows defining services action classes with custom location logic.
    Any action, that could be loaded as default action defined in fallback class, or specific action class could be configured using configuration file.
    Let's consider how one can configure options for IndexAction of ArticlesService.
    Configuration are hierarchical in the next sense: 
  • one can define default options for any action for all services in the application in the Api.Service.default.Action.default section.
  • one can define default options for index action for all services in the application in the Api.Service.default.Action.index section.
  • one can define options for any action in the specific (articles) service in the Api.Service.articles.Action.default section.
  • one can define options for index action in the specific (articles) service in the  Api.Service.articles.Action.index section.

Crud and non crud methods. Mapping non-crud actions.

Crud services mapped automatically in two levels routing by FallbackService.

Index and view. Formatting output

The CakeDC Api Plugin is flexible and provides multiple ways to prepare result data for the response objects.

There is a list of main options.

Use Entity serialization

The most trivial way to convert data is using entity serialization.

When converting an entity to a JSON, the virtual and hidden field lists are applied. 

Entities are recursively converted to JSON as well. 

This means that if you eager, and loading entities and their associations, CakePHP will correctly handle converting the associated data into the correct format.

Additional fields could be defined using Entity::$_virtual and hidden using Entity::$$_hidden.

Build object manually from Action::execute

In this case users manually perform mapping of requests received from model layer to output array.

public function process()

{

    $entity = $this->getTable()->get($this->getId());

    return [

        'id' => $entity->id,

        'name' => $entity->name,

    ];

}

Use Query::formatResults in model layer

The request could be formatted in model layer using: Query::formatResults.

So in this case, the process action just calls for a needed finder from the model layer and returns the result.

public function findApiFormat(Query $query, array $options)

{

    return $query

        ->select(['id', 'body', 'created', 'modified', 'author_id'])

        ->formatResults(function ($results) use ($options) {

            return $results->map(function ($row) use ($options) {

                $row['author'] = $this->Authors->getFormatted($row['author_id']);

                unset($row['author_id']);

 

                return $row;

            });

        });

} 

Use Action extensions to format output

In index action defined callback Action.Crud.afterFindEntities, which called after data fetched,  could be used to extend or overload results coming from the database.

Callbacks are catch-in-action extensions and could be applied to multiple endpoints.

For view action defined Action.Crud.afterFindEntity, which called after single record fetched.

Use Action extensions to append additional data to output

Sometimes there is some additional information needed to be presented in some group of endpoints. In this case it is possible to implement an action extension to append additional data.

For example, pagination provides information about number of pages, records count, and current page number.

Another example for additional data is some execution statistics about the query.

Here you see main parts of appending such data from extension.

class PaginateExtension extends Extension implements EventListenerInterface

{

    public function implementedEvents(): array

    {

        return [

            'Action.Crud.afterFindEntities' => 'afterFind',

        ];

    }

...

    public function afterFind(EventInterface $event): void

    {

        ...

        $pagination = [

            'page' => $this->_page($action),

            'limit' => $limit,

            'pages' => ceil($count / $limit),

            'count' => $count,

        ];

        $result->appendPayload('pagination', $pagination);

    }  

 

The renderer class describes how to handle payload data.

For example in JSend renderer, all payload records appended to the root of the resulting json object.

Rendering output. Renderers.

Renderers perform final mapping of response records to output format. 

Such formats like xml, json, or file are provided by  The CakeDC API plugin.

JSend is the json extension with some additional agreements about returning results.

 

 

Latest articles

15 Views

The new CakePHP RateLimitMiddleware

This article is part of the CakeDC Advent Calendar 2025 (December 21st 2025) Rate limiting a specific endpoint of your application can be a life saver. Sometimes you can't optimize the endpoint and it'll be expensive in time or CPU, or the endpoint has a business restriction for a given user. In the past, I've been using https://github.com/UseMuffin/Throttle a number of times to provide rate limiting features to CakePHP. Recently, I've been watching the addition of the RateLimitMiddleware to CakePHP 5.3, I think it was a great idea to incorporate these features into the core and I'll bring you a quick example about how to use it in your projects. Let's imagine you have a CakePHP application with an export feature that will take some extra CPU to produce an output, you want to ensure the endpoint is not abused by your users. In order to limit the access to the endpoint, add the following configuration to your config/app.php // define a cache configuration, Redis could be a good option for a fast and distributed approach 'rate_limit' => [ 'className' => \Cake\Cache\Engine\RedisEngine::class, 'path' => CACHE, 'url' => env('CACHE_RATE_LIMIT_URL', null), ], Then, in your src/Application.php middleware method, create one or many configurations for your rate limits. The middleware allows a lot of customization, for example to select the strategy, or how are you going to identify the owner of the rate limit. ->add(new RateLimitMiddleware([ 'strategy' => RateLimitMiddleware::STRATEGY_FIXED_WINDOW, 'identifier' => RateLimitMiddleware::IDENTIFIER_IP, 'limit' => 5, 'window' => 10, 'cache' => 'rate_limit', 'skipCheck' => function ($request) { return !( $request->getParam('controller') === 'Reports' && $request->getParam('action') === 'index' ); } ])) In this particular configuration we are going to limit the access to the /reports/index endpoint (we skip everything else) to 5 requests every 10 seconds. You can learn more about the middleware configuration here https://github.com/cakephp/docs/pull/8063 while the final documentation is being finished. This article is part of the CakeDC Advent Calendar 2025 (December 21st 2025)

Written by Jorge on December 21, 2025

56 Views

Real-Time Notifications? You Might Not Need WebSockets

This article is part of the CakeDC Advent Calendar 2025 (December 20th 2025) As PHP developers, when we hear "real-time," our minds immediately jump to WebSockets. We think of complex setups with Ratchet, long-running server processes, and tricky Nginx proxy configurations. And for many applications (like live chats or collaborative editing) WebSockets are absolutely the right tool. But, if you don't need all that complexity or if you just want to push data from your server to the client? Think of a new notification, a "users online" counter, or a live dashboard update. For these one-way-street use cases, WebSockets are often overkill. Enter Server-Sent Events (SSE). It's a simple, elegant, and surprisingly powerful W3C standard that lets your server stream updates to a client over a single, long-lasting HTTP connection.

SSE vs. WebSockets: The Showdown

The most important difference is direction.
  • WebSockets (WS): Bidirectional. The client and server can both send messages to each other at any time. It's a two-way conversation.
  • Server-Sent Events (SSE): Unidirectional. Only the server can send messages to the client. It's a one-way broadcast.
This single difference has massive implications for simplicity and implementation.
Feature Server-Sent Events (SSE) WebSockets (WS)
Direction Unidirectional (Server ➔ Client) Bidirectional (Client ⟺ Server)
Protocol Just plain HTTP/S A new protocol (ws://, wss://)
Simplicity High. simple API, complex ops at scale Low. Requires a special server.
Reconnection Automatic! The browser handles it. Manual. You must write JS to reconnect.
Browser API Native EventSource object. Native WebSocket object.
Best For Notifications, dashboards, live feeds. Live chats, multiplayer games, co-editing.
Pros for SSE:
  • It's just HTTP. No new protocol, no special ports.
  • Automatic reconnection is a life-saver.
  • The server-side implementation can be a simple controller action.
Cons for SSE:
  • Strictly one-way. The client can't send data back on the same connection.
  • Some older proxies or servers might buffer the response, which can be tricky.
Infrastructure Note: Since SSE keeps a persistent connection open, each active client will occupy one PHP-FPM worker. For high-traffic applications, ensure your server is configured to handle the concurrent load or consider a non-blocking server like RoadRunner. Additionally, using HTTP/2 is strongly recommended to bypass the 6-connection-per-domain limit found in older HTTP/1.1 protocols

The Implementation: A Smart, Reusable SSE System in CakePHP

We're not going to build a naive while(true) loop that hammers our database every 2 seconds. That's inefficient. Instead, we'll build an event-driven system. The while(true) loop will only check a cache key. This is lightning-fast. A separate "trigger" class will update that cache key's timestamp only when a new notification is actually created. This design is clean, decoupled, and highly performant.
Note: This example uses CakePHP, but the principles (a component, a trigger, and a controller) can be adapted to any framework like Laravel or Symfony.

1. The Explicit SseTrigger Class

First, we need a clean, obvious way to "poke" our SSE stream. We'll create a simple class whose only job is to update a cache timestamp. This is far better than a "magic" Cache::write() call hidden in a model. src/Sse/SseTrigger.php <?php namespace App\Sse; use Cake\Cache\Cache; /** * Provides an explicit, static method to "push" an SSE event. * This simply updates a cache key's timestamp, which the * SseComponent is watching. */ class SseTrigger { /** * Pushes an update for a given SSE cache key. * * @param string $cacheKey The key to "touch". * @return bool */ public static function push(string $cacheKey): bool { // We just write the current time. The content doesn't // matter, only the timestamp. return Cache::write($cacheKey, microtime(true)); } }

CRITICAL PERFORMANCE WARNING: The PHP-FPM Bottleneck

In a standard PHP-FPM environment, each SSE connection is synchronous and blocking. This means one active SSE stream = one locked PHP-FPM worker. If your max_children setting is 50, and 50 users open your dashboard, your entire website will stop responding because there are no workers left to handle regular requests. How to mitigate this: Dedicated Pool: Set up a separate PHP-FPM pool specifically for SSE requests. Go Asynchronous: Use a non-blocking server like RoadRunner, Swoole or FrankenPHP. These can handle thousands of concurrent SSE connections with minimal memory footprint. HTTP/2: Always serve SSE over HTTP/2 to bypass the browser's 6-connection limit per domain.

2. The SseComponent (The Engine)

This component encapsulates all the SSE logic. It handles the loop, the cache-checking, the CallbackStream, and even building the final Response object. The controller will be left perfectly clean. To handle the stream, we utilize CakePHP's CallbackStream. Unlike a standard response that sends all data at once, CallbackStream allows us to emit data in chunks over time. It wraps our while(true) loop into a PSR-7 compliant stream, enabling the server to push updates to the browser as they happen without terminating the request. src/Controller/Component/SseComponent.php <?php namespace App\Controller\Component; use Cake\Controller\Component; use Cake\Http\CallbackStream; use Cake\Cache\Cache; use Cake\Http\Response; class SseComponent extends Component { protected $_defaultConfig = [ 'poll' => 2, // How often to check the cache (in seconds) 'eventName' => 'message', // Default SSE event name 'heartbeat' => 30, // Keep-alive to prevent proxy timeouts ]; /** * Main public method. * Builds the stream and returns a fully configured Response. */ public function stream(callable $dataCallback, string $watchCacheKey, array $options = []): Response { $stream = $this->_buildStream($dataCallback, $watchCacheKey, $options); // Get and configure the controller's response $response = $this->getController()->getResponse(); $response = $response ->withHeader('Content-Type', 'text/event-stream') ->withHeader('Cache-Control', 'no-cache') ->withHeader('Connection', 'keep-alive') ->withHeader('X-Accel-Buffering', 'no') // For Nginx: disable response buffering ->withBody($stream); return $response; } /** * Protected method to build the actual CallbackStream. */ protected function _buildStream(callable $dataCallback, string $watchCacheKey, array $options = []): CallbackStream { $config = $this->getConfig() + $options; return new CallbackStream(function () use ($dataCallback, $watchCacheKey, $config) { set_time_limit(0); $lastSentTimestamp = null; $lastHeartbeat = time(); while (true) { if (connection_aborted()) { break; } // 1. THE FAST CHECK: Read the cache. $currentTimestamp = Cache::read($watchCacheKey); // 2. THE COMPARE: Has it been updated? if ($currentTimestamp > $lastSentTimestamp) { // 3. THE SLOW CHECK: Cache is new, so run the data callback. $data = $dataCallback(); // 4. THE PUSH: Send the data. echo "event: " . $config['eventName'] . "\n"; echo "data: " . json_encode($data) . "\n\n"; $lastSentTimestamp = $currentTimestamp; $lastHeartbeat = time(); } else if (time() - $lastHeartbeat > $config['heartbeat']) { // 5. THE HEARTBEAT: Send a comment to keep connection alive. echo ": \n\n"; $lastHeartbeat = time(); } if (ob_get_level() > 0) { ob_flush(); } flush(); // Wait before the next check sleep($config['poll']); } }); } }

3. Connecting the Logic (Model & Controller)

First, we use our SseTrigger in the afterSave hook of our NotificationsTable. This makes it clear: "After saving a notification, push an update." src/Model/Table/NotificationsTable.php (Partial) use App\Sse\SseTrigger; // Don't forget to import! public function afterSave(EventInterface $event, Entity $entity, ArrayObject $options) { // Check if the entity has a user_id if ($entity->has('user_id') && !empty($entity->user_id)) { // Build the user-specific cache key $userCacheKey = 'notifications_timestamp_user_' . $entity->user_id; // Explicitly trigger the push! SseTrigger::push($userCacheKey); } } Now, our controller action becomes incredibly simple. Its only jobs are to get the current user, define the data callback, and return the component's stream. src/Controller/NotificationsController.php <?php namespace App\Controller; use App\Controller\AppController; use Cake\Http\Exception\ForbiddenException; class NotificationsController extends AppController { public function initialize(): void { parent::initialize(); $this->loadComponent('Sse'); $this->loadComponent('Authentication.Authentication'); } public function stream() { $this->autoRender = false; // 1. Get authenticated user $identity = $this->Authentication->getIdentity(); if (!$identity) { throw new ForbiddenException('Authentication required'); } // 2. Define user-specific parameters $userId = $identity->get('id'); $userCacheKey = 'notifications_timestamp_user_' . $userId; // 3. Define the data callback (what to run when there's an update) $dataCallback = function () use ($userId) { return $this->Notifications->find() ->where(['user_id' => $userId, 'read' => false]) ->order(['created' => 'DESC']) ->limit(5) ->all(); }; // 4. Return the stream. That's it! return $this->Sse->stream( $dataCallback, $userCacheKey, [ 'eventName' => 'new_notification', // Custom event name for JS 'poll' => 2 ] ); } }

4. The Frontend (The Easy Part)

Thanks to the native EventSource API, the client-side JavaScript is trivial. No libraries. No complex connection management. <script> // 1. Point to your controller action const sseUrl = '/notifications/stream'; const eventSource = new EventSource(sseUrl); // 2. Listen for your custom event eventSource.addEventListener('new_notification', (event) => { console.log('New data received!'); const notifications = JSON.parse(event.data); // Do something with the data... // e.g., update a <ul> list or a notification counter updateNotificationBell(notifications); }); // 3. (Optional) Handle errors eventSource.onerror = (error) => { console.error('EventSource failed:', error); // The browser will automatically try to reconnect. }; // (Optional) Handle the initial connection eventSource.onopen = () => { console.log('SSE connection established.'); }; </script>

Ideas for Your Projects

You can use this exact pattern for so much more than just notifications:
  • Live Admin Dashboard: A "Recent Sales" feed or a "Users Online" list that updates automatically.
  • Activity Feeds: Show "John recently commented..." in real-time.
  • Progress Indicators: For a long-running background process (like video encoding), push status updates ("20% complete", "50% complete", etc.).
  • Live Sports Scores: Push new scores as they happen.
  • Stock or Crypto Tickers: Stream new price data from your server.

When NOT to Use SSE: Know Your Limits

While SSE is an elegant solution for many problems, it isn't a silver bullet. You should avoid SSE and stick with WebSockets or standard Polling when:
  • True Bidirectional Communication is Required: If your app involves heavy "back-and-forth" (like a fast-paced multiplayer game or a collaborative whiteboarding tool), WebSockets are the correct choice.
  • Binary Data Streams: SSE is a text-based protocol. If you need to stream raw binary data (like audio or video frames), WebSockets or WebRTC are better suited.
  • Legacy Browser Support (IE11): If you must support older browsers that lack EventSource and you don't want to rely on polyfills, SSE will not work.
  • Strict Connection Limits: If you are on a restricted shared hosting environment with very few PHP-FPM workers and no support for HTTP/2, the persistent nature of SSE will quickly exhaust your server's resources.

Conclusion

WebSockets are a powerful tool, but they aren't the only tool. For the wide array of use cases that only require one-way, server-to-client communication, Server-Sent Events are a simpler, more robust, and more maintainable solution. It integrates perfectly with the standard PHP request cycle, requires no extra daemons, and is handled natively by the browser. So the next time you need real-time updates, ask yourself: "Do I really need a two-way conversation?" If the answer is no, give SSE a try. This article is part of the CakeDC Advent Calendar 2025 (December 20th 2025)

Written by Arodriguez on December 19, 2025

61 Views

QA vs. Devs: a MEME tale of the IT environment

QA testing requires knowledge in computer science but still many devs think of us like  homer-simpson-meme   BUT... morpheus-meme   It is not like we want to detroy what you have created but... house-on-fire-meme   And we have to report it, it is our job... tom-and-jerry-meme   It is not like we think dev-vs-qa   I mean cat-meme   Plaeas do not consider us a thread :) willy-wonka-meme 0/0/0000 reaction-to-a-bug   Sometimes we are kind of lost seeing the application... futurama-meme   And sometimes your don't believe the crazy results we get... ironman-meme   I know you think aliens-meme   But remmember we are here to help xD the-office-meme   Happy Holidays to ya'll folks! the-wolf-of-wallstreet-meme   PS. Enjoy some more memes   feature-vs-user   hide-the-pain-harold-meme   idea-for-qa   peter-parker-meme   meme   dev-estimating-time-vs-pm    

Written by Rcardoso on December 17, 2025

We Bake with CakePHP