Files\Backend\Seafile\Backend

Complexity

Total Complexity

111

Size/Duplication

Total Lines	1035
Duplicated Lines	0 %

Importance

Changes	1
Bugs	0	Features	0

33 Methods

Rating	Name	Duplication	Size	Complexity
A	gpi()	0	11	2
A	backendException()	0	20	3
A	getFormConfigWithData()	0	3	1
A	log()	0	5	2
A	isLibrary()	0	3	1
A	put()	0	16	2
A	is_dir()	0	3	1
A	mkcol()	0	28	4
A	copy_file()	0	3	1
A	getQuotaBytesUsed()	0	5	1
A	init_form()	0	76	1
A	__construct()	0	20	1
A	getServerVersion()	0	6	2
B	put_file()	0	35	8
A	is_file()	0	3	1
A	set_debug()	0	3	1
B	ls()	0	52	10
A	delete()	0	25	4
A	getFormConfig()	0	10	2
A	exists()	0	3	1
A	get_file()	0	15	2
D	parseErrorCodeToMessage()	0	51	18
A	backendError()	0	5	1
A	get()	0	21	3
A	splitGrommunioPath()	0	11	2
A	backendErrorThrow()	0	6	1
A	init_backend()	0	29	5
A	debugLog()	0	30	6
A	copy_coll()	0	3	1
A	backendExceptionSeafapi()	0	21	4
A	open()	0	17	3
A	getQuotaBytesAvailable()	0	9	2
C	move()	0	75	14

<?php /** @noinspection PhpMultipleClassDeclarationsInspection */

declare(strict_types=1);

namespace Files\Backend\Seafile;

require_once __DIR__ . '/../../files/php/Files/Backend/class.abstract_backend.php';
require_once __DIR__ . '/../../files/php/Files/Backend/class.exception.php';
require_once __DIR__ . '/../../files/php/Files/Backend/interface.quota.php';
require_once __DIR__ . '/../../files/php/Files/Backend/interface.version.php';
require_once __DIR__ . '/lib/seafapi/autoload.php';

require_once __DIR__ . '/Model/Timer.php';
require_once __DIR__ . '/Model/Config.php';
require_once __DIR__ . '/Model/ConfigUtil.php';
require_once __DIR__ . '/Model/SsoBackend.php';

use EncryptionStore;
use Files\Backend\AbstractBackend;
use Files\Backend\Exception as BackendException;
use Files\Backend\iFeatureVersionInfo;
use Files\Backend\Seafile\Model\Config;
use Files\Backend\Seafile\Model\ConfigUtil;
use Files\Backend\Seafile\Model\SsoBackend;
use Files\Backend\Seafile\Model\Timer;
use Files\Core\Util\Logger;
use JsonException;
use Datamate\SeafileApi\Exception;
use Datamate\SeafileApi\SeafileApi;
use Throwable;

/**
 * Seafile Backend
 *
 * Seafile backend for the Grommunio files plugin; bound against the Seafile
 * REST API {@link https://download.seafile.com/published/web-api}.
 */
final class Backend extends AbstractBackend implements iFeatureVersionInfo
{
    public const LOG_CONTEXT = "SeafileBackend"; // Context for the Logger

    /**
     * @const string gettext domain
     */
    private const GT_DOMAIN = 'plugin_filesbackendSeafile';

    /**
     * Seafile "usage" number ("bytes") to Grommunio usage display number ("bytes") multiplier.
     *
     * 1 megabyte in bytes within Seafile represents 1 mebibyte in bytes for Grommunio
     *
     * (Seafile Usage "Bytes" U) / 1000 / 1000 * 1024 * 1024 (1.048576)
     */
    private const QUOTA_MULTIPLIER_SEAFILE_TO_GROMMUNIO = 1.048576;

    /**
     * Error codes
     *
     * @see parseErrorCodeToMessage for description
     * @see Backend::backendException() for Seafile API handling
     */
    private const SFA_ERR_UNAUTHORIZED = 401;
    private const SFA_ERR_FORBIDDEN = 403;
    private const SFA_ERR_NOTFOUND = 404;
    private const SFA_ERR_NOTALLOWED = 405;
    private const SFA_ERR_TIMEOUT = 408;
    private const SFA_ERR_LOCKED = 423;
    private const SFA_ERR_FAILED_DEPENDENCY = 423;
    private const SFA_ERR_INTERNAL = 500;
    private const SFA_ERR_UNREACHABLE = 800;
    private const SFA_ERR_TMP = 801;
    private const SFA_ERR_FEATURES = 802;
    private const SFA_ERR_NO_CURL = 803;
    private const SFA_ERR_UNIMPLEMENTED = 804;

