Skip to content

[stable31] fix: Move changes to backend section in upgrade_to_31.rst #13047

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 22, 2025
Merged

[stable31] fix: Move changes to backend section in upgrade_to_31.rst #13047

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
251 changes: 124 additions & 127 deletions developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_31.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,17 +51,122 @@ to check whether the current Files app instance is a public share or not, and if
console.info('This is a public share with the sharing token: ', getSharingToken())
}

Added APIs
^^^^^^^^^^

Changed APIs
^^^^^^^^^^^^

Deprecated APIs
^^^^^^^^^^^^^^^

Removed APIs
^^^^^^^^^^^^

- ``OCA.FilesSharingDrop`` removed as part of the Vue migration. Use the Files app API provided by the :ref:`package<js-library_nextcloud-files>` .
- ``$.Event('OCA.Notification.Action')`` jQuery event removed from Notifications app as part of the Vue migration. Use ``@nextcloud/event-bus`` :ref:`package<js-library_nextcloud-event-bus>` instead.

.. code-block:: JavaScript

import { subscribe, unsubscribe } from '@nextcloud/event-bus'

subscribe('notifications:action:execute', (event) => {
console.info('Notification action has been executed:', event.notification, event.action)
})

Back-end changes
----------------

Support for PHP 8.4 added
^^^^^^^^^^^^^^^^^^^^^^^^^

In this release support for PHP 8.4 was added. Follow the steps below to make your app compatible.

1. If ``appinfo/info.xml`` has a dependency specification for PHP, increase the ``max-version`` to 8.4.
However, it is recommended to always support all PHP versions that are compatible with supported Nextcloud version.
In that case the ``php``-dependencies entries can be omitted.

.. code-block:: xml

<dependencies>
<php min-version="8.1" max-version="8.4" />
<nextcloud min-version="29" max-version="31" />
</dependencies>


2. If your app has a ``composer.json`` and the file contains the PHP restrictions from ``info.xml``, adjust it as well.

.. code-block:: json

{
"require": {
"php": ">=8.1 <=8.4"
}
}

3. If you have :ref:`continuous integration <app-ci>` set up, extend your test matrix with PHP 8.4 tests and linters.
This happens automatically when you reuse our `GitHub Workflow templates <https://github.com/nextcloud/.github>`__,
but you can also use the underlying `icewind1991/nextcloud-version-matrix Action <https://github.com/icewind1991/nextcloud-version-matrix>`__ directly.

Information about code changes can be found on `php.net <https://www.php.net/migration84>`__ and `stitcher.io <https://stitcher.io/blog/new-in-php-84>`__.

Added APIs
^^^^^^^^^^

- If an app supports file conversion, it may now register an ``\OCP\Files\Conversion\ConversionProvider`` which will
- It is now possible to download folders as zip or tar archives using the WebDAV backend using :code:`GET` requests.
See the relevant :ref:`endpoint documentation<webdav-download-folders>`.
- ``OCP\SetupCheck\CheckServerResponseTrait`` was added to ease implementing custom :ref:`setup checks<setup-checks>`
which need to check HTTP calls to the the server itself.
- Any implementation of ``OCP\Files\Mount\IMountPoint`` can additionally implement ``OCP\Files\Mount\IShareOwnerlessMount`` which allows everyone with share permission to edit and delete any share on the files and directories below the mountpoint.
- ``OCP\Navigation\Events\LoadAdditionalEntriesEvent`` is dispatched when the navigation manager needs to know about its entries, apart of standard app entries that are loaded automatically. This is only relevant for apps that provide extraneous entries.
- ``OCP\User\Backend\ILimitAwareCountUsersBackend`` was added as a replacement for ``ICountUsersBackend``. It allows to specify a limit to the user count to avoid counting all users when the caller do not need it. You can safely ignore the limit if it does not make sense for your usecase.
- If an app supports file conversion, it may now register an ``OCP\Files\Conversion\ConversionProvider`` which will
be called automatically based on the supported MIME types. An app may register as many of these as needed.
- New events ``OCP\User\Events\BeforeUserIdUnassignedEvent``, ``OCP\User\Events\UserIdUnassignedEvent``, and ``OCP\User\Events\UserIdAssignedEvent`` have been added to replace the hooks ``\OC\User::preUnassignedUserId``, ``\OC\User::postUnassignedUserId`` and ``\OC\User::assignedUserId``.

