CakeDC Blog


CakePHP Migrations plugin: easily version and deploy whole applications

This article is a quick introduction to the Migrations plugin, open sourced a few weeks ago by our company. You will see how simple it is to use the plugin and what you could do with it. I hope this article will show you the benefits of using migrations in your CakePHP applications and make you give it a try right after the reading!

Here is a one-sentence description of the plugin: the Migrations plugin allows developers to easily version and automate the creation / update process of any database schema and application data from the command line.

For information, CakeDC uses this plugin on its project since several years to make team collaboration and deployment easier. The plugin has been entirely rewritten a few months ago and fully tested (code coverage >95% as always at CakeDC) before being open sourced under the MIT license. It is now available to the community along with its documentation... and it is free!

Why is it useful?

It has been a while since companies integrated Source Code Management in their development process and CVS, SVN, Mercurial or Git are now common tools. Inspired from the open source movement it is also a good practice for single developers to version application source code.

As you might know, an application almost always depends of the database schema it is aimed to use... however it is not easy to version both the source code and database schema with a SCM. Let's take the example of a CakePHP application: until now the only way to do was to version a single file, either a sql dump or a CakePHP schema.php file generated with the cake schema shell. These two approaches are not very convenient to use on a daily basis, the first one forcing the developer to drop and recreate the whole database every time!

Moreover, a web application development is never really finished (there are always new features to add, software updates or bug fixing to do...) and deploying these change on a test or production server is always a delicate task.

Here comes the Migrations plugin! It provides a simple and easy way to version a database... and to perform many other different tasks thanks to its callback system. Here are some features:

  • keep a local database schema up-to-date: you just have to run all non applied migrations to update the local database schema to the latest version
  • make team work easier: when several developers work on the same application it is important that all of them work with the same database schema during all the development cycle. With migrations every commit is tied to the database schema at this precise instant, which makes easy switching branches and resetting a branch to a specific commit.
  • make installation and updates easier: ready to push the new version of your application live? You will only have to push the sources on the server and run all non applied migrations!
  • migrate more than database schema: the callback system allows you to do everything you want before (or after) applying (or reverting) each migration. Here are some examples: creating an initial admin account, add initial or test data to the application (lorem ipsums, categories, content...), update values from the database, send an email if debug > 0... The only limit may be your imagination ;)

Where can I find the code?

Announced a few weeks ago, a packaged version of the plugin can be downloaded from the "Plugins" section of This page contains a link to download the 1.0 version, the plugin documentation and the Github project for tickets and direct Git access to the repository.

To make people aware of the need to show their support to the Cake Software Fundation by donating a few bucks (this is unfortunately not done enough), the plugin was first available to donors only. The "Download without donation" button was added later, when the repository was made public! However, if you find this plugin useful please consider making a donation to the CSF... that is the best thing you could do for thanking us.

Click here to lend your support to: cakephp1x and make a donation at !

Even better! A sample application was also released for those who want to see how migrations could be used and integrated in an application. To play with it, Download the code or git clone the project using:

git clone git:// sample_migrations

You will only need to create a database.php configuration file and update CakePHP's core location to make the application work. Git users, run

git submodule init
git submodule update

to automatically add the migrations plugin as a submodule!

What do I need to use it in my application?

Note: the packaged plugin is for the CakePHP 1.3 version only. You can either download the 1.3-beta package of the framework, or use the 1.2 branch available in the Git repository.

Adding the plugin to an existing application is very simple. If you downloaded the archive containing the plugin code, unzip it in the "/plugins/migrations" folder of your application. Git users can add it as a submodule with the following command:

git submodule add git:// plugins/migrations

To check that it is installed correctly, execute the following command from your application root (it will display the available command to use the plugin):

cake migration help

If you encounter any problem here, please read the official documentation about CakePHP's console usage.

How does it work?

This post is not aimed at providing a comprehensive tutorial on how to use the plugin, thus I will just introduce the most useful commands along with some use cases.

For a complete documentation, please read the official documentation provided on the plugin page. For a simple (but useful for understanding purpose) use case you can take a look at the sample application introduced above. Going through the commit history will allow you to understand how migrations could be used in a development process.

