Tutorial APIs using deprecated APIs

Reading the starting tutorial at Nextcloud it shows code that uses the OCA namespace (e.g. OCA.Files.fileActions.registerAction()).

Reading JavaScript APIs — Nextcloud latest Developer Manual latest documentation it tells us:

  • The APIs used to be provided via global variables, available on most pages of Nextcloud. To smoothen the development experience with modern development tools, this method is in the process of being deprecated and removed. Existing APIs are being migrated to npm packages and new APIs will only be available that way.
  • There are also global variables that acted as APIs in the past. The use of these variables is discouraged

So, it seems rather clear to me that the newer NPM APIs are what one should be using. Then how come the tutorial (and possibly the other tutorials too?) are showing the old and deprecated way of writing app code? (I’m thinking, “Am I missing something?”.)

On a related note, the tutorial also says to add $container = $this->getContainer(); which returns an instance implementing IAppContainer, for which Nextcloud PHP API (master) says “The interface currently extends IContainer, but this interface is deprecated as of Nextcloud 20, thus this interface won’t extend it anymore once that was removed. So migrate to the ContainerInterface only.”

It kind of seems like the tutorial is teaching the reader to write deprecated code?

Here i think you must distinguish between frontend in Javascript and backend in PHP.

The frontend typically uses npm. There was an ancient global variable OC in the page present that allowed to access various functionality of the core. This has been deprecated and replaced by imported functions.

In the backend the story is a bit different. There are three different namespaces.

  • First there is the namespace OCP for public classes and interfaces. You are free to use them. They are rather stable.
  • In contrast the is the internal OC namespace that represents the internal classes of the core. These might change without prior notice. (Please keep in mind to not get confused by the ancient JavaScript variable, as described above.)
  • Finally, there is the OCA namespace. All apps get their own namespace within that namespace to separate the classes of the different apps.

So, i see not the problem with the code as mentioned in the first post. Most probably this was a misunderstanding.


Regarding the second post:

The quoted command getContainer() would be perfectly fine. It will return an appropriate container. Depending on the location and the type of $this, you will get some class implementing these interfaces.

Now that one interfaces is a subset of the other. So, this deprecation will not remove functionality.

The important parts are more these

  • you should not Import IContainer anymore. It will break in the future. Just use the ContainerInterface instead.
  • the same holds true for PHP doc annotations
  • typically you do not work with containers much. If you did, you would request the ContainerInterface object.

If you share a link to the location in the documentation, we might be able to clarify the answer with an example a bit.

Yeah, the first post above is only about the client-side and frontend JS stuff, not the backend.

I guess it’s a bit unclear what the docs I referenced are referring to when they say “The APIs used to be provided via global variables, available on most pages of Nextcloud” and “There are also global variables that acted as APIs in the past”. These texts makes it sound as if all the JS APIs (because of “The APIs”) are subject to being replaced with imported versions, and hence not available through some global variable anymore.

Now, the reason I asked about this is that OCA.Files.fileActions.registerAction() is exactly the opposite, accessing the API using that OCA global variable. And this to me sounds like the tutorial is using deprecated ways of accessing the API. I can only guess that this specific API has not yet been migrated to the new import style of access (?).

But anyway, it’s no big deal. Just one of these things that are unclear when reading the documentation.

Thanks for the little list :slight_smile: I don’t recall seeing that summary anywhere before.

Regarding the second post:

Yeah, this is probably the main point - don’t use this yourself. It’s funny though that in the first tutorial we find, we start seeing usage of things that have been deprecated since v20 - that’s a long time ago. But i digress. Who cares.

I did :slight_smile: It’s Nextcloud PHP API (master) .

1 Like

I meant, where did you find the $container = $this->getContainer(); part? This is rather strange and might only be needed in edge cases to my knowledge. You would use the container implicitly but not explicitly unless you are doing the bootstrap process etc. I wanted to get some context to understand if it was straight outdated (possible) or required for some technical reasons.

The thing with the OCA.Files variable in JS is that the files app is just an app. It is not the core server. Thus, there was the need to provide some way to access the functions for foreign code like other apps.

They could provide a NPM package to access this (in some way) but for now they decided to use the OCA variable as a namespace prefix (in some sense) to allow accessing the files API. I confirm this is not ideal in my opinion.

Ah, sorry I misunderstood. It is in step 6 of the tutorial “Develop a simple files plugin”, direct link here: Nextcloud

Thanks, that makes sense!