CakeDC Blog

TIPS, INSIGHTS AND THE LATEST FROM THE EXPERTS BEHIND CAKEPHP

Introduction to CakeDC Api plugin

Written by Yevgeny on March 30, 2020
11967 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

184 Views

CakeFest 2025 Wrap Up

For years I have heard the team talk about Madrid being one of their favorite cities to visit, because they hosted CakeFest there more than a decade ago. I can now confirm… they were right! What a beautiful city. Another great CakeFest in the books… Thanks Madrid!   Not only are we coming down from the sugar high, but we are also honored to be celebrating 20 years of CakePHP. It was amazing to celebrate with the attendees (both physical and virtual). If you watched the cake ceremony, you saw just how emotional it made Larry to reminisce on the last 20 years. I do know one thing, CakePHP would not be where it is without the dedicated core, and community.    Speaking of the core, we had both Mark Scherer and Mark Story joining us as presenters this year. It is a highlight for our team to interact with them each year. I know a lot of the other members from the core team would have liked to join us as well, but we hope to see them soon. The hard work they put in day after day is unmatched, and often not recognized enough. It’s hard to put into words how grateful we are for this group of bakers.    Our event was 2 jam packed days of workshops and talk presentations, which you can now see a replay of on our YouTube channel (youtube.com/cakephp). We had presenters from Canada, Germany, India, Spain, USA, and more! This is one of my favorite parts about the CakePHP community, the diversity and representation from all over the world. When we come together in one room, with one common goal, it’s just magical. Aside from the conference itself, the attendees had a chance to network, mingle, and enjoy meals together as a group.  I could sense the excitement of what’s to come for a framework that is very much still alive. Speaking of which… spoiler alert: CakePHP 6 is coming. Check out the roadmap HERE.   I feel as though our team leaves the event each year with a smile on their face, and looking forward to the next. The events are growing each year, although we do like to keep the small group/intimate type of atmosphere. I am already getting messages about the location for next year, and I promise we will let you know as soon as we can (when we know!). In the meantime, start preparing your talks, and send us your location votes.   The ovens are heating up….

Written by Amanda on October 16, 2025

446 Views

Polymorphic Relationships in CakePHP: A Beginner's Guide

Have you ever wondered how to make one database table relate to multiple other tables? Imagine a comments table that needs to store comments for both articles and videos. How do you manage that without creating separate tables or complicated joins? The answer is a polymorphic relationship. It sounds fancy, but the idea is simple and super powerful.

What's a Polymorphic Relationship?

Think of it this way: instead of a single foreign key pointing to one specific table, a polymorphic relationship uses two columns to define the connection. Let's stick with our comments example. To link a comment to either an article or a video, your comments table would have these two special columns:
  1. foreign_id: This holds the ID of the related record (e.g., the id of an article or the id of a video).
  2. model_name: This stores the name of the model the comment belongs to (e.g., 'Articles' or 'Videos').
This flexible setup allows a single comment record to "morph" its relationship, pointing to different types of parent models. It's clean, efficient, and saves you from a lot of redundant code. It's not necessary for them to be called "foreign_id" and "model_name"; they could have other names (table, model, reference_key, model_id, etc.) as long as you maintain the intended function of each. Now, let's see how you can set this up in CakePHP 5 without breaking a sweat.

Making It Work in CakePHP 5

While some frameworks have built-in support for polymorphic relationships, CakePHP lets you create them just as easily using its powerful ORM (Object-Relational Mapper) associations. We'll use the conditions key to define the polymorphic link.

Step 1: Set Up Your Database

We'll use a simple schema with three tables: articles, videos, and comments. -- articles table CREATE TABLE articles ( id INT AUTO_INCREMENT PRIMARY KEY, title VARCHAR(255) ); -- videos table CREATE TABLE videos ( id INT AUTO_INCREMENT PRIMARY KEY, title VARCHAR(255) ); -- comments table CREATE TABLE comments ( id INT AUTO_INCREMENT PRIMARY KEY, content TEXT, foreign_id INT NOT NULL, model_name VARCHAR(50) NOT NULL ); Notice how the comments table has our special foreign_id and model_name columns.

Step 2: Configure Your Models in CakePHP

Now for the magic! We'll define the associations in our Table classes. ArticlesTable.php In this file, you'll tell the Articles model that it has many Comments, but with a specific condition. // src/Model/Table/ArticlesTable.php namespace App\Model\Table; use Cake\ORM\Table; class ArticlesTable extends Table { public function initialize(array $config): void { // ... $this->hasMany('Comments', [ 'foreignKey' => 'foreign_id', 'conditions' => ['Comments.model_name' => self::class], // or 'Articles' 'dependent' => true, // Deletes comments if an article is deleted ]); } } Use self::class is a best practice in modern PHP, as it prevents bugs if you ever decide to rename your classes, and your IDE can auto-complete and check it for you VideosTable.php You'll do the same thing for the Videos model, but change the model_name condition. // src/Model/Table/VideosTable.php namespace App\Model\Table; use Cake\ORM\Table; class VideosTable extends Table { public function initialize(array $config): void { // ... $this->hasMany('Comments', [ 'foreignKey' => 'foreign_id', 'conditions' => ['Comments.model_name' => self::class], // or 'Videos' 'dependent' => true, ]); } } CommentsTable.php This table is the owner of the polymorphic association. You can add associations here to easily access the related Article or Video from a Comment entity. // src/Model/Table/CommentsTable.php namespace App\Model\Table; use Cake\ORM\Table; class CommentsTable extends Table { public function initialize(array $config): void { // ... $this->belongsTo('Articles', [ 'foreignKey' => 'foreign_id', 'conditions' => ['Comments.model_name' => \App\Model\Table\ArticlesTable::class], // or 'Articles' ]); $this->belongsTo('Videos', [ 'foreignKey' => 'foreign_id', 'conditions' => ['Comments.model_name' => \App\Model\Table\VideosTable::class], // or 'Videos' ]); } }