Create a migration

To generate a new migration, type the following command

cake migration generate

The tool will ask you to give a name to the migration and suggest to do a dump of the current database schema. If a "schema.php" file is found in the application, it will ask you if you want to generate a diff between this schema and your current database one.

Generated migration files will be added to the "/config/migrations" application directory.

Apply / Revert migrations

When you pull an application containing migrations, several commands are available to apply or revert migrations. The simplest one is:

cake migration

It will display all the found migrations along with their status (applied or not applied) and id number. Just enter a migration number to update your database to the correct version. Some convenience commands are also available. You can use:

cake migration up, down, all or reset

These commands will respectively:

  • apply the next migration
  • revert the latest applied migration
  • apply all non applied migrations (and thus update the schema to the most recent version)
  • revert all applied migrations (and empty the database)

Migrations for plugins

Adding plugins to an existing application often implies adding new tables to the database or altering existing ones. The Migrations plugin brings a quick and efficient way to automate this installation. On the one hand developers can easily add necessary migrations to their plugin (making upgrades easier), on the other hand users can apply them as easily.

The only difference compared with commands introduced above is the parameter "-plugin pluginname" that needs to be added. Here is how the user will install the database for the newly added / updated plugin "test":

cake migration run all -plugin test

I would like to highlight the fact that callbacks allow the developer to do everything they want before / after each migration. It is convenient for adding initial data, and one can even implement a callback method opening the bootstrap.php file to append plugin's configuration entries there (it is just an example ;)).

... going further

Of course, feel free to add any remark or example of migrations use in the comments.

As this post is not aimed at providing support for the plugin, I recommend you to use the official tools available:

  • If you found a bug or want to suggest enhancements: open a ticket!
  • An installation problem or a question about the plugin usage? Ask your question to the community!
  • You would like a custom version of this plugin, or professional related services... contact us, it is our job ;)

I hope you enjoyed this post, it is now time for you to start playing with the Migrations plugin...

Latest articles

Building an RBAC based application in CakePHP (2/2)

This is the second article about RBAC in CakePHP series (2/2). In our previous post we did a quick introduction to RBAC and how to setup CakeDC/Auth plugin in an example project, dealing with basic array based rules. Today we'll talk about how to debug rules, and provide complex Auth rules to check permissions. We'll also discuss how to encapsulate the rules logic into `Rules` classes, and how to deal with RBAC in big projects.  

Debugging rules

Notice when debug is enabled, a detailed trace of the matched rule allowing a given action is logged into debug.log For example: 2017-10-04 23:58:10 Debug: For {"prefix":null,"plugin":null,"extension":null,"controller":"Categories","action":"index","role":"admin"} --> Rule matched {"role":"*","controller":"*","action":["index","view"],"allowed":true} with result = 1 This log could save you some time while debugging why a specific action is granted.

Callbacks for complex authentication rules

Let's imagine a more complex rule, for example, we want to block access to the articles/add action if the user has more than 3 articles already created. In this case we are going to use a callback to define at runtime the result of the allowed key in the rule. [ 'role' => '*', 'controller' => 'Articles', 'action' => 'add', 'allowed' => function (array $user, $role, \Cake\Http\ServerRequest $request) { $userId = $user['id'] ?? null; if (!$userId) { return false; } $articlesCount = \Cake\ORM\TableRegistry::get('Articles')->findByUserId($userId)->count(); return $articlesCount <= 3; } ],

Rules example

As previously discussed, we have the ability to create complex logic to check if a given role is allowed to access an action, but we could also extend this concept to define permission rules that affect specific users. One common use case is allowing the owner of the resource access to a restricted set of actions, for example the author of a given article could have access to edit and delete the entry. This case was so common that we've included a predefined Rule class you can use after minimal configuration. The final rule would be like this one: [ 'role' => '*', 'controller' => 'Articles', 'action' => ['edit', 'delete'], 'allowed' => new \CakeDC\Auth\Rbac\Rules\Owner(), ], The Owner rule will use by default the user_id field in articles table to match the logged in user id. You can customize the columns, and how the article id is extracted. This covers most of the cases where you need to identify the owner of a given row to assign specific permissions.