Changed APIs
^^^^^^^^^^^^

- Clarify ``OCP\Files\Storage\IStorage::getOwner()`` returns ``string|false``.
- Added method parameter and return types to all inheritors of ``OCP\Files\Storage\IStorage``. To migrate in a backwards compatible manner:

#. Add all return types to your implementation now.
#. Add all parameter types to your implementation once Nextcloud 31 is the lowest supported version.

- The Nextcloud implementation of the ``log`` method of ``Psr\Log\LoggerInterface`` now supports ``Psr\Log\LogLevel`` as log level parameter.
- The ``OCP\DB\QueryBuilder\IQueryBuilder`` now supports more date / time related parameter types:

- ``PARAM_DATE_MUTABLE`` and ``PARAM_DATE_IMMUTABLE`` for passing a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance when only interested in the date part.
- ``PARAM_TIME_MUTABLE`` and ``PARAM_TIME_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance when only interested in the time part.
- ``PARAM_DATETIME_MUTABLE`` and ``PARAM_DATETIME_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance without handling of the timezone.
- ``PARAM_DATETIME_TZ_MUTABLE`` and ``PARAM_DATETIME_TZ_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance with handling of the timezone.

- The ``OCP\\DB\\Types`` now support more date and time related types for usage with the ``Entity``:

- ``DATE_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with only the date part set.
- ``TIME_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with only the time part set.
- ``DATETIME_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with both the time part set but without timezone information.
- ``DATETIME_TZ`` for fields that will (de)serialized as ``\DateTime`` instances with both the time part set and with timezone information.
- ``DATETIME_TZ_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with both the time part set and with timezone information.

- It's now possible to paginate DAV requests with new headers.

- First request should contains the following headers:

- ``X-NC-Paginate: true`` enables the functionality
- ``X-NC-Paginate-Count: X`` sets the number of results per page (default 100)

- Server will answer with new headers:

- ``X-NC-Paginate-Total`` indicates the total number of results.
- ``X-NC-Paginate-Token`` gives a token to access other pages of the same result.

- Issue new requests with token:

- ``X-NC-Paginate-Token: xxx`` contains the token as sent by the server
- ``X-NC-Paginate-Count: X`` sets the number of results per page (default 100)
- ``X-NC-Paginate-Offset: Y`` sets the offset (number of ignored results) for the required page (usually "page_number × page_size")

- Legacy class ``OC_Image`` was moved to ``OC\Image``. You should never use it directly but use ``new \OCP\Image()`` instead for building the object and the ``OCP\IImage`` interface for calling methods.
- ``OCP\Preview\BeforePreviewFetchedEvent`` constructor has a new parameter ``$mimeType`` which should be a string or null.
- It has a new method ``getMimeType()`` to get the new property.
Expand All @@ -70,21 +175,29 @@ Changed APIs
Deprecated APIs
^^^^^^^^^^^^^^^

- The ``/s/{token}/download`` endpoint for downloading public shares is deprecated.
Instead use the Nextcloud provided :ref:`WebDAV endpoint<webdav-download-folders>`.
- ``OCP\DB\QueryBuilder\IQueryBuilder::PARAM_DATE`` is deprecated in favor of ``PARAM_DATETIME_MUTABLE``
to make clear that this type also includes the time part of a date time instance.
- ``OCP\User\Backend\ICountUsersBackend`` was deprecated. Please implement and use ``OCP\User\Backend\ILimitAwareCountUsersBackend`` instead.
- Hooks ``\OC\User::preUnassignedUserId``, ``\OC\User::postUnassignedUserId`` and ``\OC\User::assignedUserId`` are deprecated, use the new events in OCP instead.

Removed APIs
^^^^^^^^^^^^

- ``OCA.FilesSharingDrop`` removed as part of the Vue migration. Use the Files app API provided by the :ref:`package<js-library_nextcloud-files>` .
- ``$.Event('OCA.Notification.Action')`` jQuery event removed from Notifications app as part of the Vue migration. Use ``@nextcloud/event-bus`` :ref:`package<js-library_nextcloud-event-bus>` instead.

