CakeDC Blog

TIPS, INSIGHTS AND THE LATEST FROM THE EXPERTS BEHIND CAKEPHP

Introduction to CakeDC Api plugin

 

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.    

Remote Work, Actually Works!

As a fully remote company, the Cake Development Corporation team is used to working from home. We communicate with our team daily, keep on top of tasks, hold each other accountable and support one another. Heck, a lot of us even do it with kids in the household, too! I consider us extremely lucky to be able to work while juggling an at home life at the same time.  It has worked for CakeDC over the past decade, and in my opinion, can work for most companies.   As of last month, an estimated 4.7 million people were working remotely, which grew 44% over the last 5 years. This is just in the United States. Remote work is becoming the norm.  Obviously for the next few weeks, this number will be drastically increased, but perhaps this will educate companies on the advantages of a WFH culture. Advantages to employers, besides the operations cost (other than payroll, of course), which can decrease by close to 90%, includes increased productivity. Decreased overhead results in higher salaries, which results in more quality candidates and employees.  I understand the concern of the ability to micro-manage (UGH) being unavailable, but according to statistics, 85% of businesses that work remotely confirmed that productivity increased in their companies. When there is more flexibility, there will be higher employee morale.  With the current situation arising from COVID-19, a lot of businesses are forced to transition employees to WFH in order to stay afloat. This not only keeps employees and clients safe, but family members too.  I have put together some stats and resources that may help CEO’s and employees transition a little bit easier.  

Communication:

It is absolutely essential to keep open communication among a team when everyone is working remotely. Our team uses RocketChat* ( I will include some links in the resource section at the end of this blog), and it has proved to be effective. A chat allows for quicker response time, as well as allowing individuals to set their status (like busy, away, at lunch, sick, etc.). This is a good way to get quick answers, as users can be alerted when they have been messaged or tagged in a company chat. Most of our team work in different timezones, so this is a good way to “stay in the know” about everything happening day to day. We separate chats according to their department. For example: marketing, development, general, etc. We also have the option to private message with co-workers when needed.  Other ideas, if not daily chat interaction, include scheduled meetings. For most of our team meetings, we use Zoom. This tool allows for audio only, as well as video chats.  

Accountability & Time Management:

It is important that tasks are managed and followed through. We use programs like Redmine* to track hours and work, in addition to weekly, or monthly conference calls for each department.  If you or your team are new to remote work, it may be in your best interest to assign a project manager, someone who will assign work, track hours, and ensure that work needed is being completed in a timely manner. Without each person being held accountable, the ship will sink, fast. For personal accountability, there are many free apps and tools available. One example is Trello*. This is a scheduling board so that tasks are not forgotten and you can plan your work week and stay organized. Once tasks placed on your “schedule board” are completed, you can make note of it and stay focused on each one according to their priority. You can also keep track of documents and reports. The boards look like this:    

Resources:

Documents & Recording - We <3 Google Docs - we are able to share and edit internally, we couldn’t function without it.  Docusign is a good tool for contracts / documents needing signatures Invision Freehand - this is a tool where you can create presentations, and allows comments and feedback between designers. Good for freelance designers!    Organization/Tasks -  Trello - for individual time management scheduling.  Redmine - for project assigning, time recording, HR management,    Communication -  RocketChat - allows for multiple internal chats all rolled into one link (allows for individual logins) Zoom - good for meetings. Allows audio and video chats for teams or reps and clients.  Slack - also a great option for expanded chats. Each person has a “screen name” and can be personally messaged, or public groups can be created (we use this as well). Slack also allows video calls with their paid subscription.  Google Hangouts WhatsApp - if your team is diverse, like ours, WhatsApp is a must. We are able to text each other, regardless of location - no fees, no service problems (if you have wifi of course).  World Time Buddy - this is a tool that I am not familiar with, but being the designated “scheduler of meetings”, I think I would find it useful. If your team works within different timezones, this allows you to add the location of your teammates, compare times, and find ideal times for meetings.    Community - In the development world, community support sites are absolutely one of the most important tools. This allows for individuals - inside or outside of your company - to communicate and help each other out. Most developers are aware and utilize these, but if not, may I suggest: Discourse - chat support  GitHub - our favorite team collaboration tool. GitHub allows for hosting, editing and managing products. We use it for building software and allow for community interaction. It also integrates with a lot of other tools, which is a plus!  

