From 155d4c217fb532a301bc4e14f96c35b14dd03e0f Mon Sep 17 00:00:00 2001 From: Joas Schilling Date: Fri, 25 Jul 2025 16:12:17 +0200 Subject: [PATCH] feat(developer): Document Consumable vs. Implementable OCP Signed-off-by: Joas Schilling --- .../app_upgrade_guide/upgrade_to_32.rst | 18 ++++++++++++++ developer_manual/digging_deeper/api.rst | 24 +++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_32.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_32.rst index 0f7f1ca6a..ad043b573 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_32.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_32.rst @@ -33,6 +33,24 @@ Removed APIs Back-end changes ---------------- +- OCP API split into consumable and implementable: + For a more informed background see `RFC: Split OCP into Consumable and Implementable `_ for more information. + Short summary: + + - **Consumable:** Interfaces, Enums and classes that have the ``OCP\AppFramework\Attribute\Consumable`` attribute, must only be consumed by apps and can not be implemented by apps themselves. + This means the server side can extend the interface with new methods or reduce returned types of existing methods without it being consider an API break. + However argument types of existing methods can **not** be reduced. + Same rules apply to ``OCP\EventsDispatcher\Event`` that have the ``OCP\AppFramework\Attribute\Listenable`` attribute and ``Exception`` with the ``OCP\AppFramework\Attribute\Catchable`` attribute. + - **Implementable:** Interfaces, Enums and classes that have the ``OCP\AppFramework\Attribute\Implementable`` attribute, can be implemented by apps. + This means the server side can **not** extend the interface with new methods or reduce returned types of existing methods without it being consider an API break. + However argument types of existing methods can be reduced. + Same rules apply to ``OCP\EventsDispatcher\Event`` that have the ``OCP\AppFramework\Attribute\Dispatchable`` attribute and ``Exception`` with the ``OCP\AppFramework\Attribute\Throwable`` attribute. + - **ExceptionalImplementable:** Despite not being implementable for all apps, some interfaces can have the ``OCP\AppFramework\Attribute\ExceptionalImplementable`` attribute indicating that they are implementable by a single app (or multiple). + In those cases the general ``OCP\AppFramework\Attribute\Consumable`` rules apply, but the app maintainers or repository of named exceptions have to be informed during the process of a pull request, leaving them enough time to align with the upcoming change. + +- These new attributes will be applied on a "defacto standard" basis to the best of our knowledge. + In case an API was flagged unexpectedly, leave a comment on the respective pull request in the server repository asking for clarification. + Added APIs ^^^^^^^^^^ diff --git a/developer_manual/digging_deeper/api.rst b/developer_manual/digging_deeper/api.rst index d86ffd5dd..9a01fc76a 100644 --- a/developer_manual/digging_deeper/api.rst +++ b/developer_manual/digging_deeper/api.rst @@ -8,6 +8,30 @@ PHP public API The public API is contained in the OCP namespace. See the `OCP API reference `_ for further details. +The API is split into two categories. Those are indicated by attributes. + +``Consumable``, ``Listenable`` and ``Catchable`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Interfaces, Enums and classes that have the ``OCP\AppFramework\Attribute\Consumable`` attribute, must only be consumed by apps and can not be implemented by apps themselves. +This means the server side can extend the interface with new methods or reduce returned types of existing methods without it being consider an API break. +However argument types of existing methods can **not** be reduced. +Same rules apply to ``OCP\EventsDispatcher\Event`` that have the ``OCP\AppFramework\Attribute\Listenable`` attribute and ``Exception`` with the ``OCP\AppFramework\Attribute\Catchable`` attribute. + +``Implementable``, ``Dispatchable`` and ``Throwable`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Interfaces, Enums and classes that have the ``OCP\AppFramework\Attribute\Implementable`` attribute, can be implemented by apps. +This means the server side can **not** extend the interface with new methods or reduce returned types of existing methods without it being consider an API break. +However argument types of existing methods can be reduced. +Same rules apply to ``OCP\EventsDispatcher\Event`` that have the ``OCP\AppFramework\Attribute\Dispatchable`` attribute and ``Exception`` with the ``OCP\AppFramework\Attribute\Throwable`` attribute. + +``ExceptionalImplementable`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Despite not being implementable for all apps, some interfaces can have the ``OCP\AppFramework\Attribute\ExceptionalImplementable`` attribute indicating that they are implementable by a single app (or multiple). +In those cases the general ``OCP\AppFramework\Attribute\Consumable`` rules apply, but the app maintainers or repository of named exceptions have to be informed during the process of a pull request, leaving them enough time to align with the upcoming change. + PHP unstable API ----------------