khanh.pndc/nextcloud-docs
1
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2026-01-03 02:09:45 +07:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into wiswedel/sharing

Browse Source
This commit is contained in:
John Molakvoæ
2020-07-27 20:35:03 +02:00
committed by GitHub
parent 54df8c6e6f f316739fb8
commit 9d070372df
223 changed files with 8956 additions and 448 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
.github/workflows/generate_catalog_templates.yml vendored Normal file
View File

@@ -0,0 +1,24 @@
name: L10n
on:
push:
branches:
- master
paths:
- 'user_manual/**'
- '!user_manual/locale/**'
jobs:
user_manual:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: ammaraskar/sphinx-action@master
with:
docs-folder: "user_manual/"
pre-build-command: pip install -r requirements.txt
build-command: make gettext
- uses: peter-evans/create-pull-request@v3
with:
commit-message: Updates catalog templates (POT files fetched automatically by transifex)
title: l10n
branch: update-l10n

24
.github/workflows/transifex.yml vendored Normal file
View File

@@ -0,0 +1,24 @@
name: Transifex
on: pull_request
jobs:
approve:
runs-on: ubuntu-latest
name: Approve
steps:
- uses: hmarr/auto-approve-action@v2.0.0
if: github.actor == 'Transifex-localization-platform[bot]' || github.actor == 'transifex-integration[bot]'
with:
github-token: "${{ secrets.GITHUB_TOKEN }}"
automerge:
runs-on: ubuntu-latest
name: Auto-merge
steps:
- uses: pascalgn/automerge-action@v0.8.5
if: github.actor == 'Transifex-localization-platform[bot]' || github.actor == 'transifex-integration[bot]'
env:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
MERGE_LABELS: ""
MERGE_RETRIES: 6
MERGE_RETRY_SLEEP: 30000

8
README.rst
View File

@@ -85,6 +85,14 @@ If using the command line and your name and email are configured, you can use
In both settings be sure that your email address matches that in your Github profile,
which if you have privacy enabled will be github.username@users.noreply.github.com
Translations
------------
[Help translate the documentation](https://www.transifex.com/indiehosters/nextcloud-user-documentation/dashboard/).
For developers that want to ease the translation process, please read [this documentation](https://docs.transifex.com/integrations/sphinx-doc).
Building
--------

24
admin_manual/apps_management.rst
View File

@@ -24,7 +24,7 @@ Those apps are supported and developed by Nextcloud GmbH directly and
have an **Featured**-tag. See :doc:`installation/apps_supported` for a list of supported apps.
.. note:: Your Nextcloud server needs to be able to communicate with
``https://apps.nextcloud.com`` to list and download apps. Please make sure to whitelist this target in your firewall or proxy if necessary_.
``https://apps.nextcloud.com`` to list and download apps. Please make sure to whitelist this target in your firewall or proxy if necessary.
.. note:: To get access to work-arounds, long-term-support, priority bug fixing
and custom consulting for supported apps, contact our `sales team <https://nextcloud.com/enterprise/>`_.
@@ -89,21 +89,27 @@ in that folder.
],
],
Using your own appstore
-----------------------
.. note:: Apps paths can be located outside the server root. However, for any
**path** outside the server root, you need to create a symlink in the server
root that points **url** to **path**.
For instance, if **path** is ``/var/local/lib/nextcloud/apps``, and **url**
is ``/apps2``, then you would do this in the server root:
``ln -sf /var/local/lib/nextcloud/apps ./apps2``
You can enable the installation of apps from your own apps store. This requires that you
can write to at least one of the configured apps directories.
Using a self hosted apps store
------------------------------
To enable installation from your own apps store:
Enables the installation of apps from a self hosted apps store. Requires that at least one of the configured apps directories is writeable.
To enable a self hosted apps store:
1. Set the **appstoreenabled** parameter to "true".
This parameter is used to enable your apps store in Nextcloud.
This parameter is used to enable the apps store in Nextcloud.
2. Set the **appstoreurl** to the URL of your Nextcloud apps store.
This parameter is used to set the http path to the Nextcloud apps store.
This parameter is used to set the http path to your self hosted Nextcloud apps store.
::
@@ -113,4 +119,4 @@ To enable installation from your own apps store:
By default the apps store is enabled and configured to use ``https://apps.nextcloud.com/api/v1`` as apps store url. Nextcloud will fetch ``apps.json`` and ``categories.json`` from there. To use the defaults again remove **appstoreenabled** and **appstoreurl** from the configuration.
Example: If ``categories.json`` is available at ``https://apps.nextcloud.com/api/v1/categories.json`` the apps store url is ``https://apps.nextcloud.com/api/v1``.
Example: If ``categories.json`` is available at ``https://apps.nextcloud.com/api/v1/categories.json`` the apps store url is ``https://apps.nextcloud.com/api/v1``.

12
admin_manual/configuration_database/bigint_identifiers.rst
View File

@@ -2,12 +2,10 @@
BigInt (64bit) identifiers
==========================
Since Nextcloud 13 big integers are used to store identifiers and auto-increment keys in the database.
Because changing columns on huge tables can take quite a while (up to hours or days), the update from
Nextcloud 12 or earlier did not perform this migration on the filecache and activity table.
To make it easy to force the update on those tables too, we've added a console command, which can be used
to migrate the remaining columns to bigints.
Nextcloud uses big integers to store identifiers and auto-increment keys in the database.
Because changing columns on huge tables can take quite a while (up to hours or days)
depending on the number of files in the Nextcloud instance, this migration on the filecache-
and activity tablehas to be triggered manually by a console command.
The command can safely be executed. It will show a success message when there is nothing to do::
@@ -25,5 +23,5 @@ to suppress the confirmation message append ``--no-interaction`` to the argument
sudo -u www-data php occ db:convert-filecache-bigint --no-interaction
.. note:: Similar to a normal update, you should shutdown your apache or nginx server or enable maintenance
.. note:: Similar to a normal update, you should shutdown your Apache or nginx server or enable maintenance
mode before running the command to avoid issues with your sync clients.

8
admin_manual/configuration_database/mysql_4byte_support.rst
View File

@@ -95,7 +95,9 @@ MariaDB 10.3 or later
[mysqld]
innodb_file_per_table=1
2. Continue at step 2 of the MySQL instructions.
2. Restart the MariaDB server.
3. Continue at step 3 of the **MySQL** instructions.
MariaDB 10.2 or earlier
@@ -112,7 +114,7 @@ MariaDB 10.2 or earlier
innodb_file_format=barracuda
innodb_file_per_table=1
2. Restart the MariaDB server in case you changed the configuration in step 1.
2. Restart the MariaDB server.
3. Figure out whether the file format was changed to Barracuda::
@@ -133,4 +135,4 @@ This will return an SQL command for each table in the nextcloud database. The ro
Replace oc_tablename with the failing table. If there are too many (did not happen here), SQL commands can be generated in a batch (task for the reader).
6. Now everything should be fine and the MySQL instructions can be followed from step 3 onwards
6. Now everything should be fine and the MySQL instructions can be followed from step 3 onwards.

2
admin_manual/configuration_files/big_file_upload_configuration.rst
View File

@@ -81,7 +81,7 @@ nginx
Since nginx 1.7.11 a new config option `fastcgi_request_buffering
<https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_request_buffering>`_
is availabe. Setting this option to ``fastcgi_request_buffering off;`` in your nginx config
is available. Setting this option to ``fastcgi_request_buffering off;`` in your nginx config
might help with timeouts during the upload. Furthermore it helps if you're running out of
disc space on the tmp partition of your system.

6
admin_manual/configuration_files/encryption_configuration.rst
View File

@@ -6,12 +6,12 @@ The primary purpose of the Nextcloud server-side encryption is to protect users'
files on remote storage, such as Dropbox and Google Drive, and to do it easily
and seamlessly from within Nextcloud.
In Nextcloud 9.0 the server-side encryption separates encryption of local and
remote storage. This allows you to encrypt remote storage, such as Dropbox and
Server-side encryption separates encryption of local and remote storage.
This allows you to encrypt remote storage, such as Dropbox and
Google, without having to also encrypt your home storage on your Nextcloud
server.
.. note:: Starting with Nextcloud 9.0 we support Authenticated Encryption for all
.. note:: Nextcloud supports Authenticated Encryption for all
newly encrypted files. See https://hackerone.com/reports/108082 for more
technical information about the impact.

7
admin_manual/configuration_files/encryption_details.rst
View File

@@ -16,12 +16,12 @@ These conventions apply throughout this document:
- Static strings are denoted as ``"some string"``.
- The concatenation of strings is denoted as ``$variable."some string"``.
.. note:: This document describes the server-side encryption scheme as implemented by Nextcloud 16. Previous versions of Nextcloud implemented slightly different schemes which Nextcloud still supports for backwards compatibility. Files that have been encrypted by a recent version of Nextcloud should follow the structure documented below. However, files that have been encrypted by previous versions of Nextcloud may have slightly different structures.
.. note:: However, files that have been encrypted in Nextcloud versions 15 and lower may have slightly different structures.
Key type: master key
--------------------
While the master key encryption had to be enabled explicitly by calling ``./occ encryption:enable-master-key`` in older versions of Nextcloud it is now the default encryption mode in newer versions including Nextcloud 16. With master key encryption enabled there is one central key that is used to secure the files handled by Nextcloud. The master key is protected by a password that can be generated by the server administrator. The advantage of the master key encryption is that the encryption is transparent to the users but has the disadvantage that the server administrator is able to decrypt user files without knowing any user password.
This is the default encryption mode in Nextcloud. With master key encryption enabled there is one central key that is used to secure the files handled by Nextcloud. The master key is protected by a password that can be generated by the server administrator. The advantage of the master key encryption is that the encryption is transparent to the users but has the disadvantage that the server administrator is able to decrypt user files without knowing any user password.
Key type: public sharing key
----------------------------
@@ -36,7 +36,8 @@ The recovery key is used to provide a restore mechanism in cases where the user
Key type: user key
------------------
While the user key encryption has been enabled by default in older versions of Nextcloud it now has to be enabled explicitly in newer versions including Nextcloud 16 by calling ``./occ encryption:disable-master-key``. With user key encryption enabled all users have their own user keys that are used to secure the files handled by Nextcloud. The user keys are protected by the user passwords. The advantage is that the server administrator is not able to decrypt user files without knowing any user password - unless the file is publicly shared or a recovery key is defined - but has the disadvantage that files are permanently lost if the users forget their user passwords - unless the files are (publicly) shared or a recovery key is defined.
User key encryption needs to be explicitly activated by calling ``./occ encryption:disable-master-key``. In older versions of Nextcloud this had been enabled by default.
With user key encryption enabled all users have their own user keys that are used to secure the files handled by Nextcloud. The user keys are protected by the user passwords. The advantage is that the server administrator is not able to decrypt user files without knowing any user password - unless the file is publicly shared or a recovery key is defined - but has the disadvantage that files are permanently lost if the users forget their user passwords - unless the files are (publicly) shared or a recovery key is defined.
.. note:: This method cannot be used with SAML authentication, because Nextcloud does not get a hold of any credentials whatsoever and therefore cannot use any users' passwords for encryption.