    /**
     * @var ?SeafileApi The Seafile API client.
     */
    private ?SeafileApi $seafapi = null;

    /**
     * Configuration data for the Ext JS metaform.
     */
    private array $metaConfig = [];

    /**
     * Debug flag that mirrors `PLUGIN_FILESBROWSER_LOGLEVEL`.
     */
    private bool $debug = false;

    private Config $config;

    private ?SsoBackend $sso = null;

    /**
     * Backend name used in translations.
     */
    private string $backendTransName = '';

    /**
     * Seafile backend constructor
     */
    public function __construct()
    {
        // initialization
        $this->debug = PLUGIN_FILESBROWSER_LOGLEVEL === 'DEBUG';

        $this->config = new Config();

        $this->init_form();

        // set backend description
        $this->backendDescription = dgettext(self::GT_DOMAIN, "With this backend, you can connect to any Seafile server.");

        // set backend display name
        $this->backendDisplayName = "Seafile";

        // set backend version
        $this->backendVersion = "2.0.68";

        // set backend name used in translations
        $this->backendTransName = dgettext(self::GT_DOMAIN, 'Files ' . $this->backendDisplayName . ' Backend: ');
    }

    ////////////////////////////////////////////////////////////////////////////
    /// seafapi backend methods                                              ///
    ////////////////////////////////////////////////////////////////////////////

    /**
     * Opens the connection to the Seafile server.
     *
     * @throws BackendException if connection is not successful
     * @return boolean true if action succeeded
     */
    public function open()
    {
        $url = $this->config->getApiUrl();

        try {
            $this->sso->open();

The method open() does not exist on null.

        } catch (Throwable $throwable) {
            $this->backendException($throwable);
        }

        try {
            $this->seafapi = new SeafileApi($url, $this->config->user, $this->config->pass);
        } catch (Throwable $throwable) {
            $this->backendException($throwable);
        }

        return true;
    }

    /**
     * This function will read a list of files and folders from the server.
     *
     * @param string $dir to get listing from
     * @param bool $hidefirst skip the first entry (we ignore this for the Seafile backend)
     * @throws BackendException
     *
     * @return array
     */
    public function ls($dir, $hidefirst = true)
    {
        $timer = new Timer();
        $this->log("[LS] '$dir'");

        if ('' === trim($dir, '/')) {
            try {
                $listing = $this->seafapi->listLibraries();

The method listLibraries() does not exist on null.

            } catch (Throwable $throwable) {
                $this->backendException($throwable);
            }
            goto result;
        }

        $lsDir = $this->splitGrommunioPath($dir);
        if (null === $lsDir->lib) {
            // the library does not exist, the listing is short.
            $listing = [];
            goto result;
        }

        try {
            $listing = $this->seafapi->listItemsInDirectory($lsDir->lib, $lsDir->path ?? '');
        } catch (Throwable $throwable) {
            $this->backendException($throwable);
        }

        result:

        $result = [];
        $baseDir = rtrim($dir, '/') . '/';
        foreach ($listing as $node) {
            if (!isset($this->seafapi::TYPES[$node->type])) {
                $this->backendException(
                    new \UnexpectedValueException(sprintf('Unhandled Seafile node-type "%s" (for "%s")', $node->type, $node->name))
                );
            }
            $isDir = isset($this->seafapi::TYPES_DIR_LIKE[$node->type]);
            $name = rtrim($baseDir . $node->name, '/') . '/';
            $isDir || $name = rtrim($name, '/');
            $result[$name] = [
                'resourcetype' => $isDir ? 'collection' : 'file',
                'getcontentlength' => $isDir ? null : $node->size,
                'getlastmodified' => date('r', $node->mtime),
                'getcontenttype' => null,
                'quota-used-bytes' => null,
                'quota-available-bytes' => null,
            ];
        }

        $this->log("[LS] done in $timer seconds.");
        return $result;
    }

