Upgrade path from v2 to v3

[n-valverde]

API Platform version(s) affected: 2.7

Description
Hello,

I am currently migrating a big application from v2 to v3, and I am a bit disappointed by how hard the upgrade path is.
I truly understand the intentions of the v3, but I think the upgrade path from v2 should receive more attention, as there is probably a lot of app still in v2 out there. That leads me to the first point:

• While api-platform follows Symfony's BC promise, it does not follow the same release strategy, i.e the v2.7 is not considered "long-term".

I don't want to bring a debate about LTS, but I do want to highlight that the documentation clearly states that 2.7 is maintained for security fixes only, which leaves people like me understanding that nothing will get fixed in 2.7, even if that prevents a smooth upgrade path.
That's probably not completely true, and I'm assuming maintainers are judging on a case by case basis, but I also came across a few closed issues were the output was: it's 2.7 so won't fix.
But today, @mtarld gave a nice little talk, where he said you would happily accept contributions to improve the upgrade path 😄 so here I am, still confused but optimistic 😄.

So first question: can we contribute on v2.7 to improve the upgrade path? If yes, can we update the documentation to make it clear the api-platform is not leaving people behind. I'd be happy to contribute, but as I said right now I'm just confused on whether we can contribute to 2.7 or not.

If the answer of the above is no, no need to read further 🙃

The below is a summary of issues I've encountered so far and where I'd be happy to contribute, just don't want to spam new issues

• bin/console api:upgrade-resource

That command is mostly broken, because it completely mess up the formatting, and cs-fixer is clearly not enough to fix the mess. In a big application, where the command needs to alter roughly 200 files, that's an issue. It currently alter source code, while it's supposed to deal with annotations and attributes, but is adding/removing parenthesis in method bodies, adding/removing whitespaces and blanklines litterally everywhere.

I left a little fix for that in another closed issue (not perfect but enough to make the command usable). But that also brings the question of: why not just rector?

• Rector rules

Apart from the above question of why not rector for the upgrade resource command, I am also confused to not find any rector rule out there helping with the namespace updates. There are a lot of namespace changes, some are very simple to fix, others pretty hard, but it would be nice to have some rector rules to help. Did I miss them somewhere?

I would love to find a, let's say rector/rector-api-platform for example 😄

• Unsolvable deprecations

While the upgrade path should be to resolve deprecations prior to turning any BC flag off (or to upgrade to next major), api-platform currently throw deprecations that are purely not solvable.
Because of the new metadata system and the BC layer, the services available in the container are different with BC flag on or off.
That leads to situation where you cannot get rid of the deprecation, because the service you need is purely not available, so you have to turn that BC flag off, and your whole app explode (makes sense) and then you cannot fix smoothly the deprecation. That leads to bigbang upgrade situation, which I am currently living 🙃 , and this is mostly why major upgrades ends up being postponed forever in companies.

One good exemple of that is the new IriConverterInterface, which basically cannot be injected with BC flag on, leading to a type error because the container is injecting the old service, which does not implement the interface you're trying to inject.

Another good example of that is userland service decoration, where in some cases you can't decorate the new services because they're basically not available, so can't fix deprecation.

There are probably other examples, I am still in the upgrade path trying to solve issues one by one 🙃

• Documentation issues

Some deprecation messages are very unclear, and the documentation does not really help. The best example I have for that is

Since api-platform/core 2.7: An anonymous resource will use a Skolem IRI in API Platform 3.0. Use #[ApiProperty(genId: false)] to keep this behavior in 3.0

Api-platform documentation never mentions what an anonymous resource is, and only mention once the Skolem iri. It's really hard to understand if any action should be taken by the user about this deprecation (and AFAIK, most users can just ignore this right?)

I did not find the alternate method for php8.0 that @mtarld showed us today in the documentation, did I miss it? I only found documentation using attributes with new in initializers, which cannot be used prior to php8.1

Also, the upgrade guide has some updates in its 3.1 version, which are not there if you read the upgrade guide on 2.7 🙃

• Final thoughts

Thanks for reading 😄 , I truly hope we can make that upgrade path better 🤞
Cheers!

[soyuka]

Hi,

Yes I'm 👍 to merge anything that helps with the backward compatibility on 2.7 but I don't want to fix bugs as:

• they're probably fixed on 3.1
• it's hard to maintain as we need to merge 2.7 into 3.0 and it is a pain

That command is mostly broken, because it completely mess up the formatting, and cs-fixer is clearly not enough to fix the mess. In a big application, where the command needs to alter roughly 200 files, that's an issue.

Excuse me but this is totally wrong as the produced code works. If cs-fixer doesn't fixes your attributes properly you can use prettier with the php extension which is a bit better but still will need you to do hand changes and we can't do much about it. Another solution is to do everything by hand.
Why not rector? We used rector at first, but rector is not near to a stable version, and in a few months every interface broke and we had to suffer again to make everything work. We decided to use the php parser directly, which in the end is what rector does.

This script helps but indeed, it's not perfect, although I think that it is very appreciated by the community and it was a really hard work (~6 months work).
By criticizing this work it's like you're spitting on me and everyone that worked hard on this so bear with us. You should use this script and change it to cover your needs. Note that on top of that it's a script that is useful only to migrate from 2.7 to 3.0 and it got removed from current branches so adding more effort on something that is "fire and forget" is not easy. I'll obviously accept patches but I don't want to spend too much time on it I've more urgent work (state providers, documentation).

Just like #5595 I'll accept work on this upgrade path but it's hard to accept criticism without code.

Unsolvable deprecations

Yes you can have code with deprecations, they'll get fixed when you'll remove the flag. I think it's better to have deprecations then not to. If you find a way to silent them or we made a mistake, please provide a patch on 2.7. The work between 2.7 and 3.0 was really hard, it took 2 years and it's open source software. I'm not surprised that some of the deprecation are not perfect.

Since api-platform/core 2.7: An anonymous resource will use a Skolem IRI in API Platform 3.0. Use #[ApiProperty(genId: false)] to keep this behavior in 3.0

An anonymous resource is a class that is not marked with ApiResource. Usually you get that when you're resource has an object property. In 3.0, every resource has an @id which will be generated if it can't be found. This may break your tests and we provide the genId option if you don't want an @id to be generated. IMHO its your work as developer to look for the corresponding patches: #5046 which should explain everything. We did some work to improve our changelogs and release cycle...

Documentation issues

Yes, I'm aware. I'm currently working hard on improving the documentation A LOT. Still this is a lot of work but we see progress. The new api platform website should come out this month, and by the 3.2 release we should have better docs, or at least documentation that'll be easier to contribute. I'll explain that during my conference at the API Platform con.

On a general note, you need to see this 3.0 version as the gap there was between Symfony 1 and 2. There won't be any hard upgrade paths anymore and if you talked with @mtarld I guess you know why this new version is really good. I understand the frustration but you need to deal with it and help us make it better.
This is free software, I work a lot on this and I almost didn't wanted to answer this as I see only negativity. I'll end by quoting the license:

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Peace.

[n-valverde]

Hello @soyuka , just wanted to give a quick follow up here, I did not mean to blame anyone so I'm sorry if you felt offended, my point was just to give feedback and ask if we can contribute to 2.7 to make this feedback better in the future 😄 .

If you don't mind, I'd like to keep this issue opened as I might send more PRs in a (hopefully) near future, and I think this issue is a good tracking one. I am also considering a contrib to rector/rector-symfony to add some rules there, I think that's the best place for them (not rules for "annotations to attributes" obviously 😄 just for all the namespaces & interface contracts updates)

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.