2
admin_manual/configuration_files/external_storage/smb.rst
View File

@@ -49,7 +49,7 @@ See :doc:`auth_mechanisms` for more information on authentication schemes.
SMB update notifications
------------------------
Starting with Nextcloud 10, Nextcloud can use smb update notifications to
Nextcloud can use smb update notifications to
listen for changes made to a configured SMB/CIFS storage and detect external
changes made to the storage in near real-time.

7
admin_manual/configuration_files/external_storage_configuration.rst
View File

@@ -1,7 +0,0 @@
=================================================
Configuring External Storage (configuration file)
=================================================
Starting with Nextcloud 9.0, the :file:`data/mount.json` file for configuring
external storages has been removed, and replaced with a set of
:ref:`occ commands <files_external_label>`.

9
admin_manual/configuration_files/external_storage_configuration_gui.rst
View File

@@ -6,18 +6,11 @@ The External Storage Support application enables you to mount external storage
services and devices as secondary Nextcloud storage devices. You may also allow
users to mount their own external storage services.
Nextcloud 9.0 introduces a new set of :ref:`occ commands for managing external storage <files_external_label>`.
Also new in 9.0 is an option for the Nextcloud admin to enable or disable sharing
on individual external mountpoints (see
:ref:`external_storage_mount_options_label`). Sharing on such mountpoints is
disabled by default.
For configuration of external storages via occ command, see :ref:`occ documentation <files_external_label>`.
Enabling External Storage Support
---------------------------------
.. warning:: Enabling this app will disable the **Stay logged in** checkbox on the login page.
The External storage support application is enabled on your Apps page.
.. figure:: external_storage/images/enable-app.png

4
admin_manual/configuration_files/file_sharing_configuration.rst
View File

@@ -76,6 +76,10 @@ Trashbin contents are not transferred::
(See :doc:`../configuration_server/occ_command` for a complete ``occ``
reference.)
Users may also transfer files or folders selectively by themselves.
See `user documentation <https://docs.nextcloud.com/server/latest/user_manual/files/transfer_ownership.html>`_ for details.
Creating persistent file Shares
-------------------------------

2
admin_manual/configuration_files/file_versioning.rst
View File

@@ -40,4 +40,4 @@ Additional options are:
Keep versions for at least D1 days and delete when they exceed D2 days.
* ``disabled``
Disable Versions; no files will be deleted.
Disable the Versions app; no old file versions will be deleted.

1
admin_manual/configuration_files/index.rst
View File

@@ -12,7 +12,6 @@ File sharing and management
default_files_configuration
primary_storage
external_storage_configuration_gui
external_storage_configuration
external_storage/auth_mechanisms
encryption_configuration
encryption_details

9
admin_manual/configuration_files/previews_configuration.rst
View File

@@ -95,3 +95,12 @@ to 'null':
<?php
'preview_max_scale_factor' => null,
JPEG quality setting:
^^^^^^^^^^^^^^^^^^^^^
Default JPEG quality setting for preview images is '90'. Change this with:
::
occ config:app:set preview jpeg_quality --value="60"

6
admin_manual/configuration_server/activity_configuration.rst
View File

@@ -44,7 +44,7 @@ like in normal shares when set to ``true``.
.. warning::
This config option comes with the following limitations::
This config option comes with the following limitations:
1. Users that had access to a groupfolder, share or external storage can see activities in their stream and emails that happen after they are removed until they login again
2. Users that are newly added to a groupfolder, share or external storage can not see activities in their stream nor emails that happen after they are added until they login again
@@ -57,8 +57,8 @@ e.g. you want to send the hourly emails always at the full hour, daily emails be
people start to work in the morning and weekly mails shall be send on monday morning,
so people can read up when starting into the week.
Therefore in Nextcloud 12 a console command was added to allow sending those emails
intentionally. This allows to set up special cron jobs on your server with the known
A console command is available to trigger sending those emails.
This allows to set up special cron jobs on your server with the known
granularity, instead of relying on the Nextcloud cron feature which is not very flexible
on scheduling.

2
admin_manual/configuration_server/caching_configuration.rst
View File

@@ -59,7 +59,7 @@ Refresh your Nextcloud admin page, and the cache warning should disappear.
.. warning:: APCu is disabled by default on CLI which could cause issues with nextcloud's
cron jobs. Please make sure you set the ``apc.enable_cli`` to ``1`` on your ``php.ini``
config file.
config file or append ``--define apc.enable_cli=1`` to the cron job call.
Redis
-----

10
admin_manual/configuration_server/config_sample_php_parameters.rst
View File

