-
-
Notifications
You must be signed in to change notification settings - Fork 84
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
29 changed files
with
692 additions
and
417 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,163 @@ | ||
| # Migration guide from Foundry 1.x to 2.0 | ||
|
|
||
| Foundry 2 has changed some of its API. | ||
| The global philosophy is still the same. | ||
| The main is that we've introduced a separation between "object" factories, | ||
| "persistence" factories and "persistence with proxy" factories. | ||
|
|
||
| When Foundry 1.x was "persistence" first, Foundry 2 is "object" first. | ||
| This would allow a lot more decoupling from the persistence layer. | ||
|
|
||
| ## How to | ||
|
|
||
| Every modification needed for a smooth migration is covered by a deprecation. | ||
| All you have to do is to activate the deprecation helper, make the tests run, fix all the deprecations reported. | ||
|
|
||
| Here is an example of how the deprecation helper could be activated. | ||
| You should the `SYMFONY_DEPRECATIONS_HELPER` in `phpunit.xml` or `.env.local` file: | ||
| ```shell | ||
| SYMFONY_DEPRECATIONS_HELPER="max[self]=0&max[direct]=0&quiet[]=indirect&quiet[]=other" | ||
| ``` | ||
|
|
||
| Here is the full list of modifications needed: | ||
|
|
||
| ## Factory | ||
|
|
||
| - `withAttributes()` and `addState()` are both deprecated in favor of `with()` | ||
| - `sequence()` and `createSequence()` do not accept `callable` as a parameter anymore (how do we leverage `__index` instead??) | ||
|
|
||
| ### Change factories' parent class | ||
|
|
||
| `Zenstruck\Foundry\ModelFactory` is now deprecated. | ||
| You should choose between `\Zenstruck\Foundry\Persistence\PersistentProxyObjectFactory` and `\Zenstruck\Foundry\Persistence\PersistentObjectFactory`. | ||
| Both act the same way, but the latter does not return a `Proxy` object. | ||
|
|
||
| > [!NOTE] | ||
| > You will have to change some methods prototypes in your classes: | ||
| ```php | ||
| // before | ||
| protected function getDefaults(): array | ||
| { | ||
| // ... | ||
| } | ||
|
|
||
| // after | ||
| protected function defaults(): array|callable | ||
| { | ||
| // ... | ||
| } | ||
| ``` | ||
|
|
||
| ```php | ||
| // before | ||
| protected static function getClass(): string | ||
| { | ||
| // ... | ||
| } | ||
|
|
||
| // after | ||
| public static function class(): string | ||
| { | ||
| // ... | ||
| } | ||
| ``` | ||
|
|
||
| As a rule of thumb to help you to choose between these two new factory parent classes: | ||
| - only entities (ORM) or documents (ODM) should use `PersistentProxyObjectFactory` | ||
| - you should only use `PersistentProxyObjectFactory` if you want to leverage "auto refresh" behavior | ||
| - all "non-persistable" objects could use `PersistentObjectFactory`, since `Proxy` is only useful for entities/documents | ||
| - final object cannot use `PersistentProxyObjectFactory`, but that should not be a problem, since entities/documents cannot be final objects | ||
|
|
||
| > [!WARNING] | ||
| > `PersistentProxyObjectFactory` should not be chosen to create `final` classes instances. | ||
| > This will throw a deprecation in 1.x and will create an error in 2.0 | ||
| > [!IMPORTANT] | ||
| > Since `PersistentObjectFactory` does not return a `Proxy` anymore, you'll have to remove all calls to `->object()` | ||
| > or any other proxy method on object created by this type of factory. | ||
| ## Proxy | ||
|
|
||
| Foundry 2.0 will completely change how `Proxy` system works, by leveraging Symfony's lazy proxy mechanism. | ||
| `Proxy` won't be anymore a wrapper class, but a "real" proxy, meaning your objects will be of the desired class AND `Proxy` object. | ||
| This implies that calling `->object()` (or, now, `_real()`) everywhere to satisfy the type system won't be needed anymore! | ||
|
|
||
| `Proxy` class comes with deprecations as well: | ||
| - replace everywhere you're type-hinting `Zenstruck\Foundry\Proxy` to the interface `Zenstruck\Foundry\Persistence\Proxy` | ||
| - most of `Proxy` methods are deprecated: | ||
| - `object()` -> `_real()` | ||
| - `save()` -> `_save()` | ||
| - `remove()` -> `_delete()` | ||
| - `refresh()` -> `_refresh()` | ||
| - `forceSet()` -> `_set()` | ||
| - `forceGet()` -> `_get()` | ||
| - `repository()` -> `_repository()` | ||
| - `enableAutoRefresh()` -> `_enableAutoRefresh()` | ||
| - `disableAutoRefresh()` -> `_disableAutoRefresh()` | ||
| - `withoutAutoRefresh()` -> `_withoutAutoRefresh()` | ||
| - `isPersisted()` is removed without any replacement | ||
| - `forceSetAll()` is removed without any replacement | ||
| - `assertPersisted()` is removed without any replacement | ||
| - `assertNotPersisted()` is removed without any replacement | ||
| - Everywhere you've type-hinted `Zenstruck\Foundry\FactoryCollection<T>` which was coming from a `PersistentProxyObjectFactory`, replace to `Zenstruck\Foundry\FactoryCollection<Proxy<T>>` | ||
|
|
||
| ## Instantiator | ||
|
|
||
| - `Zenstruck\Foundry\Instantiator` class is deprecated in favor of `\Zenstruck\Foundry\Object\Instantiator`. You should change them everywhere. | ||
| - `new Instantiator()` is deprecated: use `Instantiator::withConstructor()` or `Instantiator::withoutConstructor()` depending on your needs. | ||
| - `Instantiator::alwaysForceProperties()` is deprecated in favor of `Instantiator::alwaysForce()`. Be careful of the modification of the parameter which is now a variadic. | ||
| - `Instantiator::allowExtraAttributes()` is deprecated in favor of `Instantiator::allowExtra()`. Be careful of the modification of the parameter which is now a variadic. | ||
| - Configuration `zenstruck_foundry.without_constructor` is deprecated in favor of `zenstruck_foundry.use_constructor` | ||
|
|
||
| ## Standalone functions | ||
|
|
||
| - `Zenstruck\Foundry\create()` -> `Zenstruck\Foundry\Persistence\persist()` | ||
| - `Zenstruck\Foundry\instantiate()` -> `Zenstruck\Foundry\object()` | ||
| - `Zenstruck\Foundry\repository()` -> `Zenstruck\Foundry\Persistence\repository()` | ||
| - `Zenstruck\Foundry\Factory::delayFlush()` -> `Zenstruck\Foundry\Persistence\flush_after()` | ||
| - Usage of any method in `Zenstruck\Foundry\Test\TestState` should be replaced by `Zenstruck\Foundry\Test\UnitTestConfig::configure()` | ||
| - `Zenstruck\Foundry\instantiate_many()` is removed without any replacement | ||
| - `Zenstruck\Foundry\create_many()` is removed without any replacement | ||
|
|
||
| ## Trait `Factories` | ||
| - `Factories::disablePersist()` -> `Zenstruck\Foundry\Persistence\disable_persisting()` | ||
| - `Factories::enablePersist()` -> `Zenstruck\Foundry\Persistence\enable_persisting()` | ||
| - both `disablePersist()` and `enable_persisting()` should not be called when Foundry is booted without Doctrine (ie: in a unit test) | ||
|
|
||
| ## Bundle configuration | ||
|
|
||
| Here is a diff of the bundle's configuration, all configs in red should be migrated to the green ones: | ||
|
|
||
| ```diff | ||
| zenstruck_foundry: | ||
| - auto_refresh_proxies: null | ||
| instantiator: | ||
| - without_constructor: false | ||
| + use_constructor: true | ||
| + orm: | ||
| + auto_persist: true | ||
| + reset: | ||
| + connections: [default] | ||
| + entity_managers: [default] | ||
| + mode: schema | ||
| + mongo: | ||
| + auto_persist: true | ||
| + reset: | ||
| + document_managers: [default] | ||
| - database_resetter: | ||
| - enabled: true | ||
| - orm: | ||
| - connections: [] | ||
| - object_managers: [] | ||
| - reset_mode: schema | ||
| - odm: | ||
| - object_managers: [] | ||
| ``` | ||
|
|
||
| ## Misc. | ||
| - type-hinting to `Zenstruck\Foundry\RepositoryProxy` should be replaced by `Zenstruck\Foundry\Persistence\RepositoryDecorator` | ||
| - type-hinting to `Zenstruck\Foundry\RepositoryAssertions` should be replaced by `Zenstruck\Foundry\Persistence\RepositoryAssertions` | ||
|
|
||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.