CakeDC Blog

TIPS, INSIGHTS AND THE LATEST FROM THE EXPERTS BEHIND CAKEPHP

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 CakeDC.com. 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 www.pledgie.com !

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://codaset.com/cakedc/sample-migrations-application.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://codaset.com/cakedc/migrations.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

Payment integration, E-commerce made easy

With ecommerce trending, it may be the next step for your business. However, it can seem daunting - so where do you start?   Starting with basics, you need a website that will serve as a platform for your products - a good starting point is key. Perhaps your website is up and running, but you aren’t happy with it - why not do a redesign at the same time as doing payment integration. Be sure to discuss your needs with your development team.   Next is to ensure your product list is up to date and aligned with your ecommerce goals. With the ecommerce industry becoming so competitive, it's important to stand out - both with your products as well as with the overall user experience.   So your products stand out on your website, things are looking good! But having a functional payment processor is key to making those sales! Here are some key tips to ask your development team today!  

  • Before considering technical aspects, take consideration of the payment processing fees but be sure to pick a provider that is trusted by customers
  • Reference check your selection of payment gateway with your development team, will they be comfortable integrating this third party service with your site or do they have an alternative solution
  • Are you selecting a payment gateway that has been certified as safe and secure? By choosing one that is popular and trusted with customers will keep you on track for this requirement.
  • Is the payment gateway capable of accepting different payment methods such as credit cards, debit cards and others
  • Where are you planning to sell geographically via your ecommerce store? Is your payment gateway compatible with this geographical location? Some payment gateways are limited to certain countries - be sure to double check this before implementing the integration.
  • Should you chose to scale your business in the future, will your payment gateway be able to grow with you?
  Just remember, that whatever you choose to do with your ecommerce site, your payment integration should be as secure and smooth as possible. Chat to the expert team behind CakePHP today, to discuss how we can take your ecommerce integration to the next level. CakeDC is here to lead, so you can lead.  

Launching your new site? Read this first!

As exciting as launching a brand new website is, there are a lot of expectations that can be built up around it. Here are some top tips to not fall into the easy traps of launching your website   Don’t be a perfectionist It can be easy for some people to take the perfectionist view point when launching a new site. Rather focus on launching your website to its best and get feedback from testing and website visitors.   Doing it all yourself With the launch of your new site, it's important to delegate - make sure you have a expert team behind you so that you can manage your business and end goals. CakeDC, the experts behind CakePHP, believe in this philosophy - we lead, so you can lead.   Create a launch plan, now! If you do not have a plan for your launch, then the time is now! With research and strategy building, your launch will have direction, while reaching the right audience. Write everything down and be sure to share it with your team.   Linking to all Social media platforms With social media becoming an important way to reach out and talk to potential clients, it is key to ensure that you link your social media accounts to your websites and visa versa.   Have you tested? Testing is another key part to the success of your new site’s launch. Be sure to not miss this step. Not sure how to properly test your site? Here’s a great checklist to check out. From how to test elements such as HTML, CSS, security and performance through to SEO and accessibility, this checklist will guide you along best practices when it comes to testing.   Relax and execute your plan Lasty, relax and execute your plan! The final step to your new site’s launch is rollout. Things should be set up and in place which allow you to roll out your launch with minimal hassle.   At CakeDC, our goal is to help you, as a business leader, develop, achieve and maintain your competitive leadership in your market. Contact us to find out more about how we can create your custom application today.

Do you ever code for free? Contributing to open source

If you have ever taken a moment to contribute to open source, then you would know that it can be quite rewarding. But perhaps you are involved in an open source community, but aren’t necessarily contributing - yet! Maybe you are too nervous to contribute or you make a list of excuses as to why you aren't able to commit the time.   If you aren’t contributing just yet, here are some great benefits to you to start today.   Meet others in the community who are interested in similar things The CakePHP Community is welcoming and warm - by getting involved in the forums, online chats or through other participation, you can get to know others with similar interests.   Finding mentors within the community Get to know the community by getting involved - is there someone in the community who you think does an amazing job doing what they do? Chat to them, learn from them. There are some incredible mentors in the open source world - and they are normally down to earth and approachable.   Grow your knowledge and skill set base By contributing to open source, it gives you the opportunity to practise your skills. Through community involvement, you will learn new ways of doing things or suggest ways to improve on how things are done.   Help others - sense of giving Find reward in helping others solve the problems that have been troubling them. Giving back to the community brings in many rewards and a sense of achievement can be gained by helping out.   And now you may be asking - but how do I start? Easy! Just go ahead and find some issues that you can help out with, or simply join the support forums around the community and answer some questions - people appreciate the help and you never know, you could find help by helping others!   At CakeDC, time is committed to open source contributions. From our open source plugins through to support on community platforms, CakeDC ensures that time is committed to ongoing community support.

We Bake with CakePHP