    /**
     * Creates a new directory on the server.
     *
     * @param string $dir
     * @throws BackendException
     * @return bool
     */
    public function mkcol($dir)
    {
        $timer = new Timer();
        $this->log("[MKCOL] '$dir'");

        if ($this->isLibrary($dir)) {
            // create library
            try {
                $result = $this->seafapi->createLibrary($dir);
                unset($result);
            } catch (Throwable $throwable) {
                $this->backendException($throwable);
            }
            $success = true;
        } else {
            // create directory within library
            $lib = $this->seafapi->getLibraryFromPath($dir)->id;
            [, $path] = explode('/', trim($dir, '/'), 2);
            try {
                $result = $this->seafapi->createNewDirectory($lib, $path);
            } catch (Throwable $throwable) {
                $this->backendException($throwable);
            }
            $success = 'success' === $result;
        }

        $this->log("[MKCOL] done in $timer seconds.");
        return $success;
    }

    /**
     * Deletes a files or folder from the backend.
     *
     * @param string $path
     * @throws BackendException
     * @return bool
     */
    public function delete($path)
    {
        $timer = new Timer();
        $this->log("[DELETE] '$path'");

        if ($this->isLibrary($path)) {
            // delete library
            try {
                $this->seafapi->deleteLibraryByName($path);
                $result = 'success';
            } catch (Throwable $throwable) {
                $this->backendException($throwable);
            }
        } else {
            // delete file or directory within library
            $deletePath = $this->splitGrommunioPath($path);
            try {
                $result = $this->seafapi->deleteFile($deletePath->lib, $deletePath->path);
            } catch (Throwable $throwable) {
                $this->backendException($throwable);
            }
        }

        $this->log("[DELETE] done in $timer seconds.");
        return 'success' === $result;

The variable $result does not seem to be defined for all execution paths leading up to this point.

    }

    /**
     * Move a file or collection on the backend server (serverside).
     *
     * @param string $src_path Source path
     * @param string $dst_path Destination path
     * @param bool $overwrite Overwrite file if exists in $dest_path
     * @throws BackendException
     * @return bool
     */
    public function move($src_path, $dst_path, $overwrite = false)
    {
        $timer = new Timer();
        $this->log("[MOVE] '$src_path' -> '$dst_path'");

        // check if the move operation would move src into itself - error condition
        if (0 === strpos($dst_path, $src_path . '/')) {
            $this->backendError(self::SFA_ERR_FORBIDDEN, 'Moving failed');
        }

        // move library/file/directory is one of in the following order:
        // 1/5: rename library
        // 2/5: noop - source and destination are the same
        // 3/5: rename file/directory
        // 4/5: move file/directory
        // 5/5: every other operation (e.g. move library into another library) is not implemented

        $src = $this->splitGrommunioPath($src_path);
        $dst = $this->splitGrommunioPath($dst_path);

        // 1/5: rename library
        if ($src->path === null && $dst->path === null) {
            if ($dst->lib !== null) {
                // rename to an existing library name (not allowed as not supported)
                $this->backendError(self::SFA_ERR_NOTALLOWED, 'Moving failed');
            }
            try {
                $this->seafapi->renameLibrary($src->libName, $dst->libName);
                $result = true;
            } catch (Throwable $throwable) {
                $this->backendException($throwable);
            }
            goto done;
        }

        $isIntraLibTransaction = $src->libName === $dst->libName;

        // 2/5: noop - src and dst are the same
        if ($isIntraLibTransaction && $src->path === $dst->path) {
            // source and destination are the same path, nothing to do
            $result = 'success';
            goto done;
        }

        $dirNames = array_map('dirname', [$src->path, $dst->path]);
        $pathsHaveSameDirNames = $dirNames[0] === $dirNames[1];

        // 3/5: rename file/directory
        if ($isIntraLibTransaction && $pathsHaveSameDirNames) {
            try {
                $result = $this->seafapi->renameFile($src->lib, $src->path, basename($dst->path));
            } catch (Throwable $throwable) {
                $this->backendException($throwable);
            }
            goto done;
        }

        // 4/5: move file/directory
        if (isset($src->path, $dst->lib)) {
            try {
                $result = $this->seafapi->moveFile($src->lib, $src->path, $dst->lib, $dirNames[1]);
            } catch (Throwable $throwable) {
                $this->backendException($throwable);
            }
        }

        done:

        // 5/5: every other operation (move library into another library, not implemented)
        if (!isset($result)) {
            $this->backendError(self::SFA_ERR_UNIMPLEMENTED, 'Not implemented.');
        }

        $this->log("[MOVE] done in $timer seconds.");
        return 'success' === $result;

The variable $result does not seem to be defined for all execution paths leading up to this point.

    }

