From 463ce8a859af3bc5198bf400ac6f7196453f9168 Mon Sep 17 00:00:00 2001 From: Christoph Wurst Date: Mon, 5 Oct 2020 13:08:05 +0200 Subject: [PATCH 1/3] Document Nextcloud 20 critical changes Signed-off-by: Christoph Wurst --- .../upgrade-guide.rst | 74 ++++++++++++++++++- developer_manual/digging_deeper/psr.rst | 2 + 2 files changed, 73 insertions(+), 3 deletions(-) diff --git a/developer_manual/app_publishing_maintenance/upgrade-guide.rst b/developer_manual/app_publishing_maintenance/upgrade-guide.rst index cd6f9aecb55..0a8fa5574a0 100644 --- a/developer_manual/app_publishing_maintenance/upgrade-guide.rst +++ b/developer_manual/app_publishing_maintenance/upgrade-guide.rst @@ -11,15 +11,48 @@ Upgrading to Nextcloud 20 .. note:: Critical changes were collected `on Github `_. See the original ticket for links to the pull requests and tickets. +Front-end changes +^^^^^^^^^^^^^^^^^ + +Body theme +********** + +The body theme classes are now ``theme--highcontrast``, ``theme--dark`` and/or ``theme--light``. + +jQuery update +************* + +jQuery was updated to v2.2. The most notable change is that ``$(document).ready(...)`` or ``$(...)`` for short fires sooner than before. Use the `DOMContentLoaded event `_ instead. + +Search +****** + +The unified search replaces the traditional search input, hence ``OCA.Search`` became a noop. For backwards compatibility, the code will not raise any errors now, but it does not have any functionality. + + Back-end changes ^^^^^^^^^^^^^^^^ +App bootstrap logic +******************* + +The code that initializes an app or anything that should run for every request and command is now moved to a dedicated and typed API. The ``appinfo/app.php`` is therefore obsolete and deprecated. See :ref:`bootstrapping` for details. + +.. _upgrade-psr3: + +PSR-3 integration +***************** + +Nextcloud 20 is the first major release of Nextcloud that brings full compatibility with :ref:`psr3`. From this point on it is highly recommended to use this interface mainly as the old ``\OCP\ILogger`` got deprecated with the last remaining changes. The majority of methods are identical between the Nextcloud-specific interface and the PSR one. Pay attention to usages of ``\OCP\ILogger::logException`` as that method does not exist on the PSR logger. However, you can specifcy an ``exception`` key in the ``$context`` argument of any ``\Psr\Log\LoggerInterface`` method and Nextcloud will format it like it did with the old ``logException``. + .. _upgrade-psr11: PSR-11 integration ****************** -Nextcloud 20 is the first major release of Nextcloud that brings full compatibility with :ref:`psr11`. From this point on it is highly recommended to use this interface mainly as the old ``\OCP\AppFramework\IAppContainer``, ``\OCP\IContainer`` and ``\OCP\IServerContainer`` got deprecated with this change. +Nextcloud 20 is the first major release of Nextcloud that brings full compatibility with :ref:`psr11`. From this point on it is highly recommended to use this interface mainly as the old ``\OCP\IContainer`` got deprecated with this change. + +The interfaces ``\OCP\AppFramework\IAppContainer`` and ``\OCP\IServerContainer`` will remain, but they won't extend the ``IContainer`` anymore once that interface gets removed. As a result, ``IAppContainer`` and ``IServerContainer`` will eventually become tagging interfaces with the sole purpose of making it possible to have either the app or server container injected explicitly. If your app requires Nextcloud 20 or later, you can replace any of the old type hints with one of ``\Psr\Container\ContainerInterface`` and replace calls of ``query`` with ``get``, e.g. on the closures used when registering services: @@ -54,9 +87,44 @@ becomes Deprecated APIs *************** -* ``\OCP\AppFramework\IAppContainer``: see :ref:`upgrade-psr11` * ``\OCP\IContainer``: see :ref:`upgrade-psr11` -* ``\OCP\IServerContainer``: see :ref:`upgrade-psr11` +* ``\OCP\ILogger``: see :ref:`upgrade-psr3` +* ``\OCP\IServerContainer::getEventDispatcher`` +* ``\OC_App::registerLogIn()``: use :ref:`bootstrapping` and ``\OCP\AppFramework\Bootstrap\IRegistrationContext::registerAlternativeLogin`` +* Event ``\OCA\DAV\CalDAV\CalDavBackend::createCachedCalendarObject``: listen to ``\OCA\DAV\Events\CachedCalendarObjectCreatedEvent`` +* Event ``\OCA\DAV\CalDAV\CalDavBackend::createCalendar``: listen to ``\OCA\DAV\Events\CalendarCreatedEvent`` +* Event ``\OCA\DAV\CalDAV\CalDavBackend::createCalendarObject``: listen to ``\OCA\DAV\Events\CalendarObjectCreatedEvent`` +* Event ``\OCA\DAV\CalDAV\CalDavBackend::createSubscription``: listen to ``\OCA\DAV\Events\SubscriptionCreatedEvent`` +* Event ``\OCA\DAV\CalDAV\CalDavBackend::deleteCachedCalendarObject``: listen to ``\OCA\DAV\Events\CachedCalendarObjectDeletedEvent`` +* Event ``\OCA\DAV\CalDAV\CalDavBackend::deleteCalendar``: listen to ``\OCA\DAV\Events\CalendarDeletedEvent`` +* Event ``\OCA\DAV\CalDAV\CalDavBackend::deleteCalendarObject``: listen to ``\OCA\DAV\Events\CalendarObjectDeletedEvent`` +* Event ``\OCA\DAV\CalDAV\CalDavBackend::deleteSubscription``: listen to ``\OCA\DAV\Events\SubscriptionDeletedEvent`` +* Event ``\OCA\DAV\CalDAV\CalDavBackend::publishCalendar``: listen to ``\OCA\DAV\Events\CalendarPublishedEvent`` +* Event ``\OCA\DAV\CalDAV\CalDavBackend::publishCalendar``: listen to ``\OCA\DAV\Events\CalendarUnpublishedEvent`` +* Event ``\OCA\DAV\CalDAV\CalDavBackend::updateCachedCalendarObject``: listen to ``\OCA\DAV\Events\CachedCalendarObjectUpdatedEvent`` +* Event ``\OCA\DAV\CalDAV\CalDavBackend::updateCalendar``: listen to ``\OCA\DAV\Events\CalendarUpdatedEvent`` +* Event ``\OCA\DAV\CalDAV\CalDavBackend::updateCalendarObject``: listen to ``\OCA\DAV\Events\CalendarObjectUpdatedEvent`` +* Event ``\OCA\DAV\CalDAV\CalDavBackend::updateShares``: listen to ``\OCA\DAV\Events\CalendarShareUpdatedEvent`` +* Event ``\OCA\DAV\CalDAV\CalDavBackend::updateSubscription``: listen to ``\OCA\DAV\Events\SubscriptionUpdatedEvent`` +* Event ``\\OCA\DAV\CardDAV\CardDavBackend::createCard``: listen to ``\OCA\DAV\Events\CardCreatedEvent`` +* Event ``\OCA\DAV\CardDAV\CardDavBackend::deleteCard``: listen to ``\OCA\DAV\Events\CardDeletedEvent`` +* Event ``\OCA\DAV\CardDAV\CardDavBackend::updateCard``: listen to ``\OCA\DAV\Events\CardUpdatedEvent`` +* Event ``\OCA\Files_Sharing::loadAdditionalScripts:: publicShareAuth``: listen to ``\OCA\Files_Sharing\Event\BeforeTemplateRenderedEvent`` +* Event ``\OCA\Files_Sharing::loadAdditionalScripts``: listen to ``\OCA\Files_Sharing\Event\BeforeTemplateRenderedEvent`` +* Event ``\OCA\User_LDAP\User\User::postLDAPBackendAdded``: listen to ``\OCA\User_LDAP\Events\UserBackendRegistered`` +* Event ``\OCA\User_LDAP\User\User::postLDAPBackendAdded``: listen to ``\OCA\User_LDAP\Events\GroupBackendRegistered`` +* Event ``\OCP\AppFramework\Http\StandaloneTemplateResponse::EVENT_LOAD_ADDITIONAL_SCRIPT``: listen to ``\OCP\AppFramework\Http\Events\BeforeTemplateRenderedEvent`` +* Event ``\OCP\AppFramework\Http\StandaloneTemplateResponse::EVENT_LOAD_ADDITIONAL_SCRIPTS_LOGGEDIN``: listen to ``\OCP\AppFramework\Http\Events\BeforeTemplateRenderedEvent`` +* Event ``\OCP\WorkflowEngine::loadAdditionalSettingScripts``: listen to ``\OCP\WorkflowEngine\Events\LoadSettingsScriptsEvent`` + + +Removed from public namespace +***************************** + +* ``\OCP\IServerContainer::getAppFolder`` +* Hook ``\OCA\DAV\Connector\Sabre::authInit``: use the ``\OCA\DAV\Events\SabrePluginAuthInitEvent`` event instead +* Event ``\OC_User::post_removeFromGroup``: listen to ``\OCP\Group\Events\UserRemovedEvent`` +* Event ``\OCA\DAV\Connector\Sabre::authInit``: listen to ``\OCA\DAV\Events\SabrePluginAuthInitEvent`` Upgrading to Nextcloud 19 diff --git a/developer_manual/digging_deeper/psr.rst b/developer_manual/digging_deeper/psr.rst index a51c608e6b9..351b6576901 100644 --- a/developer_manual/digging_deeper/psr.rst +++ b/developer_manual/digging_deeper/psr.rst @@ -6,6 +6,8 @@ PSR On this page you find information about the implemented `php standards recommendations `_ in Nextcloud. +.. _psr3: + PSR-3: Logger Interface ----------------------- From a3bc1ade588ae3a8cd969fb3bdff73e67990c8cd Mon Sep 17 00:00:00 2001 From: Christoph Wurst Date: Mon, 5 Oct 2020 13:19:07 +0200 Subject: [PATCH 2/3] Use LoggerInterface in the example repair step Signed-off-by: Christoph Wurst --- developer_manual/digging_deeper/repair.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/developer_manual/digging_deeper/repair.rst b/developer_manual/digging_deeper/repair.rst index 0f761a55ae6..1e42b331d9c 100644 --- a/developer_manual/digging_deeper/repair.rst +++ b/developer_manual/digging_deeper/repair.rst @@ -24,14 +24,14 @@ The following repairstep will log a message when executed. use OCP\Migration\IOutput; use OCP\Migration\IRepairStep; - use OCP\ILogger; + use Psr\Log\LoggerInterface; class MyRepairStep implements IRepairStep { - /** @var ILogger */ + /** @var LoggerInterface */ protected $logger; - public function __construct(ILogger $logger) { + public function __construct(LoggerInterface $logger) { $this->logger = $logger; } From 5111715c344f2bcd429db2629aba7bf1a741f47e Mon Sep 17 00:00:00 2001 From: Christoph Wurst Date: Mon, 5 Oct 2020 13:31:58 +0200 Subject: [PATCH 3/3] Migrate logging docs to new interface Signed-off-by: Christoph Wurst --- developer_manual/basics/logging.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/developer_manual/basics/logging.rst b/developer_manual/basics/logging.rst index 42ed7401b80..272a34e079e 100644 --- a/developer_manual/basics/logging.rst +++ b/developer_manual/basics/logging.rst @@ -4,7 +4,7 @@ Logging .. sectionauthor:: Bernhard Posselt -The logger is present by default in the container. The app that is Logging is +The logger is present by default in the container. The app that is logging is set automatically. The logger can be used in the following way: @@ -14,21 +14,20 @@ The logger can be used in the following way: logger = $logger; $this->appName = $appName; } public function log($message) { - $this->logger->error($message, array('extra_context' => 'my extra context')); + $this->logger->error($message, ['extra_context' => 'my extra context']); } }