Update OCP

NCU/Config/Lexicon/ConfigLexiconEntry.php

@@ -0,0 +1,189 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace NCU\Config\Lexicon;
+
+use NCU\Config\ValueType;
+
+/**
+ * Model that represent config values within an app config lexicon.
+ *
+ * @see IConfigLexicon
+ * @experimental 31.0.0
+ */
+class ConfigLexiconEntry {
+	private string $definition = '';
+	private ?string $default = null;
+
+	/**
+	 * @param string $key config key
+	 * @param ValueType $type type of config value
+	 * @param string $definition optional description of config key available when using occ command
+	 * @param bool $lazy set config value as lazy
+	 * @param int $flags set flags
+	 * @param bool $deprecated set config key as deprecated
+	 *
+	 * @experimental 31.0.0
+	 * @psalm-suppress PossiblyInvalidCast
+	 * @psalm-suppress RiskyCast
+	 */
+	public function __construct(
+		private readonly string $key,
+		private readonly ValueType $type,
+		null|string|int|float|bool|array $default = null,
+		string $definition = '',
+		private readonly bool $lazy = false,
+		private readonly int $flags = 0,
+		private readonly bool $deprecated = false,
+	) {
+		if ($default !== null) {
+			// in case $default is array but is not expected to be an array...
+			$default = ($type !== ValueType::ARRAY && is_array($default)) ? json_encode($default) : $default;
+			$this->default = match ($type) {
+				ValueType::MIXED => (string)$default,
+				ValueType::STRING => $this->convertFromString((string)$default),
+				ValueType::INT => $this->convertFromInt((int)$default),
+				ValueType::FLOAT => $this->convertFromFloat((float)$default),
+				ValueType::BOOL => $this->convertFromBool((bool)$default),
+				ValueType::ARRAY => $this->convertFromArray((array)$default)
+			};
+		}
+
+		/** @psalm-suppress UndefinedClass */
+		if (\OC::$CLI) { // only store definition if ran from CLI
+			$this->definition = $definition;
+		}
+	}
+
+	/**
+	 * @inheritDoc
+	 *
+	 * @return string config key
+	 * @experimental 31.0.0
+	 */
+	public function getKey(): string {
+		return $this->key;
+	}
+
+	/**
+	 * @inheritDoc
+	 *
+	 * @return ValueType
+	 * @experimental 31.0.0
+	 */
+	public function getValueType(): ValueType {
+		return $this->type;
+	}
+
+	/**
+	 * @param string $default
+	 * @return string
+	 * @experimental 31.0.0
+	 */
+	private function convertFromString(string $default): string {
+		return $default;
+	}
+
+	/**
+	 * @param int $default
+	 * @return string
+	 * @experimental 31.0.0
+	 */
+	private function convertFromInt(int $default): string {
+		return (string)$default;
+	}
+
+	/**
+	 * @param float $default
+	 * @return string
+	 * @experimental 31.0.0
+	 */
+	private function convertFromFloat(float $default): string {
+		return (string)$default;
+	}
+
+	/**
+	 * @param bool $default
+	 * @return string
+	 * @experimental 31.0.0
+	 */
+	private function convertFromBool(bool $default): string {
+		return ($default) ? '1' : '0';
+	}
+
+	/**
+	 * @param array $default
+	 * @return string
+	 * @experimental 31.0.0
+	 */
+	private function convertFromArray(array $default): string {
+		return json_encode($default);
+	}
+
+	/**
+	 * @inheritDoc
+	 *
+	 * @return string|null NULL if no default is set
+	 * @experimental 31.0.0
+	 */
+	public function getDefault(): ?string {
+		return $this->default;
+	}
+
+	/**
+	 * @inheritDoc
+	 *
+	 * @return string
+	 * @experimental 31.0.0
+	 */
+	public function getDefinition(): string {
+		return $this->definition;
+	}
+
+	/**
+	 * @inheritDoc
+	 *
+	 * @see IAppConfig for details on lazy config values
+	 * @return bool TRUE if config value is lazy
+	 * @experimental 31.0.0
+	 */
+	public function isLazy(): bool {
+		return $this->lazy;
+	}
+
+	/**
+	 * @inheritDoc
+	 *
+	 * @see IAppConfig for details on sensitive config values
+	 * @return int bitflag about the config value
+	 * @experimental 31.0.0
+	 */
+	public function getFlags(): int {
+		return $this->flags;
+	}
+
+	/**
+	 * @param int $flag
+	 *
+	 * @return bool TRUE is config value bitflag contains $flag
+	 * @experimental 31.0.0
+	 */
+	public function isFlagged(int $flag): bool {
+		return (($flag & $this->getFlags()) === $flag);
+	}
+
+	/**
+	 * @inheritDoc
+	 *
+	 * @return bool TRUE if config si deprecated
+	 * @experimental 31.0.0
+	 */
+	public function isDeprecated(): bool {
+		return $this->deprecated;
+	}
+}

