NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist
Packagist, #5131 most downloaded on Packagist
A CakePHP plugin to shim applications between major framework versions.
Latest stable
3.9.2
Last release 1 months ago
11 Oct 2026
Release timing varies
gaps range from 2 weeks to 5 months
Nearly every release is documented
notes for 59 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
12 years old
88 releases · first in 2015
Drag across the ruler to compare, or tap a release to open it.
…longer triggers the CakePHP 5 "options array is deprecated" warning and a custom finder combined with other options (fields, contain, ...) is applied.…
Table::record() now calls Table::get() with a finder name and named arguments, so it no longer triggers the CakePHP 5 "options array is deprecated" warning and a custom finder combined with other options (fields, contain, ...) is applied. #134Table::record() accepts the legacy key option as an alias for cacheKey; an explicit cacheKey wins. #134YearType::marshal() and YearType::toDatabase() return null for array input without a year key instead of raising an undefined-index warning. #134Shim\Annotator\EntityAnnotator keeps the iterable value type on generated set...OrFail() setter annotations (for example array<\App\Model\Entity\Tag>) when IdeHelper.genericsInParam is enabled. Without the option the type still collapses to array. #130Controller::afterFilter() documents its event parameter as EventInterface<\Cake\Controller\Controller>, so PHPStan no longer reports a missing generic on it. #131Full Changelog: https://github.com/dereuromark/cakephp-shim/compare/3.9.1...3.9.2
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Fix three bugs: record() get() arguments, File::read() trim handling, and beforeFind() order opt-out
Full Changelog: https://github.com/dereuromark/cakephp-shim/compare/3.9.0...3.9.1
Deprecations.php now validates the Shim.deprecationType config value against the levels trigger_error() actually accepts (E_USER_NOTICE / WARNING / DE…
Database\Type\YearType::toDatabase() and marshal() now actually cast the input to int, matching their ?int return signature. Previously they returned the raw $value (typically a numeric string) under declare(strict_types=1), breaking the declared contract (#124).Model\Table\Table::saveAll() no longer folds per-row save results via bitwise & — that operator coerced the accumulator to int after the first iteration, so callers using strict comparisons (=== true) saw 1 instead of true. Replaced with a proper bool early-out (#124).View\Widget\DateTimeWidget::_deconstructDate() now reads the AM/PM character from the same source it checked ($value['meridian']) instead of the str-padded copy, eliminating a long-standing decoupling between conditional and read paths (#125).Model\Table\Table::delete() restores the parent's typed array $options parameter. The previous override widened it to bare $options plus a runtime is_array() check that was dead under declare(strict_types=1) (#125).LegacyModelAwareTrait::loadModel() now guards _modelFactories with property_exists(). CakePHP 5.x removed ModelAwareTrait, so consumers that don't redeclare the property no longer trip an undeclared-dynamic-property warning under PHP 8.2+ — the lookup falls back cleanly to FactoryLocator::get() (#125).Filesystem\Folder::isAbsolute(), isWindowsPath(), and isRegisteredStreamWrapper() now cast preg_match() results to bool explicitly so the : bool contract holds under stricter PHPStan rules. The Windows-path check also moves to str_starts_with() (#125).Deprecations.php now validates the Shim.deprecationType config value against the levels trigger_error() actually accepts (E_USER_NOTICE / WARNING / DEPRECATED / ERROR), falling back to E_USER_DEPRECATED. A misconfigured value like E_NOTICE previously crashed the shim's own deprecation pathway with a ValueError on PHP 8+ (#125).Controller\Component\RequestHandlerComponent::accepts() and prefers() no longer carry the misleading deprecated 4.4.0 doc tag inherited from upstream. The shim's purpose is to keep these methods available for consumers who have not yet migrated to ContentTypeNegotiation::prefersChoice() / Controller::getViewClasses() — flagging them deprecated inside the shim was misleading IDEs and consumers (#125).Model\Table\Table::record() uses PHP 8 capture-omit catch (RecordNotFoundException) instead of an empty catch (RecordNotFoundException $e) {} body that PSR2R / phpcs flagged (#125).TestSuite\TestTrait::invokeMethod() and invokeProperty() drop the redundant & on the object parameter — objects are passed by handle in PHP, so the reference was dead syntax. Subclasses overriding these (e.g. EntityAnnotatorTest) must drop the & from their override signature; updated in this release (#125).Deprecations.php now declares strict_types=1, matching the rest of src/ (#125).Full Changelog: https://github.com/dereuromark/cakephp-shim/compare/3.8.5...3.9.0
Fix SetTrait magic setOrFail off-by-one in argument index - https://github.com/dereuromark/cakephp-shim/pull/123
Full Changelog: https://github.com/dereuromark/cakephp-shim/compare/3.8.4...3.8.5
Forward TEntity template from Cake\ORM\Table through Shim\Model\Table\Table so subclasses can type their entity for PHPStan. Requires CakePHP 5.3.4+ t
TEntity template from Cake\ORM\Table through Shim\Model\Table\Table so subclasses can type their entity for PHPStan. Requires CakePHP 5.3.4+ to resolve against a two-generic Cake\ORM\Table.Full Changelog: https://github.com/dereuromark/cakephp-shim/compare/3.8.3...3.8.4
Fix null array offset deprecation (PHP 8.5+)
Full Changelog: https://github.com/dereuromark/cakephp-shim/compare/3.8.2...3.8.3
### Fixes - Removed deprecations Full Changelog: https://github.com/dereuromark/cakephp-shim/compare/3.8.1...3.8.2
Full Changelog: https://github.com/dereuromark/cakephp-shim/compare/3.8.1...3.8.2
Fix up groupBy() shim for Paginator.
Fixed find('list') to auto-use correct fields for 2 (or 1) select fields given. Shims old 3.x behavior again.
find('list') to auto-use correct fields for 2 (or 1) select fields given. Shims old 3.x behavior again.loadModel() callsFixed more timezone handling for DateTime dropdowns
Fixed timezone handling for DateTime dropdowns
If you overwrote the afterFilter() callback in controllers, please make sure those are now all return void.
If you overwrote the afterFilter() callback in controllers, please make sure those are now all return void.
### Improvements - Removed more deprecations
Removed deprecation in beforeFind(). Return signature changed to void.
In your AppView.php: `php $this->loadHelper('Shim.Number'); ` instead of the core one.
In your AppView.php:
$this->loadHelper('Shim.Number');
instead of the core one.
You have now the empty functionality of CakePHP 5.3+ in your Number helper:
Instead of ternary checks you can pass your DB values directly, it will print out an empty string (or defined default string) where needed.
echo $this->Number->format($entity->value);
// or
echo $this->Number->format($entity->value, ['default' => '-']);
and
echo $this->Number->currency($entity->value);
// or
echo $this->Number->currency($entity->value, ['default' => '-']);
This aims to provide forward compatibility.
> deprecated: 8192 :: strlen(): Passing null to parameter # 1 ($string) of type string is deprecated
Implemented require() as trait method to add to your entities.
It adds a sometimes needed feature of verbosely and clearly asserting the (nested) entity data structure needed for following code.
use Shim\Model\Entity\RequireTrait;
class MyEntity extends Entity {
use RequireTrait;
This can be useful when you have service classes or parts of the system that "know" what data inside they need to calculate or render results. If you now add this to another part of the application, it can easily be forgotten to contain a certain relation the code inside depends on it. With this you would get alerted right away as developer and can fix up those relations.
// in some service method at the beginning
public function buildPdf(Product $product): string {
$product->require('supplier.company.state.country')
//Render template
}
This avoids the usual kind of hidden and not speaking
warning: 2 :: Attempt to read property "sku" on null
deprecated: 8192 :: strlen(): Passing null to parameter # 1 ($string) of type string is deprecated
warning: 2 :: foreach() argument must be of type array|object, null given
etc then inside the business logic or rendering. Especially the latter means that you forgot a "has many" relation here to be added. Even if there would be no results, a fetched relation and an empty array then inside the entity would not trigger such warnings.
Entity::isModified() has been renamed to isModifiedValue() since it would clash with CakePHP 5.2+. Since 5.2+ the core functionality is now properly checking isDirty(), so this method became less relevant.
Shimmed RequestHandler component from CakePHP 4 into 5.
Adjusted for core release of trait method isDebug()
isDebug()Included commits: https://github.com/dereuromark/cakephp-shim/compare/3.2.2...3.2.3
Fixed up isModified() on entity for non strict comparison, e.g. when comparing DateTime values.
Fixed up isModified() on entity for non strict comparison, e.g. when comparing DateTime values.
Fixed RedirectOutOfBoundsTrait to continue to support paginate property as well as config.
Fixed RedirectOutOfBoundsTrait to continue to support paginate property as well as config.
Added RedirectOutOfBoundsTrait for controller pagination to auto-fix 404s for humans.
Added RedirectOutOfBoundsTrait for controller pagination to auto-fix 404s for humans.
Simply add the trait and enjoy the magic:
use Shim\Controller\Controller;
use Shim\Controller\RedirectOutOfBoundsTrait;
class AppController extends Controller {
use RedirectOutOfBoundsTrait;
Instead of showing a not user-friendly 404 page, the pagination will redirect right away to the last page available.
Fixed up default model class detection for shims.
Fixed up default model class detection for shims.
Added NumericPaginator shim for contain shimming in 5.x.
Fixed Command args to be not nullable.
Fixed Command args to be not nullable.
The plugin to help ease migration coming from CakePHP 4.x apps.
The plugin to help ease migration coming from CakePHP 4.x apps.
Shim Up: With CakePHP 4.x core and some of the shims, you can prepare your app already for 5.x. Shim Down: Then, once upgraded, with 5.x core and some more shims you can further minimize required changes until the app works again. Then you can slowly start refactoring again further while the app is already running again.
loadModel() for apps that make heavy use of it still.The tool to help ease migration coming from CakePHP 4.x apps.
The tool to help ease migration coming from CakePHP 4.x apps.
Shim Up: With CakePHP 4.x core and some of the shims, you can prepare your app already for 5.x. Shim Down: Then, once upgraded, with 5.x core and some more shims you can further minimize required changes until the app works again. Then you can slowly start refactoring again further while the app is already running again.
Fixed Overriding class attribute in DateTimeWidget. by @otukutun in https://github.com/dereuromark/cakephp-shim/pull/99
Full Changelog: https://github.com/dereuromark/cakephp-shim/compare/2.4.0...2.4.1
Added set*OrFail() functionality for entities to make it easier to have an early error system for invalid null setting. This compliments the already e
set*OrFail() functionality for entities to make it easier to have an early error system for invalid null setting.
This compliments the already existing get*OrFail() functionality.CakePHP 4.3 checked/approved and CakePHP 4.2+ / PHP 7.3+ now.
Added ConfigureHelper::consumeOrFail() method as view template proxy to Configure class.
ConfigureHelper::consumeOrFail() method as view template proxy to Configure class.read() or consume().Fixed propagation of options into widgets like Year, especially in dropdown use case.
Fixed propagation of options into widgets like Year, especially in dropdown use case.
Fixed signature of Table::beforeFind()
Table::beforeFind()Table::save()Shim.Nullable behavior can now also run on beforeSave() callback instead of beforeMarshal(). This helps with validation that needs to have the empty s
Shim.Nullable behavior can now also run on beforeSave() callback instead of beforeMarshal().
This helps with validation that needs to have the empty string posted still available for isset() checks and alike.
Also, that callback can be used specifically on "dirty" fields.
You can also refactor those to array_key_exists(), if you want to keep the default event and expect nullish input.
The tool to help ease migration coming from CakePHP 3.x apps.
The tool to help ease migration coming from CakePHP 3.x apps.
Then you can slowly start refactoring again further while the app is already running again.
Feel free to contribute more shims to either CakePHP 3.x or 4.x version branch.
Please help to finalize for stable release.
Please help to finalize for stable release.
Shim.Nullable behavior can now also run on beforeSave() callback instead of beforeMarshal(). This helps with validation that needs to have the empty s
Shim.Nullable behavior can now also run on beforeSave() callback instead of beforeMarshal().
This helps with validation that needs to have the empty string posted still available for isset() checks and alike.
Also, that callback can be used specifically on "dirty" fields.
You can also refactor those to array_key_exists(), if you want to keep the default event and expect nullish input.
An Inflector backport has been added as an opt-in replacement for the core one. Its Inflector::pluralize() already uses new 4.x behavior:
An Inflector backport has been added as an opt-in replacement for the core one.
Its Inflector::pluralize() already uses new 4.x behavior:
pluralize(): index => indexes (instead of indices)You can also configure the core one with custom inflections from your bootstrap, though.
Customizable deprecation output (use your own E_USER_* type if needed).
E_USER_* type if needed).Shim.deprecations set to true. You can also silence specific deprecations.newEntity() vs newEmptyEntity().Controller::referer() now defaults to true for internal referer only (as per 4.x default).
Add more 4.x shims:
Controller::referer() now defaults to true for internal referer only (as per 4.x default).Allow CastTrait to handle empty strings. This is mainly important when handling request data in controller, as they can be empty strings coming from e
Allow CastTrait to handle empty strings. This is mainly important when handling request data in controller, as they can be empty strings coming from either data or query.
This is useful if you want to get your CakePHP 3 plugins to PHPStan level 7 on controller level, as the query input needs to be properly asserted/cast
This is useful if you want to get your CakePHP 3 plugins to PHPStan level 7 on controller level, as the query input needs to be properly asserted/cast depending on if it is optional or required input (nullable or not).
Add read() method for entities to allow dot syntax convenience access. $entity->read('tags.0.name') will return the property if it exists or returns n
Add read() method for entities to allow dot syntax convenience access.
$entity->read('tags.0.name') will return the property if it exists or returns null otherwise.
This compliments the getOrFail() part which does the opposite (guarantees the path to be present).
Allow adding get...OrFail() methods to Entity classes to have non-nullable return values asserted. This is needed for chaining, as null-pointer-occurr
Allow adding get...OrFail() methods to Entity classes to have non-nullable return values asserted.
This is needed for chaining, as null-pointer-occurrences should be avoided here.
Just use the trait here:
use Shim\Model\Entity\GetTrait;
class Post extends Entity {
use GetTrait;
...
}
It automatically provides the getters here for you.
// bad (tag could be null)
$tagName = $entity->tag->name;
// good (tag cannot be null as this would throw clear exception)
$tagName = $entity->getOrFail('tag')->name;
This will please both analyzers and IDE as well as throw meaningful exceptions in case the field is not set in the entity as expected in this particular case.
For all nullable cases you can still use the normal property access, of course.
Pro tip: Use the included IdeHelper EntityAnnotator replacement to allow annotations to be added for all of your entities' fields.
/**
* @property int $id
* @property string $title
* @property \Cake\I18n\FrozenTime|null $created
* @property \Tags\Model\Entity\Tag|null $tag
* @method int getIdOrFail()
* @method string getTitleOrFail()
* @method \Cake\I18n\FrozenTime getCreatedOrFail()
* @method \Tags\Model\Entity\Tag getTagOrFail()
*/
class Post extends Entity {
...
}
Small NullableBehavior fix for nullable foreign keys.
Small NullableBehavior fix for nullable foreign keys.
### Improvements CakePHP 3.6+ from now on.
CakePHP 3.6+ from now on.
Included commits: https://github.com/dereuromark/cakephp-shim/compare/1.6.1...1.7.0
Included commits: https://github.com/dereuromark/cakephp-shim/compare/1.6.1...1.7.0
CakePHP 3.6 compatibility.
The plugin now also is CakePHP 3.5+.
Small validation shim fix for simple string validation rules.
Small validation shim fix for simple string validation rules.
Fixed simple validation shim cases.
'null').Note: This version now requires CakePHP 3.4+
### Improvements - autoNullConditionsArray() - Session shim behavior #### Dropped - JsHelper
The Timestamp behavior now just checks for $modifiedField and $createdField in the class, and does no lookup anymore on the schema. This prevents addi
The Timestamp behavior now just checks for $modifiedField and $createdField in the class, and does no lookup anymore on the schema. This prevents additional fixtures needed for all relations inside a test case.
delete() can now be called with 'strict' option to throw an exception instead of returning false. This can help to catch silent non-deletes where you
delete() can now be called with 'strict' option to throw an exception instead of returning false.
This can help to catch silent non-deletes where you would otherwise manually wrap it with exception handling everywhere.
E.g. in a CLI script:
$this->TableName->delete($entityName, ['strict' => true]);
save() can now be called with 'strict' option to throw an exception instead of returning false. This can help to catch silent non-saves where you woul
save() can now be called with 'strict' option to throw an exception instead of returning false.
This can help to catch silent non-saves where you would otherwise manually wrap it with exception handling everywhere.
E.g. in a CLI script:
$this->TableName->save($entityName, ['strict' => true]);
Also:
Nothing published for this version
find(list) when upgrading from 2.x can have undesired and silent output so far. This is shimmed at the moment until a core decision to support the 2.x
find(list) when upgrading from 2.x can have undesired and silent output so far. This is shimmed at the moment until a core decision to support the 2.x use case with 1-2 selected fields can be made.
Also an InflectedRoute class functioning as any other 3.x route class has been added. Better use that one if you want to have camelBacked method names as actions in 3.x and have to use inflected URLs.
saveAll() wrapper as convenience method
Dont forget to take a look at the docs and at https://github.com/dereuromark/cakephp-shim/wiki
See https://github.com/dereuromark/cakephp-upgrade/wiki/Upgrading-Notes-for-CakePHP-3.x#query-conditions
See https://github.com/dereuromark/cakephp-upgrade/wiki/Upgrading-Notes-for-CakePHP-3.x#query-conditions
Using Configure::read('Shim.assertActionNames') you can assert that all controller actions have been properly migrated to the new camelBacked naming s
Using Configure::read('Shim.assertActionNames') you can assert that all controller actions have been properly migrated to the new camelBacked naming scheme. They must not be underscored anymore for DashedRoute setup.
Nothing published for this version
Prevent a small issue with validation rules shim.
Prevent a small issue with validation rules shim.
It is now possible again to set up an array for the validation message.
It is now possible again to set up an array for the validation message.
One column per quarter.