CakeDC Blog

TIPS, INSIGHTS AND THE LATEST FROM THE EXPERTS BEHIND CAKEPHP

CakePHP Upgrade to 4 - Piece by Piece

Let's imagine you have a huge application in CakePHP 2.x (or 1.x) and you're planning to upgrade to the latest CakePHP 4.x.

After doing some estimations, you realize the upgrade process is out of your scope, because you don't have the budget or developer availability to do it in 1 shot. At this point, some companies would abort the upgrade and keep working on 2.x for "some more time" until "this last release is delivered" or until "budget is available next fall", digging deeper and deeper into the rabbit hole…

 

There's an alternative you could follow if this is your case: proceed with the upgrade of a smaller portion of your application and let the 2 versions coexist for some time.

 

Warning: This is NOT for every project or company. Please carefully think about this decision as it has overhead you'll need to handle.

 

So, if your application has a portion that could be extracted, with a small set of dependencies from other areas of your application, or if you are creating a new feature with a limited set of dependencies with the rest of your application, this approach would be good for you.

 

In order to allow both applications to coexist, we are going to keep the CakePHP 1.x application as the main one, and use CakePHP 4.x as a subfolder inside of the first one. It's important to note that in order to share sessions between both applications you'll need to use a storage you can actually share, like database or cache based sessions (redis, etc). Then, you can use a configuration like this one (see below) to add a new upstream to handle your new application. Note: the upstream could be located in another server of your network, using a different PHP version etc.

 

We've used nginx as an example, but you can use the same approach in other web servers like Apache.

 

In our example we're going to use all paths starting with /api  to be managed by our new CakePHP 4.x application.

upstream cake4 {

     # Note this could be any server/port in your network where the cake4 application is installed     

    server 127.0.0.1:9090;

}

 

# This is our CakePHP 2.x server

server {

    server_name example.com;

 

    root   /var/virtual/example.com/app/webroot;

    index index.php;

 

    # All requests /api are forwarded to our CakePHP 4.x application

location /api {

        proxy_pass http://cake4;

            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        proxy_set_header Host $host;

            proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;

            proxy_set_header Connection "Upgrade";

    }

 

    location / {

            try_files $uri $uri/ /index.php?$args;

    }

 

    location ~ \.php$ {

          try_files $uri =404;

          include fastcgi_params;

               fastcgi_pass unix:/run/php/php7.4-fpm.sock;

 

        fastcgi_index index.php;

            fastcgi_intercept_errors on;

        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

    }

}

 

# This is our CakePHP 4.x server

server {

    listen 9090;

    server_name example.com;

 

    root   /var/virtual/cake4-example.com/webroot;

    index index.php;

 

    location / {

        try_files $uri $uri/ /index.php?$args;

    }

 

    location ~ \.php$ {

        try_files $uri =404;

            include fastcgi_params;

        fastcgi_pass unix:/run/php/php7.4-fpm.sock;

            fastcgi_index index.php;

        fastcgi_intercept_errors on;

            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

    }

}

 

As you can see, we have 3 blocks defined in our configuration file:

  • upstream cake4 {...} to forward requests to the CakePHP 4.x application

  • server {... 2.x ...} using a location /api to forward all these calls to the CakePHP 4.x server

  • server {... 4.x ...} using a specific port (9090) to handle requests in CakePHP 4.x

 

Using this approach, you can break your application into 2 parts, and start moving features by path to CakePHP 4. You'll need to handle the changes in 2 projects for a while, and pay this overhead,  but this could be better to maintain than a CakePHP 2.x application sitting on an old PHP version.

Happy baking!

 

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