@@ -1060,6 +1060,16 @@ When enabled, admins may install apps from the Nextcloud app store.
Defaults to ``true``
::
'appstoreurl' => 'https://apps.nextcloud.com/api/v1',
Enables the installation of apps from a self hosted apps store.
Requires that at least one of the configured apps directories is writeable.
Defaults to ``https://apps.nextcloud.com/api/v1``
::
'apps_paths' => [

30
admin_manual/configuration_server/occ_command.rst
View File

@@ -68,7 +68,7 @@ Running ``occ`` with no options lists all commands and options, like this
example on Ubuntu::
sudo -u www-data php occ
Nextcloud version 9.0.0
Nextcloud version 19.0.0
Usage:
command [options] [arguments]
@@ -103,14 +103,14 @@ Run it with the ``-h`` option for syntax help::
Display your Nextcloud version::
sudo -u www-data php occ -V
Nextcloud version 9.0.0
Nextcloud version 19.0.0
Query your Nextcloud server status::
sudo -u www-data php occ status
- installed: true
- version: 9.0.0.19
- versionstring: 9.0.0
- version: 19.0.0.12
- versionstring: 19.0.0
- edition:
``occ`` has options, commands, and arguments. Options and arguments are
@@ -142,15 +142,15 @@ The ``status`` command from above has an option to define the output format.
The default is plain text, but it can also be ``json``::
sudo -u www-data php occ status --output=json
{"installed":true,"version":"9.0.0.19","versionstring":"9.0.0","edition":""}
{"installed":true,"version":"19.0.0.9","versionstring":"19.0.0","edition":""}
or ``json_pretty``::
sudo -u www-data php occ status --output=json_pretty
{
"installed": true,
"version": "9.0.0.19",
"versionstring": "9.0.0",
"version": "19.0.0.12",
"versionstring": "19.0.0",
"edition": ""
}
@@ -164,7 +164,7 @@ Enabling autocompletion
.. note:: Command autocompletion currently only works if the user you use to execute the occ commands has a profile.
``www-data`` in most cases is ``nologon`` and therefor **cannot** use this feature.
Since Nextcloud 11 autocompletion is available for bash (and bash based consoles).
Autocompletion is available for bash (and bash based consoles).
To enable it, you have to run **one** of the following commands::
# BASH ~4.x, ZSH
@@ -198,7 +198,8 @@ The ``app`` commands list, enable, and disable apps::
app:enable enable an app
app:getpath get an absolute path to the app directory
app:list list all available apps
app:update update an app or all apps
app:update update an app or all apps
app:remove disable and remove an app
List all of your installed apps, and show whether they are
enabled or disabled::
@@ -327,7 +328,7 @@ Getting a single configuration value
These commands get the value of a single app or system configuration::
sudo -u www-data php occ config:system:get version
9.0.0.19
19.0.0.12
sudo -u www-data php occ config:app:get activity installed_version
2.2.1
@@ -724,6 +725,9 @@ It is also possible to transfer only one directory along with it's contents. Thi
sudo -u www-data php occ files:transfer-ownership --path="path_to_dir" <source-user> <destination-user>
Users may also transfer files or folders selectively by themselves.
See `user documentation <https://docs.nextcloud.com/server/latest/user_manual/files/transfer_ownership.html>`_ for details.
.. _files_external_label:
Files external
@@ -780,7 +784,7 @@ Verify your app::
sudo -u www-data php occ integrity:check-app --path=/pathto/app appname
When it returns nothing, your app is signed correctly. When it returns a message then there is an error. See `Code Signing
<https://docs.nextcloud.org/server/15/developer_manual/app/code_signing.html#how-to-get-your-app-signed>`_ in the Developer manual for more detailed information.
<https://docs.nextcloud.org/server/latest/developer_manual/app/code_signing.html#how-to-get-your-app-signed>`_ in the Developer manual for more detailed information.
.. TODO ON RELEASE: Update version number above on release
``integrity:sign-core`` is for Nextcloud core developers only.
@@ -1105,7 +1109,7 @@ You can delete users::
View a user's most recent login::
sudo -u www-data php occ user:lastseen layla
layla's last login: 09.01.2015 18:46
layla's last login: 09.01.2020 18:46
Read user settings::
@@ -1257,7 +1261,7 @@ Then choose your ``occ`` options. This lists your available options::
sudo -u www-data php /var/www/nextcloud/occ
Nextcloud is not installed - only a limited number of commands are available
Nextcloud version 9.0.0
Nextcloud version 19.0.0
Usage:
[options] command [arguments]

6
admin_manual/configuration_user/two_factor-auth.rst
View File

@@ -13,7 +13,7 @@ Several 2FA apps are already available including
a Telegram/Signal/SMS gateway and `U2F <https://en.wikipedia.org/wiki/Universal_2nd_Factor>`_.
Developers can `build new two-factor provider apps <https://docs.nextcloud.com/server/14/developer_manual/app/two-factor-provider.html>`_.
Developers can `build new two-factor provider apps <https://docs.nextcloud.com/server/latest/developer_manual/app/two-factor-provider.html>`_.
.. TODO ON RELEASE: Update version number above on release
@@ -27,7 +27,7 @@ you want, 2FA will be installed and enabled on your Nextcloud server.
.. figure:: ../images/2fa-app-install.png
Once 2FA has been enabled, users have to `activate it in their personal settings. <https://docs.nextcloud.com/server/14/user_manual/user_2fa.html>`_
Once 2FA has been enabled, users have to `activate it in their personal settings. <https://docs.nextcloud.com/server/latest/user_manual/user_2fa.html>`_
.. TODO ON RELEASE: Update version number above on release
@@ -36,7 +36,7 @@ Enforcing two-factor authentication
-----------------------------------
By default 2FA is *optional*, hence users are given the choice whether to enable
it for their account. Since Nextcloud 15, admins may enforce the use of 2FA.
it for their account. Admins may enforce the use of 2FA.
Enforcement is possible systemwide (all users), for selected groups only and can

2
admin_manual/groupware/calendar.rst
View File

@@ -20,7 +20,7 @@ by a background task. See :doc:`../configuration_server/occ_command` section Dav
Reminder notifications
----------------------
Since version 17, Nextcloud handles sending notifications for events.
Nextcloud handles sending notifications for events.
Nextcloud currently handles two types of reminder notifications: Build-in Nextcloud notifications and
email notifications. For the emails to be send, you'll need a configured email server.

4
admin_manual/installation/command_line_installation.rst
View File

@@ -19,8 +19,8 @@ this example for Debian/Ubuntu. You must run ``occ`` as your HTTP user; see
of running the graphical Installation Wizard::
$ cd /var/www/nextcloud/
$ sudo -u www-data php occ maintenance:install --database
"mysql" --database-name "nextcloud" --database-user "root" --database-pass
$ sudo -u www-data php occ maintenance:install --database \
"mysql" --database-name "nextcloud" --database-user "root" --database-pass \
"password" --admin-user "admin" --admin-pass "password"
Nextcloud is not installed - only a limited number of commands are available
Nextcloud was successfully installed

2
admin_manual/installation/example_centos.rst
View File

@@ -88,7 +88,7 @@ Manually building redis/imagick (optional)
dnf config-manager --set-enabled PowerTools
dnf install -y Imagemagick ImageMagick-devel
dnf install -y ImageMagick ImageMagick-devel
pecl install imagick

37
admin_manual/installation/example_ubuntu.rst
View File

@@ -1,23 +1,42 @@
.. _ubuntu_installation_label:
Example installation on Ubuntu 18.04 LTS
Example installation on Ubuntu 20.04 LTS
========================================
Or you can use .deb packages to install the required and recommended modules for a typical Nextcloud
You can use .deb packages to install the required and recommended modules for a typical Nextcloud
installation, using Apache and MariaDB, by issuing the following commands in a
terminal::
apt-get install apache2 mariadb-server libapache2-mod-php7.2
apt-get install php7.2-gd php7.2-json php7.2-mysql php7.2-curl php7.2-mbstring
apt-get install php7.2-intl php-imagick php7.2-xml php7.2-zip
sudo apt update
sudo apt install apache2 mariadb-server libapache2-mod-php7.4
sudo apt install php7.4-gd php7.4-mysql php7.4-curl php7.4-mbstring php7.4-intl
sudo apt install php7.4-gmp php7.4-bcmath php-imagick php7.4-xml php7.4-zip
* This installs the packages for the Nextcloud core system.
If you are planning on running additional apps, keep in mind that they might require additional
packages. See :ref:`prerequisites_label` for details.
* At the installation of the MySQL/MariaDB server, you will be prompted to
create a root password. Be sure to remember your password as you will need it
during Nextcloud database setup.
Now you need to create a database user and the database itself by using the
MySQL command line interface. The database tables will be created by Nextcloud
when you login for the first time.
To start the MySQL command line mode use the following command and press the enter key when prompted for a password::
sudo /etc/init.d/mysql start
sudo mysql -uroot -p
Then a **MariaDB [root]>** prompt will appear. Now enter the following lines, replacing username and password with appropriate values, and confirm them with the enter key:
::
CREATE USER 'username'@'localhost' IDENTIFIED BY 'password';
CREATE DATABASE IF NOT EXISTS nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
GRANT ALL PRIVILEGES ON nextcloud.* TO 'username'@'localhost';
FLUSH PRIVILEGES;
You can quit the prompt by entering::
quit;
Now download the archive of the latest Nextcloud version:
@@ -45,7 +64,7 @@ Now download the archive of the latest Nextcloud version:
* Now you can extract the archive contents. Run the appropriate unpacking
command for your archive type::
tar -xjf nextcloud-x.y.z.tar.bz2
tar -xjfv nextcloud-x.y.z.tar.bz2
unzip nextcloud-x.y.z.zip
* This unpacks to a single ``nextcloud`` directory. Copy the Nextcloud directory

8
admin_manual/installation/nginx.rst
View File

@@ -34,7 +34,7 @@ webroot of your nginx installation. In this example it is
upstream php-handler {
server 127.0.0.1:9000;
#server unix:/var/run/php/php7.2-fpm.sock;
#server unix:/var/run/php/php7.4-fpm.sock;
}
server {
@@ -179,7 +179,7 @@ webroot of your nginx installation. In this example it is
access_log off;
}
location ~ \.(?:png|html|ttf|ico|jpg|jpeg|bcmap|mp4|webm)$ {
location ~ \.(?:png|html|ttf|ico|jpg|jpeg|bcmap|mp4|webm|mp3|ogg|wav)$ {
try_files $uri /index.php$request_uri;
# Optional: Don't log access to other assets
access_log off;
@@ -198,7 +198,7 @@ In this example the webroot is located at
upstream php-handler {
server 127.0.0.1:9000;
#server unix:/var/run/php/php7.2-fpm.sock;
#server unix:/var/run/php/php7.4-fpm.sock;
}
server {
@@ -347,7 +347,7 @@ In this example the webroot is located at
access_log off;
}
location ~ ^\/nextcloud\/.+[^\/]\.(?:png|html|ttf|ico|jpg|jpeg|bcmap|mp4|webm)$ {
location ~ ^\/nextcloud\/.+[^\/]\.(?:png|html|ttf|ico|jpg|jpeg|bcmap|mp4|webm|mp3|ogg|wav)$ {
try_files $uri /nextcloud/index.php$request_uri;
# Optional: Don't log access to other assets
access_log off;

14
admin_manual/installation/source_installation.rst
View File

@@ -14,8 +14,7 @@ archive <https://nextcloud.com/install/>`_. This method is recommended to instal
If you prefer a more automated installation of Nextcloud and there are no packages for your Linux distribution, you have the option to
install the community `Snap Packages <http://snapcraft.io/docs/core/install/>`_. See
:ref:`snaps_label` You can also use the `Nextcloud VM scripts <https://github.com/nextcloud/vm/>`_ to install directly on a clean Ubuntu Server. It will setup everything for you and include scripts for automated installation of apps like; Collabora, OnlyOffice, Talk and so on. Please note that those two options are not officially supported by Nextcloud GmbH.
install the community `Snap Package <https://snapcraft.io/nextcloud>`_. This includes a full production-ready stack, will maintain your HTTPS certificates for you, and will automatically update as needed to stay secure. You can also use the `Nextcloud VM scripts <https://github.com/nextcloud/vm/>`_ to install directly on a clean Ubuntu Server. It will setup everything for you and include scripts for automated installation of apps like; Collabora, OnlyOffice, Talk and so on. Please note that those two options are not officially supported by Nextcloud GmbH.
This installation guide is giving a general overview of required dependencies and their configuration. For a distribution specific setup guide have a look at the :doc:`./example_ubuntu` and :doc:`./example_centos`.
@@ -77,6 +76,7 @@ Required for specific apps:
* PHP module gmp (for passwordless login)
Recommended for specific apps (*optional*):
* PHP module gmp (for SFTP storage)
* PHP module exif (for image rotation in pictures app)
@@ -406,15 +406,9 @@ The `Nextcloud VM`_ is maintained by
`T&M Hansson IT <https://www.hanssonit.se/nextcloud-vm/>`_ and several different versions are
offered. Collabora, OnlyOffice, Full Text Search and other apps can easily be installed with the included scripts which you can choose to run during the first setup, or download them later and run it afterwards. You can find all the currently available automated app installations `on GitHub <https://github.com/nextcloud/vm/tree/master/apps/>`_.
The VM is made with VMware version 10 and it comes in different sizes and versions:
The VM comes in different sizes and versions.
- 40 GB (VMware, VirtualBox, Hyper-V)
- 500 GB (VMware, VirtualBox, Hyper-V)
- 1 TB (VMware, VirtualBox, Hyper-V)
- 2 TB (VMware & VirtualBox, Hyper-V)
- Custom size? Please `ask us <https://www.hanssonit.se/#contact>`_.
You can find all the different version `here <https://shop.hanssonit.se/product-category/virtual-machine/nextcloud-vm/>`_.
You can find all the available versions `here <https://shop.hanssonit.se/product-category/virtual-machine/nextcloud-vm/>`_.
For complete instructions and downloads see:

2
admin_manual/installation/system_requirements.rst
View File

@@ -89,5 +89,5 @@ of a browser from this list, or one based on those:
- Apple **Safari**
.. note:: If you want to use Nextcloud Talk you should use Mozilla **Firefox** 52+ or Google **Chrome**/Chromium 49+ to have
the full experience with video calls and screensharing. Google Chrome/Chromium requires a additional plugin for
the full experience with video calls and screensharing. Google Chrome/Chromium requires an additional plugin for
screensharing.

2
admin_manual/issues/general_troubleshooting.rst
View File

@@ -36,7 +36,7 @@ configuration report with the :ref:`occ config command
.. _FAQ page: https://help.nextcloud.com/c/faq
.. _bugtracker: https://github.com/nextcloud/server/issues
.. _webchat: http://webchat.freenode.net/?channels=nextcloud
https://docs.nextcloud.org/server/14/developer_manual/bugtracker/index.html
https://docs.nextcloud.org/server/latest/developer_manual/bugtracker/index.html
.. TODO ON RELEASE: Update version number above on release
General troubleshooting

2
admin_manual/maintenance/restore.rst
View File

@@ -44,7 +44,7 @@ MySQL is the recommended database engine. To restore MySQL::
mysql -h [server] -u [username] -p[password] -e "DROP DATABASE nextcloud"
mysql -h [server] -u [username] -p[password] -e "CREATE DATABASE nextcloud"
If you use UTF8 with multibyte support (e.g. for emoijs in filenames), use::
If you use UTF8 with multibyte support (e.g. for emojis in filenames), use::
mysql -h [server] -u [username] -p[password] -e "DROP DATABASE nextcloud"
mysql -h [server] -u [username] -p[password] -e "CREATE DATABASE nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci"

42
admin_manual/release_notes.rst
View File

@@ -2,44 +2,4 @@
Release notes
=============
Changes in Nextcloud |version|
------------------------------
A detailed log of all changes can be found in the official `Changelog
<https://nextcloud.com/changelog/>`_. There are also all current and previous
versions linked.
Updates to Nginx configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
* In the Nginx configuration the Same-Origin header was added. Please add
this line to your Nginx config: ``add_header X-Frame-Options "SAMEORIGIN" always;``
See :doc:`installation/nginx`
* For improvements in serving HTTP requests the Nginx configuration now has
HTTP 2 enabled. Please update your Nginx config accordingly. See
:doc:`installation/nginx`
* The GZip configuration for Nginx was updated. See :doc:`installation/nginx`
for details.
Common questions
----------------
Could not install core app bundle
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following error message is shown during the update: "Repair warning: Could
not install core app bundle: Could not download app <app>".
This basically means that Nextcloud could not fetch the app from the appstore
automatically. This could have multiple reasons: either you disabled the
appstore with the config.php flag or your server could not reach the app store.
The instance will work fine, but the features that are usually provided by this
app are not available.
Theming changes
---------------
With Nextcloud 12, CSS files have been merged into one server.css so in order
to keep your theme working you should consolidate your existing css styles into
a server.css file. As for the example theme the styles.css file has been
renamed to server.css.
See `the official changelog <https://nextcloud.com/changelog/>`_ for release notes.

15
developer_manual/app/coding-style.rst
View File

@@ -1,15 +0,0 @@
============
Coding Style
============
.. sectionauthor:: Christoph Wurst <christoph@winzerhof-wurst.at>
PHP
---
Starting with Nextcloud 19 there is a shared `PHP Coding Standards Fixer <https://github.com/FriendsOfPhp/PHP-CS-Fixer>`_ configuration you can use to automatically format your app's source code. For full details see the `repository on Github <https://github.com/nextcloud/coding-standard/>`_.
JavaScript
----------
There is a shared configuration for `eslint <https://eslint.org/>`_ that you can use to automatically format your Nextcloud apps's JavaScript code. It consists of two parts: a `config package <https://github.com/nextcloud/eslint-config>`_ that contains the formatting preferences and a `plugin <https://github.com/nextcloud/eslint-plugin>`_ to detect deprecated and removed APIs in your code. See their readmes for instructions.

37
developer_manual/app/index.rst
View File

@@ -1,37 +0,0 @@
===============
App development
===============
.. toctree::
:maxdepth: 1
intro
tutorial
upgrade-guide
npm
javascript-apis
requests/index
view/index
storage/index
changelog
classloader
code_signing
info
init
publishing
users
two-factor-provider
events
backgroundjobs
settings
notifications
flow
logging
repair
publicpage
testing
coding-style
psr
../api

12
developer_manual/app/psr.rst
View File

@@ -1,12 +0,0 @@
===
PSR
===
.. sectionauthor:: Christoph Wurst <christoph@winzerhof-wurst.at>
On this page you find information about the implemented `php standards recommendations <https://www.php-fig.org/psr/>`_ in Nextcloud.
PSR-3: Logger Interface
-----------------------
As of Nextcloud 19, the dependency injection container can inject an instance of a ``\Psr\Log\LoggerInterface``. This is merely a wrapper of the existing (and strongly typed) ``\OCP\ILogger``. Apps may still use the Nextcloud logger, but the PSR-3 implementation shall easy the integration of 3rd party libraries that require the PSR-3 logger.

135
developer_manual/app_development/bootstrap.rst Normal file
View File

@@ -0,0 +1,135 @@
.. _Bootstrapping:
=============
Bootstrapping
=============
Every php process has a relatively short lifespan that lasts as long as the HTTP request or the invokation of the command
line program. At the beginning of this lifespan, Nextcloud initializes its services. At the same time, any additional apps
might want to register their services to Nextcloud as well. This event is called the *bootstrapping* and this chapter
shall shed some light on how to hook into this with an app.
.. _application-php:
The Application class
---------------------
The `Application` class is the main entry point of an app. This class is optional but highly recommended if your app needs
to register any services or run some code for every request.
Nextcloud will try to autoload the class from the namespace ``\OCA\<App namespace>\AppInfo\Application``, like e.g.
``\OCA\Mail\AppInfo\Application``. The file will therefore be located at ``lib/AppInfo``.
.. code-block:: php
<?php
declare(strict_types=1);
namespace OCA\MyApp\AppInfo;
use OCP\AppFramework\App;
class Application extends App {
public function __construct() {
parent::__construct('myapp');
\OCP\Util::connectHook('OC_User', 'pre_deleteUser', 'OCA\MyApp\Hooks\User', 'deleteUser');
}
}
The class **must** extend ``OCP\AppFramework\App`` and it may optionally implement ``\OCP\AppFramework\Bootstrap\IBootstrap``:
.. code-block:: php
<?php
declare(strict_types=1);
namespace OCA\MyApp\AppInfo;
use OCA\MyApp\Listeners\UserDeletedListener;
use OCA\MyApp\Notifications\Notifier;
use OCP\AppFramework\App;
use OCP\AppFramework\Bootstrap\IBootstrap;
use OCP\Notification\IManager;
use OCP\User\Events;
class Application extends App implements IBootstrap {
public function register(IRegistrationContext $context): void {
// ... registration logic goes here ...
$context->registerEventListener(
BeforeUserDeletedEvent::class,
UserDeletedListener::class
);
}
public function boot(IBootContext $context): void {
// ... boot logic goes here ...
/** @var IManager $manager */
$manager = $context->getAppContainer()->query(IManager::class)
$manager->registerNotifierService(Notifier::class);
}
}
Bootstrapping process
---------------------
To give a better overview of *when* each of the bootstrapping stages are reached and how they app can interact with them,
this section explains the changes done for Nextcloud 20.
Nextcloud 20 and later
**********************
Nextcloud 20 is the first release with the interface ``\OCP\AppFramework\Bootstrap\IBootstrap``. This interface can be
implemented by apps' Application class to signal that they want to act on the bootstrapping stages. The major difference
between this and the old process is that the boostrapping is not performed in a sequence, but apps register and boot
interleaved. This should ensure that an app that boots can rely on all other apps' registration to be finished.
The overall process is as follows.
1) Each installed and enabled app that has an ``Application`` class class that implements ``IBootstrap``, the ``register``
method will be called. This method receives a context argument via which the app can prime the dependency injection
container and register many other services lazily. The emphasis is on **lazyness**. At this very early stage of the
process lifetime, no other apps nor all of the server components are ready. Therefore the app **must not** try to use
anything except the API provided by the context. That shall ensure that all apps can safely run their registration logic
before any services are queried from the DI container or related code is run.
2) Nextcloud will load groups of certain apps early, like filesystem or session apps, and other later. For this their optional
:ref:`app-php` will be included. As ``app.php`` is deprecated, apps should try not to rely on this step.
3) Nextcloud will query the app's ``Application`` class (again), no matter if it implements ``IBootstrap`` or not.
4) Nextcloud will invoke the ``boot`` method of every ``Application`` instance that implements ``IBootstrap``. At this stage
you may assume that all registrations via ``IBootstrap::register`` have been done.
Nextcloud 19 and older
**********************
Nextcloud will load groups of certain apps early, like filesystem or session apps, and other later. For this their optional
:ref:`app-php` will be included. The ``Application`` class is only queried for some requests, so there is no guarantee that
its contstructor will be invoked.
.. _app-php:
app.php (deprecated)
--------------------
Nextcloud will ``require_once`` every installed and enabled app's ``appinfo/app.php`` file if it exists. The app can use
this file to run registrations of services, event listeners and similar.
To leverage the advantages of object-oriented programming, it's recommended to put the logic into an :ref:`Application<application-php>`
class and query an instance like
.. code-block:: php
<?php
declare(strict_types=1);
$app = \OC::$server->query(\OCA\MyApp\AppInfo\Application::class);

13
developer_manual/app_development/index.rst Normal file
View File

@@ -0,0 +1,13 @@
===============
App development
===============
.. toctree::
:maxdepth: 2
intro
tutorial
bootstrap
info
init
logging

0
developer_manual/app/info.rst → developer_manual/app_development/info.rst
View File

35
developer_manual/app/init.rst → developer_manual/app_development/init.rst
View File

@@ -60,38 +60,3 @@ purpose there are several events emitted that an app can act upon.
\OCP\Util::addStyle('myapp', 'style');
}
);
Best practice
-------------
A common way to have a cleaner code structure is to create a class Application in :file:`lib/AppInfo/Application.php` that will then execute your setup of hooks or background tasks. You can then just call it in your :file:`appinfo/app.php`. That way you can also make use of Nextclouds dependency injection feature and properly test those methods.
appinfo/app.php
^^^^^^^^^^^^^^^
.. code-block:: php
<?php
$app = new \OCA\MyApp\AppInfo\Application();
$app->registerHooks();
lib/AppInfo/Application.php
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: php
<?php
namespace OCA\MyApp\AppInfo;
use OCP\AppFramework\App;
class Application extends App {
public function registerHooks() {
\OCP\Util::connectHook('OC_User', 'pre_deleteUser', 'OCA\MyApp\Hooks\User', 'deleteUser');
}
}