    /**
     * Download a remote file to a buffer variable.
     *
     * @param string $path The source path on the server
     * @param mixed $buffer Buffer for the received data
     *
     * @throws BackendException if request is not successful
     *
     * @return boolean true if action succeeded
     */
    public function get($path, &$buffer)
    {
        $timer = new Timer();
        $this->log("[GET] '$path'");

        $src = $this->splitGrommunioPath($path);

        try {
            $result = $this->seafapi->downloadFileAsBuffer($src->lib, $src->path);
        } catch (Throwable $throwable) {
            $this->backendException($throwable);
        }

        $success = false !== $result;

        if ($success) {

The condition $success is always true.

            $buffer = $result;
        }

        $this->log("[GET] done in $timer seconds.");
        return $success;
    }

    /**
     * Download a remote file to a local file.
     *
     * @param string $srcpath Source path on server
     * @param string $localpath Destination path on local filesystem
     *
     * @throws BackendException if request is not successful
     *
     * @return boolean true if action succeeded
     */
    public function get_file($srcpath, $localpath)
    {
        $timer = new Timer();
        $this->log("[GET_FILE] '$srcpath' -> '$localpath'");

        $src = $this->splitGrommunioPath($srcpath);

        try {
            $result = $this->seafapi->downloadFileToFile($src->lib, $src->path, $localpath);
        } catch (Throwable $throwable) {
            $this->backendException($throwable);
        }

        $this->log("[GET_FILE] done in $timer seconds.");
        return $result;
    }

    /**
     * Puts a file into a collection.
     *
     * @param string $path Destination path
     *
     * @string mixed $data Any kind of data
     * @throws BackendException if request is not successful
     *
     * @return boolean true if action succeeded
     */
    public function put($path, $data)
    {
        $timer = new Timer();
        $this->log(sprintf("[PUT] start: path: %s (%d)", $path, strlen($data)));

        $target = $this->splitGrommunioPath($path);

        try {
            /** @noinspection PhpUnusedLocalVariableInspection */
            $result = $this->seafapi->uploadBuffer($target->lib, $target->path, $data);

The assignment to $result is dead and can be removed.

        } catch (Throwable $throwable) {
            $this->backendException($throwable);
        }

        $this->log("[PUT] done in $timer seconds.");
        return true;
    }

    /**
     * Upload a local file
     *
     * @param string $path Destination path on the server
     * @param string $filename Local filename for the file that should be uploaded
     *
     * @throws BackendException if request is not successful
     *
     * @return boolean true if action succeeded
     */
    public function put_file($path, $filename)
    {
        $timer = new Timer();
        $this->log(sprintf("[PUT_FILE] %s -> %s", $filename, $path));

        // filename can be null if an attachment of draft-email that has not been saved
        if (empty($filename)) {
            return false;
        }

        $target = $this->splitGrommunioPath($path);

        // put file into users default library if no library given
        if ($target->path === null && $target->libName !== null) {
            try {
                $defaultLibrary = $this->seafapi->getDefaultLibrary();
            } catch (Throwable $throwable) {
                $this->backendException($throwable);
            }
            if (isset($defaultLibrary->repo_id, $defaultLibrary->exists) && true === $defaultLibrary->exists) {
                $target->path = $target->libName;
                $target->libName = null;
                $target->lib = $defaultLibrary->repo_id;
            }
        }

        try {
            /** @noinspection PhpUnusedLocalVariableInspection */
            $result = $this->seafapi->uploadFile($target->lib, $target->path, $filename);

The assignment to $result is dead and can be removed.

        } catch (Throwable $throwable) {
            $this->backendException($throwable);
        }

        $this->log("[PUT_FILE] done in $timer seconds.");
        return true;
    }

    ////////////////////////////////////////////////////////////////////////////
    /// non-seafapi backend implementation                                   ///
    ////////////////////////////////////////////////////////////////////////////

    /**
     * Initialize backend from $backend_config array
     *
     * @param $backend_config
     * @return void
     */
    public function init_backend($backend_config)
    {
        $config = $backend_config;

        if ($backend_config["use_zarafa_credentials"]) {
            // For backward compatibility we will check if the Encryption store exists. If not,
            // we will fall back to the old way of retrieving the password from the session.
            if (class_exists('EncryptionStore')) {
                // Get the username and password from the Encryption store
                $encryptionStore = EncryptionStore::getInstance();
                if ($encryptionStore instanceof EncryptionStore) {
                    $config['user'] = $encryptionStore->get('username');
                    $config['password'] = $encryptionStore->get('password');
                }
            } else {
                $config['user'] = ConfigUtil::loadSmtpAddress();
                $password = $_SESSION['password'];
                if (function_exists('openssl_decrypt')) {
                    /** @noinspection PhpUndefinedConstantInspection */
                    $config['password'] = openssl_decrypt($password, "des-ede3-cbc", PASSWORD_KEY, 0, PASSWORD_IV);
                }
            }
        }

        $this->config->importConfigArray($config);

        SsoBackend::bind($this->sso)->initBackend($this->config);

        Logger::debug(self::LOG_CONTEXT, __FUNCTION__ . ' done.');
    }