.. code-block:: JavaScript

import { subscribe, unsubscribe } from '@nextcloud/event-bus'

subscribe('notifications:action:execute', (event) => {
console.info('Notification action has been executed:', event.notification, event.action)
})
- Legacy, non functional, ``OC_App::getForms`` was removed.
- The private and legacy ``OC_Files`` class was removed.
Instead use ``OCP\AppFramework\Http\StreamResponse`` or ``OCP\AppFramework\Http\ZipResponse``.
- The private and legacy Ajax endpoint for downloading file archives (``/apps/files/ajax/download.php``) was removed.
Instead use the Nextcloud provided :ref:`WebDAV endpoint<webdav-download-folders>`.
- All ``OCP\ILogger`` logging methods, deprecated since Nextcloud 20, are removed.
- The interface now only holds the Nextcloud internal logging level constants.
For all logging ``Psr\Log\LoggerInterface`` should be used.
- The ``OCP\ILogger`` interface can no longer be dependency injected as it now only holds constants.
- ``OCP\IServerContainer::getLogger`` was removed, use dependency injection with ``Psr\Log\LoggerInterface`` instead.
- The internal class ``OC\AppFramework\Logger`` was removed, it should have been never used by apps.
All using apps should migrate to ``Psr\Log\LoggerInterface``.
- Legacy endpoint to test remote share endpoint (``/testremote``) was removed.

- Legacy class ``OC_API`` was moved to a private namespace. It should not be needed by applications.
- Deprecated interface ``OCP\Files\Storage`` was removed. Use ``OCP\Files\Storage\IStorage`` instead.
Expand Down Expand Up @@ -223,119 +336,3 @@ Removed APIs
- ``OCP\AppFramework\Utility\ITimeFactory::class``
* - Defaults
- ``OCP\Defaults::class``

Back-end changes
----------------

Support for PHP 8.4 added
^^^^^^^^^^^^^^^^^^^^^^^^^

In this release support for PHP 8.4 was added. Follow the steps below to make your app compatible.

1. If ``appinfo/info.xml`` has a dependency specification for PHP, increase the ``max-version`` to 8.4.
However, it is recommended to always support all PHP versions that are compatible with supported Nextcloud version.
In that case the ``php``-dependencies entries can be omitted.

.. code-block:: xml

<dependencies>
<php min-version="8.1" max-version="8.4" />
<nextcloud min-version="29" max-version="31" />
</dependencies>


2. If your app has a ``composer.json`` and the file contains the PHP restrictions from ``info.xml``, adjust it as well.

.. code-block:: json

{
"require": {
"php": ">=8.1 <=8.4"
}
}

3. If you have :ref:`continuous integration <app-ci>` set up, extend your test matrix with PHP 8.4 tests and linters.
This happens automatically when you reuse our `GitHub Workflow templates <https://github.com/nextcloud/.github>`__,
but you can also use the underlying `icewind1991/nextcloud-version-matrix Action <https://github.com/icewind1991/nextcloud-version-matrix>`__ directly.

Information about code changes can be found on `php.net <https://www.php.net/migration84>`__ and `stitcher.io <https://stitcher.io/blog/new-in-php-84>`__.

Added APIs
^^^^^^^^^^

- It is now possible to download folders as zip or tar archives using the WebDAV backend using :code:`GET` requests.
See the relevant :ref:`endpoint documentation<webdav-download-folders>`.
- ``OCP\SetupCheck\CheckServerResponseTrait`` was added to ease implementing custom :ref:`setup checks<setup-checks>`
which need to check HTTP calls to the the server itself.
- Any implementation of ``OCP\Files\Mount\IMountPoint`` can additionally implement ``OCP\Files\Mount\IShareOwnerlessMount`` which allows everyone with share permission to edit and delete any share on the files and directories below the mountpoint.
- ``OCP\Navigation\Events\LoadAdditionalEntriesEvent`` is dispatched when the navigation manager needs to know about its entries, apart of standard app entries that are loaded automatically. This is only relevant for apps that provide extraneous entries.
- ``OCP\User\Backend\ILimitAwareCountUsersBackend`` was added as a replacement for ``ICountUsersBackend``. It allows to specify a limit to the user count to avoid counting all users when the caller do not need it. You can safely ignore the limit if it does not make sense for your usecase.