0
developer_manual/app/intro.rst → developer_manual/app_development/intro.rst
View File

2
developer_manual/app/tutorial.rst → developer_manual/app_development/tutorial.rst
View File

@@ -16,7 +16,7 @@ First the :doc:`development environment <../general/devenv>` needs to be set up.
cd server
git submodule update --init
.. note:: ``$BRANCH`` is the desired Nextcloud branch (e.g. ``stable17`` for Nextcloud 17, ``master`` for the upcoming release)
.. note:: ``$BRANCH`` is the desired Nextcloud branch (e.g. ``stable19`` for Nextcloud 19, ``master`` for the upcoming release)
First you want to enable debug mode to get proper error messages. To do that set ``debug`` to ``true`` in the **config/config.php** file::

0
developer_manual/app/code_signing.rst → developer_manual/app_publishing_maintenance/code_signing.rst
View File

10
developer_manual/app_publishing_maintenance/index.rst Normal file
View File

@@ -0,0 +1,10 @@
==============================
App publishing and maintenance
==============================
.. toctree::
:maxdepth: 2
code_signing
publishing
upgrade-guide

0
developer_manual/app/publishing.rst → developer_manual/app_publishing_maintenance/publishing.rst
View File

53
developer_manual/app/upgrade-guide.rst → developer_manual/app_publishing_maintenance/upgrade-guide.rst
View File

