Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update docs for foundry v2 #613

Merged
merged 1 commit into from
Jun 7, 2024
Merged

docs: update docs for foundry v2 #613

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .symfony.bundle.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
branches: ["1.x", "1.23.x"]
maintained_branches: ["1.x", "1.23.x"]
branches: ["2.x", "1.x"]
maintained_branches: ["2.x", "1.x"]
doc_dir: "docs/"
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I put the 2.x in first position, I don't know how it would impact the order in the symfony docs. I'm assuming the first one is the default one

32 changes: 19 additions & 13 deletions UPGRADE-2.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,14 @@ The global philosophy is still the same.
The main change 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".
While Foundry 1.x was "persistence first", Foundry 2 is "object first".
This would allow more decoupling from the persistence layer.

## How to

Every modification needed for a 1.x to 2.0 migration is covered by a deprecation.
You'll to upgrade to the latest 1.x version, and to activate the deprecation helper, make the tests run, and
fix all the deprecations reported.
You'll need to upgrade to the latest 1.x version, activate the deprecation helper,
make the tests run, and fix all the deprecations reported.

Here is an example of how the deprecation helper can be activated.
You should set the `SYMFONY_DEPRECATIONS_HELPER` variable in `phpunit.xml` or `.env.local` file:
Expand All @@ -24,6 +24,15 @@ SYMFONY_DEPRECATIONS_HELPER="max[self]=0&max[direct]=0&quiet[]=indirect&
> Some deprecations can also be sent during compilation step.
> These deprecations can be displayed by using the command: `$ bin/console debug:container --deprecations`

> [!WARNING]
> If using PHPUnit 10 or above, Symfony's PHPUnit bridge is not compatible, and configuring `SYMFONY_DEPRECATIONS_HELPER`
> is not useful. Instead, you'll need to add `ignoreSuppressionOfDeprecations=true` to the `<source>` tag in `phpunit.xml`
> and run PHPUnit with the `--display-deprecations` option.

> [!TIP]
> PHPStan plugin [`phpstan/phpstan-deprecation-rules`](https://github.com/phpstan/phpstan-deprecation-rules) might also
> be useful to detect the remaining deprecations.

## Rector rules

In the latest 1.x version, you'll find [rector rules](https://getrector.org/) which will help with the migration path.
Expand Down Expand Up @@ -62,11 +71,11 @@ vendor/bin/rector process
> and then fix all deprecations left.

> [!TIP]
> You can try to run twice these rules. Sometimes, the second run will find some difference that it could not spot on
> You can try to run these rules twice. 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.0, it is not necessary anymore to keep the Foundry's rule set in your Rector
> Once you've finished the migration to 2.0, it is not necessary to keep the Foundry rule set in your Rector
> config.

### Doctrine's mapping
Expand All @@ -91,7 +100,7 @@ $kernel->boot();
return $kernel->getContainer()->get('doctrine')->getManager();
```

2. Provide this file path to Rector's config:
2. Set this file path in Rector's config:

```php
<?php
Expand Down Expand Up @@ -156,13 +165,13 @@ You should choose between:
- `\Zenstruck\Foundry\Persistence\PersistentProxyObjectFactory`: same as above, but returns a "proxy" version of the object.
This last class basically acts the same way as the old `ModelFactory`.

As a rule of thumb to help you to choose between these two new factory parent classes:
As a rule of thumb to help you choose between these two new factory parent classes:
- using `ObjectFactory` is straightforward: if the object cannot be persisted, you must use this one
- only entities (ORM) or documents (ODM) should use `PersistentObjectFactory` or `PersistentProxyObjectFactory`
- you should only use `PersistentProxyObjectFactory` if you want to leverage "auto refresh" behavior

> [!WARNING]
> nor `PersistentObjectFactory` or `PersistentProxyObjectFactory` should be chosen to create not persistent objects.
> Neither `PersistentObjectFactory` or `PersistentProxyObjectFactory` should be chosen to create not persistent objects.
> This will throw a deprecation in 1.x and will create an error in 2.0

> [!IMPORTANT]
Expand Down Expand Up @@ -216,8 +225,8 @@ protected function initialize(); static

### 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.
Foundry 2.0 will completely change how the `Proxy` system works, by leveraging Symfony's lazy proxy mechanism.
`Proxy` will no longer be 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:
Expand Down Expand Up @@ -296,6 +305,3 @@ zenstruck_foundry:
- 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`
- Methods in `Zenstruck\Foundry\RepositoryProxy` do not return `Proxy` anymore, but they return the actual object



Loading
Loading