    /**
     * @return false|string
     * @noinspection PhpMultipleClassDeclarationsInspection Grommunio has a \JsonException shim
     */
    public function getFormConfig()
    {
        try {
            $json = json_encode($this->metaConfig, JSON_THROW_ON_ERROR);
        } catch (JsonException $e) {
            $this->log(sprintf('[%s]: %s', get_class($e), $e->getMessage()));
            $json = false;
        }

        return $json;

The expression return $json returns the type false|string which is incompatible with the return type mandated by Files\Backend\AbstractBackend::getFormConfig() of array.

    }

    public function getFormConfigWithData()
    {
        return $this->getFormConfig();

The expression return $this->getFormConfig() returns the type false|string which is incompatible with the return type mandated by Files\Backend\AbstractBackend::getFormConfigWithData() of array.

    }

    /**
     * set debug on (1) or off (0).
     * produces a lot of debug messages in webservers error log if set to on (1).
     *
     * @param boolean $debug enable or disable debugging
     *
     * @return void
     */
    public function set_debug($debug)
    {
        $this->debug = (bool)$debug;
    }

    ////////////////////////////////////////////////////////////////////////////
    /// not_used_implemented()                                               ///
    ////////////////////////////////////////////////////////////////////////////

    /**
     * Duplicates a folder on the backend server.
     *
     * @param string $src_path
     * @param string $dst_path
     * @param bool $overwrite
     * @throws BackendException
     * @return bool
     * @noinspection PhpReturnDocTypeMismatchInspection Upstream Interface Issue
     */
    public function copy_coll($src_path, $dst_path, $overwrite = false)
    {
        $this->backendError(self::SFA_ERR_UNIMPLEMENTED, 'Not implemented');
    }

    /**
     * Duplicates a file on the backend server.
     *
     * @param string $src_path
     * @param string $dst_path
     * @param bool $overwrite
     * @throws BackendException
     * @return bool
     * @noinspection PhpReturnDocTypeMismatchInspection Upstream Interface Issue
     */
    public function copy_file($src_path, $dst_path, $overwrite = false)
    {
        $this->backendError(self::SFA_ERR_UNIMPLEMENTED, 'Not implemented');
    }

    /**
     * Checks if the given $path exists on the remote server.
     *
     * @param string $path
     * @throws BackendException
     * @return bool
     * @noinspection PhpReturnDocTypeMismatchInspection Upstream Interface Issue
     */
    public function exists($path)
    {
        $this->backendError(self::SFA_ERR_UNIMPLEMENTED, 'Not implemented');
    }

    /**
     * Gets path information from Seafile server.
     *
     * @param string $path
     * @throws BackendException if request is not successful
     * @return array directory info
     */
    public function gpi($path)
    {
        $this->log("[GPI] '$path'");
        $list = $this->ls(dirname($path), false); // get contents of the parent dir

        if (isset($list[$path])) {
            return $list[$path];
        }

        $this->log('[GPI] wrong response from ls');
        $this->backendError(self::SFA_ERR_FAILED_DEPENDENCY, 'Connection failed');
    }

    /**
     * Checks if the given $path is a folder.
     *
     * @param string $path
     * @throws BackendException
     * @return bool
     * @noinspection PhpReturnDocTypeMismatchInspection Upstream Interface Issue
     */
    public function is_dir($path)
    {
        $this->backendError(self::SFA_ERR_UNIMPLEMENTED, 'Not implemented');
    }

    /**
     * Checks if the given $path is a file.
     *
     * @param string $path
     * @throws BackendException
     * @return bool
     * @noinspection PhpReturnDocTypeMismatchInspection Upstream Interface Issue
     */
    public function is_file($path)
    {
        $this->backendError(self::SFA_ERR_UNIMPLEMENTED, 'Not implemented');
    }