@@ -6,6 +6,59 @@ Once you've created and published the first version of your app, you will want t
This document will cover the most important changes in Nextcloud, as well as some guides on how to upgrade existing apps.
Upgrading to Nextcloud 20
-------------------------
.. note:: Critical changes were collected `on Github <https://github.com/nextcloud/server/issues/20953>`_. See the original ticket for links to the pull requests and tickets.
Back-end changes
^^^^^^^^^^^^^^^^
.. _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.
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:
.. code-block:: php
// old
$container->registerService('DecryptAll', function (IAppContainer $c) {
return new DecryptAll(
$c->query('Util'),
$c->query(KeyManager::class),
$c->query('Crypt'),
$c->query(ISession::class)
)
})
becomes
.. code-block:: php
// new
$container->registerService('DecryptAll', function (ContainerInterface $c) {
return new DecryptAll(
$c->get('Util'),
$c->get(KeyManage::class'),
$c->get('Crypt'),
$c->get(ISession::class)
)
})
.. note:: For a smoother transition, the old interfaces were changed so they are based on ``ContainerInterface``, hence you can use ``has`` and ``get`` on ``IContainer`` and sub types.
Deprecated APIs
***************
* ``\OCP\AppFramework\IAppContainer``: see :ref:`upgrade-psr11`
* ``\OCP\IContainer``: see :ref:`upgrade-psr11`
* ``\OCP\IServerContainer``: see :ref:`upgrade-psr11`
Upgrading to Nextcloud 19
-------------------------

2
developer_manual/app/backgroundjobs.rst → developer_manual/basics/backgroundjobs.rst
View File

@@ -45,7 +45,7 @@ your job class of choice.
parent::setInterval(3600);
}
public static function run($arguments) {
protected function run($arguments) {
$this->myService->doCron($arguments['uid']);
}

0
developer_manual/app/requests/controllers.rst → developer_manual/basics/controllers.rst
View File

78
developer_manual/app/requests/container.rst → developer_manual/basics/dependency_injection.rst
View File

@@ -1,6 +1,6 @@
=========
Container
=========
====================
Dependency injection
====================
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>
@@ -28,6 +28,7 @@ new dependencies in your constructor or methods but pass them in. So this:
// without dependency injection
class AuthorMapper {
/** @var IDBConnection */
private $db;
public function __construct() {
@@ -42,12 +43,15 @@ would turn into this by using Dependency Injection:
<?php
use OCP\IDBConnection;
// with dependency injection
class AuthorMapper {
/** @var IDBConnection */
private $db;
public function __construct($db) {
public function __construct(IDBConnection $db) {
$this->db = $db;
}
@@ -69,6 +73,9 @@ The solution for this particular problem is to limit the **new AuthorMapper** to
one file, the container. The container contains all the factories for creating
these objects and is configured in :file:`lib/AppInfo/Application.php`.
Nextcloud 20 and later uses the :ref:`PSR-11 standard <psr11>` for the container interface, so working
with the container might feel familiar if you've worked with other php applications
before that also adhere to the convention.
To add the app's classes simply open the :file:`lib/AppInfo/Application.php` and
use the **registerService** method on the container object:
@@ -79,11 +86,12 @@ use the **registerService** method on the container object:
namespace OCA\MyApp\AppInfo;
use \OCP\AppFramework\App;
use OCP\AppFramework\App;
use \OCA\MyApp\Controller\AuthorController;
use \OCA\MyApp\Service\AuthorService;
use \OCA\MyApp\Db\AuthorMapper;
use OCA\MyApp\Controller\AuthorController;
use OCA\MyApp\Service\AuthorService;
use OCA\MyApp\Db\AuthorMapper;
use Psr\Container\ContainerInterface;
class Application extends App {
@@ -99,29 +107,29 @@ use the **registerService** method on the container object:
/**
* Controllers
*/
$container->registerService('AuthorController', function($c){
$container->registerService('AuthorController', function(ContainerInterface $c){
return new AuthorController(
$c->query('AppName'),
$c->query('Request'),
$c->query('AuthorService')
$c->get('AppName'),
$c->get('Request'),
$c->get('AuthorService')
);
});
/**
* Services
*/
$container->registerService('AuthorService', function($c){
$container->registerService('AuthorService', function(ContainerInterface $c){
return new AuthorService(
$c->query('AuthorMapper')
$c->get('AuthorMapper')
);
});
/**
* Mappers
*/
$container->registerService('AuthorMapper', function($c){
$container->registerService('AuthorMapper', function(ContainerInterface $c){
return new AuthorMapper(
$c->query('ServerContainer')->getDatabaseConnection()
$c->get('ServerContainer')->getDatabaseConnection()
);
});
}
@@ -136,26 +144,26 @@ The container works in the following way:
* The matched route queries **AuthorController** service from the container::
return new AuthorController(
$c->query('AppName'),
$c->query('Request'),
$c->query('AuthorService')
$c->get('AppName'),
$c->get('Request'),
$c->get('AuthorService')
);
* The **AppName** is queried and returned from the base class
* The **Request** is queried and returned from the server container
* **AuthorService** is queried::
$container->registerService('AuthorService', function($c){
$container->registerService('AuthorService', function(ContainerInterface $c){
return new AuthorService(
$c->query('AuthorMapper')
$c->get('AuthorMapper')
);
});
* **AuthorMapper** is queried::
$container->registerService('AuthorMappers', function($c){
$container->registerService('AuthorMappers', function(ContainerInterface $c){
return new AuthorService(
$c->query('ServerContainer')->getDatabaseConnection()
$c->get('ServerContainer')->getDatabaseConnection()
);
});
@@ -170,15 +178,15 @@ So basically the container is used as a giant factory to build all the classes t
Use automatic dependency assembly (recommended)
-----------------------------------------------
In Nextcloud it is possible to omit the **lib/AppInfo/Application.php** and use automatic dependency assembly instead.
In Nextcloud it is possible to build classes and their dependencies without having to explicitly register them on the container, as long as the container can `reflect <reflection>`_ the constructor and look up the parameters by their type. This concept is widely known as *auto-wiring*.
How does automatic assembly work
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
How does auto-wiring work
^^^^^^^^^^^^^^^^^^^^^^^^^
Automatic assembly creates new instances of classes just by looking at the class name and its constructor parameters. For each constructor parameter the type or the variable name is used to query the container, e.g.:
Automatic assembly creates new instances of classes just by looking at the class name and its constructor parameters. For each constructor parameter the type or the argument name is used to query the container, e.g.:
* **SomeType $type** will use **$container->query('SomeType')**
* **$variable** will use **$container->query('variable')**
* **SomeType $type** will use **$container->get('SomeType')**
* **$variable** will use **$container->get('variable')**
If all constructor parameters are resolved, the class will be created, saved as a service and returned.
@@ -203,12 +211,12 @@ So basically the following is now possible:
$app = new \OCP\AppFramework\App('myapp');
$class2 = $app->getContainer()->query('OCA\MyApp\MyTestClass2');
$class2 = $app->getContainer()->get('OCA\MyApp\MyTestClass2');
$class2 instanceof MyTestClass2; // true
$class2->class instanceof MyTestClass; // true
$class2->appName === 'appname'; // true
$class2 === $app->getContainer()->query('OCA\MyApp\MyTestClass2'); // true
$class2 === $app->getContainer()->get('OCA\MyApp\MyTestClass2'); // 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.
@@ -223,7 +231,7 @@ How does it affect the request lifecycle
* A request is matched for the route, e.g. with the name **page#index**
* The appropriate container is being queried for the entry PageController (to keep backwards compatibility)
* If the entry does not exist, the container is queried for OCA\\AppName\\Controller\\PageController and if no entry exists, the container tries to create the class by using reflection on its constructor parameters
* If the entry does not exist, the container is queried for OCA\\AppName\\Controller\\PageController and if no entry exists, the container tries to create the class by using `reflection`_ on its constructor parameters
How does this affect controllers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -284,8 +292,8 @@ Interfaces and primitive types can not be instantiated, so the container can not
$container->registerParameter('TableName', 'my_app_table');
// the interface is called IAuthorMapper and AuthorMapper implements it
$container->registerService('OCA\MyApp\Db\IAuthorMapper', function ($c) {
return $c->query('OCA\MyApp\Db\AuthorMapper');
$container->registerService('OCA\MyApp\Db\IAuthorMapper', function (ContainerInterface $c) {
return $c->get('OCA\MyApp\Db\AuthorMapper');
});
}
@@ -380,3 +388,5 @@ What not to inject:
* It is pure data and has methods that only act upon it (arrays, data objects)
* It is a `pure function <http://en.wikipedia.org/wiki/Pure_function>`_
.. _`reflection`: https://www.php.net/manual/en/book.reflection.php

21
developer_manual/app/events.rst → developer_manual/basics/events.rst
View File

@@ -167,6 +167,27 @@ Available Events
Here you find an overview of the public events that can be consumed in apps. See their source files for more details.
``\OCA\DAV\Events\SabrePluginAuthInitEvent``
********************************************************
*Available in Nextcloud 20 and later.*
This event is triggered during the setup of the SabreDAV server to allow the registration of additional authentication backends.
``\OCA\Files_Sharing\Event\BeforeTemplateRenderedEvent``
********************************************************
*Available in Nextcloud 20 and later.*
Emitted before the rendering step of the public share page happens. The event holds a flag that specifies if it is the authentication page of a public share.
``\OCP\AppFramework\Http\Events\BeforeTemplateRenderedEvent``
*************************************************************
*Available in Nextcloud 20 and later.*
Emitted before the rendering step of each TemplateResponse. The event holds a flag that specifies if an user is logged in.
``\OCP\Authentication\Events\LoginFailedEvent``
***********************************************

2
developer_manual/app/view/css.rst → developer_manual/basics/front-end/css.rst
View File

@@ -18,7 +18,7 @@ The CSS files reside in the **css/** folder and should be included in the templa
// include vendor file (also allows array syntax)
vendor_style('myapp', 'style'); // adds vendor/style.(s)css
.. note:: Since the version 12 of Nextcloud, we support ``SCSS`` natively.
.. note:: ``SCSS`` is supported natively.
You can migrate your files by simply renaming your ``.css`` files to ``.scss``.
The server will automatically compile, cache and and serve it.
The priority goes to the scss file. So having two file with the same name and a ``scss`` & ``css`` extension

6
developer_manual/app/view/index.rst → developer_manual/basics/front-end/index.rst
View File

@@ -1,6 +1,6 @@
====
View
====
=========
Front-end
=========
.. toctree::
:maxdepth: 2

0
developer_manual/app/view/js.rst → developer_manual/basics/front-end/js.rst
View File

0
developer_manual/app/view/l10n.rst → developer_manual/basics/front-end/l10n.rst
View File

0
developer_manual/app/view/templates.rst → developer_manual/basics/front-end/templates.rst
View File

0
developer_manual/app/view/theming.rst → developer_manual/basics/front-end/theming.rst
View File

17
developer_manual/basics/index.rst Normal file
View File

@@ -0,0 +1,17 @@
==============
Basic concepts
==============
.. toctree::
:maxdepth: 2
request_lifecycle
routing
dependency_injection
controllers
middlewares
events
front-end/index
backgroundjobs
logging
storage/index

0
developer_manual/app/logging.rst → developer_manual/basics/logging.rst
View File

6
developer_manual/app/requests/middleware.rst → developer_manual/basics/middlewares.rst
View File

@@ -1,6 +1,6 @@
==========
Middleware
==========
===========
Middlewares
===========
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>

3
developer_manual/app/requests/index.rst → developer_manual/basics/request_lifecycle.rst
View File

@@ -5,10 +5,7 @@ Request lifecycle
.. toctree::
:maxdepth: 1
routes
middleware
container
controllers
api
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>, Morris Jobke <hey@morrisjobke.de>

0
developer_manual/app/requests/routes.rst → developer_manual/basics/routing.rst
View File

0
developer_manual/app/storage/appdata.rst → developer_manual/basics/storage/appdata.rst
View File

0
developer_manual/app/storage/configuration.rst → developer_manual/basics/storage/configuration.rst
View File

0
developer_manual/app/storage/database.rst → developer_manual/basics/storage/database.rst
View File

0
developer_manual/app/storage/filesystem.rst → developer_manual/basics/storage/filesystem.rst
View File

0
developer_manual/app/storage/index.rst → developer_manual/basics/storage/index.rst
View File

0
developer_manual/app/storage/migrations.rst → developer_manual/basics/storage/migrations.rst
View File

0
developer_manual/app/storage/schema.rst → developer_manual/basics/storage/schema.rst
View File

0
developer_manual/app/testing.rst → developer_manual/basics/testing.rst
View File

4
developer_manual/client_apis/LoginFlow/index.rst
View File

@@ -55,8 +55,6 @@ On the final login the server will do a redirect to a url of the following forma
This information will be used by the client to create a new account.
After this the webview is destroyed including all the state the webview holds.
.. note:: On Nextcloud 12 the returned server is just the server address without any possible subfolder. This is corrected in Nextcloud 13.
Converting to app passwords
---------------------------
@@ -119,8 +117,6 @@ Login flow v2
While the login flow works very nice in a lot of cases there are especially on dekstop application certain hurdles. Special proxy configuration, client side certificates and the likes can cause trouble. To solve this we have come up with a second login flow that uses the users default webbrowser to authenticate. Thus ensuring that if they can login via the web they can also login in the client.
The login flow v2 is available since Nextcloud 16. So check the status.php if it can be used on a given server.
To initiate a login do an anonymous POST request

8
developer_manual/client_apis/OCS/ocs-api-overview.rst
View File

@@ -166,13 +166,19 @@ Values of the theming app are exposed through the capabilities API, allowing cli
<slogan>A safe home for all your data</slogan>
<color>#0082c9</color>
<color-text>#ffffff</color-text>
<color-element>#006295</color-element>
<color-element>#0082c9</color-element>
<color-element-bright>#aaaaaa</color-element-bright>
<color-element-dark>#555555</color-element-dark>
<logo>http://cloud.example.com/index.php/apps/theming/logo?v=1</logo>
<background>http://cloud.example.com/index.php/apps/theming/logo?v=1</background>
<background-plain></background-plain>
<background-default></background-default>
</theming>
For elements like radio buttons, input borders and more, instead of the primary ``color`` value, the ``color-element-bright`` should be used on bright background and ``color-element-dark`` on dark background.
This when the primary color is e.g. set to ``#000000`` the ``color-elemenet-dark`` will be set to ``#555555`` so items are still visible. In the Nextcloud web UI only the top header uses ``color``, everything else uses ``color-element-*``.
Text and icons on these elements should use ``color-text``.
The background value can either be an URL to the background image or a hex color value.

2
developer_manual/client_apis/OCS/ocs-share-api.rst
View File

@@ -141,7 +141,7 @@ Federated Cloud Shares
----------------------
Both the sending and the receiving instance need to have federated cloud sharing
enabled and configured. See `Configuring Federated Cloud Sharing <https://docs.nextcloud.org/server/14/admin_manual/configuration_files/federated_cloud_sharing_configuration.html>`_.
enabled and configured. See `Configuring Federated Cloud Sharing <https://docs.nextcloud.org/server/latest/admin_manual/configuration_files/federated_cloud_sharing_configuration.html>`_.
.. TODO ON RELEASE: Update version number above on release

0
developer_manual/android_library/examples.rst → developer_manual/client_apis/android_library/examples.rst
View File

6
developer_manual/android_library/index.rst → developer_manual/client_apis/android_library/index.rst
View File

@@ -1,8 +1,8 @@
.. _androidindex:
===============================
Android application development
===============================
=======
Android
=======
Nextcloud provides an official Nextcloud Android client, which gives its users
access to their files on their Nextcloud. It also includes functionality like
automatically uploading pictures and videos to Nextcloud.

0
developer_manual/android_library/library_installation.rst → developer_manual/client_apis/android_library/library_installation.rst
View File

7
developer_manual/client_apis/index.rst
View File

@@ -1,12 +1,13 @@
.. _apiindex:
===============================
Client APIs
===============================
=======================
Clients and Client APIs
=======================
.. toctree::
:maxdepth: 2
android_library/index
WebDAV/index
OCS/index
LoginFlow/index

6
developer_manual/design/css.rst
View File

@@ -6,7 +6,7 @@
SCSS
====
Since version 12 of Nextcloud, we support SCSS natively.
Nextcloud supports SCSS natively.
You can migrate your files by simply renaming your ``.css`` files to ``.scss``.
The server will automatically compile, cache and serve it.
The SCSS file is prioritized. Having two files with the same name and a ``scss`` & ``css`` extension
@@ -18,7 +18,7 @@ will ensure backwards compatibility with <12 versions as scss files will be igno
CSS variables
=============
Since Nextcloud 14, app developers should use CSS4 variables so you get the values which Nextcloud defines. This way you can be sure that the theming and accessibility app can dynamically adjust the values.
App developers should use CSS4 variables so you get the values which Nextcloud defines. This way you can be sure that the theming and accessibility app can dynamically adjust the values.
A list of available variables is listed in the server repository:
https://github.com/nextcloud/server/blob/master/core/css/css-variables.scss
@@ -30,7 +30,7 @@ https://github.com/nextcloud/server/blob/master/core/css/css-variables.scss
SCSS icon mixins
================
Since Nextcloud 14, we added some SCSS mixins and functions to add and manage SVG icons.
Some SCSS mixins and functions are employed to add and manage SVG icons.
These functions need to be used to add the icons via background-image. They create a list of every icon used in Nextcloud and create an associated list of variables.
This allows us to invert the colors of the SVGs when using the dark theme.

2
developer_manual/api.rst → developer_manual/digging_deeper/api.rst
View File

@@ -1,6 +1,6 @@
.. only:: html
API Documentation
API documentation
=================

0
developer_manual/app/changelog.rst → developer_manual/digging_deeper/changelog.rst
View File

2
developer_manual/app/classloader.rst → developer_manual/digging_deeper/classloader.rst
View File

@@ -10,7 +10,7 @@ The classloader is provided by Nextcloud and loads all your classes automaticall
PSR-4 autoloading
-----------------
Since Nextcloud 10 there is a PSR-4 autoloader in place. The namespace **\\OCA\\MyApp**
Nextcloud uses a PSR-4 autoloader. The namespace **\\OCA\\MyApp**
is mapped to :file:`/apps/myapp/lib/`. Afterwards normal PSR-4 rules apply, so
a folder is a namespace section in the same casing and the class name matches
the file name.

0
developer_manual/general/debugging.rst → developer_manual/digging_deeper/debugging.rst
View File

0
developer_manual/app/flow.rst → developer_manual/digging_deeper/flow.rst
View File

25
developer_manual/digging_deeper/index.rst Normal file
View File

@@ -0,0 +1,25 @@
==============
Digging deeper
==============
.. toctree::
:maxdepth: 2
api
changelog
debugging
classloader
flow
javascript-apis
npm
notifications
performance
psr
publicpage
repair
rest_apis
search
settings
testing
two-factor-provider
users

0
developer_manual/app/javascript-apis.rst → developer_manual/digging_deeper/javascript-apis.rst
View File

0
developer_manual/app/notifications.rst → developer_manual/digging_deeper/notifications.rst
View File

0
developer_manual/app/npm.rst → developer_manual/digging_deeper/npm.rst
View File

0
developer_manual/general/performance.rst → developer_manual/digging_deeper/performance.rst
View File

22
developer_manual/digging_deeper/psr.rst Normal file
View File

@@ -0,0 +1,22 @@
===
PSR
===
.. sectionauthor:: Christoph Wurst <christoph@winzerhof-wurst.at>
On this page you find information about the implemented `php standards recommendations <https://www.php-fig.org/psr/>`_ in Nextcloud.
PSR-3: Logger Interface
-----------------------
As of Nextcloud 19, the dependency injection container can inject an instance of a ``\Psr\Log\LoggerInterface``. This is merely a wrapper of the existing (and strongly typed) ``\OCP\ILogger``. Apps may still use the Nextcloud logger, but the `PSR-3`_ implementation shall easy the integration of 3rd party libraries that require the `PSR-3`_ logger.
.. _psr11:
PSR-11: Container Interface
---------------------------
As of Nextcloud 20, the dependency injection container follows the `PSR-11`_ container interface, so you may start type-hinting ``\Psr\Container\ContainerInterface`` whenever you want an instance of a container and use ``has($id)`` to check for existance and ``get($id)`` to retrieve an instance of a service. See the :ref:`dependency injection docs <dependency-injection>` for details.
.. _`PSR-3`: https://www.php-fig.org/psr/psr-3/
.. _`PSR-11`: https://www.php-fig.org/psr/psr-11/

0
developer_manual/app/publicpage.rst → developer_manual/digging_deeper/publicpage.rst
View File

0
developer_manual/app/repair.rst → developer_manual/digging_deeper/repair.rst
View File

6
developer_manual/app/requests/api.rst → developer_manual/digging_deeper/rest_apis.rst
View File

@@ -1,6 +1,6 @@
===========
RESTful API
===========
=========
REST APIs
=========
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>

328
developer_manual/digging_deeper/search.rst Normal file
View File

@@ -0,0 +1,328 @@
======
Search
======
Nextcloud 20 offers a new **unified search**. The overall idea is to have one combined view for search, but have results of any data source displayed there. Hence this is logic is built on a pluggable architecture where apps register their search providers.
Concept overview
----------------
The unified search combines a variable number of search providers into a unified search result for the user. To improve the user experience with search, the search results should be displayed quickly. Therefore parallelism is used to split the process into several requests that can be processed concurrently, to give the client (e.g. JavaScript in the browser) the ability to display partial search results as they come on.
Hence the search process consists of two steps.
1. Fetch the current set of search provider IDs
2. Fetch each provider's search results
These two steps have to be run consecutively, but the individual requests in the second step can be dispatched and processed concurrently.
Fetching provider IDs
^^^^^^^^^^^^^^^^^^^^^
``GET https://cloud.domain/search/providers``
This will return a structure like
.. code-block:: json
[
"files",
"mail"
]
Fetching individual search results
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``GET https://cloud.domain/search/providers/files/search?term=cat``
.. code-block:: json
{
"name": "Files",
"isPaginated": false,
"entries": [
{
"thumbnailUrl": "/core/preview?x=32&y=32&fileId=9261",
"title": "my cute cats.jpg",
"subline": "/my cute cats.jpg",
"resourceUrl": "/apps/files/?dir=/&scrollto=my%20cute%20cats.jpg"
},
{
"thumbnailUrl": "/core/preview?x=32&y=32&fileId=1553",
"title": "cat (2).png",
"subline": "/cat (2).png",
"resourceUrl": "/apps/files/?dir=/&scrollto=cat%20%282%29.png"
}
],
"cursor": null
}
Search providers
----------------
A **search provider** is a class the implements the interface ``\OCP\Search\IProvider``.
.. code-block:: php
<?php
declare(strict_types=1);
namespace OCA\MyApp\Search;
use OCP\IUser;
use OCP\Search\IProvider;
class Provider implements IProvider {
public function getId(): string {
return 'mysearchprovider';
}
public function search(IUser $user, ISearchQuery $query): SearchResult {
return SearchResult::complete(
'My custom group', // TODO: this should be translated
[
...
]
);
}
}
The method ``getId`` returns a string idenfier of the registered provider. It has to be globally unique, hence must not conflict with any other apps. Therefore it's advised to use just the app ID (e.g. ``mail``) as ID or an ID that is prefixed with the app id, like ``mail_recipients``.
The method ``search`` transforms a search request into a search result.
The class would typically be saved into a file in ``lib/Search`` of your app but you are free to put it elsewhere as long as it's loadable by Nextcloud's :ref:`dependency injection container<dependency-injection>`.
Provider registration
---------------------
The provider class is registered via the :ref:`bootstrap mechanism<Bootstrapping>` of the ``Application`` class.
.. code-block:: php
<?php
declare(strict_types=1);
namespace OCA\MyApp\AppInfo;
use OCA\MyApp\Search\Provider;
use OCP\AppFramework\App;
use OCP\AppFramework\Bootstrap\IBootContext;
use OCP\AppFramework\Bootstrap\IBootstrap;
use OCP\AppFramework\Bootstrap\IRegistrationContext;
class Application extends App implements IBootstrap {
public function register(IRegistrationContext $context): void {
$context->registerSearchProvider(Provider::class);
}
public function boot(IBootContext $context): void {}
}
Handling search requests
------------------------
Search requests are processed in the ``search`` method. The ``$user`` object is the user who the result shall be generated for. ``$query``gives context information like the **search term**, the **sort order**, the **size limit** of a request and the **cursor** for follow-up request of paginated results.
The result is encapsulated in the ``SearchResult`` class that offers two static factory methods ``complete`` and ``paginated``. Both of these methods take an array of ``ASearchResultEntry`` objects. ``ASearchResultEntry`` is a static class that has be extended and used by the provider.
.. note:: In most cases you don't have to add any methods or fieds to this new result entry type, but this API design was chosen so new optional properties can be added in the future without breaking the existing implementations in 3rd party apps.
.. code-block:: php
<?php
declare(strict_types=1);
namespace OCA\MyApp\Search;
use OCP\Search\ASearchResultEntry;
class MySearchResultEntry extends ASearchResultEntry {}
The above snippet shows this implementation of a result entry. Again, this class should be saved to ``lib/Search`` in the app directory.
Next, you'll see a dummy provider that returns a static set of results using the result entry class from above.
.. code-block:: php
<?php
declare(strict_types=1);
namespace OCA\MyApp\Search;
use OCP\IL10N;
use OCP\IURLGenerator;
use OCP\IUser;
use OCP\Search\IProvider;
class Provider implements IProvider {
/** @var IL10N */
private $l10n;
/** @var IURLGenerator */
private $urlGenerator;
public function __construct(IL10N $l10n,
IURLGenerator $urlGenerator) {
$this->l10n = $l10n;
$this->urlGenerator = $urlGenerator;
}
public function getId(): string {
return 'mysearchprovider';
}
public function search(IUser $user, ISearchQuery $query): SearchResult {
return MySearchResultEntry::complete(
$this->l10n->t('My app'),
[
new MySearchResultEntry(
$this->urlGenerator->linkToRoute(
'myapp.Preview.getPreviewByFileId',
[
'id' => 1
]
),
'Search result 1',
'This goes into the subline',
$this->urlGenerator->linkToRoute(
'myapp.view.index',
[
'id' => 1,
]
)
)
]
);
}
}
Each of the result result entries has
* A thumbnail or icon that is a (relative) URL
* A title, e.g. the name of a file
* A subline, e.g. the path to a file
* A resource URL that makes it possible to navigate to the details of this result
Apps **may** return the full result in ``search``, but in most cases the size of the result set can become too big to fit into one HTTP request and is complicated to display to the user, hence the set should be split into chunks – it should be **paginated**.
Pagination
^^^^^^^^^^
Paginated results work almost like complete results. The differences are that the ``SearchResult::paginated`` factory method is used to build the set and that you need a **cursor** for this.
There are two ways to use the **cursor**: offset-based pagination and cursor-based pagination.
For **offset-based pagination** you return ``$query->getLimit()`` results and specify this number as **cursor**. Any subsequent call where ``$query->getCursor()`` does not return ``null`` you take the value as **offset** for the next page. The following example shall demonstrate this use case.
.. code-block:: php
<?php
declare(strict_types=1);
namespace OCA\MyApp\Search;
use OCP\IL10N;
use OCP\IURLGenerator;
use OCP\IUser;
use OCP\Search\IProvider;
class Provider implements IProvider {
/** @var IL10N */
private $l10n;
/** @var IURLGenerator */
private $urlGenerator;
public function __construct(IL10N $l10n,
IURLGenerator $urlGenerator) {
$this->l10n = $l10n;
$this->urlGenerator = $urlGenerator;
}
public function getId(): string {
return 'mysearchprovider';
}
public function search(IUser $user, ISearchQuery $query): SearchResult {
$offset = ($query->getCursor() ?? 0);
$limit = $query->getLimit();
$data = []; // Fill this with $limit entries, where the first entry is row $offset
return MySearchResultEntry::complete(
$this->l10n->t('My app'),
$data,
$offset + $limit
);
}
}
So the first call will get a cursor of ``null`` and a limit of, say, 20. So the first 20 rows are fetched. The next call will have a cursor of 20, so the 20st to 39th rows are fetched.
The downside of a offset-based pagination is that when the underlying data changes (new entries are inserted into or deleted from the database, files change), the offset might be out of sync from on request to its successor. Therefor, if possible, a true cursor-based pagination is preferable.
For a **cursor-based pagination** a app-specific property is used to know a reference to the last element of the previous search request. The presumption of this algorithm is that the result set is sorted by an attribute and this attribute is an ``int`` or ``string``. The attribute value of the last element in the result page determines the cursor for the next search request. Again, a small example shall demonstrate how this works.
.. code-block:: php
<?php
declare(strict_types=1);
namespace OCA\MyApp\Search;
use OCP\IL10N;
use OCP\IURLGenerator;
use OCP\IUser;
use OCP\Search\IProvider;
class Provider implements IProvider {
/** @var IL10N */
private $l10n;
/** @var IURLGenerator */
private $urlGenerator;
public function __construct(IL10N $l10n,
IURLGenerator $urlGenerator) {
$this->l10n = $l10n;
$this->urlGenerator = $urlGenerator;
}
public function getId(): string {
return 'mysearchprovider';
}
public function search(IUser $user, ISearchQuery $query): SearchResult {
$cursor = $query->getCursor();
$limit = $query->getLimit();
if ($cursor === null) {
$data = []; // Fill this with $limit entries sorted ascending by created_at
} else {
$data = []; // Fill this with $limit entries sorted ascending by created_at that have a created_at > $cursor
}
$last = end($data);
return MySearchResultEntry::complete(
$this->l10n->t('My app'),
$data,
$last->getCreatedAt()
);
}
}

1
developer_manual/app/settings.rst → developer_manual/digging_deeper/settings.rst
View File

@@ -212,6 +212,7 @@ An example implementation of the IIconSection interface:
namespace OCA\YourAppNamespace\Settings;
use OCP\IL10N;
use OCP\IURLGenerator;
use OCP\Settings\IIconSection;
class AdminSection implements IIconSection {

0
developer_manual/app/two-factor-provider.rst → developer_manual/digging_deeper/two-factor-provider.rst
View File

0
developer_manual/app/users.rst → developer_manual/digging_deeper/users.rst
View File

24
developer_manual/general/backporting.rst
View File

@@ -1,24 +0,0 @@
===========
Backporting
===========
.. sectionauthor:: Morris Jobke, Jos Poortvliet
General
-------
We backport important fixes and improvements from the current master release to get them to our users faster.
Process
-------
We mostly consider bug fixes for back porting. Occasionally, important changes to the API can be backported to make it easier for developers to keep their apps working between major releases. If you think a pull request (PR) is relevant for the stable release, go through these steps:
1. Make sure the PR is merged to master
2. Ask Frank (**@karlitschek**), if the code should be backported and add the label `backport-request <https://github.com/nextcloud/server/labels/backport-request>`_ to the PR
3. If Frank approves, create a new branch based on the respective stable branch (stable10 for the 10.0.x series), cherry-pick the needed commits to that branch and create a PR on GitHub.
4. Specify the corresponding milestone for that series (10.0.x-next-maintenance for the 10.0.x series) to this PR and reference the original PR in there. This enables the QA team to find the backported items for testing and having the original PR with detailed description linked.
.. note:: Before each patch release there is a freeze to be able to test everything as a whole without pulling in new changes. While this freeze is active a backport isn't allowed and has to wait for the next patch release.
The QA team will try to reproduce all the issues with the X.Y.Z-next-maintenance milestone on the relevant release and verify it is fixed by the patch release (and doesn't cause new problems). Once the patch release is out, the post-fix -next-maintenance is removed and a new -next-maintenance milestone is created for that series.

14
developer_manual/general/index.rst
View File

@@ -1,14 +0,0 @@
==============================
General contributor guidelines
==============================
.. toctree::
:maxdepth: 2
code-of-conduct
devenv
security
codingguidelines
performance
debugging
backporting

19
developer_manual/getting_started.rst Normal file
View File

@@ -0,0 +1,19 @@
===============
Getting started
===============
Table of contents
-----------------
.. toctree::
:maxdepth: 1
general/index
app/index
core/index
design/index
android_library/index
client_apis/index
bugtracker/index
commun/index
api

8
developer_manual/general/codingguidelines.rst → developer_manual/getting_started/codingguidelines.rst
View File

@@ -103,7 +103,7 @@ User interface
PHP
---
The Nextcloud coding style guide is based on `PEAR Coding Standards <http://pear.php.net/manual/en/standards.php>`_.
Starting with Nextcloud 19 there is a shared `PHP Coding Standards Fixer <https://github.com/FriendsOfPhp/PHP-CS-Fixer>`_ configuration you can use to automatically format your app's source code. For full details see the `repository on Github <https://github.com/nextcloud/coding-standard/>`_.
Always use::
@@ -261,12 +261,10 @@ with ``Data``.
JavaScript
----------
In general take a look at `JSLint <http://www.jslint.com>`_ without the whitespace rules.
There is a shared configuration for `eslint <https://eslint.org/>`_ that you can use to automatically format your Nextcloud apps's JavaScript code. It consists of two parts: a `config package <https://github.com/nextcloud/eslint-config>`_ that contains the formatting preferences and a `plugin <https://github.com/nextcloud/eslint-plugin>`_ to detect deprecated and removed APIs in your code. See their readmes for instructions.
* Use a :file:`js/main.js` or :file:`js/app.js` where your program is started
* Complete every statement with a **;**
* Use **var** to limit variable to local scope
* To keep your code local, wrap everything in a self executing function. To access global objects or export things to the global namespace, pass all global objects to the self executing function.
* Use **const** or **let** to limit variable to local scope
* Use JavaScript strict mode
* Use a global namespace object where you bind publicly used functions and objects to

89
developer_manual/getting_started/debugging.rst Normal file
View File

@@ -0,0 +1,89 @@
=========
Debugging
=========
Debug mode
----------
When debug mode is enabled in Nextcloud, a variety of debugging features are enabled - see debugging documentation. Set ``debug`` to ``true`` in :file:`/config/config.php` to enable it:
.. code-block:: php
<?php
$CONFIG = array (
'debug' => true,
... configuration goes here ...
);
Identifying errors
------------------
Nextcloud uses custom error PHP handling that prevents errors being printed to Web server log files or command line output. Instead, errors are generally stored in Nextcloud's own log file, located at: :file:`/data/nextcloud.log`
Debugging variables
-------------------
You should use exceptions if you need to debug variable values manually, and not alternatives like trigger_error() (which may not be logged).
e.g.:
.. code-block:: php
<?php throw new \Exception( "\$user = $user" ); // should be logged in Nextcloud ?>
not:
.. code-block:: php
<?php trigger_error( "\$user = $user" ); // may not be logged anywhere ?>
To disable custom error handling in Nextcloud (and have PHP and your Web server handle errors instead), see Debug mode.
Using a PHP debugger (XDebug)
-----------------------------
Using a debugger connected to PHP allows you to step through code line by line, view variables at each line and even change values while the code is running. The de-facto standard debugger for PHP is XDebug, available as an installable package in many distributions. It just provides the PHP side however, so you will need a frontend to actually control XDebug. When installed, it needs to be enabled in :file:`php.ini`, along with some parameters to enable connections to the debugging interface:
.. code-block:: ini
zend_extension=/usr/lib/php/modules/xdebug.so
xdebug.remote_enable=on
xdebug.remote_host=127.0.0.1
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
XDebug will now (when activated) try to connect to localhost on port 9000, and will communicate over the standard protocol DBGP. This protocol is supported by many debugging interfaces, such as the following popular ones:
- vdebug - Multi-language DBGP debugger client for Vim
- SublimeTextXdebug - XDebug client for Sublime Text
- PHPStorm - in-built DBGP debugger
For further reading, see the XDebug documentation: http://xdebug.org/docs/remote
Once you are familiar with how your debugging client works, you can start debugging with XDebug. To test Nextcloud through the web interface or other HTTP requests, set the ``XDEBUG_SESSION_START`` cookie or POST parameter. Alternatively, there are browser extensions to make this easy:
- The Easiest XDebug (Firefox): https://addons.mozilla.org/en-US/firefox/addon/the-easiest-xdebug/
- XDebug Helper (Chrome): https://chrome.google.com/extensions/detail/eadndfjplgieldjbigjakmdgkmoaaaoc
For debugging scripts on the command line, like ``occ`` or unit tests, set the ``XDEBUG_CONFIG`` environment variable.
Debugging JavaScript
--------------------
By default all JavaScript files in Nextcloud are minified (compressed) into a single file without whitespace. To prevent this, see Debug mode.
Debugging HTML and templates
----------------------------
By default Nextcloud caches HTML generated by templates. This may prevent changes to app templates, for example, from being applied on page refresh. To disable caching, see Debug mode.
Using alternative app directories
---------------------------------
It may be useful to have multiple app directories for testing purposes, so you can conveniently switch between different versions of applications. See the configuration file documentation for details.

0
developer_manual/general/devenv.rst → developer_manual/getting_started/devenv.rst
View File

9
developer_manual/getting_started/index.rst Normal file
View File

@@ -0,0 +1,9 @@
===============
Getting started
===============
.. toctree::
:maxdepth: 2
devenv
codingguidelines

Some files were not shown because too many files have changed in this diff Show More