CakeDC Blog

TIPS, INSIGHTS AND THE LATEST FROM THE EXPERTS BEHIND CAKEPHP

A Quick CakePHP Local Environment With Docker

CakePHP and Docker

We all know that while developing a CakePHP software, we need to have a local environment with PHP, HTTP Server (nginx, apache) and a database (MySql, Postgres, Mongodb, etc). Installing those tools directly to your system is the basic way, but it can become a bit tricky when we have multiple projects using different versions of those tools... that’s where Docker will help us. In this article, we will show a quick docker setup to improve our CakePHP local environment.

If you don’t have docker installed go to: https://docs.docker.com/get-docker/. It is available for Linux, MacOS and Windows.

For our setup we are going to use PHP, Nginx, and Mysql. All of the information required will be added to a new file named docker-compose.yml. In our environment we will need two docker images [https://docs.docker.com/engine/reference/commandline/images/], one image for php + nginx and one for mysql. 

 

Setup Nginx + PHP service

Create the file  docker-compose.yml inside your application with this: 

 

version: "3.1"

services:

  php-fpm:

    image: webdevops/php-nginx:7.4

    container_name: myapp-webserver

    working_dir: /app

    volumes:

      - ./:/app

    environment:

      - WEB_DOCUMENT_ROOT=/app/webroot

    ports:

      - "80:80"

 

Now,we have a service named php-fpm, which is able to run php 7.4 and nginx at port 80 pointing to our webroot dir. Important note: the container_name must be unique in your system. 

 

Setup MySql service

Our MySql service requires a username, password and database name. For this, we are going to create the file mysql.env (don’t use a weak password in production, you could share a mysql.env.default file with your team) with this content:

 

MYSQL_ROOT_PASSWORD=password

MYSQL_DATABASE=my_app

MYSQL_USER=my_user

MYSQL_PASSWORD=password

 

Now, at the end of docker-compose.yml , add this: 

 

  mysql:

    image: mysql:5.6

    container_name: myapp-mysql

    working_dir: /app

    volumes:

      - .:/app

      - ./tmp/data/mysql_db:/var/lib/mysql

    env_file:

      - mysql.env

    command: mysqld --character-set-server=utf8 --init-connect='SET NAMES UTF8;'

    ports:

      - "3306:3306"

 

Before we start this service, lets add the service for our database, include this at the end of the file:  docker-compose.yml .

You’ll see that we have - ./tmp/data/mysql_db:/var/lib/mysql, this allows us to persist mysql data. Now we also have a service named mysql with one empty database named my_app and a user name my_user.
 

Starting the services and app configuration

Before we continue, make sure that you don’t have any other http server or mysql server running.

Now that we have finished our docker-compose.yml  we can execute docker-compose up to start the services and access the app at http://localhost. The next thing you need to do is update your database configuration with the correct credentials - the host is the service name, in our case it is “mysql”:

 

'host' => ‘mysql’,

            'username' => 'my_user',

            'password' => ‘password’,

            'database' => 'my_app',

 

That’s it! Now we have a working local environment for our CakePHP app. We can now access the services using docker-compose exec php-fpm bash  and docker-compose exec mysql bash

The files mentioned here (docker-compose.yml and mysql.env) can be found at  https://gist.github.com/CakeDCTeam/263a65336a85baab2667e08c907bfff6.

 

The icing on the cake

Going one step further, we could add some alias (with linux) to make it even easier. Let’s add these lines at the end of your ~/.bashrc file:

 

alias cake="docker-compose exec -u $(id -u ${USER}):$(id -g ${USER}) php-fpm bin/cake"

alias fpm="docker-compose exec -u $(id -u ${USER}):$(id -g ${USER}) php-fpm"

alias composer="docker-compose exec -u $(id -u ${USER}):$(id -g ${USER}) php-fpm composer"

 

With those entries, instead of typing docker-compose exec php-fpm bin/cake, we can just type cake. The other two aliases are for composer and bash. Notice that we have ${USER}? This will ensure that we are using the same user inside the services.

 

Additional information

Normally docker images allow us to customize the service, for webdevops/php-nginx:7.4 - you can check more information at: https://dockerfile.readthedocs.io/en/latest/content/DockerImages/dockerfiles/php-nginx.html and for mysql check: https://hub.docker.com/_/mysql . You can find more images at: https://hub.docker.com/.

If you are not familiar with docker, take a look at: https://docs.docker.com/get-started/overview/, as this documentation provides good information.

 

Hope you have enjoyed this article and will take advantage of docker while working in your CakePHP application.

 

Latest articles

Almost 20 years: A bit of history about CakePHP

This article is part of the CakeDC Advent Calendar 2024 (December 12th 2024) As many of you may know, CakePHP started back in 2005 with a minimal version of a framework for PHP. Then, in May 2006, version 1.0 of CakePHP was released including many of the features we still use today. Over the years a lot of features have been added to the project, and others have been greatly improved. As the framework has evolved, many people have been involved on this project, and we think now it is good time to say *THANK YOU* to everyone that has participated in greater or lesser extent. In this article, we will briefly recap some of the changes to the major (or most important) CakePHP versions throughout history. We will highlight the features that are still present in current version.   CakePHP 1.0 and 1.1: May 2006

  • Compatibility with PHP4 and PHP5
  • Integrated CRUD for database interaction and simplified queries
  • Application Scaffolding
  • Model View Controller (MVC) Architecture
  • Request dispatcher with good looking, custom URLs
  • Built-in Validation
  • Fast and flexible templating (PHP syntax, with helpers)
  • View Helpers for AJAX, Javascript, HTML Forms and more
  • Security, Session, and Request Handling Components
  • Flexible access control lists
  • Data Sanitization
  • Flexible View Caching
As you can see, most of the original features from CakePHP 1.x are still present in the 5.x version. Of course PHP4 and PHP5 compatibility does not makes sense right now, and Security and Session components have been replaced by most modern solutions.   CakePHP 1.2: Dec 2008
  • CakePHP 1.0 and 1.1 features
  • Code generation
  • Email and Cookie component joins the party
  • Localization
For CakePHP 1.2, we first see the code generation using the well-known Bake tool (now a plugin). Additionally, it is the first version where we have a way to create multi-language applications.   CakePHP 1.3: Apr 2010
  • Improved Logging
  • Removed inflections.php
  • Some internal library renames and changes.
  • Controller and Component improvements.
  • Routing changes
  • Performance improvement on Cache classes
  CakePHP 2.0: October 2011
  • Dropped PHP 4 support
  • New Error and Exception handlers which are easier to configure, and ease working with errors such as page not found, unauthorized error and lots more.
  • Improved I18n functions for easier multilingual development.
  • Support for injecting your own objects to act as CakePHP libraries
  • New Request and Response objects for easier handling of HTTP requests.
  • Completely refactored Auth system.
  • Brand new email library with support for multiple transports.
  • Dropped SimpleUnit in favor of PHPUnit.
  • Improved support for PostgreSql, SQLite and SqlServer.
  • HTML 5 form inputs support in form helper.
  • Huge performance improvements compared to version 1.3
CakePHP 2.0 did not change a lot from the way things were done in CakePHP 1.3, but it laid the foundation for the success of the following versions (including 2.x and the next major 3.x)   CakePHP 3.0: March 2015
  • A New ORM
  • Faster and more flexible routing
  • Improved migrations using Phinx
  • Better internationalization
  • Improved Debugging Toolbar
  • Composer usage
  • Standalone libraries
  • View cells
It is impossible to explain how much the framework changed from 2.x to 3.x. It is probably the most revolutionary version, since it introduced lots of improvements and changes like the amazing ORM and the database migrations management, both still in use. Even after almost 10 years it looks very timely and up-to-date.   CakePHP 4.0: December 2019
  • PHP 7.2 required.
  • Streamlined APIs with all deprecated methods and behavior removed.
  • Additional typehints across the framework giving you errors faster.
  • Improved error messages across the framework.
  • A refreshed application skeleton design.
  • New database types for fixed length strings (CHAR), datetime with
    microseconds, and datetime with timezone types.
  • Table now features OrFail methods that raise exceptions on failure
    making error handling more explicit and straightforward.
  • Middleware for CSP headers, Form tampering prevention, and HTTPS enforcement.
  • Cake\Routing\Asset to make generating asset URLs simple from anywhere in
    your application code.
  • FormHelper now generates HTML5 validation errors.
  • FormHelper now generates HTML5 datetime input elements.
It seems as though the list is self-explanatory. If CakePHP 3.0 was revolutionary, CakePHP 4.0 continued modernizing the framework with middlewares, new table methods, database types and a new application skeleton.   CakePHP 5.0: September 2023
  • PHP 8.1 required.
  • Improved typehints across the framework. CakePHP now leverages union types to formalize the types of many parameters across the framework.
  • Upgraded to PHPUnit 10.x
  • Support for read and write database connection roles.
  • New enum type mapping support in the ORM enabling more expressive model layers with improved type checking.
  • Table finders with named parameters, providing more expressive query building APIs.
  • Added time-only Time type and greatly improved Date and DateTime support via chronos 3.x.
  • Support for PSR17 HTTP factories was added.
And here we are, 1 year after CakePHP 5 was released, we are currently in version 5.1.20 (released November 10th). It is unbelievable that 20 years have already passed, and the team is more than excited about the upcoming changes and features we expect in CakePHP 6, 7 ,8 and beyond!   To finish we would like to make a special tribute (and thank them again) to the top 8 contributors from all time! Especially to our lead (and oldest active) developer, Mark Story (@markstory on Github or his Website) , who has been contributing for almost 17 years with more than 17k commits (an incredible average of 1000+ commits per year). Remember your name could be here as well! You just need to start contributing! (check out https://github.com/cakephp/cakephp/blob/5.x/.github/CONTRIBUTING.md). This article is part of the CakeDC Advent Calendar 2024 (December 12th 2024)

Troubleshooting Queue Jobs with Queue Monitor Plugin

This article is part of the CakeDC Advent Calendar 2024 (December 11th 2024) In this article we'll show how to easily monitor the queue jobs in CakePHP 5.0 using the CakePHP Queue Monitor plugin. Queue Monitor Plugin is a companion plugin for the official CakePHP Queue plugin .

Why I should monitor the queues

Monitoring queue jobs is crucial for maintaining the health and efficiency of your application's background processing. Here are some compelling reasons why you should monitor queue jobs:
  • Performance and Throughput: Monitoring helps ensure that your jobs are processed within acceptable time frames, preventing bottlenecks and ensuring that your application runs smoothly.
  • Error Detection and Handling: By keeping an eye on your queue jobs, you can quickly identify and address errors or failures in the jobs. This allows you to reduce the potential downtime.
  • Scalability: As your application grows, monitoring helps you understand how the queue system is handling the increased load, guiding decisions about scaling up or distributing workloads among multiple workers to speed up the job processing.
  • User Experience: Ensuring that background tasks are processed efficiently directly impacts the user experience. For example, timely processing of tasks like email notifications or data updates keeps users satisfied.
By monitoring your queue jobs, you can maintain a robust and efficient application that enhances performance and ensures reliability.

Key Features

This plugin will allow you to monitor the queue, in particular:
  • monitor and notify about jobs that exceed the specified working time
  • check if configured queues are working correctly
  • clear the queue of queued jobs
  • inspect job messages that have been processed

Getting Started

Before we discuss the functionality, we will go through the installation and configuration of the plugin.

Step 1: Installing the plugin

First you need to install the plugin into your CakePHP 5 application. To do this, you will need to run this command in the root of your project: composer require cakedc/queue-monitor When the plugin is installed please load it into your application: bin/cake plugin load CakeDC/QueueMonitor After the plugin is loaded please run the required migrations: bin/cake migrations migrate -p CakeDC/QueueMonitor

Step 2: Configuring the monitoring

To configure monitoring, place the following directives in your config/app_local.php and adjust values if needed. // ... 'QueueMonitor' => [ 'disable' => false, 'mailerConfig' => 'default', 'longJobInMinutes' => 30, 'purgeLogsOlderThanDays' => 7, 'notificationRecipients' => '[email protected],[email protected],[email protected]', ], // ... Options explained:
  • QueueMonitor.disable - With this setting you can enable or disable the queue monitoring, as the queue monitoring is enabled by default.
  • QueueMonitor.mailerConfig - mailer config used for notification, the default is default mailer.
  • QueueMonitor.longJobInMinutes - This is the time in minutes after which the job will be considered as working too long, and will be taken into account when sending notifications. The default values is 30 minutes.
  • QueueMonitor.purgeLogsOlderThanDays - This is the time in days after which logs will be deleted from the database to keep the log table small. The default value is 7 days.
  • QueueMonitor.notificationRecipients - This is a comma-separated list of recipients of notifications about jobs exceeding the configured working time.

Step 3: Configuring queue to use the monitoring

To enable the monitoring capabilities to a queue, you will need to add the listener to the queue configurations that you want monitor: 'Queue' => [ 'default' => [ // ... 'listener' => \CakeDC\QueueMonitor\Listener\QueueMonitorListener::class, // ... ] ],

Step 4: Configure notification cronjob

To receive emails about jobs that take too long to process, you need to add the following command to cron: bin/cake queue-monitor notify It is best to configure this command to run every few minutes.

Step 5: Configure the log purging

To keep the log table size small, you need to add automatic log purging to cron: bin/cake queue-monitor purge-logs It is best to configure this command to run every day.

Features

Continuous queue job monitoring

With the Queue Monitoring plugin installed and configured, all of your queued jobs are logged with time points and full message content. The entire processing of each job is also logged, starting from the moment the job is enqueued until one of the many ways the job ends. When any of the jobs exceeds the configured working time, you will be notified by email.

Inspecting the queue logs

Using CakeDC\QueueMonitor\Model\Table\LogsTable you can view all logged job messages. This functionality will be expanded in subsequent versions of the plugin.

Testing the queues

To quickly test if all queues are running correctly, run this command (replace [email protected] with working email address: bin/cake queue-monitor test-enqueue [email protected] This command will send the email through all configured queues.

Purging the queues

To purge the content of a specified queue you can use the purge queue command: bin/cake queue-monitor purge-queue your-queue-name The above command will remove all pending queue jobs from the specified queue. To purge all queues you can use command: bin/cake queue-monitor purge-queue --all

Conclusion

And that's it, you have successfully enabled queue monitoring and troubleshooting tools in your application. This plugin is in active development and more features will be added to it soon, some of them are:
  • browsing the content of messages in the queue
  • deleting a specified number of messages from the queue
  • deleting the first job in the queue
  • CRUD for queue logs
  • asynchronous queue logging to prevent degradation of job processing performance in case of high job frequency
We look forward to your feedback and contributions as we continue to enhance this plugin for the benefit of the entire CakePHP community. This article is part of the CakeDC Advent Calendar 2024 (December 11th 2024)

Introducing the CakePHP Goto View VSCode Extension

This article is part of the CakeDC Advent Calendar 2024 (December 10th 2024) As we embrace the spirit of giving during this holiday season, I'm glad to announce a new tool that aims to enhance the development experience for CakePHP developers using Visual Studio Code. The CakePHP Goto View extension brings intelligent navigation and autocompletion features to streamline your CakePHP development workflow.

Why Another Extension?

While CakePHP's convention over configuration approach makes development intuitive, navigating between related files in large projects can still be challenging. Whether you're working with templates, elements, cells, or assets, finding the right file quickly can impact your development speed and focus. This extension was born from the daily challenges we face as CakePHP developers, designed to make file navigation and discovery as seamless as possible while respecting CakePHP's conventions.

Key Features

Smart Navigation

Controller and Template Integration

  • Seamlessly navigate between controllers and their views by hovering over ->render() calls
  • Quick access to template files directly from controller actions
  • Smart detection of template paths based on controller context

Element and Cell Management

  • Instant access to element files by hovering over $this->element() calls
  • Complete cell navigation showing both cell class and template files
  • Support for nested elements and plugin elements

Asset File Navigation

  • Quick access to JavaScript files through Html->script() calls
  • CSS file navigation via Html->css() helper references
  • Support for both direct paths and plugin assets
  • Integration with asset_compress.ini configuration for compressed assets

Email Template Support

  • Navigate to both HTML and text versions of email templates
  • Quick access from Mailer classes to corresponding templates
  • Support for plugin-specific email templates

Plugin-Aware Intelligence

  • Smart resolution of files across different plugins
  • Support for both app-level and plugin-level resources
  • Automatic detection of plugin overrides in your application
  • Composer autoload integration for accurate namespace resolution

Autocompletion

  • Context-aware suggestions for elements, cells, and assets
  • Support for plugin resources with proper namespacing
  • Intelligent path completion based on your project structure

Developer Experience

  • Hover information showing related files and their locations
  • Real-time map updates as you modify your project structure
  • Support for both application and plugin resources
  • Minimal configuration needed - it just works!

Community Contribution

As with any open-source project, this extension is open to community involvement. Whether it's reporting bugs, suggesting features, or contributing code, every input helps make this tool better for everyone in the CakePHP ecosystem.

Getting Started

The extension is available in the Visual Studio Code marketplace. Simply search for "CakePHP Goto View" in your extensions panel or visit the marketplace website. Once installed, the extension automatically detects your CakePHP project structure and begins working immediately. No complex configuration required - it's designed to follow CakePHP conventions out of the box.

Conclusion

In the spirit of the CakePHP community's collaborative nature, this extension is our contribution to making CakePHP development even more enjoyable. We hope it helps streamline your development workflow and makes navigating your CakePHP projects a breeze. We look forward to your feedback and contributions as we continue to enhance this tool for the benefit of the entire CakePHP community. This article is part of the CakeDC Advent Calendar 2024 (December 10th 2024)

We Bake with CakePHP