Step 3: Using the Relationship

Now that everything is set up, you can fetch data as if it were a normal association. Fetching Comments for an Article: $article = $this->Articles->get(1, ['contain' => 'Comments']); // $article->comments will contain a list of comments for that article Creating a new Comment for a Video: $video = $this->Videos->get(2); $comment = $this->Comments->newEmptyEntity(); $comment->content = 'This is an awesome video!'; $comment->foreign_id = $video->id; $comment->model_name = \App\Model\Table\VideosTable::class; // or 'Videos' $this->Comments->save($comment); As you can see, the model_name and foreign_id fields are the secret sauce that makes this pattern work.

What About the Future? The Power of This Solution

Now that you've got comments working for both articles and videos, what if your app grows and you want to add comments to a new model, like Photos? With this polymorphic setup, the change is incredibly simple. You don't need to alter your comments table at all. All you have to do is: Create your photos table in the database. Add a new PhotosTable.php model. In the new PhotosTable's initialize() method, add the hasMany association, just like you did for Articles and Videos. // src/Model/Table/PhotosTable.php namespace App\Model\Table; use Cake\ORM\Table; class PhotosTable extends Table { public function initialize(array $config): void { // ... $this->hasMany('Comments', [ 'foreignKey' => 'foreign_id', 'conditions' => ['Comments.model_name' => self::class], 'dependent' => true, ]); } } That's it! You've just extended your application's functionality with minimal effort. This demonstrates the true power of polymorphic relationships: a single, scalable solution that can easily adapt to your application's evolving needs. It's a key pattern for building flexible and maintainable software.

Conclusion

This approach is flexible, scalable, and a great way to keep your database schema simple. Now that you know the basics, you can start applying this pattern to more complex problems in your own CakePHP applications!

Written by Arodriguez on September 24, 2025

2894 Views

Closing Advent Calendar 2024

This article is part of the CakeDC Advent Calendar 2024 (December 24th 2024) That’s a wrap on the CakeDC 2024 advent calendar blog series. Did you get to read all of them? Hopefully you obtained some useful information to use in your future baking. We would love to get your feedback, feel free to share! It is still hard to believe that 2024 is almost over, but we are looking forward to an extraordinary 2025. On behalf of CakeDC, we want to thank our team for all the hours of hard work they put in this year. Also, thank you to our clients for trusting us with your CakePHP projects, it is an absolute pleasure getting to work with each of you. We are thankful for the great relationships we have built, or carried on in the last 12 months. For our CakePHP community, especially the core team, please know how incredibly grateful we are for your support of the framework. There is a reason that Cake is still around after 20 years, and it’s great developers like you, who dedicate their time and efforts to keep the code going. THANK YOU, THANK YOU, THANK YOU. As far as what is to come for CakePHP in 2025, stay tuned. However, I am told that there are some top secret (not really, we are opensource after all) talks about CakePHP 6 happening. With the release of PHP 8.4, I am sure some awesome features will be implemented in Cake specifically. We will also be celebrating 20 years of CakePHP next year, can you believe it? CakeFest will be in honor of all core members past and present, and it may be a good time to introduce some new ones as well. If you are a core member (or former), we would love to have you attend the conference this year. The location will be announced soon. Interested in getting involved or joining the core team? You can find some helpful links here: https://cakephp.org/get-involved We hope you enjoyed our gift this year, it’s the least we could do. Wishing you a happy holiday season from our CakeDC family to yours. See you next year! … sorry, I had to do it. :) Also, here are some final words from our President: Larry Masters.

A Christmas Message to the CakePHP Community

As we gather with loved ones to celebrate the joy and hope of the Christmas season, I want to take a moment to reflect on the incredible journey we’ve shared this year as part of the CakePHP community. This is a special time of year when people around the world come together to celebrate love, grace, and the hope that light brings into the world. It’s also a time to give thanks for the connections that make our lives richer. The CakePHP framework has always been about more than just code, it’s about people. It’s the collective effort of contributors from around the world who believe in building something better, together. To everyone who has shared their expertise, contributed code, written documentation, tested features, or offered guidance to others, I want to express my deepest gratitude for your dedication and passion. As we approach 2025, it brings even greater meaning to reflect on how far we’ve come. Next year marks the 20th anniversary of CakePHP. From the first lines of code to the projects we support today, the journey has been nothing short of remarkable. As we look ahead to the new year, let us carry forward this spirit of generosity, collaboration, and unity. Together, we can continue to empower developers, build exceptional tools, and foster a community that is inclusive, welcoming, and supportive. On behalf of everyone at Cake Development Corporation, I wish you and your families a blessed Christmas filled with peace, joy, and love. May the new year bring us more opportunities to create, connect, and grow together. Thank you for being part of this journey. Merry Christmas and a very Happy New Year to everyone. With gratitude, Larry Masters This article is part of the CakeDC Advent Calendar 2024 (December 24th 2024)

Written by Amanda on December 24, 2024

We Bake with CakePHP