    /////////////////////////////////////////////////////////////
    // @see iFeatureVersionInfo implementation                 //
    /////////////////////////////////////////////////////////////

    /**
     * Return the version string of the server backend.
     *
     * @throws BackendException
     * @return String
     */
    public function getServerVersion()
    {
        try {
            return $this->seafapi->getServerVersion();
        } catch (Throwable $throwable) {
            $this->backendException($throwable);
        }
    }

    /////////////////////////////////////////////////////////////
    // @see iFeatureQuota implementation                       //
    /////////////////////////////////////////////////////////////

    /**
     * @param string $dir
     * @return float
     * @noinspection PhpMissingParamTypeInspection
     * @noinspection PhpUnusedParameterInspection
     */
    public function getQuotaBytesUsed($dir)
    {
        $return = $this->seafapi->checkAccountInfo();

        return ($return->usage ?? 0) * self::QUOTA_MULTIPLIER_SEAFILE_TO_GROMMUNIO;
    }

    /**
     * @param string $dir
     * @return float|int
     * @noinspection PhpUnusedParameterInspection
     * @noinspection PhpMissingParamTypeInspection
     */
    public function getQuotaBytesAvailable($dir)
    {
        $return = $this->seafapi->checkAccountInfo();
        $avail = $return->total - $return->usage;
        if (-2 === (int)$return->total) {
            return -1;
        }

        return $avail * self::QUOTA_MULTIPLIER_SEAFILE_TO_GROMMUNIO;
    }

    /////////////////////////////////////////////////////////////
    // @internal private helper methods                        //
    /////////////////////////////////////////////////////////////

    /**
     * Initialise form fields
     */
    private function init_form()
    {
        $this->metaConfig = [
            "success" => true,
            "metaData" => [
                "fields" => [
                    [
                        "name" => "server_address",
                        "fieldLabel" => dgettext(self::GT_DOMAIN, 'Server address'),
                        "editor" => [
                            "allowBlank" => false,
                        ],
                    ],
                    [
                        "name" => "server_port",
                        "fieldLabel" => dgettext(self::GT_DOMAIN, 'Server port'),
                        "editor" => [
                            "ref" => "../../portField",
                            "allowBlank" => false,
                        ],
                    ],
                    [
                        "name" => "server_ssl",
                        "fieldLabel" => dgettext(self::GT_DOMAIN, 'Use SSL'),
                        "editor" => [
                            "xtype" => "checkbox",
                            "listeners" => [
                                "check" => "Zarafa.plugins.files.data.Actions.onCheckSSL" // this javascript function will be called!
                            ],
                        ],
                    ],
                    [
                        "name" => "user",
                        "fieldLabel" => dgettext(self::GT_DOMAIN, 'Username'),
                        "editor" => [
                            "ref" => "../../usernameField",
                        ],
                    ],
                    [
                        "name" => "password",
                        "fieldLabel" => dgettext(self::GT_DOMAIN, 'Password'),
                        "editor" => [
                            "ref" => "../../passwordField",
                            "inputType" => "password",
                        ],
                    ],
                    [
                        "name" => "use_zarafa_credentials",
                        "fieldLabel" => dgettext(self::GT_DOMAIN, 'Use grommunio credentials'),
                        "editor" => [
                            "xtype" => "checkbox",
                            "listeners" => [
                                "check" => "Zarafa.plugins.files.data.Actions.onCheckCredentials" // this javascript function will be called!
                            ],
                        ],
                    ],
                ],
                "formConfig" => [
                    "labelAlign" => "left",
                    "columnCount" => 1,
                    "labelWidth" => 80,
                    "defaults" => [
                        "width" => 292,
                    ],
                ],
            ],

            // here we can specify the default values.
            "data" => [
                "server_address" => "seafile.example.com",
                "server_port" => "443",
                "server_ssl" => "1",
                "server_path" => "",
                "use_zarafa_credentials" => "0",
                "user" => "",
                "password" => "",
            ],
        ];
    }

    /**
     * split grommunio path into library and library path
     *
     * obtains the seafile library ID (if available, otherwise NULL)
     *
     * return protocol: object{
     *   lib: ?string     # library ID e.g. "ccc60923-8cdf-4cc8-8f71-df86aba3a085"
     *   path: ?string    # path inside library, always prefixed with "/" if set
     *   libName: ?string # name of the library
     * }
     *
     * @param string $grommunioPath
     * @throws Exception
     * @return object
     */
    private function splitGrommunioPath(string $grommunioPath): object
    {
        static $libraries;
        $libraries = $libraries ?? array_column($this->seafapi->listLibraries(), null, 'name');

        [, $libName, $path] = explode('/', $grommunioPath, 3) + [null, null, null];
        if (null !== $path) {
            $path = "/$path";
        }
        $lib = $libraries[$libName]->id ?? null;
        return (object)['lib' => $lib, 'path' => $path, 'libName' => $libName];
    }