NCU/Config/Lexicon/ConfigLexiconStrictness.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace NCU\Config\Lexicon;
+
+/**
+ * Strictness regarding using not-listed config keys
+ *
+ * - **ConfigLexiconStrictness::IGNORE** - fully ignore
+ * - **ConfigLexiconStrictness::NOTICE** - ignore and report
+ * - **ConfigLexiconStrictness::WARNING** - silently block (returns $default) and report
+ * - **ConfigLexiconStrictness::EXCEPTION** - block (throws exception) and report
+ *
+ * @experimental 31.0.0
+ */
+enum ConfigLexiconStrictness {
+	/** @experimental 31.0.0 */
+	case IGNORE; // fully ignore
+	/** @experimental 31.0.0 */
+	case NOTICE; // ignore and report
+	/** @experimental 31.0.0 */
+	case WARNING; // silently block (returns $default) and report
+	/** @experimental 31.0.0 */
+	case EXCEPTION; // block (throws exception) and report
+}

NCU/Config/Lexicon/IConfigLexicon.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+namespace NCU\Config\Lexicon;
+
+/**
+ * This interface needs to be implemented if you want to define a config lexicon for your application
+ * The config lexicon is used to avoid conflicts and problems when storing/retrieving config values
+ *
+ * @experimental 31.0.0
+ */
+interface IConfigLexicon {
+
+	/**
+	 * Define the expected behavior when using config
+	 * keys not set within your application config lexicon.
+	 *
+	 * @see ConfigLexiconStrictness
+	 * @return ConfigLexiconStrictness
+	 * @experimental 31.0.0
+	 */
+	public function getStrictness(): ConfigLexiconStrictness;
+
+	/**
+	 * define the list of entries of your application config lexicon, related to AppConfig.
+	 *
+	 * @return ConfigLexiconEntry[]
+	 * @experimental 31.0.0
+	 */
+	public function getAppConfigs(): array;
+
+	/**
+	 * define the list of entries of your application config lexicon, related to UserPreferences.
+	 *
+	 * @return ConfigLexiconEntry[]
+	 * @experimental 31.0.0
+	 */
+	public function getUserConfigs(): array;
+}

NCU/Config/ValueType.php

@@ -9,6 +9,7 @@
 namespace NCU\Config;
 
 use NCU\Config\Exceptions\IncorrectTypeException;
+use OCP\IAppConfig;
 use UnhandledMatchError;
 
 /**
@@ -89,4 +90,28 @@ public function getDefinition(): string {
 			throw new IncorrectTypeException('unknown type definition ' . $this->value);
 		}
 	}
+
+	/**
+	 * get corresponding AppConfig flag value
+	 *
+	 * @return int
+	 * @throws IncorrectTypeException
+	 *
+	 * @experimental 31.0.0
+	 */
+	public function toAppConfigFlag(): int {
+		try {
+			return match ($this) {
+				self::MIXED => IAppConfig::VALUE_MIXED,
+				self::STRING => IAppConfig::VALUE_STRING,
+				self::INT => IAppConfig::VALUE_INT,
+				self::FLOAT => IAppConfig::VALUE_FLOAT,
+				self::BOOL => IAppConfig::VALUE_BOOL,
+				self::ARRAY => IAppConfig::VALUE_ARRAY,
+			};
+		} catch (UnhandledMatchError) {
+			throw new IncorrectTypeException('unknown type definition ' . $this->value);
+		}
+	}
+
 }

OCP/AppFramework/Bootstrap/IRegistrationContext.php

@@ -423,4 +423,15 @@ public function registerTaskProcessingTaskType(string $taskProcessingTaskTypeCla
 	 */
 	public function registerMailProvider(string $class): void;
 
+
+	/**
+	 * Register an implementation of \OCP\Config\Lexicon\IConfigLexicon that
+	 * will handle the config lexicon
+	 *
+	 * @param string $configLexiconClass
+	 *
+	 * @psalm-param class-string<\NCU\Config\Lexicon\IConfigLexicon> $configLexiconClass
+	 * @since 31.0.0
+	 */
+	public function registerConfigLexicon(string $configLexiconClass): void;
 }

OCP/Calendar/ICalendar.php

@@ -53,7 +53,7 @@ public function getDisplayColor(): ?string;
 	public function search(string $pattern, array $searchProperties = [], array $options = [], ?int $limit = null, ?int $offset = null): array;
 
 	/**
-	 * @return int build up using \OCP\Constants
+	 * @return int build up using {@see \OCP\Constants}
 	 * @since 13.0.0
 	 */
 	public function getPermissions(): int;

OCP/IAppConfig.php

@@ -45,6 +45,9 @@ interface IAppConfig {
 	/** @since 29.0.0 */
 	public const VALUE_ARRAY = 64;
 
+	/** @since 31.0.0 */
+	public const FLAG_SENSITIVE = 1;   // value is sensitive
+
 	/**
 	 * Get list of all apps that have at least one config value stored in database
 	 *