Changed APIs
^^^^^^^^^^^^

- Clarify ``OCP\Files\Storage\IStorage::getOwner()`` returns ``string|false``.
- Added method parameter and return types to all inheritors of ``OCP\Files\Storage\IStorage``. To migrate in a backwards compatible manner:

#. Add all return types to your implementation now.
#. Add all parameter types to your implementation once Nextcloud 31 is the lowest supported version.

- The Nextcloud implementation of the ``log`` method of ``Psr\Log\LoggerInterface`` now supports ``Psr\Log\LogLevel`` as log level parameter.
- The ``OCP\DB\QueryBuilder\IQueryBuilder`` now supports more date / time related parameter types:

- ``PARAM_DATE_MUTABLE`` and ``PARAM_DATE_IMMUTABLE`` for passing a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance when only interested in the date part.
- ``PARAM_TIME_MUTABLE`` and ``PARAM_TIME_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance when only interested in the time part.
- ``PARAM_DATETIME_MUTABLE`` and ``PARAM_DATETIME_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance without handling of the timezone.
- ``PARAM_DATETIME_TZ_MUTABLE`` and ``PARAM_DATETIME_TZ_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance with handling of the timezone.

- The ``OCP\\DB\\Types`` now support more date and time related types for usage with the ``Entity``:

- ``DATE_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with only the date part set.
- ``TIME_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with only the time part set.
- ``DATETIME_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with both the time part set but without timezone information.
- ``DATETIME_TZ`` for fields that will (de)serialized as ``\DateTime`` instances with both the time part set and with timezone information.
- ``DATETIME_TZ_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with both the time part set and with timezone information.

- It's now possible to paginate DAV requests with new headers.

- First request should contains the following headers:

- ``X-NC-Paginate: true`` enables the functionality
- ``X-NC-Paginate-Count: X`` sets the number of results per page (default 100)

- Server will answer with new headers:

- ``X-NC-Paginate-Total`` indicates the total number of results.
- ``X-NC-Paginate-Token`` gives a token to access other pages of the same result.

- Issue new requests with token:

- ``X-NC-Paginate-Token: xxx`` contains the token as sent by the server
- ``X-NC-Paginate-Count: X`` sets the number of results per page (default 100)
- ``X-NC-Paginate-Offset: Y`` sets the offset (number of ignored results) for the required page (usually "page_number × page_size")

Deprecated APIs
^^^^^^^^^^^^^^^

- The ``/s/{token}/download`` endpoint for downloading public shares is deprecated.
Instead use the Nextcloud provided :ref:`WebDAV endpoint<webdav-download-folders>`.
- ``OCP\DB\QueryBuilder\IQueryBuilder::PARAM_DATE`` is deprecated in favor of ``PARAM_DATETIME_MUTABLE``
to make clear that this type also includes the time part of a date time instance.
- ``OCP\User\Backend\ICountUsersBackend`` was deprecated. Please implement and use ``OCP\User\Backend\ILimitAwareCountUsersBackend`` instead.

Removed APIs
^^^^^^^^^^^^

- Legacy, non functional, ``OC_App::getForms`` was removed.
- The private and legacy ``OC_Files`` class was removed.
Instead use ``OCP\AppFramework\Http\StreamResponse`` or ``OCP\AppFramework\Http\ZipResponse``.
- The private and legacy Ajax endpoint for downloading file archives (``/apps/files/ajax/download.php``) was removed.
Instead use the Nextcloud provided :ref:`WebDAV endpoint<webdav-download-folders>`.
- All ``OCP\ILogger`` logging methods, deprecated since Nextcloud 20, are removed.
- The interface now only holds the Nextcloud internal logging level constants.
For all logging ``Psr\Log\LoggerInterface`` should be used.
- The ``OCP\ILogger`` interface can no longer be dependency injected as it now only holds constants.
- ``OCP\IServerContainer::getLogger`` was removed, use dependency injection with ``Psr\Log\LoggerInterface`` instead.
- The internal class ``OC\AppFramework\Logger`` was removed, it should have been never used by apps.
All using apps should migrate to ``Psr\Log\LoggerInterface``.
- Legacy endpoint to test remote share endpoint (``/testremote``) was removed.