CakeDC Blog

TIPS, INSIGHTS AND THE LATEST FROM THE EXPERTS BEHIND CAKEPHP

CakePHP Migrations plugin: easily version and deploy whole applications

Written by Pierre on February 05, 2010 •
38393 VIEWS

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 G ithub 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.

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

408 Views

A quick CakePHP Local environment with DDEV

In the realm of web development, a seamless local environment is the bedrock for efficient and stress-free coding. Enter DDEV, a powerful tool that simplifies the setup process and empowers developers to dive into their projects with ease. In this blog post, we'll embark on a journey to demystify the process of setting up a local development environment using DDEV. Whether you're a seasoned developer or just starting in the world of web development, optimizing your local environment can significantly enhance your workflow.

Pre Conditions :

Install Docker https://docs.docker.com/get-docker/ and install DDEV https://ddev.readthedocs.io/en/stable/

Step 1: Create a new CakePHP project skeleton

composer create-project cakephp/app myproject A new folder "myproject" will be created with a CakePHP project skeleton inside. Go to this new directory and proceed with the following instructions.

Step 2: Initial ddev setup

Run ddev config
This will do the initial ddev setup, press enter for all questions. Run ddev auth ssh
This will add ssh key authentication to the ddev-ssh-auth container

Step 3: Adjust the settings

Inside "myproject" a new .ddev folder will be created, open config.yaml and adjust there: php version, database and the database url environment. For PHP:
php_version: "8.1"

For the database: database: type: mysql version: "8.0" For the environment variable: web_environment: - DATABASE_URL=mysql://db:db@db/db

Step 4: Start ddev

ddev start This will spin up the project.

Step 5: Open your application

ddev launch This will open your project in a browser. Once you have the application up and running, some useful commands you could run are:

ddev composer to execure composer
ddev mysql to get into the database
ddev ssh takes you into the web container.

In this link https://ddev.readthedocs.io/en/latest/users/usage/cli/ you can see more useful commands. Hope you enjoy playing with DDEV!

Written by Yelitza on November 22, 2023

667 Views

CakeFest 2023 Recap

CakeFest 2023 once again brought together developers from around the world for a weekend of baking (code), insightful talks, and community building. This year's event, featuring speakers from eight different countries and attendees joining both in person and via live streaming, was a refreshing convergence of passion and technology.

International Flavor:

One of the highlights of CakeFest 2023 was its international reach. Speakers from the United States, Canada, the Netherlands, Austria, Germany, Brazil, and Spain graced the virtual and physical stages, sharing experiences in the world of CakePHP and software development. This lineup added a diverse perspective to the event's discussions.

A Weekend of Learning and Networking:

CakeFest attendees enjoyed a weekend filled with learning opportunities, covering things from beginner workshops to cutting-edge software development trends, to the future of CakePHP. Workshops, panels, and presentations provided valuable insights and knowledge of the framework. We hope that everyone had the chance to expand their skills, connect with other developers, and forge new professional relationships. When CakeFest wasn't in session, the core/CakePHP team and attendees spent a lot of time getting to know each other… Groups went to lunch and dinner every day of the event. This is probably my favorite part of the physical conferences.

Baking and Code:

Day 1 consisted of 2 full workshops from Jorge González and lead core developer Mark Story. The third workshop presented by Kevin Pfeifer was included in day 2’s hybrid model. Followed by talks from: John Killcommons (keynote) of Zulucare/Zulucloud, Rafael Queiroz (Github actions for beginners and applied to CakePHP basic projects), Celso Fontes (PGE Digital, a successful CakePHP project in Rio de Janeiro's Attorney), and Andres Campanario (Integration of inertiajs on CakePHP to bake CRUD SPA). Day 3’s speakers included: Remy Bertot (keynote) of Passbolt, Mark Scherer (How to use your IDE effectively for CakePHP), Alejandro Ibarra (Unveiling the Ultimate Showdown: A Comparative Analysis of Local Development Tools), Stefan Koopmanschap (Domain-Driven Design: The Basics), Umer Salman (Agile Deployment of CakePHP Web Applications in a Hybrid Kubernetes Cluster), and Wim Godden (Websockets as the glue to interactivity). It was a weekend worth remembering for sure. The unique blend of networking and code at CakeFest allowed attendees to see just how far CakePHP has come, and will go, plus some pretty cool things built with the framework.

The Cake Ceremony:

No CakeFest would be complete without the much-anticipated cake ceremony. We hope that those attending virtually were able to enjoy some with us. In LA, we carried on the tradition of allowing Mark Story to be the “cutter of the cake”. Now that I think about it, he never asks to cut the cake, but it’s a honor nonetheless.

Conclusion:

CakeFest 2023 was a celebration of passion, knowledge, and creativity. With its global reach, experienced speaker lineup, and faithful community, we believe that the event left attendees inspired and eager to continue their works using Cake. We also learned about all of the cool places that CakePHP is being utilized, from the attorney general's office in Brazil, all the way to nasa using some CakePHP in space (more or less). We also heard from some of our CakePHP core developers - specifically their thoughts on CakePHP 5 and what’s to come. You can see a lot of photos on Facebook and Twitter and the edited presentation videos will be posted to YouTube soon. We are working on getting slides uploaded into the CakeFest site as we speak (or type). Someone said to me that there's a little bit of magic in every slice of cake and every line of code… I think that pretty well sums up our great weekend at CakeFest.

Written by Amanda on October 12, 2023

5713 Views

How to push Docker image to Container Registry and create App on...

The title speaks for itself, let’s jump right in! As a preliminary step, we start from a user registered in DigitalOcean with a validated account. Use the doctl tool for the entire communication process with DigitalOcean.

Step 1: Install doctl

$ cd ~

			$ wget https://github.com/digitalocean/doctl/releases/download/v1.71.0/doctl-1.71.0-linux-amd64.tar.gz

			$ tar xvf doctl-1.71.0-linux-amd64.tar.gz

			$ sudo mv doctl /usr/local/bin

Step 2: Create an API token

Go to https://cloud.digitalocean.com/account/api/tokens

Generate new token for read and write and save apart the value of token generated <TOKEN NAME>: personaltoken
<TOKEN VALUE>: 6e981fc2a674dbb7a610b9b85d0c8b00

Step 3: Use the API token to grant account access to doctl

$ doctl auth init --context personaltoken

			Validating token... OK

Prompt for <TOKEN VALUE>, then enter it and press return

Step 4: Validate that doctl is working

$ doctl auth init Validating token... OK

Prompt for <TOKEN VALUE>, then enter it and press return Validate by obtaining the account information

$ doctl account get Email Droplet Limit Email Verified UUID Status [email protected] 10 true 5415bbf8-d501-4096-9b75-ab781c017948 active

Step 5: Create a Container Registry with doctl

<MY-REGISTRY-NAME> : container-nyc-795 <REGION> : nyc3

$ doctl registry create container-nyc-795 --region nyc3 Name Endpoint Region slug container-nyc-795 registry.digitalocean.com/container-nyc-795 nyc3

Important: the region of the Container registry and Kubernetes cluster MUST be the same Keep in mind that container names must be unique, must be lowercase, and only accepts alphanumeric characters and hyphens.

Step 6: Login to authenticate docker with your registry

$ doctl registry login

			Logging Docker in to registry.digitalocean.com

Step 7: Create kubernetes cluster

$ doctl kubernetes cluster create cluster-static-example --region nyc3 Notice: Cluster is provisioning, waiting for cluster to be running ................................................................... Notice: Cluster created, fetching credentials Notice: Adding cluster credentials to kubeconfig file found in "/home/andres/.kube/config" Notice: Setting current-context to do-nyc3-cluster-static-example

ID                                      Name                      Region    Version        Auto Upgrade    Status     Node Pools

d24f180b-6007-4dbc-a2fe-3952801570aa    cluster-static-example    nyc3      1.22.7-do.0    false           running    cluster-static-example-default-pool

Important: the region of the Container registry and Kubernetes cluster MUST be the same here as well. This operation isn’t a fast process.

Step 8: Integrate kubernetes cluster in Container register

$ doctl kubernetes cluster registry add cluster-static-example

Step 9: Get token certificate and connect to cluster

$ doctl kubernetes cluster kubeconfig save cluster-static-example Notice: Adding cluster credentials to kubeconfig file found in "/home/andres/.kube/config" Notice: Setting current-context to do-nyc3-cluster-static-example

To validate this, use the kubectl tool to get context. If is not installed, get the last version you find - for example in googleapis

$ wget https://storage.googleapis.com/kubernetes-release/release/v1.23.5/bin/linux/amd64/kubectl

			$ chmod +x kubectl

			$ sudo mv kubectl /usr/local/bin/

Check with

$ kubectl config current-context

			do-nyc3-cluster-static-example

Here, you see: bash prompt do-ny3-cluster-sttic-example. That is the context you created in Step 7

Step 10: Generate docker image, tag and push to DigitalOcean

We assume that the user already has docker installed

$ mkdir myapp

			$ mkdir myapp/html

			$ nano myapp/Dockerfile

Inside Dockerfile put

FROM nginx:latest

			COPY ./html/hello.html /usr/share/nginx/html/hello.htm

We create simple Dockerfile with NGINX Server and copy the file hello.html in the default html of nginx

$ nano myapp/html/hello.html

Inside hello.html put

<!DOCTYPE html> <html> <head> <title>Hello World!</title> </head> <body> <p>This is an example of a simple HTML page served from the Nginx container.</p> </body> </html>

Then build a docker image file tag with repository and push with docker

$ cd myapp

			$ docker build -t registry.digitalocean.com/container-nyc-795/static-app .

Sending build context to Docker daemon 3.584kB Step 1/2 : FROM nginx:latest latest: Pulling from library/nginx c229119241af: Pull complete 2215908dc0a2: Pull complete 08c3cb2073f1: Pull complete 18f38162c0ce: Pull complete 10e2168f148a: Pull complete c4ffe9532b5f: Pull complete Digest: sha256:2275af0f20d71b293916f1958f8497f987b8d8fd8113df54635f2a5915002bf1 Status: Downloaded newer image for nginx:latest ---> 12766a6745ee Step 2/2 : COPY ./html/hello.html /usr/share/nginx/html/hello.html ---> 2b9be913c377 Successfully built 2b9be913c377 Successfully tagged registry.digitalocean.com/container-nyc-795/static-app:latest $ docker images

REPOSITORY                                               TAG       IMAGE ID       CREATED         SIZE

registry.digitalocean.com/container-nyc-795/static-app latest 2b9be913c377 2 minutes ago 142MB $ docker push registry.digitalocean.com/container-nyc-795/static-app Using default tag: latest The push refers to repository [registry.digitalocean.com/container-nyc-795/static-app] ac03ae036a53: Pushed ea4bc0cd4a93: Pushed fac199a5a1a5: Pushed 5c77d760e1f4: Pushed 33cf1b723f65: Pushed ea207a4854e7: Pushed 608f3a074261: Pushed latest: digest: sha256:22615ad4c324ca5dc13fe2c3e1d2d801bd166165e3809f96ed6a96a2b2ca2748 size: 1777

Step 11: Create app

Create file example-static-app.yaml and insert:

alerts:                                 

- rule: DEPLOYMENT_FAILED               

- rule: DOMAIN_FAILED                   

name: example-static-app                

region: nyc                             

services:                               

- http_port: 80                         

  image:                                

    registry_type: DOCR                 

    repository: static-app              

    tag: latest                         

  instance_count: 2                     

  instance_size_slug: professional-xs   

  name: static-service                  

  routes:                               

  - path: /                             

  source_dir: /

Validate file with

$ doctl apps spec validate example-static-app.yaml

Create app

$ doctl apps create --spec example-static-app.yaml

			Notice: App created

			ID        Spec Name             Default Ingress    Active Deployment ID    In Progress Deployment ID    Created At     Updated At

			55a7cb68-65b7-4ff1-b6af-388cdb1df507    example-static-app   2022-03-30 09:34:01.288257225 +0000 UTC    2022-03-30 09:34:01.288257225 +0000 UTC

If you access https://cloud.digitalocean.com/apps

And in the live url + /hello.html you can see:

Step 12: Deploy app

If you modify the code of your app, you need to generate a new image with docker and push (see step 10). Then you don’t need to create a new app, you need to deploy the image in the already created app, with the id executing the command to deploy in bash.

$ doctl apps create-deployment 55a7cb68-65b7-4ff1-b6af-388cdb1df507

How to generate deploy of Docker image to Container Registry on DigitalOcean Platform Apps

Once you have created the application (and if you have the code in gitlab), you can create a direct deployment of your code in the DigitalOcean container and deploy on top of your application.

Step 1: Define variables

First two variables are defined in gitlab. You can find these inside project in the left menu - enter in Settings > CI/CD > Variables $DIGITALOCEAN_API_KEY = token generated in DigitalOcean dashboard $APP_ID = previously generated application identifier More can be defined as the name of the repository. The value of these variables will be injected into the file that we will create below in the Step 3

Step 2: Register runner in gitlab

In your project in the left menu, go to Settings > CI/CD > Runners

Create a specific runner for the project in the URL with registration token. Register GitLab Runner from the command line. It is important to use docker and privileged

# Download the binary for your system

sudo curl -L --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64

# Give it permission to execute
sudo chmod +x /usr/local/bin/gitlab-runner

# Register runner

sudo gitlab-runner register -n --url https://git.cakedc.com --registration-token GR1348941gx7sgV3pZFQgRqg5qUR_ --executor docker --description "My Docker Runner" --docker-image "docker:19.03.12" --docker-privileged --docker-volumes "/certs/client"

Step 3: Create file gitlab-ci.yml

The gitlab-ci.yml file takes care of

Authentication and identification using doctl in DigitalOcean
Generating and sending the docker image to the DigitalOcean container
Deploying the container image to an existing app

Create the file gitlab-ci.yml in the root of your project as

image: docker:20-dind

			

			variables:

			  DOCKER_HOST: tcp://docker:2375

			  DOCKER_DRIVER: overlay2

			  DOCKER_TLS_CERTDIR: ""

			  REPOSITORY_URL: registry.digitalocean.com/container-nyc-795/static-app

			  CONTAINER_NAME: static-app

			

			services:

			  - name: docker:20-dind

			    alias: docker

			    command: ["--tls=false"]

			

			before_script:

			  - apk update

			  - apk upgrade

			  - apk add doctl --repository=http://dl-cdn.alpinelinux.org/alpine/edge/community

			  - docker info

			

			build:

			  stage: build

			  script:

			    - doctl auth init --access-token $DIGITALOCEAN_API_KEY

			    - doctl account get     

			    - echo $DIGITALOCEAN_API_KEY | docker login -u $DIGITALOCEAN_API_KEY --password-stdin registry.digitalocean.com

			    - docker build -t $REPOSITORY_URL:latest .

			    - docker push $REPOSITORY_URL

			    - doctl apps create-deployment $APP_ID

Now, every time you do a git push in your project, the runner will automatically inject the variables defined previously in the gitlab-ci.yml file. Then, it will generate a docker image with docker (docker-in-docker) to create an image of your project, send it to the digitalocean repository and deploy it in the app configured. That’s it!

Written by Acampanario on August 03, 2022