The next release of @nextcloud is coming with many API improvements for application developers. This introduces a new way to interact with the database using objects, public APIs to create commands and migrations and a few more conveniences.
You can learn more on my blog post: Modern, Stable APIs for Your Nextcloud Application
Hello and thanks for the heads-up! I do want to ask a few questions based on the blog post.
The new #[AsCommand] attribute seems to make the work easier for devs. I think this is no breaking change but just an option to use actually stable APIs for accessing OCC. Am I correct?
The migration to OCP/DB/Schema should only affect type hinting and type lookup. Thus, functionality is equivalent (probably just encapsulated to allow updating the dependencies without breaking apps). Correct?
Now, it get’s interesting. I assume, the old API is still available and will be removed at most once the current NC (prior to 35) releases are EOL, correct? Will the classical QBMapper-based approach still be present in the long-run? How about the IQueryBuilder?
If there is a legacy app (I am still using good old IQueryBuilder to store the DB data), is there an update path planned? Especially, when thinking to use the ORM, the data should be well-prepared in order to have a realistic chance to keep them in good shape.
Is it advised (for me) to migrate plain SQL → QBMapper → ORM or directly plain SQL → ORM?
Quickly looking at the attributes, there are kind of different notions of tables names in the bidirectional case (mappedBy and invertedBy) which seem to be rather unexplained so far. This seems not 100% compatible with state-of-the-art ORMs as a quick check on Google Gemini brought up all sorts of issues and obvious code smells and bugs. In the worst case, I have to play with it and dig into the code but I would avoid it if there was a clean documentation available.
Are there plans for the *ToMany attributes as well?
How are the criteria (e.g. for Repository::fineOneBy) build up?
Will there be updated documentation on docs.nextcloud.com on all these changes?
Nevertheless, thanks for bringing these up!
Does this mean, that many applications will become incompatible again like during the change from Nextcloud 32 to 33?
Yes, this is correct. The old API is still available, but has a small breaking change due to a Symfony update and might a similar patch like this: refactor(commands): add type hinting to execute method by CarlSchwan · Pull Request #970 · nextcloud/fulltextsearch · GitHub This breaking change was in part my motivation to provide a public API.
Yes, only type hinting changed, but this is affecting fortunately very little app. for now as saw change to mail and tables only as they had some complex migrations.
the old API is still available and will be for a very long time as it is used in so many places. And for the IQueryBuilder there is no plans at all to remove it, it’s important to have a lower level API when working on performance sensitive parts where you want to have full control.
I would migrate from the plain SQL/IQueryBuilder to the ORM. No need to use QBMapper for new code. And this can be done progressively and both system can coexist quite well.
The mappedBy and invertedBy is very much inspired by Doctrine Association Mapping - Doctrine Object Relational Mapper (ORM)
I already updated the doc about the commands feat: Update doc related to commands by CarlSchwan · Pull Request #15429 · nextcloud/documentation · GitHub , I still need to the same for the sql parts.
The only real breaking change is the type hinting issues for the DBAL vs OCP\DB\Schema types. This fortunately only affects few apps as this was only used in complex migrations. All the rest is new APIs that apps can use.