Take Away:

These resources are just a drop in the bucket compared to what is available to remote workers. I think this is a reflection of how WFH is becoming more accepted and more normal in the corporate world. I’d love to hear some of your favorites: amanda.goff@cakedc.com.  Let’s take away some positivity to the current quarantined times, and encourage more companies to follow suit. In today’s world, flexibility goes a long way and this type of transition can be mutually beneficial for employers and employees. I mean look at us, we are PRETTY normal… right?  Speaking of being in quarantine - stay healthy, stay inside, and wash your hands!  

Two Factor Authentication & CakeDC Use...

Why 2FA?

Nowadays we have noticed that many of the websites or applications that we access offer the option to activate an extra layer of security called Two Factor Authentication, better known as 2FA. Most of our lives happen on our mobile devices and laptops, so it’s not a secret that cyber-thieves would like to gain access to our personal and financial data. This is why adding an extra layer for protecting logins is worth it.  2FA  is an extra layer of security to make sure that someone that is trying to gain access to an account is who they say they are. The first layer is generally a combination of a username and password, and the second layer could ask for a code that is sent to your phone, a fingerprint scan or the name of your best friend. Currently 2FA has become a security standard in the digital world.

How does it work?

First the user will enter his username and password, then instead of getting in immediately into the system, he will be required to provide  additional information. Which could be one of the following options or factors:
  • Something you know : This could be a password, a personal identification number (PIN), answers to a secret question or a specific keystroke pattern.
  • Something you have: This is something the user owns, a physical device, like a mobile phone, an id card, an usb stick, a token, etc.
  • Something you are: This could be face or voice recognition, retina scan,  fingerprint, DNA, handwriting.

CakeDC Users Plugin and 2FA

There are various ways to implement Time-based One-Time Password (TOTP), Short Message Service (SMS), Electronic Mail (Email),  Universal Second Factor (U2F). CakeDC Users Plugin provides the ability to enable in your site TOTP or U2F. 
 

TOTP Google Authenticator

Enabling 2FA Google Authenticator in CakeDC Users Plugin is quite easy, it just takes a few minutes. In case you have not installed CakeDC Users Plugin in your application, follow the installation steps described here. Once you have installed the plugin and your basic login is working, you just need to do the following:
  1. Run the next command: composer require robthree/twofactorauth
  2. In Application::pluginBootstrap() add the following: Configure::write('OneTimePasswordAuthenticator.login', true);
  Once you have 2FA enabled in your site, when you try to login will happen next 
  1. Type your username and password.   
  2. You proceed to the next step where you are asked for the authentication code
    • First time you will be shown a QR code that you need to scan from your authenticator application.   
    • Next time you will only get the input to type your authentication code  
  3. You open the authenticator application to get a secondary code called a one-time password (OTP)—usually six characters in length. There are many options in the market for the authenticator application, some of the most used are: Google Authenticator, Duo Mobile, FreeOTP etc.
  4. You type the 6-digit code into the website, and you’re in!
 

FIDO U2F

If you want something more solid and reliable, then you could use U2F (Universal 2nd Factor) standard created by the FIDO Alliance. With this kind of authentication you use a physical security key, and insert that into your PC, touch the key’s button, and you’re “automatically” logged in.  U2F standard was implemented in CakeDC Users Plugin by using  the YubiKey, the most famous and common example of U2F. To enable 2FA via Yubico follow the next steps:
  1. Run the next command: composer require yubico/u2flib-server:^1.0
  2. In Application::pluginBootstrap() add the following: Configure::write(‘U2f.enabled’, true);
     
Yubico is a hardware based 2FA, it’s a small device with one end that slots into a standard Type-A USB port. You just need to Insert your YubiKey and touch it! You won’t need to manually enter the code. Take into account that you will need to use https to be able to use 2FA features in your applicatins.