    /**
     * test if a grommunio path is a library only
     *
     * @param string $grommunioPath
     * @return bool
     */
    private function isLibrary(string $grommunioPath): bool
    {
        return 0 === substr_count(trim($grommunioPath, '/'), '/');
    }

    /**
     * Turn a Backend error code into a Backend exception
     *
     * @param int $errorCode one of the Backend::SFA_ERR_* codes, e.g. {@see Backend::SFA_ERR_INTERNAL}
     * @param ?string $title msg-id from the plugin_files domain, e.g. 'PHP-CURL not installed'
     * @throws BackendException
     * @return no-return

The doc comment no-return at position 0 could not be parsed: Unknown type name 'no-return' at position 0 in no-return.

     */
    private function backendError(int $errorCode, string $title = null)
    {
        $message = $this->parseErrorCodeToMessage($errorCode);
        $title = $this->backendTransName;
        $this->backendErrorThrow($title, $message, $errorCode);
    }

    /**
     * Throw a BackendException w/ title, message and code
     *
     * @param string $title
     * @param string $message
     * @param int $code
     * @throws BackendException
     * @return no-return

The doc comment no-return at position 0 could not be parsed: Unknown type name 'no-return' at position 0 in no-return.

     */
    private function backendErrorThrow(string $title, string $message, int $code = 0)
    {
        /** {@see \Files\Backend\Exception} */
        $exception = new BackendException($message, $code);
        $exception->setTitle($title);
        throw $exception;
    }

    /**
     * Turn a throwable/exception with the Seafile API into a Backend exception
     *
     * @param Throwable $t
     * @throws BackendException
     * @return no-return

The doc comment no-return at position 0 could not be parsed: Unknown type name 'no-return' at position 0 in no-return.

     */
    private function backendException(Throwable $t)
    {
        // if it is already a backend exception, throw it.
        if ($t instanceof BackendException) {
            throw $t;
        }

        [$callSite, $inFunc] = debug_backtrace();
        $logLabel = "$inFunc[function]:$callSite[line]";

        $class = get_class($t);
        $message = $t->getMessage();
        $this->log(sprintf('%s: [%s] #%s: %s', $logLabel, $class, $t->getCode(), $message));

        // All SeafileApi exceptions are handled by this
        if ($t instanceof Exception) {
            $this->backendExceptionSeafapi($t);
        }

        $this->backendErrorThrow('Error', "[SEAFILE $logLabel] $class: $message", 500);
    }

    /**
     * Turn an Exception into a BackendException
     *
     * Enriches message information for grommunio with API error messages
     * if a Seafile ConnectionException.
     *
     * helper for {@see Backend::backendException()}
     *
     * @param Exception $exception
     * @throws BackendException
     * @return void
     */
    private function backendExceptionSeafapi(Exception $exception)
    {
        $code = $exception->getCode();
        $message = $exception->getMessage();

        $apiErrorMessagesHtml = null;
        if ($exception instanceof Exception\ConnectionException) {
            $messages = $exception->tryApiErrorMessages();
            null === $messages || $apiErrorMessagesHtml = implode(
                    "<br/>\n",
                    array_map(static function (string $subject) {
                        return htmlspecialchars($subject, ENT_QUOTES | ENT_HTML5);
                    }, $messages)
                ) . "<br/>\n";
        }

        if (null !== $apiErrorMessagesHtml) {
            $message .= " - $apiErrorMessagesHtml";
        }

        $this->backendErrorThrow($this->backendDisplayName . ' Error', $message, $code);
    }

    /**
     * a simple php error_log wrapper.
     *
     * @param string $err_string error message
     *
     * @return void
     */
    private function log(string $err_string)
    {
        if ($this->debug) {
            Logger::debug(self::LOG_CONTEXT, $err_string);
            $this->debugLog($err_string, 2);
        }
    }

