Skip to content

Latest commit

 

History

History
106 lines (80 loc) · 4.62 KB

UPGRADE-2.7.md

File metadata and controls

106 lines (80 loc) · 4.62 KB

Migration guide from Foundry 2.6 to 2.7

Foundry 2.7 provides a new way to auto-refresh entities, which leverages new PHP 8.4 lazy objects!

This means that the Proxy mechanism and all related classes and functions are deprecated. This change was made to fix a lot of quirks involved by the proxy mechanism, and to reduce the maintenance burden of this feature.

How to

Important

The new auto-refresh mechanism only applies for PHP 8.4, if you're still not using PHP 8.4, there is nothing to do (yet!)

First, you need to configure whether you want to use the new auto-refresh mechanism:

zenstruck_foundry:
    # from Foundry 2.7, with PHP >=8.4, not setting this configuration is deprecated
    enable_auto_refresh_with_lazy_objects: true

In both cases, you'll need to migrate your factories and code to remove all the Proxy-related code:

  • remove all _real() calls
  • more generally, replace all proxy methods, by their function equivalent
  • replace PersistentProxyObjectFactory to PersistentObjectFactory
  • remove all types and PHPDoc related to proxies

Every modification needed for the migration is covered by a deprecation. You'll need to upgrade to the 2.7 version, run the tests, and fix all the deprecations reported.

Rector rules

This could be a lot of work in big projects, so we provide a Rector rule set to help you with this migration.

First, you'll need to install rector/rector:

composer require --dev rector/rector

Then, create a rector.php file:

<?php

use Rector\Config\RectorConfig;
use Zenstruck\Foundry\Utils\Rector\FoundrySetList;

return RectorConfig::configure()
    ->withPaths([
        // add all paths where your factories are defined and where Foundry is used
        'src',
        'tests'
    ])
    ->withSets([FoundrySetList::FOUNDRY_2_7])
;

And finally, run Rector:

# you can run Rector in "dry run" mode, in order to see which files will be modified
vendor/bin/rector process --dry-run

# actually modify files
vendor/bin/rector process

Important

Rector rules may not totally cover all deprecations (some complex cases may not be handled) You'd still need to run the tests to ensure everything is fixed and no more deprecation are reported.

Tip

You can try to run these rules twice with --clear-cache option. Sometimes, the second run will find differences that it could not spot on the first run.

Note

Once you've finished the migration to 2.7, it is not necessary to keep the Foundry rule set in your Rector config.

Deprecations list

Here is the full list of modifications needed:

  • Change the base class of your factories from PersistentProxyObjectFactory to PersistentObjectFactory You'll also need to update the PHPDoc @extends annotation to use the new class (covered by ChangeFactoryBaseClassRector).

  • Remove all _real(), _enableAutoRefresh() and _disableAutoRefresh() calls (covered by RemoveMethodCallRector).

  • Remove all \Zenstruck\Foundry\Persistence\proxy() and \Zenstruck\Foundry\Persistence\proxy() calls (covered by RemoveFunctionCallRector).

  • Remove all _withoutAutoRefresh() calls (covered by RemoveWithoutAutorefreshCallRector).

  • Replace some method calls on Proxy class with their function equivalent (covered by MethodCallToFuncCallWIthObjectAsFirstParameterRector):

    • _get() => \Zenstruck\Foundry\Persistence\get()
    • _set() => \Zenstruck\Foundry\Persistence\set()
    • _save() => \Zenstruck\Foundry\Persistence\save()
    • _refresh() => \Zenstruck\Foundry\Persistence\refresh()
    • _delete() => \Zenstruck\Foundry\Persistence\delete()
    • _assertPersisted() => \Zenstruck\Foundry\Persistence\assert_persisted()
    • _assertNotPersisted() => \Zenstruck\Foundry\Persistence\assert_not_persisted()

  • Remove Proxy type for parameters in the prototype in methods and functions (covered by ChangeProxyParamTypesRector).

  • Remove Proxy return type in methods and functions (covered by ChangeProxyReturnTypesRector).

  • Remove all Proxy type hints in PHPDoc (covered by RemovePhpDocProxyTypeHintRector).

Troubleshooting

After enabling the new auto-refresh mechanism and removing all proxy-related code, you may encounter some issues. Most of the time, these can be resolved by calling the \Zenstruck\Foundry\Persistence\refresh() function on the affected entity, which mimics the behavior of the former proxy mechanism.