So, what to choose for two-factor authentication? There is no universal answer, it will depend on the level of security you are expecting, but start protecting your account by enabling 2FA! In this article you could noticed how easy is to enable 2FA in any CakePHP application by using CakeDC Users Plugin.
  References: https://github.com/CakeDC/users https://en.wikipedia.org/wiki/Multi-factor_authentication https://en.wikipedia.org/wiki/One-time_password https://en.wikipedia.org/wiki/FIDO_Alliance https://en.wikipedia.org/wiki/Universal_2nd_Factor  

Things about CakePHP that you probably...

CakePHP is often more than just a framework to many in the community, but there are some great features and treasures that many may not know about - so join us with your piece of cake and let’s check these out!

Cake Bake

Cake Bake is an incredibly helpful tool for any developer starting up a new application, or adding new functionality to an existing one.

Using your existing database schema (that follows the CakePHP conventions), running the cake bake command will quickly generate a fully working application skeleton with all your database fields and associations. It will even generate sane validation rules and pretty view files for you.  This allows you to concentrate on the features of your application that actually matter, rather than the generic admin CRUD interfaces. Have some kind of structure or class in your application that you regularly need to create? Maybe a specifically formatted view, or adaptor class? Cake Bake allows you to easily extend it and create your own bakeable templates. Find out more about Cake Bake in the CakePHP Cookbook (i.e. the framework docs)

CakePHP standalone packages

CakePHP’s core is built using standalone packages - this means that you aren’t bound to the framework.

The ORM, database, console, log to just name a few are available to use in your own PHP projects - even if you aren’t using CakePHP. Have you checked these out

Interactive console (REPL)

Not many developers are aware that CakePHP ships with an interactive console tool (Or REPL - Read Eval Print Loop).

You can start the console with bin/cake console. This console tool allows you to quickly and easily explore CakePHP and your application. Use it to quickly check if a finder method is working as expected, or to experiment with a specific query. Anything that you can code, you can run in the interactive console, much quicker and easier than coding a class.

Chronos

Chronos is a standalone DateTime library originally based off of Carbon.

The biggest difference between Chronos and Carbon is that Chronos extends DateTimeImmutable instead of DateTime. Chronos is immutable by default. Carbon is not. 

CakePHP Core team

The core team is built up of community members - just like yourself - who contribute their time to improving the framework.

All of their time is volunteered - so if you see them in the support channels, be sure to say hi! How did they get onto the core team you ask? They showed commitment to improving the core and the community.

There are some plugins that are just around to make your life a little easier

While most plugins were developed to add to the functionality of your CakePHP application without too much extra effort, there are some plugins that have been written to actually just make your life easier.

One such plugin is the CakePHP IDE helper, written by dereuromark. This plugin improves your IDE compatibility and uses annotations to make the IDE understand the "magic" of CakePHP - so you can click through the class methods and object chains as well as spot obvious issues and mistakes easier. For a curated list of CakePHP Plugins, grouped by topic, check https://github.com/FriendsOfCake/awesome-cakephp.   What’s your favourite part of the CakePHP framework or community? Let us know!

How not to be a good CakePHP developer...

I have been writing code for almost 20 years. It hasn't always been PHP, the first 6 or 7 years I was very involved with the Java world. While I partially agree with people thinking you can write bad code with PHP (more than other programming languages), I personally think that you can write bad code in any language because bad practices are common for all of them. For instance, you can call functions or initialize variables inside a loop, you can hit database many times, or you can repeat yourself no matter the language you use. That said, I want to list the most common questions that good developers should never ask themselves.   1.  Are you serious? Is it possible to add code to tables / entities? If you want to be a bad CakePHP developer, this is your golden rule. Almost every code we receive for review follow this one. Controllers with thousands of lines and models with just baked code.  That’s wrong because all the logic related to your tables should never be in your controllers (or helpers / views).  


  2.  I love using SQL queries in my code, is it really so bad? The short answer is YES. It’s bad, really bad. It is the greatest source of issues and unpredictable behaviors. It is hard to test but of course if you are asking this question you will probably ask the next one.     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.
  To summarize,  for sure there are lots of things to look at, but from my perspective these are the 10 basic questions that can define you as a good (or bad) developer. I hope you've never had these questions before but if you do, don’t worry about it, don’t tell anybody, just follow these recommendations to improve yourself!  

We Bake with CakePHP