Other considerations

Permissions and big projects

Having permission rules in a single file could be a solution for small projects, but when they grow, it's usually hard to manage them. How could we deal with the complexity?
  • Break permission file into additional configuration files
  • Per role, usually a good idea when you have a different set of permissions per role. You can use the Configure class to append the permissions, usually having a defaults file with common permissions would be a good idea, then you can read N files, one per role to apply the specific permissions per role.
  • Per feature/plugin, useful when you have a lot of actions, and a small set of roles, or when the roles are mostly the same regarding permissions, with a couple changes between them. In this case you will define the rules in N files, each one covering a subset of the actions in your application, for example invoices.php file would add the pemissions to the Invoices plugin. In the case you work with plugins, keep in mind you could write the permission rules inside each plugin and share/distribute the rules if you reuse the plugin in other apps (as long as the other apps will have similar roles).
  • QA and maintenance
  • It's always a good idea to think about the complexity of testing the application based on the existing roles. Automated integration testing helps a lot, but if you are planning to have some real humans doing click through, each role will multiply the time to pass a full regression test on the release. Key question here is "Do we really need this role?"
  • Having a clear and documented permissions matrix file, with roles vs actions and either "YES" | "NO" | "RuleName" in the cell value will help a lot to understand if the given role should be allowed to access to a given action. If it's a CSV file it could be actually used to create a unit test and check at least the static permission rules.
  • Debugging and tracing is also important, for that reason we've included a trace feature in CakeDC/Auth that logs to debug.log the rule matched to allow/deny a specific auth check.

About performance

Performance "could" become an issue in the case you have a huge amount of rules, and some of them would require database access to check if they are matching. As a general recommendation, remember the following tips:
  • Rules are matched top to bottom
  • Try to leave the permission rules reading the database to the end of the file
  • Cache the commonly used queries, possibly the same query will be used again soon
  • Note cache invalidation is always fun, and could lead to very complex scenarios, keep it simple
  • If you need too much context and database interaction for a given rule, maybe the check should be done elsewhere. You could give some flexibility and get some performance in return

Last words

We've collected some notes about the implementation of a RBAC based system in CakePHP using our CakeDC/Auth plugin. As stated before, there are many other ways, but this is ours, worked well on several projects and we thought it was a good idea to share it with other members of the CakePHP community to expose a possible solution for their next project Authorization flavor. Please let us know if you use it, we are always improving on them - And happy to get issues and pull requests for our open source plugins. As part of our open source work in CakeDC, we maintain many open source plugins as well as contribute to the CakePHP Community. Reference

Building an RBAC based application in CakePHP (1/2)

This is the first post of a small series covering how to setup, organize and implement an RBAC based authorization system in CakePHP using the CakeDC/Auth Plugin. We'll cover the basic concepts, setup and implementation of the basic permission rules in part 1.

What does RBAC mean in this context?

We'll use RBAC as "Role Base Access Control", meaning your app will be using the following concepts to define who can access what:
  • "Who" is an existing user, mainly identified as his role in the system, such as an "admin" or "writer", etc.
  • "What" is a specific action in your application, identified as the associated routing params, for example ['controller' => 'Posts', 'action' => 'add'].
  • A permission in this context would be a link between who, and what.

Why not ACL?

ACL is a really good choice when your answer is 'yes' to any of the following questions:
  • Do we need to let users create new roles on the fly?
  • Do we need the roles to inherit permissions (tree structure)?
  • Do we need to assign permissions NOT based on controller actions? For example CRUD based permissions, checked on the model layer for each operation on a given row.
If your answer is yes, you should consider using cakephp/acl. It provides a very powerful, reliable and flexible way to configure your permissions, but with greater power comes a bigger maintenance burden, that is keeping the acl data in your tables. Specially if you have several environments to maintain, you'll need to write migrations to populate your acl tables, then create import/export scripts and utilities to reproduce permission issues from live environments, and so on. Not an impossible task, but could increase the complexity of your project in a significant way...

