Overview
The Shim plugin "shims" functionality up and down across CakePHP major versions. It also provides a handful of small, app-friendly convenience wrappers.
This is mainly useful when upgrading large applications to the next major framework version. A lot of code usually needs to be adjusted; with this plugin fewer lines need to be touched. Especially the ORM layer, which would otherwise require heavy refactoring, needs far fewer changes to get things working again.
Zero-dependency plugin
Apart from the framework core, this plugin has no other dependencies. It is used one piece at a time. Classes and plugin aliases work without registration. Loading Shim additionally runs its bootstrap.
CakePHP version
This documentation is for the branch that shims 4.x in 5.x for applications running CakePHP 5. For older releases, see the version map.
How it works
Choose the functionality you need. For most cases you do not even need to load the plugin. The individual elements (database types, traits, behaviors, helpers) can be used directly where needed.
There are two broad categories of shims:
- Main shims: convenience functionality that will most likely be ported forward into future releases. Review their API when moving to a new major version.
- BC shims: backwards-compatibility helpers that only exist to ease the 3.x → 4.x → 5.x transition. These are intended to be removed again once your upgrade is complete.
Use BC shims deliberately
Using backwards-compatibility shims on purpose in new code is usually a bad idea. They exist to keep an in-flight upgrade running, not to be a permanent crutch.
The pieces
| Area | What the shim provides |
|---|---|
| Database | Custom column types: UUID (binary), time-as-string, year, and array. |
| Datasource | A paginator that still understands contain/conditions, plus loadModel() shimming. |
| Model | A base Table re-using legacy properties, entity read/require/get-set traits, and a Nullable behavior. |
| Controller | A base Controller, the CastTrait, and an out-of-bounds pagination redirect trait. |
| Component | A RequestHandler component for continued automatic view-class switching. |
| View | Configure, Cookie, and Number helpers. |
| Utility | Inflector::slug() BC wrapper. |
| Testing | A TestTrait, ConsoleOutput, and integration/test case base classes. |
Next steps
- Installation: install the plugin via Composer.
- Getting started: use your first trait or helper.
- Preconditions: what to have in place before upgrading.
- Upgrade Guide: migrating from 4.x to 5.x.
Helpful links
When planning an upgrade, also look into the official upgrade docs and the linked upgrade tool. They contain many more ideas on how to align code with the current direction of the framework and reduce friction long term. See also the blog post on the CakePHP 5 upgrade guide.
A full overview of all shimming between versions can be found in the Wiki.