diff options
22 files changed, 486 insertions, 125 deletions
diff --git a/admin_manual/configuration_database/linux_database_configuration.rst b/admin_manual/configuration_database/linux_database_configuration.rst index 9ac1a1181..0d77289d9 100644 --- a/admin_manual/configuration_database/linux_database_configuration.rst +++ b/admin_manual/configuration_database/linux_database_configuration.rst @@ -182,6 +182,11 @@ Adjust the paths to the pem files for your environment. PostgreSQL database ^^^^^^^^^^^^^^^^^^^ +In order to run Nextcloud securely on PostgreSQL, it is assumed that only +Nextcloud uses this database and thus only one user accesses the database. +For further services and users, we recommend to create a separate +database or PostgreSQL instance. + If you decide to use a PostgreSQL database make sure that you have installed and enabled the PostgreSQL extension in PHP. The PHP configuration in :file:`/etc/php7/conf.d/pgsql.ini` could look like this: @@ -210,7 +215,8 @@ Then a **template1=#** prompt will appear. Now enter the following lines and con :: CREATE USER username CREATEDB; - CREATE DATABASE nextcloud OWNER username; + CREATE DATABASE nextcloud OWNER username TEMPLATE template0 ENCODING 'UTF8'; + GRANT CREATE ON SCHEMA public TO username; You can quit the prompt by entering:: @@ -248,10 +254,11 @@ Then a **postgres=#** prompt will appear. Now enter the following lines and conf :: - CREATE USER username WITH PASSWORD 'password'; - CREATE DATABASE nextcloud TEMPLATE template0 ENCODING 'UNICODE'; + CREATE USER username WITH PASSWORD 'password' CREATEDB; + CREATE DATABASE nextcloud TEMPLATE template0 ENCODING 'UTF8'; ALTER DATABASE nextcloud OWNER TO username; GRANT ALL PRIVILEGES ON DATABASE nextcloud TO username; + GRANT ALL PRIVILEGES ON SCHEMA public TO username; You can quit the prompt by entering:: diff --git a/admin_manual/configuration_server/config_sample_php_parameters.rst b/admin_manual/configuration_server/config_sample_php_parameters.rst index 9d6c26c82..1b30c2151 100644 --- a/admin_manual/configuration_server/config_sample_php_parameters.rst +++ b/admin_manual/configuration_server/config_sample_php_parameters.rst @@ -1302,6 +1302,29 @@ Defaults to ``true`` :: + 'preview_concurrency_all' => 8, + +Number of all preview requests being processed concurrently, +including previews that need to be newly generated, and those that have +been generated. + +This should be greater than 'preview_concurrency_new'. +If unspecified, defaults to twice the value of 'preview_concurrency_new'. + +:: + + 'preview_concurrency_new' => 4, + +Number of new previews that are being concurrently generated. + +Depending on the max preview size set by 'preview_max_x' and 'preview_max_y', +the generation process can consume considerable CPU and memory resources. +It's recommended to limit this to be no greater than the number of CPU cores. +If unspecified, defaults to the number of CPU cores, or 4 if that cannot +be determined. + +:: + 'preview_max_x' => 4096, The maximum width, in pixels, of a preview. A value of ``null`` means there diff --git a/admin_manual/installation/system_requirements.rst b/admin_manual/installation/system_requirements.rst index 88acaf4c1..a65495fe8 100644 --- a/admin_manual/installation/system_requirements.rst +++ b/admin_manual/installation/system_requirements.rst @@ -15,7 +15,7 @@ For best performance, stability and functionality we have documented some recomm | Platform | Options | +==================+=======================================================================+ | Operating System | - **Ubuntu 22.04 LTS** (recommended) | -| (64bit) | - Ubuntu 20.04 LTS | +| (64-bit) | - Ubuntu 20.04 LTS | | | - **Red Hat Enterprise Linux 8** (recommended) | | | - Debian 10 (Buster) | | | - SUSE Linux Enterprise Server 15 | @@ -39,7 +39,7 @@ See :doc:`source_installation` for minimum PHP-modules and additional software f CPU Architecture and OS ^^^^^^^^^^^^^^^^^^^^^^^ -A 64bit CPU and 64bit OS is required for Nextcloud to run well. +A 64-bit CPU and 64-bit OS is required for Nextcloud 26 and higher. Memory ^^^^^^ diff --git a/admin_manual/issues/general_troubleshooting.rst b/admin_manual/issues/general_troubleshooting.rst index 7daa7772c..46c8a4594 100644 --- a/admin_manual/issues/general_troubleshooting.rst +++ b/admin_manual/issues/general_troubleshooting.rst @@ -366,15 +366,17 @@ The command will do a test decryption for all files and automatically repair the Fair Use Policy --------------- -Nextcloud is open source and you can host it for free on your own instance. +Nextcloud is open source and you can host it for free on your own server or at a provider. -Nextcloud recommends against deploying an instance for more than 500 users without an Enterprise Subscription, because Nextcloud considers your instance with so many users mission-critical and we believe you and your users would have a better experience when the instance is officially supported by Nextcloud. +Nextcloud recommends Using Nextcloud Enterprise for deploying instances with more than 500. With that size, issues like a broken server or a data leak become very serious. -Nextcloud Enterprise is pre-configured and optimized for the needs of professional organizations rather than home users. It comes with support, security and scaling benefits, compliance expertise, and access to other knowledge related to scaling, which guarantees the best experience for all and also reduces the load on the http://help.nextcloud.com forum about issues caused by wrong scaling. +If there is an issue with the server, 500 people can't work. A data leak would risk the data of many users. In short, the server should be considered mission-critical. We believe you and your users would have a better experience with Nextcloud Enterprise. -An additional consideration is technical. Nextcloud provides some infrastructure components for examples notification services and the app store. To ensure these resources do not get overloaded by administrators who run Nextcloud for hundreds of users without providing financial resources to Nextcloud in return, these components are limited and will not work for more than 500 users. +Nextcloud Enterprise is pre-configured and optimised for the needs of professional organisations rather than home users. It comes with support, security and scaling benefits, compliance expertise, and access to our knowledge about running a successful Nextcloud, to get the best possible experience for users and admins. This also reduces the load on our home user forum http://help.nextcloud.com from issues unique to big deployments. -We believe all organisations who run Nextcloud for hundreds of users should be officially supported. We have possibilities available for those organisations who lack the required financial resources. Examples are NGOs or small schools. Please reach out to talk about the possibilities through the `contact form on our site <https://nextcloud.com/contact/>`_. +Nextcloud provides some infrastructure components needed for Nextcloud servers to run reliably. This includes notification, our app store and more. To ensure these resources do not get overloaded by administrators who run Nextcloud for thousands of users without providing financial resources to Nextcloud in return, these components are limited and will not work for more than 500 users. + +We believe all organisations who run Nextcloud for hundreds of users should be officially supported. We know there can be financial restrictions for non-profit organisations and, as we want everybody to have a chance to get the most out of Nextcloud, we have special offers for NGOs, small schools and other non-profits. Please reach out to talk to us about what is possible through the `contact form on our site <https://nextcloud.com/contact/>`_ or ask your system administrator to reach out. Other issues ------------ diff --git a/developer_manual/app_development/tutorial.rst b/developer_manual/app_development/tutorial.rst index 324f4ccde..3d7736c2a 100644 --- a/developer_manual/app_development/tutorial.rst +++ b/developer_manual/app_development/tutorial.rst @@ -107,8 +107,8 @@ This route calls the controller **OCA\\notestutorial\\PageController->index()** class PageController extends Controller { - public function __construct(string $AppName, IRequest $request){ - parent::__construct($AppName, $request); + public function __construct(string $appName, IRequest $request){ + parent::__construct($appName, $request); } /** @@ -133,8 +133,8 @@ Since the route which returns the initial HTML has been taken care of, the contr class NoteController extends Controller { - public function __construct(string $AppName, IRequest $request){ - parent::__construct($AppName, $request); + public function __construct(string $appName, IRequest $request){ + parent::__construct($appName, $request); } /** @@ -386,7 +386,7 @@ Connect database & controllers The mapper which provides the database access is finished and can be passed into the controller. -You can pass in the mapper by adding it as a type hinted parameter. Nextcloud will figure out how to :doc:`assemble them by itself <../basics/dependency_injection>`. Additionally we want to know the userId of the currently logged in user. Simply add a **$UserId** parameter to the constructor (case sensitive!). To do that open **notestutorial/lib/Controller/NoteController.php** and change it to the following: +You can pass in the mapper by adding it as a type hinted parameter. Nextcloud will figure out how to :doc:`assemble them by itself <../basics/dependency_injection>`. Additionally we want to know the userId of the currently logged in user. Simply add a **$userId** parameter to the constructor (case sensitive!). To do that open **notestutorial/lib/Controller/NoteController.php** and change it to the following: .. code-block:: php @@ -408,10 +408,10 @@ You can pass in the mapper by adding it as a type hinted parameter. Nextcloud wi private NoteMapper $mapper; private ?string $userId; - public function __construct(string $AppName, IRequest $request, NoteMapper $mapper, ?string $UserId = null){ - parent::__construct($AppName, $request); + public function __construct(string $appName, IRequest $request, NoteMapper $mapper, ?string $userId = null){ + parent::__construct($appName, $request); $this->mapper = $mapper; - $this->userId = $UserId; + $this->userId = $userId; } /** @@ -654,11 +654,11 @@ Now we can wire up the trait and the service inside the **NoteController**: use Errors; - public function __construct(string $AppName, IRequest $request, - NoteService $service, ?string $UserId = null) { - parent::__construct($AppName, $request); + public function __construct(string $appName, IRequest $request, + NoteService $service, ?string $userId = null) { + parent::__construct($appName, $request); $this->service = $service; - $this->userId = $UserId; + $this->userId = $userId; } /** @@ -967,11 +967,11 @@ With that in mind create a new controller in **notestutorial/lib/Controller/Note use Errors; - public function __construct($AppName, IRequest $request, - NoteService $service, ?string $UserId = null) { - parent::__construct($AppName, $request); + public function __construct(string $appName, IRequest $request, + NoteService $service, ?string $userId = null) { + parent::__construct($appName, $request); $this->service = $service; - $this->userId = $UserId; + $this->userId = $userId; } /** diff --git a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_26.rst b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_26.rst index 9b804c049..02b90ae85 100644 --- a/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_26.rst +++ b/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_26.rst @@ -18,6 +18,13 @@ Make sure your ``appinfo/info.xml`` allows for Nextcloud 26. <nextcloud min-version="23" max-version="26" /> </dependencies> +Personal settings section *Groupware* moved to *Availability* +------------------------------------------------------------- + +Up to Nextcloud 25 there had been a :ref:`settings section<settings-section>` *Groupware* with the ID ``groupware``. As of Nextcloud 26 this section doesn't exist anymore. Existing server settings were moved to a new section *Availability*/``availability``. + +If your app provides groupware-related settings, see if they make can be shown on the *Availability* page or need a new app-provided section. + Front-end changes ----------------- @@ -26,7 +33,10 @@ tbd Back-end changes ---------------- -tbd +Dependency Injection Parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +App container parameters with pascal case names ``AppName``, ``UserId`` and ``WebRoot`` are deprecated. Use the camel case variants ``appName``, ``userId`` and ``webRoot`` instead if you have them injected into one of your app classes. Changed APIs ^^^^^^^^^^^^ diff --git a/developer_manual/basics/controllers.rst b/developer_manual/basics/controllers.rst index 59cdce03a..f7f30a992 100644 --- a/developer_manual/basics/controllers.rst +++ b/developer_manual/basics/controllers.rst @@ -238,8 +238,8 @@ Then session variables can be accessed like this: private ISession $session; - public function __construct($AppName, IRequest $request, ISession $session) { - parent::__construct($AppName, $request); + public function __construct($appName, IRequest $request, ISession $session) { + parent::__construct($appName, $request); $this->session = $session; } diff --git a/developer_manual/basics/dependency_injection.rst b/developer_manual/basics/dependency_injection.rst index d3efaf34f..59d2ec158 100644 --- a/developer_manual/basics/dependency_injection.rst +++ b/developer_manual/basics/dependency_injection.rst @@ -104,7 +104,7 @@ use the **registerService** method on the container object: */ $container->registerService(AuthorController::class, function(ContainerInterface $c): AuthorController { return new AuthorController( - $c->get('AppName'), + $c->get('appName'), $c->get(Request::class), $c->get(AuthorService::class) ); @@ -139,12 +139,12 @@ The container works in the following way: * The matched route queries **AuthorController** service from the container:: return new AuthorController( - $c->get('AppName'), + $c->get('appName'), $c->get(Request::class), $c->get(AuthorService::class) ); -* The **AppName** is queried and returned from the base class +* The **appName** is queried and returned from the base class * The **Request** is queried and returned from the server container * **AuthorService** is queried:: @@ -198,9 +198,9 @@ So basically the following is now possible: public MyTestClass $class; public string $appName; - public function __construct(MyTestClass $class, string $AppName) { + public function __construct(MyTestClass $class, string $appName) { $this->class = $class; - $this->appName = $AppName; + $this->appName = $appName; } } @@ -213,7 +213,7 @@ So basically the following is now possible: $class2->appName === 'myname'; // true $class2 === $app->getContainer()->get(MyTestClass2::class); // true -.. note:: $AppName is resolved because the container registered a parameter under the key 'AppName' which will return the app id. The lookup is case sensitive so while $AppName will work correctly, using $appName as a constructor parameter will fail. +.. note:: $appName is resolved because the container registered a parameter under the key 'appName' which will return the app id. How does it affect the request lifecycle ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -252,8 +252,8 @@ The only thing that needs to be done to add a route and a controller method is n use OCP\IRequest; class PageController { - public function __construct($AppName, IRequest $request) { - parent::__construct($AppName, $request); + public function __construct($appName, IRequest $request) { + parent::__construct($appName, $request); } public function index() { @@ -309,46 +309,54 @@ The following parameter names and type hints can be used to inject core services Parameters: -* **AppName**: The app id -* **WebRoot**: The path to the Nextcloud installation -* **UserId**: The id of the current user +* **appName**: The app id +* **userId**: The id of the current user +* **webRoot**: The path to the Nextcloud installation + +Aliases: + +* **AppName**: resolves to ``appName`` (deprecated) +* **Request**: resolves to ``\OCP\IRequest`` +* **ServerContainer**: resolves to ``\OCP\IServerContainer`` +* **UserId**: resolves to ``userId`` (deprecated) +* **WebRoot**: resolves to ``webRoot`` (deprecated) Types: -* **OCP\\IAppConfig** -* **OCP\\IAppManager** -* **OCP\\IAvatarManager** -* **OCP\\Activity\\IManager** -* **OCP\\ICache** -* **OCP\\ICacheFactory** -* **OCP\\IConfig** -* **OCP\\AppFramework\\Utility\\IControllerMethodReflector** -* **OCP\\Contacts\\IManager** -* **OCP\\IDateTimeZone** -* **OCP\\IDBConnection** -* **OCP\\Diagnostics\\IEventLogger** -* **OCP\\Diagnostics\\IQueryLogger** -* **OCP\\Files\\Config\\IMountProviderCollection** -* **OCP\\Files\\IRootFolder** -* **OCP\\IGroupManager** -* **OCP\\IL10N** -* **OCP\\ILogger** -* **OCP\\BackgroundJob\\IJobList** -* **OCP\\INavigationManager** -* **OCP\\IPreview** -* **OCP\\IRequest** -* **OCP\\AppFramework\\Utility\\ITimeFactory** -* **OCP\\ITagManager** -* **OCP\\ITempManager** -* **OCP\\Route\\IRouter** -* **OCP\\ISearch** -* **OCP\\ISearch** -* **OCP\\Security\\ICrypto** -* **OCP\\Security\\IHasher** -* **OCP\\Security\\ISecureRandom** -* **OCP\\IURLGenerator** -* **OCP\\IUserManager** -* **OCP\\IUserSession** +* ``\OCP\IAppConfig`` +* ``\OCP\IAppManager`` +* ``\OCP\IAvatarManager`` +* ``\OCP\Activity\IManager`` +* ``\OCP\ICache`` +* ``\OCP\ICacheFactory`` +* ``\OCP\IConfig`` +* ``\OCP\AppFramework\Utility\IControllerMethodReflector`` +* ``\OCP\Contacts\IManager`` +* ``\OCP\IDateTimeZone`` +* ``\OCP\IDBConnection`` +* ``\OCP\Diagnostics\IEventLogger`` +* ``\OCP\Diagnostics\IQueryLogger`` +* ``\OCP\Files\Config\IMountProviderCollection`` +* ``\OCP\Files\IRootFolder`` +* ``\OCP\IGroupManager`` +* ``\OCP\IL10N`` +* ``\OCP\ILogger`` +* ``\OCP\BackgroundJob\IJobList`` +* ``\OCP\INavigationManager`` +* ``\OCP\IPreview`` +* ``\OCP\IRequest`` +* ``\OCP\AppFramework\Utility\ITimeFactory`` +* ``\OCP\ITagManager`` +* ``\OCP\ITempManager`` +* ``\OCP\Route\IRouter`` +* ``\OCP\ISearch`` +* ``\OCP\ISearch`` +* ``\OCP\Security\ICrypto`` +* ``\OCP\Security\IHasher`` +* ``\OCP\Security\ISecureRandom`` +* ``\OCP\IURLGenerator`` +* ``\OCP\IUserManager`` +* ``\OCP\IUserSession`` How to enable it ^^^^^^^^^^^^^^^^ @@ -396,7 +404,7 @@ What not to inject: Accessing the container from anywhere ------------------------------------- +------------------------------------- Sometimes it can be hard to inject some service inside legacy code, in these case you can use :code:`OCP\Server::get(MyService::class)`. This should only be used in diff --git a/developer_manual/basics/front-end/l10n.rst b/developer_manual/basics/front-end/l10n.rst index b326ff3a9..bcb45c119 100644 --- a/developer_manual/basics/front-end/l10n.rst +++ b/developer_manual/basics/front-end/l10n.rst @@ -16,7 +16,7 @@ In order to make your app translatable (internationalization), you should use Ne PHP ^^^ -If localized strings are used in the backend code, simply inject the``OCP\IL10N`` class into your service via type hinting it in the constructor. You will automatically get the language object containing the translations of your app: +If localized strings are used in the backend code, simply inject the ``\OCP\IL10N`` class into your service via type hinting it in the constructor. You will automatically get the language object containing the translations of your app: .. code-block:: php diff --git a/developer_manual/basics/storage/configuration.rst b/developer_manual/basics/storage/configuration.rst index 1b619119c..afb26e856 100644 --- a/developer_manual/basics/storage/configuration.rst +++ b/developer_manual/basics/storage/configuration.rst @@ -30,7 +30,7 @@ The config that allows the app to set global, app and user settings can be injec $container->registerService('AuthorService', function(IServerContainer $c): AuthorService { return new AuthorService( $c->get(IConfig::class), - $c->get('AppName') + $c->get('appName') ); }); } diff --git a/developer_manual/digging_deeper/dashboard.rst b/developer_manual/digging_deeper/dashboard.rst index 9eacdf3c3..77108946b 100644 --- a/developer_manual/digging_deeper/dashboard.rst +++ b/developer_manual/digging_deeper/dashboard.rst @@ -147,6 +147,20 @@ however this method is deprecated and will be removed once Nextcloud 19 is EOL. } } +The IConditionalWidget interface +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The IConditionalWidget interface adds the **isEnabled** method to provide the option for a widget to opt-out later. +While registering the widget the information whether or not a widget should be displayed to the specific user might +not be available or to complex to calculate up front. In this case the IConditionalWidget allows you to check the +conditions only when really needed. + +.. code-block:: php + + public function isEnabled(): bool { + return false; + } + Provide a user interface ------------------------ @@ -188,9 +202,8 @@ those additional interfaces: * IOptionWidget to set additional options * IAPIWidget to actually provide the widget content (the item list) -+++++++++++++++++++++++++++ The IButtonWidget interface -+++++++++++++++++++++++++++ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ The IButtonWidget interface adds the **getWidgetButtons** method to provide a list of buttons @@ -225,9 +238,8 @@ There are 3 types of buttons: ]; } -+++++++++++++++++++++++++++ The IIconWidget interface -+++++++++++++++++++++++++++ +^^^^^^^^^^^^^^^^^^^^^^^^^ The IIconWidget interface adds the **getIconUrl** method to provide the URL to the widget icon. In the following example it returns the URL to the img/app.svg file in your app. @@ -240,9 +252,8 @@ it returns the URL to the img/app.svg file in your app. ); } -+++++++++++++++++++++++++++ The IOptionWidget interface -+++++++++++++++++++++++++++ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ The IOptionWidget interface adds the **getWidgetOptions** method to provide additional widget options. It returns a WidgetOptions object which only contains the **roundItemIcons** boolean value for now. This tells the clients if @@ -254,9 +265,8 @@ the widget item icons should be rounded or kept as squares. return new WidgetOptions(true); } -+++++++++++++++++++++++++++ The IAPIWidget interface -+++++++++++++++++++++++++++ +^^^^^^^^^^^^^^^^^^^^^^^^ If you want your widget content to be accessible with the dashboard API for Nextcloud clients, it must implement the `OCP\\Dashboard\\IAPIWidget` interface rather than `OCP\\Dashboard\\IWidget`. @@ -289,9 +299,8 @@ This interface contains an extra `getItems` method which returns an array of `OC * iconUrl: URL to a square icon (svg or jpg/png of at least 44x44px) * sinceId: Item ID or timestamp. The client will then send the latest known sinceId in next dashboard API request. -+++++++++++ Use the API -+++++++++++ +^^^^^^^^^^^ The list of enabled widgets can be requested like that: diff --git a/developer_manual/digging_deeper/groupware/calendar.rst b/developer_manual/digging_deeper/groupware/calendar.rst index 91467c837..437e59290 100644 --- a/developer_manual/digging_deeper/groupware/calendar.rst +++ b/developer_manual/digging_deeper/groupware/calendar.rst @@ -161,6 +161,27 @@ Calendars that only return `ICalendar` are implicitly read-only. If your app's c } +Handling iMIP data +~~~~~~~~~~~~~~~~~~ + +You may implement the ``IHandleIMipMessage`` interface to process iMIP data you receive in a client and want to pass on for processing to the backend. + +Please be aware that there are some security considerations to take into account. You can find more infomation on these and the conditions that have to be fulfilled for iMIP data to be processed in the `RFC <https://www.rfc-editor.org/rfc/rfc6047>`_ + +.. code-block:: php + + <?php + + use OCP\Calendar\IHandleIMipMessage; + + class HandleIMipMessage implements IHandleIMipMessage { + + public function handleIMipMessage(string $name, string $calendarData): void { + // Validation and write to your calendar representation + } + + } + Resources --------- diff --git a/developer_manual/digging_deeper/http_client.rst b/developer_manual/digging_deeper/http_client.rst new file mode 100644 index 000000000..a34158415 --- /dev/null +++ b/developer_manual/digging_deeper/http_client.rst @@ -0,0 +1,134 @@ +=========== +HTTP Client +=========== + +Nextcloud comes with a simple HTTP client that can be used to send requests to other web servers. This client follows Nextcloud's configuration, security restrictions and proxy settings. + +Acquiring a HTTP Client +----------------------- + +HTTP client instances are built using the client service `factory <https://en.wikipedia.org/wiki/Factory_(object-oriented_programming)>`_ ``IClientService``. The factory can be :ref:`injected<dependency-injection>` into any app class: + +.. code-block:: php + + <?php + + use OCP\Http\IClientService; + + class MyRemoteServerIntegration { + private IClientService $clientService; + public function __construct(IClientService $clientService) { + $this->clientService = $clientService; + } + + public function downloadNextcloudWebsite(): void { + $client = $this->clientService->newClient(); + $response = $client->get('https://nextcloud.com'); + } + } + +HEAD request +------------ + +.. code-block:: php + + <?php + + $client = $this->clientService->newClient(); + $response = $client->head('https://nextcloud.com'); + + +GET request +----------- + +.. code-block:: php + + <?php + + $client = $this->clientService->newClient(); + $response = $client->get('https://nextcloud.com'); + +POST request +------------ + +.. code-block:: php + + <?php + + $client = $this->clientService->newClient(); + $response = $client->post('https://api.domain.tld/pizza', [ + 'headers' => [ + 'Accept' => 'application/json', + 'Content-Type' => 'application/json', + ], + 'body' => json_encode([ + 'toppings' => [ + 'cheese', + 'pineapple', + ], + ]) + ]); + $pizza = json_decode($response, true); + +PUT request +----------- + +.. code-block:: php + + <?php + + $client = $this->clientService->newClient(); + $response = $client->put('https://api.domain.tld/pizza/42', [ + 'headers' => [ + 'Accept' => 'application/json', + 'Content-Type' => 'application/json', + ], + 'body' => json_encode([ + 'toppings' => [ + 'cheese', + 'pineapple', + ], + ]) + ]); + $pizza = json_decode($response, true); + +DELETE request +-------------- + +.. code-block:: php + + <?php + + $client = $this->clientService->newClient(); + $response = $client->delete('https://api.domain.tld/pizza/42'); + +OPTIONS request +--------------- + +.. code-block:: php + + <?php + + $client = $this->clientService->newClient(); + $response = $client->options('https://nextcloud.com'); + $status = $response->getStatusCode(); + $allHeaders = $response->getHeaders(); + $contentType = $response->getHeader('content-type'); + +Error handling +-------------- + +Errors are signaled with exceptions. Catch PHP's base ``Exception``. + +.. code-block:: php + + <?php + + use Exception; + + $client = $this->clientService->newClient(); + try { + $response = $client->options('https://nextcloud.com'); + } catch (Exception $e) { + // Handle the error + }
\ No newline at end of file diff --git a/developer_manual/digging_deeper/index.rst b/developer_manual/digging_deeper/index.rst index c336f0167..97f03d1fe 100644 --- a/developer_manual/digging_deeper/index.rst +++ b/developer_manual/digging_deeper/index.rst @@ -11,6 +11,7 @@ Digging deeper classloader continuous_integration flow + http_client javascript-apis npm notifications diff --git a/developer_manual/digging_deeper/security.rst b/developer_manual/digging_deeper/security.rst index 4ff169715..7c78ce72b 100644 --- a/developer_manual/digging_deeper/security.rst +++ b/developer_manual/digging_deeper/security.rst @@ -4,6 +4,35 @@ Security ======== +Remote Host Validation +---------------------- + +Nextcloud can help validating a remote host so that no internal infrastructure is contacted by user-provided host names or IPs. The validator ``\OCP\Security\IRemoteHostValidator`` can be :ref:`injected<dependency-injection>` into any app class: + +.. code-block:: php + + <?php + + use OCP\Security\IRemoteHostValidator; + + class MyRemoteServerIntegration { + private IRemoteHostValidator $hostValidator; + + public function __construct(IRemoteHostValidator $hostValidator) { + $this->hostValidator = $hostValidator; + } + + public function contactRemoteServer(string $hostname): void { + if (!$this->hostValidator->isValid($hostname)) { + // ABORT + } + + // Contact the server + } + } + +.. note:: Nextcloud's HTTP clients obtained from ``\OCP\Http\Client\IClientService`` have this validation built in so you don't have to check hosts of HTTP requests as long as you use this provided abstraction. + Trusted domain ---------------- diff --git a/developer_manual/digging_deeper/settings.rst b/developer_manual/digging_deeper/settings.rst index 4d0eac649..9b260705a 100644 --- a/developer_manual/digging_deeper/settings.rst +++ b/developer_manual/digging_deeper/settings.rst @@ -1,3 +1,5 @@ +.. _settings-section: + ======== Settings ======== diff --git a/developer_manual/digging_deeper/talk.rst b/developer_manual/digging_deeper/talk.rst index 60c85c77e..42a185244 100644 --- a/developer_manual/digging_deeper/talk.rst +++ b/developer_manual/digging_deeper/talk.rst @@ -61,3 +61,15 @@ It's possible to adjust the defaults. [$alice, $bob], $broker->newConversationOptions()->setPublic() ); + +Delete a conversation +--------------------- + +A conversation can be deleted by id (token). + +.. code-block:: php + + <?php + + /** @var \OCP\Talk\IBroker $broker */ + $broker->deleteConversation('abc123'); diff --git a/developer_manual/getting_started/development_process.rst b/developer_manual/getting_started/development_process.rst new file mode 100644 index 000000000..c76d74ef0 --- /dev/null +++ b/developer_manual/getting_started/development_process.rst @@ -0,0 +1,69 @@ +=================== +Development process +=================== + +This page gives an overview of how Nextcloud code is developed. + +Source Code Version Control +--------------------------- + +Nextcloud uses `git <https://git-scm.com/>`_ to manage revisions of the code. Software components have their own repositories. + +Branch Names +^^^^^^^^^^^^ + +Default branches of Nextcloud and its app repositories are named ``main`` or ``master``. Additionally, there are *stable branches* whenever a major version of Nextcloud is released. Those are named ``stableX``, where X refers to the version. For Nextcloud 25, for example, the stable branch is named ``stable25``. + +Target Branches for Contributions +--------------------------------- + +Any changes made to the source code go into the default branch of a repository through a `pull request <https://docs.github.com/en/pull-requests>`_. + +.. code-block:: bash + + # Switch to the default branch and update it + git checkout main + git pull origin/main + + # Create the new feature branch + git checkout -b feature/foo-bar + + # Add and commit the changes + git add file1 file2 + git commit --signoff -m 'Add foo bar' + + # Push the new commit to the remote repository and open a pull request + git push origin feature/foo-bar + +Bugfixes +^^^^^^^^ + +If a contribution fixes a bug that also affects older Nextcloud or app releases, it may qualify for a *backport*. Backporting a fix means applying the change on an older version of the code. Git calls this operation *cherry picking*. + +Automatic Backport +****************** + +In many cases the cherry pick results in a clean apply of the patch and git is able to resolve any small conflicts. In those cases it's easiest to let the `backport bot <https://github.com/nextcloud/backportbot>`_ do the backport. + +See the `bot usage <https://github.com/nextcloud/backportbot#usage>`_ for its commands. + +Manual Backport +*************** + +More complex changes may require the developer to do the backport manually. This can be done as follows: + +.. code-block:: bash + + # Switch to the target branch and update it + git checkout stable25 + git pull origin/stable25 + + # Create the new backport branch + git checkout -b fix/foo-stable25 + + # Cherry pick the change from the commit sha1 of the change against the default branch + # This might cause conflicts. Resolve them. + git cherry-pick abc123 + + # Push the cherry pick commit to the remote repository and open a pull request + git push origin fix/foo-stable25 diff --git a/developer_manual/getting_started/index.rst b/developer_manual/getting_started/index.rst index ab7e2f242..3eeab21ec 100644 --- a/developer_manual/getting_started/index.rst +++ b/developer_manual/getting_started/index.rst @@ -5,6 +5,7 @@ Getting started .. toctree:: :maxdepth: 2 + development_process devenv codingguidelines debugging diff --git a/user_manual/files/access_webdav.rst b/user_manual/files/access_webdav.rst index 59611d063..4d9c084ff 100644 --- a/user_manual/files/access_webdav.rst +++ b/user_manual/files/access_webdav.rst @@ -515,6 +515,39 @@ To get the properties of files in the root folder: </d:propstat> </d:response> </d:multistatus> + + + + +Accessing files using WinSCP +------------------------------- + +`WinSCP <https://winscp.net/eng/docs/introduction/>`_ is an open source free SFTP client, FTP client, WebDAV client, S3 client and SCP client for Windows. Its main function is file transfer between a local and a remote computer. Beyond this, WinSCP offers scripting and basic file manager functionality. + +You can `download <https://winscp.net/eng/downloads.php/>`_ the portable version of WinSCP and run it on Linux through `Wine <https://wiki.winehq.org/Main_Page/>`_. + +To run WinSCP on Linux, download wine through your distribution's package manager, then run it via: wine WinSCP.exe. + +To connect to Nextcloud: + +* Start WinSCP +* Press 'Session' in the menu +* Press the 'New Session' menu option +* Set the 'File protocol' dropdown to WebDAV +* Set the 'Encryption' dropdown to TSL/SSL Implicit encryption +* Fill in the hostname field: example.com +* Fill in the username field: NEXTCLOUDUSERNAME +* Fill in the password field: NEXTCLOUDPASSWORD +* Press the 'Advanced...' button +* Navigate to 'Environment', 'Directories' on the left side +* Fill in the 'Remote directory' field with the following: /nextcloud/remote.php/dav/files/NEXTCLOUDUSERNAME/ +* Press the 'OK' button +* Press the 'Save' button +* Select the desired options and press the 'OK' button +* Press the 'Login' button to connect to Nextcloud + +Note: it is recommended to use an app password for the password if you use TOTP, as WinSCP does not understand TOTP in Nextcloud at the time of writing (2022-11-07). + .. _KB2668751: https://web.archive.org/web/20211008025539/https://support.microsoft.com/en-us/topic/you-cannot-download-more-than-50-mb-or-upload-large-files-when-the-upload-takes-longer-than-30-minutes-using-web-client-in-windows-7-8709ae9d-e808-c5a0-95d0-9a7143c50b11 diff --git a/user_manual/locale/ca/LC_MESSAGES/external_storage/external_storage.pot b/user_manual/locale/ca/LC_MESSAGES/external_storage/external_storage.pot index 9bbd3fac0..989aee4a9 100644 --- a/user_manual/locale/ca/LC_MESSAGES/external_storage/external_storage.pot +++ b/user_manual/locale/ca/LC_MESSAGES/external_storage/external_storage.pot @@ -1,19 +1,19 @@ # SOME DESCRIPTIVE TITLE. -# Copyright (C) 2021 Nextcloud GmbH +# Copyright (C) 2022 Nextcloud GmbH # This file is distributed under the same license as the Nextcloud latest User Manual package. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. # # Translators: -# Joan Marcè <jmigual0@gmail.com>, 2021 +# Sergi Moreno <ettenmoors@hotmail.com>, 2022 # #, fuzzy msgid "" msgstr "" "Project-Id-Version: Nextcloud latest User Manual latest\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2021-01-15 16:50+0000\n" +"POT-Creation-Date: 2022-06-03 12:01+0000\n" "PO-Revision-Date: 2019-11-07 20:28+0000\n" -"Last-Translator: Joan Marcè <jmigual0@gmail.com>, 2021\n" +"Last-Translator: Sergi Moreno <ettenmoors@hotmail.com>, 2022\n" "Language-Team: Catalan (https://www.transifex.com/nextcloud/teams/64236/ca/)\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" @@ -22,17 +22,17 @@ msgstr "" "Plural-Forms: nplurals=2; plural=(n != 1);\n" #: ../../external_storage/external_storage.rst:3 -msgid "Configuring external Storage" -msgstr "Configuració de l'emmagatzematge extern" +msgid "Configuring External Storage" +msgstr "Configurant Enmagatzemmatge Extern" #: ../../external_storage/external_storage.rst:5 msgid "" "The External Storage application allows you to mount external storage " -"services, such as Amazon S3, SMB/CIFS fileservers and FTP servers... in " +"services, such as Amazon S3, SMB/CIFS file servers and FTP servers… in " "Nextcloud. Your Nextcloud server administrator controls which of these are " "available to you. Please see `Configuring External Storage (GUI) " "<https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/external_storage_configuration_gui.html>`_" -" in the Nextcloud Administrator's manual for configuration howtos and " +" in the Nextcloud Administrator's manual for configuration how-tos and " "examples." msgstr "" "L'aplicació d'emmagatzematge extern permet muntar serveis d'emmagatzematge " @@ -40,5 +40,5 @@ msgstr "" "Nextcloud. L'administrador del teu Nextcloud controla quins d'aquests estan " "disponibles per a tu. Pots visitar `Configuració de l'emmagatzematge extern " "(GUI) " -"<https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/external_storage_configuration_gui.html>`_" +"<https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/external_storage_configuration_gui.html>`" " al manual de l'administrador de Nextcloud per veure'n alguns exemples." diff --git a/user_manual/locale/es/LC_MESSAGES/talk/talk_basics.pot b/user_manual/locale/es/LC_MESSAGES/talk/talk_basics.pot index 4e659d62f..ea9d6c696 100644 --- a/user_manual/locale/es/LC_MESSAGES/talk/talk_basics.pot +++ b/user_manual/locale/es/LC_MESSAGES/talk/talk_basics.pot @@ -1,26 +1,27 @@ # SOME DESCRIPTIVE TITLE. -# Copyright (C) 2021 Nextcloud GmbH +# Copyright (C) 2022 Nextcloud GmbH # This file is distributed under the same license as the Nextcloud latest User Manual package. # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR. # # Translators: # Roboron <robertoms258@gmail.com>, 2021 -# Next Cloud <nextcloud.translator.es@cgj.es>, 2021 +# FranciscoFJ <dev-ooo@satel-sa.com>, 2022 +# Julio C. Ortega, 2022 # #, fuzzy msgid "" msgstr "" "Project-Id-Version: Nextcloud latest User Manual latest\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2021-10-26 12:22+0000\n" +"POT-Creation-Date: 2022-05-20 09:09+0000\n" "PO-Revision-Date: 2021-10-11 16:50+0000\n" -"Last-Translator: Next Cloud <nextcloud.translator.es@cgj.es>, 2021\n" +"Last-Translator: Julio C. Ortega, 2022\n" "Language-Team: Spanish (https://www.transifex.com/nextcloud/teams/64236/es/)\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Language: es\n" -"Plural-Forms: nplurals=2; plural=(n != 1);\n" +"Plural-Forms: nplurals=3; plural=n == 1 ? 0 : n != 0 && n % 1000000 == 0 ? 1 : 2;\n" #: ../../talk/talk_basics.rst:3 msgid "Basics of Nextcloud Talk" @@ -204,9 +205,9 @@ msgstr "Gestionar una conversación" #: ../../talk/talk_basics.rst:80 msgid "" "You are always moderator in your new conversation. In the participant list " -"on the right you can elevate other participants to moderators using the " -"``...`` menu to the right of their user name, or remove them from the " -"conversation." +"you can promote other participants to moderators using the ``...`` menu to " +"the right of their user name, assign them custom permissions or remove them " +"from the conversation." msgstr "" "Siempre eres moderador en tu nueva conversación. En la lista de " "participantes a la derecha, puede elevar a otros participantes a moderadores" @@ -216,8 +217,7 @@ msgstr "" #: ../../talk/talk_basics.rst:84 msgid "" "Moderators can configure the conversation. Select ``Configuration settings``" -" from the ``...`` menu of the conversation on the top to access the " -"settings." +" from the gear menu of the conversation on the top to access the settings." msgstr "" "Los moderadores pueden configurar la conversación. Selecciona `` Ajustes de " "configuración'' en el menú ``...`` de la conversación en la parte superior " @@ -225,8 +225,8 @@ msgstr "" #: ../../talk/talk_basics.rst:88 msgid "" -"Here you can configure the name, guest access, if the conversation is " -"visible to others on the server and more." +"Here you can configure the description, guest access, if the conversation is" +" visible to others on the server and more." msgstr "" "Aquí puede configurar el nombre, el acceso de invitados, si la conversación " "es visible para otros en el servidor y más." @@ -251,20 +251,20 @@ msgstr "" #: ../../talk/talk_basics.rst:99 msgid "" "During a call, you can mute your microphone and disable your video with the " -"buttons on your video on the bottom-right, or using the shortcuts ``M`` to " +"buttons on the right side of the top bar, or using the shortcuts ``M`` to " "mute audio and ``V`` to disable video. You can also use the space bar to " "toggle mute. When you are muted, pressing space will unmute you so you can " "speak until you let go of the space bar. If you are unmuted, pressing space " "will mute you until you let go." msgstr "" -"Durante una llamada, puedes silenciar su micrófono y deshabilitar tu video " -"con los botones del video en la parte inferior derecha, o usando los accesos" -" directos ``M`` para silenciar el audio y ``V`` para deshabilitar el video. " -"También puede usar la barra espaciadora para alternar el silencio. Cuando " -"esté silenciado, al presionar la barra espaciadora se reactivará el silencio" -" para que pueda hablar hasta que suelte la barra espaciadora. Si no está " -"silenciado, al presionar la barra espaciadora se silenciará hasta que lo " -"suelte." +"Durante una llamada, puedes silenciar tu micrófono y deshabilitar tu video " +"con los botones de tu video en la parte inferior derecha, o usando los " +"accesos directos ``M`` para silenciar el audio y ``V`` para deshabilitar el " +"video. También puedes usar la barra espaciadora para alternar el silencio. " +"Cuando estéssilenciado, al presionar la barra espaciadora se reactivará el " +"silencio para que puedas hablar hasta que suelte la barra espaciadora. Si no" +" estás silenciado, al presionar la barra espaciadora se silenciará hasta que" +" lo suelte." #: ../../talk/talk_basics.rst:101 msgid "" @@ -278,16 +278,16 @@ msgstr "" #: ../../talk/talk_basics.rst:103 msgid "" "You can access your settings and choose a different webcam, microphone and " -"other settings in the ``...`` menu on your video." +"other settings in the ``...`` menu in the top bar." msgstr "" -"Puedes acceder a tu configuración y elegir una cámara web, un micrófono y " -"otras configuraciones diferentes en el menú ``...`` del video." +"Puede acceder a su configuración y elegir una cámara web, micrófono y otras " +"configuraciones diferentes en el menú ``...`` en la barra superior." -#: ../../talk/talk_basics.rst:112 +#: ../../talk/talk_basics.rst:110 msgid "Starting a screen share" msgstr "Compartir tu pantalla" -#: ../../talk/talk_basics.rst:114 +#: ../../talk/talk_basics.rst:112 msgid "" "You can click the monitor icon on your video stream to share your screen. " "Depending on your browser, you will get the option to share a monitor, an " @@ -298,11 +298,11 @@ msgstr "" "compartir un monitor, una ventana de aplicación o una sola pestaña del " "navegador." -#: ../../talk/talk_basics.rst:118 +#: ../../talk/talk_basics.rst:116 msgid "Changing view in a call" msgstr "Cambiar de vista en una llamada" -#: ../../talk/talk_basics.rst:120 +#: ../../talk/talk_basics.rst:118 msgid "" "You can switch the view in a call with the little four-block icon in the " "top-right between promoted-view and grid view. The grid view will show " @@ -315,7 +315,7 @@ msgstr "" "las personas no caben en la pantalla, aparecerán botones a la izquierda y a " "la derecha que te permitirán navegar." -#: ../../talk/talk_basics.rst:124 +#: ../../talk/talk_basics.rst:122 msgid "" "The promoted view shows the speaker large and others in a row below. If the " "people do not fit on the screen, buttons will appear on the left and right " |