Doc - How easy is it to upgrade from the old version of the package with the new version?

[lironesamoun]

Is there (or Will there) be any tutorial for upgrading ?
Thank

[lironesamoun]

And is it possible to make both work at the same time ?

[lindyhopchris]

Hey! Thanks for asking this question, it's probably useful for me to put an answer here so other people can see too.

I haven't spent any time on working out an upgrade tutorial yet. My thinking was I'd probably want this new package to get to 1.0.0-rc.1 before doing that. That's because there's been a lot of things for me to do, so I don't want to write a tutorial that I have to keep adjusting as I work my way through the remaining things in the beta series.

I'd originally envisaged a gradual upgrade process, but unfortunately as I've been pushed to put more and more information into the schemas this is now looking unlikely - as basically you need the schema for everything else to work. I've upgraded one of my production APIs. That involved going through and converting all the old classes to the new classes rather than it being a gradual swap over.

My main tip for upgrading is this: the test suite has barely changed at all. I do TDD so the thing that made that upgrade easier was I had a solid set of tests that I could run after the upgrade to make sure everything passed. If you're planning to upgrade at some point, then making sure you've got a great set of tests in the meantime really helps.

And is it possible to make both work at the same time ?

No. The new package is using v4 of the neomerx/jsonapi encoder package, whereas the old one is on v1. There were technical problems in the old package with upgrading that dependency to v4 that I never managed to convince neomerx that he needed to address. In the past I've investigated upgrading the dependency in the old package, but it was too complex an upgrade - and I don't think it's useful to force that upon users of the old package when the target is actually to get them to eventually switch to laravel-json-api/laravel.

Once I get laravel-json-api/laravel to 1.0.0-rc.1 I'll probably revisit the old package and start investigating whether I can make changes to the old package that would present easier stepping stones to a full upgrade. I haven't started that investigation yet, but will update this issue when I do.

One thing I want to make really clear here is that the old package (cloudcreativity/laravel-json-api) is still supported for bug fixes, and will receive updates for new Laravel versions. I'm really conscious that people are using that package in production applications (including me) so I'm not going to abandon it until there is an upgrade path and sufficient time has passed for people to upgrade. I.e. that won't be any time soon!

Feel fre to drop more questions or thoughs on this issue!

[Patrick-M90]

Hello, are there any updates on how to upgrade from the old cloudcreativity package to the new one?

Best regards

Patrick

[Patrick-M90]

Hello,

I really would like to upgrade my growing project to the new package. Do you have a guide or tutorial for me on how to do this efficiently?

Thank you very much. :)

[lironesamoun]

Up :)

[lindyhopchris]

Hi. This is on my radar. I need to focus on getting Laravel 9 support out in the next week, then I can think about putting together some sort of upgrade guide.

Just to reiterate a point I've made above...

The test suite has barely changes between the two packages, so having a great set of tests really helps with the upgrade.

Just putting that out there now because if you haven't got a great set of tests, then putting some time into that pre-upgrade will be really useful.

[vrusua]

Up :) Thanks in advance!

[lindyhopchris]

Yep, haven't forgotten. FYI I'm currently working on this issue:
cloudcreativity/laravel-json-api#632

Then I can turn my attention to this issue, as this issue follows on from that one. I am slightly limited on Open Source time at the moment but am trying to keep things progressing.

[vrusua]

@lindyhopchris Chris, thanks for the update and awesome news regarding the #632 issue progress. Cheers.

[lindyhopchris]

For info, if you're on the old package cloudcreativity/laravel-json-api, I've just tagged an alpha release v5.0.0-alpha.1. That release upgrades the Neomerx package so both the old package and this new one (laravel-json-api/laravel) are on the same Neomerx package version.

As explained in the upgrade guide, this unlocks being able to install both the old and the new packages in the same application. You can't mix classes from both packages in a single API, but it allows you to have one API using the old package, and one using the new package.

The upgrade guide for the old package to get it onto the alpha release is here:
https://github.com/cloudcreativity/laravel-json-api/blob/v5.0.0-alpha.1/docs/upgrade.md

I don't have any applications using the old package any more, so I really need people to try out the alpha release and let me know if there are any problems with it, or anything that should be in the upgrade guide that isn't. If you find any problems, report them as issues in the cloudcreativity/laravel-json-api repo, making it clear you're using the 5.0 alpha release.

[swichers]

I recently did an upgrade of an application from v2 -> v3 -> v4 -> v5 and everything went relatively smoothly. This application has pretty decent test coverage that uses a lot of the JSONAPI helpers. I did not have to do anything outside of the upgrade guides. Once the listed changes were completed all tests continue to pass.

The only hiccup I hit was doing the v3 to v4 upgrade. We were using $this->jsonApi()->data(...) which was removed in favor of using withData. The upgrade guide does not call this out clearly (it's a footnote under an example codeblock instead of being listed alongside other removed methods).

The only thing that wasn't addressed was usage of Neomerx\JsonApi\Exceptions\JsonApiException for the exception handler.

I went through the install docs for each version and they all reference this Neomerx class, so I presume it is correct to keep using it. I'd recommend adding a note about it in the v5 documentation to remove confusion.

Before

cloudcreativity/json-api-testing            v3.2.0
cloudcreativity/laravel-json-api            v2.2.0
neomerx/json-api                            v1.0.9

After

cloudcreativity/json-api-testing            v4.0.0
cloudcreativity/laravel-json-api            v5.0.0-alpha.1
laravel-json-api/neomerx-json-api           v5.0.1
laravel-json-api/testing                    v1.1.1