Skip to content

Commit 6f4e159

Browse files
come-nccome-nc
committed
fix: Move changes to backend section in upgrade_to_31.rst
Some backend changes were mistakenly added to frontend section Signed-off-by: Côme Chilliet <[email protected]>
1 parent 1b80300 commit 6f4e159

File tree

1 file changed

+124
-127
lines changed

1 file changed

+124
-127
lines changed

‎developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_31.rst

Lines changed: 124 additions & 127 deletions
Original file line numberDiff line numberDiff line change
@@ -51,17 +51,122 @@ to check whether the current Files app instance is a public share or not, and if
5151
console.info('This is a public share with the sharing token: ', getSharingToken())
5252
}
5353
54+
Added APIs
55+
^^^^^^^^^^
56+
57+
Changed APIs
58+
^^^^^^^^^^^^
59+
60+
Deprecated APIs
61+
^^^^^^^^^^^^^^^
62+
63+
Removed APIs
64+
^^^^^^^^^^^^
65+
66+
- ``OCA.FilesSharingDrop`` removed as part of the Vue migration. Use the Files app API provided by the :ref:`package<js-library_nextcloud-files>` .
67+
- ``$.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.
68+
69+
.. code-block:: JavaScript
70+
71+
import { subscribe, unsubscribe } from '@nextcloud/event-bus'
72+
73+
subscribe('notifications:action:execute', (event) => {
74+
console.info('Notification action has been executed:', event.notification, event.action)
75+
})
76+
77+
Back-end changes
78+
----------------
79+
80+
Support for PHP 8.4 added
81+
^^^^^^^^^^^^^^^^^^^^^^^^^
82+
83+
In this release support for PHP 8.4 was added. Follow the steps below to make your app compatible.
84+
85+
1. If ``appinfo/info.xml`` has a dependency specification for PHP, increase the ``max-version`` to 8.4.
86+
However, it is recommended to always support all PHP versions that are compatible with supported Nextcloud version.
87+
In that case the ``php``-dependencies entries can be omitted.
88+
89+
.. code-block:: xml
90+
91+
<dependencies>
92+
<php min-version="8.1" max-version="8.4" />
93+
<nextcloud min-version="29" max-version="31" />
94+
</dependencies>
95+
96+
97+
2. If your app has a ``composer.json`` and the file contains the PHP restrictions from ``info.xml``, adjust it as well.
98+
99+
.. code-block:: json
100+
101+
{
102+
"require": {
103+
"php": ">=8.1 <=8.4"
104+
}
105+
}
106+
107+
3. If you have :ref:`continuous integration <app-ci>` set up, extend your test matrix with PHP 8.4 tests and linters.
108+
This happens automatically when you reuse our `GitHub Workflow templates <https://github.com/nextcloud/.github>`__,
109+
but you can also use the underlying `icewind1991/nextcloud-version-matrix Action <https://github.com/icewind1991/nextcloud-version-matrix>`__ directly.
110+
111+
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>`__.
54112

55113
Added APIs
56114
^^^^^^^^^^
57115

58-
- If an app supports file conversion, it may now register an ``\OCP\Files\Conversion\ConversionProvider`` which will
116+
- It is now possible to download folders as zip or tar archives using the WebDAV backend using :code:`GET` requests.
117+
See the relevant :ref:`endpoint documentation<webdav-download-folders>`.
118+
- ``OCP\SetupCheck\CheckServerResponseTrait`` was added to ease implementing custom :ref:`setup checks<setup-checks>`
119+
which need to check HTTP calls to the the server itself.
120+
- 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.
121+
- ``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.
122+
- ``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.
123+
- If an app supports file conversion, it may now register an ``OCP\Files\Conversion\ConversionProvider`` which will
59124
be called automatically based on the supported MIME types. An app may register as many of these as needed.
60125
- 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``.
61126

62127
Changed APIs
63128
^^^^^^^^^^^^
64129

130+
- Clarify ``OCP\Files\Storage\IStorage::getOwner()`` returns ``string|false``.
131+
- Added method parameter and return types to all inheritors of ``OCP\Files\Storage\IStorage``. To migrate in a backwards compatible manner:
132+
133+
#. Add all return types to your implementation now.
134+
#. Add all parameter types to your implementation once Nextcloud 31 is the lowest supported version.
135+
136+
- The Nextcloud implementation of the ``log`` method of ``Psr\Log\LoggerInterface`` now supports ``Psr\Log\LogLevel`` as log level parameter.
137+
- The ``OCP\DB\QueryBuilder\IQueryBuilder`` now supports more date / time related parameter types:
138+
139+
- ``PARAM_DATE_MUTABLE`` and ``PARAM_DATE_IMMUTABLE`` for passing a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance when only interested in the date part.
140+
- ``PARAM_TIME_MUTABLE`` and ``PARAM_TIME_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance when only interested in the time part.
141+
- ``PARAM_DATETIME_MUTABLE`` and ``PARAM_DATETIME_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance without handling of the timezone.
142+
- ``PARAM_DATETIME_TZ_MUTABLE`` and ``PARAM_DATETIME_TZ_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance with handling of the timezone.
143+
144+
- The ``OCP\\DB\\Types`` now support more date and time related types for usage with the ``Entity``:
145+
146+
- ``DATE_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with only the date part set.
147+
- ``TIME_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with only the time part set.
148+
- ``DATETIME_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with both the time part set but without timezone information.
149+
- ``DATETIME_TZ`` for fields that will (de)serialized as ``\DateTime`` instances with both the time part set and with timezone information.
150+
- ``DATETIME_TZ_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with both the time part set and with timezone information.
151+
152+
- It's now possible to paginate DAV requests with new headers.
153+
154+
- First request should contains the following headers:
155+
156+
- ``X-NC-Paginate: true`` enables the functionality
157+
- ``X-NC-Paginate-Count: X`` sets the number of results per page (default 100)
158+
159+
- Server will answer with new headers:
160+
161+
- ``X-NC-Paginate-Total`` indicates the total number of results.
162+
- ``X-NC-Paginate-Token`` gives a token to access other pages of the same result.
163+
164+
- Issue new requests with token:
165+
166+
- ``X-NC-Paginate-Token: xxx`` contains the token as sent by the server
167+
- ``X-NC-Paginate-Count: X`` sets the number of results per page (default 100)
168+
- ``X-NC-Paginate-Offset: Y`` sets the offset (number of ignored results) for the required page (usually "page_number × page_size")
169+
65170
- 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.
66171
- ``OCP\Preview\BeforePreviewFetchedEvent`` constructor has a new parameter ``$mimeType`` which should be a string or null.
67172
- It has a new method ``getMimeType()`` to get the new property.
@@ -70,21 +175,29 @@ Changed APIs
70175
Deprecated APIs
71176
^^^^^^^^^^^^^^^
72177

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

75185
Removed APIs
76186
^^^^^^^^^^^^
77187

78-
- ``OCA.FilesSharingDrop`` removed as part of the Vue migration. Use the Files app API provided by the :ref:`package<js-library_nextcloud-files>` .
79-
- ``$.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.
80-
81-
.. code-block:: JavaScript
82-
83-
import { subscribe, unsubscribe } from '@nextcloud/event-bus'
84-
85-
subscribe('notifications:action:execute', (event) => {
86-
console.info('Notification action has been executed:', event.notification, event.action)
87-
})
188+
- Legacy, non functional, ``OC_App::getForms`` was removed.
189+
- The private and legacy ``OC_Files`` class was removed.
190+
Instead use ``OCP\AppFramework\Http\StreamResponse`` or ``OCP\AppFramework\Http\ZipResponse``.
191+
- The private and legacy Ajax endpoint for downloading file archives (``/apps/files/ajax/download.php``) was removed.
192+
Instead use the Nextcloud provided :ref:`WebDAV endpoint<webdav-download-folders>`.
193+
- All ``OCP\ILogger`` logging methods, deprecated since Nextcloud 20, are removed.
194+
- The interface now only holds the Nextcloud internal logging level constants.
195+
For all logging ``Psr\Log\LoggerInterface`` should be used.
196+
- The ``OCP\ILogger`` interface can no longer be dependency injected as it now only holds constants.
197+
- ``OCP\IServerContainer::getLogger`` was removed, use dependency injection with ``Psr\Log\LoggerInterface`` instead.
198+
- The internal class ``OC\AppFramework\Logger`` was removed, it should have been never used by apps.
199+
All using apps should migrate to ``Psr\Log\LoggerInterface``.
200+
- Legacy endpoint to test remote share endpoint (``/testremote``) was removed.
88201

89202
- Legacy class ``OC_API`` was moved to a private namespace. It should not be needed by applications.
90203
- Deprecated interface ``OCP\Files\Storage`` was removed. Use ``OCP\Files\Storage\IStorage`` instead.
@@ -223,119 +336,3 @@ Removed APIs
223336
- ``OCP\AppFramework\Utility\ITimeFactory::class``
224337
* - Defaults
225338
- ``OCP\Defaults::class``
226-
227-
Back-end changes
228-
----------------
229-
230-
Support for PHP 8.4 added
231-
^^^^^^^^^^^^^^^^^^^^^^^^^
232-
233-
In this release support for PHP 8.4 was added. Follow the steps below to make your app compatible.
234-
235-
1. If ``appinfo/info.xml`` has a dependency specification for PHP, increase the ``max-version`` to 8.4.
236-
However, it is recommended to always support all PHP versions that are compatible with supported Nextcloud version.
237-
In that case the ``php``-dependencies entries can be omitted.
238-
239-
.. code-block:: xml
240-
241-
<dependencies>
242-
<php min-version="8.1" max-version="8.4" />
243-
<nextcloud min-version="29" max-version="31" />
244-
</dependencies>
245-
246-
247-
2. If your app has a ``composer.json`` and the file contains the PHP restrictions from ``info.xml``, adjust it as well.
248-
249-
.. code-block:: json
250-
251-
{
252-
"require": {
253-
"php": ">=8.1 <=8.4"
254-
}
255-
}
256-
257-
3. If you have :ref:`continuous integration <app-ci>` set up, extend your test matrix with PHP 8.4 tests and linters.
258-
This happens automatically when you reuse our `GitHub Workflow templates <https://github.com/nextcloud/.github>`__,
259-
but you can also use the underlying `icewind1991/nextcloud-version-matrix Action <https://github.com/icewind1991/nextcloud-version-matrix>`__ directly.
260-
261-
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>`__.
262-
263-
Added APIs
264-
^^^^^^^^^^
265-
266-
- It is now possible to download folders as zip or tar archives using the WebDAV backend using :code:`GET` requests.
267-
See the relevant :ref:`endpoint documentation<webdav-download-folders>`.
268-
- ``OCP\SetupCheck\CheckServerResponseTrait`` was added to ease implementing custom :ref:`setup checks<setup-checks>`
269-
which need to check HTTP calls to the the server itself.
270-
- 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.
271-
- ``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.
272-
- ``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.
273-
274-
Changed APIs
275-
^^^^^^^^^^^^
276-
277-
- Clarify ``OCP\Files\Storage\IStorage::getOwner()`` returns ``string|false``.
278-
- Added method parameter and return types to all inheritors of ``OCP\Files\Storage\IStorage``. To migrate in a backwards compatible manner:
279-
280-
#. Add all return types to your implementation now.
281-
#. Add all parameter types to your implementation once Nextcloud 31 is the lowest supported version.
282-
283-
- The Nextcloud implementation of the ``log`` method of ``Psr\Log\LoggerInterface`` now supports ``Psr\Log\LogLevel`` as log level parameter.
284-
- The ``OCP\DB\QueryBuilder\IQueryBuilder`` now supports more date / time related parameter types:
285-
286-
- ``PARAM_DATE_MUTABLE`` and ``PARAM_DATE_IMMUTABLE`` for passing a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance when only interested in the date part.
287-
- ``PARAM_TIME_MUTABLE`` and ``PARAM_TIME_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance when only interested in the time part.
288-
- ``PARAM_DATETIME_MUTABLE`` and ``PARAM_DATETIME_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance without handling of the timezone.
289-
- ``PARAM_DATETIME_TZ_MUTABLE`` and ``PARAM_DATETIME_TZ_IMMUTABLE`` to pass a ``\DateTime`` (``\DateTimeImmutable`` respectively) instance with handling of the timezone.
290-
291-
- The ``OCP\\DB\\Types`` now support more date and time related types for usage with the ``Entity``:
292-
293-
- ``DATE_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with only the date part set.
294-
- ``TIME_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with only the time part set.
295-
- ``DATETIME_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with both the time part set but without timezone information.
296-
- ``DATETIME_TZ`` for fields that will (de)serialized as ``\DateTime`` instances with both the time part set and with timezone information.
297-
- ``DATETIME_TZ_IMMUTABLE`` for fields that will (de)serialized as ``\DateTimeImmutable`` instances with both the time part set and with timezone information.
298-
299-
- It's now possible to paginate DAV requests with new headers.
300-
301-
- First request should contains the following headers:
302-
303-
- ``X-NC-Paginate: true`` enables the functionality
304-
- ``X-NC-Paginate-Count: X`` sets the number of results per page (default 100)
305-
306-
- Server will answer with new headers:
307-
308-
- ``X-NC-Paginate-Total`` indicates the total number of results.
309-
- ``X-NC-Paginate-Token`` gives a token to access other pages of the same result.
310-
311-
- Issue new requests with token:
312-
313-
- ``X-NC-Paginate-Token: xxx`` contains the token as sent by the server
314-
- ``X-NC-Paginate-Count: X`` sets the number of results per page (default 100)
315-
- ``X-NC-Paginate-Offset: Y`` sets the offset (number of ignored results) for the required page (usually "page_number × page_size")
316-
317-
Deprecated APIs
318-
^^^^^^^^^^^^^^^
319-
320-
- The ``/s/{token}/download`` endpoint for downloading public shares is deprecated.
321-
Instead use the Nextcloud provided :ref:`WebDAV endpoint<webdav-download-folders>`.
322-
- ``OCP\DB\QueryBuilder\IQueryBuilder::PARAM_DATE`` is deprecated in favor of ``PARAM_DATETIME_MUTABLE``
323-
to make clear that this type also includes the time part of a date time instance.
324-
- ``OCP\User\Backend\ICountUsersBackend`` was deprecated. Please implement and use ``OCP\User\Backend\ILimitAwareCountUsersBackend`` instead.
325-
326-
Removed APIs
327-
^^^^^^^^^^^^
328-
329-
- Legacy, non functional, ``OC_App::getForms`` was removed.
330-
- The private and legacy ``OC_Files`` class was removed.
331-
Instead use ``OCP\AppFramework\Http\StreamResponse`` or ``OCP\AppFramework\Http\ZipResponse``.
332-
- The private and legacy Ajax endpoint for downloading file archives (``/apps/files/ajax/download.php``) was removed.
333-
Instead use the Nextcloud provided :ref:`WebDAV endpoint<webdav-download-folders>`.
334-
- All ``OCP\ILogger`` logging methods, deprecated since Nextcloud 20, are removed.
335-
- The interface now only holds the Nextcloud internal logging level constants.
336-
For all logging ``Psr\Log\LoggerInterface`` should be used.
337-
- The ``OCP\ILogger`` interface can no longer be dependency injected as it now only holds constants.
338-
- ``OCP\IServerContainer::getLogger`` was removed, use dependency injection with ``Psr\Log\LoggerInterface`` instead.
339-
- The internal class ``OC\AppFramework\Logger`` was removed, it should have been never used by apps.
340-
All using apps should migrate to ``Psr\Log\LoggerInterface``.
341-
- Legacy endpoint to test remote share endpoint (``/testremote``) was removed.

0 commit comments

Comments
 (0)