Setting up CakeDC/Auth

There are other plugins you could use, but this one will cover everything you'll need, so let's go. CakeDC/Auth usually comes installed from within CakeDC/Users (a complete solution covering many more features) but today we'll set it up alone. composer require cakedc/auth bin/cake plugin load CakeDC/Auth And last, but not least, add the RBAC Auth to the list of Authorize objects. Here is a working configuration based on the blog tutorial. We'll be using the blog tutorial described in the book as an example application Change AppController.php Auth related configuration to: $this->loadComponent('Auth', [ 'authorize' => ['CakeDC/Auth.SimpleRbac'], 'loginRedirect' => [ 'controller' => 'Articles', 'action' => 'index' ], 'logoutRedirect' => [ 'controller' => 'Pages', 'action' => 'display', 'home' ] ]); With this change, we'll be using only the rules defined in config/permissions.php file. If this file is not present, default permissions will be in place. Default permissions will grant access to admin role to all actions. To override permissions, you can copy the default permissions to your project and fix the rules: cp vendor/cakedc/auth/config/permissions.php config/ Then edit this file and check the provided examples and defaults.

Using CakeDC/Auth

The core of the RBAC system is the ability to define permission rules that will match one given role with the actions granted. Rules are defined in an array, but you can extend the AbstractProvider class to retrieve the rules from somewhere else (database?). By default, nothing will be granted. Rules are evaluated top to bottom. The first rule matched will stop the evaluation, and the authentication result will be provided by the value of the allowed key. Note we can use a callback to implement complex rules, or encapsulate the rules into classes that we could reuse across projects, like the Owner rule class provided. This is an example rule [ 'role' => '*', 'plugin' => 'CakeDC/Users', 'controller' => 'Users', 'action' => ['profile', 'logout'], ], We could read this rule as follows: "For any role, we grant access to actions 'profile' and 'logout' in the Users controller in plugin CakeDC/Users". Note default allowed value is true, we can use an array, or a string to determine the role, plugin, controller and action. We can also use * in the value to match anything or use * at the start of the key to match anything but the values, for example '*controller' => 'Users', would match all the controllers but 'Users'.

Simple Rules

As our first objective, we are going to grant access to all the index and view pages, using the rule [ 'role' => '*', 'controller' => '*', 'action' => ['index', 'view'], ],
Stay tuned for the second post, where we'll deal with complex rules, rule classes and implementation tips for complex applications...

Has your website been hacked? Learn more on what you can do

If you have a website and have not made the necessary security precautions, then you may become victim to hacking.   Besides the obvious defacing that can take place once your website has fallen victim, here are some other signs you have been hacked:

  • Your website redirects to another site, not your own.
  • Google or Bing notifies you.
  • Your browser indicates that your site is not secure.
  • You notice a change in your website traffic, especially from different countries.
  So you’ve been hacked - what do you do? Where do you start?   We’ve put together a few things that you need to look into as soon as possible!  
  • Do you have a support team? Contact them!
In this situation, it is best to immediately contact your technical support - your web developers who have experience in how to handle these situations. From what to shut down, what to look for and where to check. Someone without the technical expertise to help you is going to have difficulty properly fixing things!  
  • Get together all of the information required for your support team
Your support team will need all the access information, so start putting this together - things they will need access to include your CMS; hosting provider and login details; web logs, FTP/sFTP access credentials as well as any back ups you may have. If you have never been hacked or do not have regular back ups running - here’s a good place to start.  
  • Temporarily take your website down
If you haven’t already done so, make sure to take your site down temporarily. While you are doing this, it is also important to check all your servers and computers for malware, spyware or trojans. And if you have a virtual server, it may be in the best interest to start over - some attacks leave software that may not be visible or you may not know what to look for.  
  • Change your passwords
Make sure to change your passwords! Not sure what to use? For the best security, make use of a password generator that includes both letters and numbers of more than 12.
  For expert development and consultation services, give CakeDC a call - we lead, so you can lead.

We Bake with CakePHP