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.
Anyway, I am not going to talk about remote work because these days there are thousands of articles about it (even in one of our previous posts). I want to focus today on writing about our experience with different communication tools and the pros and cons for each of them.
Back in 2011 when I started working at CakeDC, we had an IRC server in place with a couple of plugins to retain messages for our day-to-day communication. Everyone used different clients like Colloquy on mac or Pidgin on Linux. Additionally, we used Skype for peer/team calls and also for client communication. In my opinion, the linux experience was awful until they improved the client a few years later. This setup was implemented in 2007 when the company was started, and in 2012, we decided to shut it down because it was easier just using Skype for everything, messages and calls.
After several years using - suffering - Skype, with new options in the market, we decided to move away to a more reliable and modern approach. The main reason was the lack of updates for Skype linux client, and the message retention limits. In 2016 we started utilizing the more than popular Slack and its open source alternative, Rocket Chat; always keeping Skype for client communication.
Some months later the team concluded that Rocket Chat was the right choice, mainly because we wanted to have control over the messages and the information transmitted. Since the features we were using were available in both solutions, we installed our own Rocket Chat server. At this point I have to say that we did try the calls solution (Jitsy) inside Rocket Chat, but the experience was not good at all, issues with missing calls, poor call quality, etc, made us keep Skype for calls.
On the other hand CakePHP training was provided using Join.me and even when it worked very well in most situations; our trainer Jorge, always had to use a Windows machine instead of his usual Linux one. And then, Zoom emerged.
The year was 2018, when Zoom became so popular even though it started back in 2011 (yes, Zoom existed before COVID-19 crisis). We started using it and it quickly replaced Skype for our team calls. It allowed multiple people calls, screen share, etc. I must say, however, the Zoom chat is one of the worst things I have ever seen.
Going back to Jorge, as you can imagine he was very happy when he saw Zoom had a good Linux client. Unfortunately, he was quickly disappointed because the client screen crashed randomly, went black, and the computer ran out of memory when he tried to share his screen to more than 10 attendees. Happily he didn't throw his windows machine out of the window yet so he could continue giving the training with that machine.
It's 2020, COVID-19 is around us, and Zoom is probably the most popular telecommuting tool. For both adults and children, it is an essential tool to keep working and studying. However, fame never comes alone and threats, rumors and comments are making us move away (again) from Zoom to Google Meet. Also, it didn't make sense to pay for Zoom if we were already paying for GSuite.
I didn't mention it before, but we have been using GSuite (former Google Apps) since the beginning. Google - late as usual - detected a market niche and decided to pump out its meeting tool. In my opinion, I am a standalone app person. This means that I will always prefer having 20 apps instead of 20 browser tabs. So, I don't like Google Meet a lot because of this, but I must say the call quality is superb.
I am not sure how or when we will move to other tools, but right now we are very happy with our Rocket Chat installation and we are still getting used to Google Meet, but it fits our needs.
As a side note we are still using skype to communicate with clients because it is the app everyone has, and sometimes people simply don't want to install something else or use something they are not used to.
To conclude I must say that each team and person should try all of these different tools before choosing one, because one tool that may fits my needs may not fit yours.
It’s time to beat out the competition, are you ready? I first recommend seeing where you stand. There are a few tools you can use to test your SEO score. One example is: 
To keep up with the planning process or any changes, make sure you follow us on 
3. Tests? Baked tests are enough, aren’t they?
Ehm.. no. You won’t be a bad developer if you don’t have 100% coverage. Even more, I don’t like to talk about what coverage is good because it exclusively depends on the project itself. I would say that you should feel good if your core features are fully covered.
4. Why should I put the code in one place only if you can copy and paste it everywhere?
Even most modern IDEs identify this as a bad practice now, but this is something we see in almost every code we get for review. People prefer to copy and paste the same function in multiple classes instead of creating a Component or Behavior or even a library and use it everywhere.
5. Plugins? What is a plugin?
CakePHP has a very large set of available plugins, or you can always start your own plugin and publish it so other people can use it. Plugins are one of the most important features in CakePHP since you can encapsulate a feature or a set of features to use them in multiple projects. Just be careful and don’t overplugin.
6. How the hell would somebody hash a password?
Well, even when you think it's a joke, no, it's not. Some people think hashing a password is not required. CakePHP provides several options for password hashing to secure your application.
7. Do you document your code? I don’t think it is useful.
Having the availability of documentation aids in understanding the intended use, as well as the expected functionality and result of the code's execution. It is pretty easy if you just document your code while you are doing it instead of waiting to have 20 classes to document.
8. Should I declare variables to execute find methods / DB / Service requests or should I put them inside a for/while loop to "save" memory?
Please no, doing external service requests (DB / File / Web Service) from inside a loop affects application performance very badly. You should always try to put the result in a variable and then use it inside the loop.
9. Who needs coding standards?
Coding standards help make code more readable and maintainable. For CakePHP applications, the Cake Conventions and Coding Standards should be applied.
10. Is it better to make all calculations inside for/while loops level in code instead of calculating at the DB/query level?
Data iteration at the DB level offers way better performance than iteration done at the application level.