    /**
     * This function will return a user-friendly error string.
     *
     * Error codes were migrated from WebDav backend.
     *
     * @param int $error_code An error code
     *
     * @return string user friendly error message
     */
    private function parseErrorCodeToMessage(int $error_code)
    {
        $error = $error_code;

        switch ($error) {
            case CURLE_BAD_PASSWORD_ENTERED:
            case self::SFA_ERR_UNAUTHORIZED:
                $msg = dgettext(self::GT_DOMAIN, 'Unauthorized. Wrong username or password.');
                break;
            case CURLE_SSL_CONNECT_ERROR:
            case CURLE_COULDNT_RESOLVE_HOST:
            case CURLE_COULDNT_CONNECT:
            case CURLE_OPERATION_TIMEOUTED:
            case self::SFA_ERR_UNREACHABLE:
                $msg = dgettext(self::GT_DOMAIN, 'Seafile is not reachable. Correct backend address entered?');
                break;
            case self::SFA_ERR_FORBIDDEN:
                $msg = dgettext(self::GT_DOMAIN, 'You don\'t have enough permissions for this operation.');
                break;
            case self::SFA_ERR_NOTFOUND:
                $msg = dgettext(self::GT_DOMAIN, 'File is not available any more.');
                break;
            case self::SFA_ERR_TIMEOUT:
                $msg = dgettext(self::GT_DOMAIN, 'Connection to server timed out. Retry later.');
                break;
            case self::SFA_ERR_LOCKED:
                $msg = dgettext(self::GT_DOMAIN, 'This file is locked by another user.');
                break;
            case self::SFA_ERR_FAILED_DEPENDENCY:
                $msg = dgettext(self::GT_DOMAIN, 'The request failed due to failure of a previous request.');
                break;
            case self::SFA_ERR_INTERNAL:
                $msg = dgettext(self::GT_DOMAIN, 'Seafile-server encountered a problem.');
                break;
            case self::SFA_ERR_TMP:
                $msg = dgettext(self::GT_DOMAIN, 'Could not write to temporary directory. Contact the server administrator.');
                break;
            case self::SFA_ERR_FEATURES:
                $msg = dgettext(self::GT_DOMAIN, 'Could not retrieve list of server features. Contact the server administrator.');
                break;
            case self::SFA_ERR_NO_CURL:
                $msg = dgettext(self::GT_DOMAIN, 'PHP-Curl is not available. Contact your system administrator.');
                break;
            case self::SFA_ERR_UNIMPLEMENTED:
                $msg = dgettext(self::GT_DOMAIN, 'This function is not yet implemented.');
                break;
            default:
                $msg = dgettext(self::GT_DOMAIN, 'Unknown error');
        }

        return $msg;
    }

    /////////////////////////////////////////////////////////////
    // @debug development helper method                        //
    /////////////////////////////////////////////////////////////

    /**
     * Log debug message while developing the plugin in dedicated DEBUG.log file
     *
     * TODO(tk): remove debugLog, we shall not use it in production.
     *
     * @param mixed $message
     * @param int $backSteps [optional] offset of call point in stacktrace
     * @return void
     * @see \Files\Backend\Seafile\Backend::log()
     */
    public function debugLog($message, int $backSteps = 0): void
    {
        $baseDir = dirname(__DIR__);
        $debugLogFile = $baseDir . '/DEBUG.log';
        $backtrace = debug_backtrace();
        $callPoint = $backtrace[$backSteps];
        $path = $callPoint['file'];
        $shortPath = $path;
        if (0 === strpos($path, $baseDir)) {
            $shortPath = substr($path, strlen($baseDir));
        }
        // TODO(tk): track if the parent function is log() or not, not only the number of back-steps (or check all call points)
        $callInfoExtra = '';
        if (1 !== $backSteps) { // this is not a log() call with debug switched on
            $callInfoExtra = " ($backSteps) " . $backtrace[$backSteps + 1]['type'] . $backtrace[$backSteps + 1]['function'] . '()';
        }
        $callInfo = sprintf(' [ %s:%s ]%s', $shortPath, $callPoint['line'], $callInfoExtra);

        if (!is_string($message)) {
            /** @noinspection JsonEncodingApiUsageInspection */
            $type = gettype($message);
            if ('object' === $type && is_callable([$message, '__debugInfo'])) {
                $message = $message->__debugInfo();
            }
            $message = $type . ': ' . json_encode($message, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
        }

        $message = substr(sprintf('%.3f', $_SERVER['REQUEST_TIME_FLOAT']), -7) . " $message";

        error_log(str_pad($message, 48) . $callInfo . "\n", 3, $debugLogFile);
    }
}