nextcloud · skjnldsv · Sep 22, 2026
@@ -2171,6 +2171,7 @@
     'OC\\Preview\\Photoshop' => $baseDir . '/lib/private/Preview/Photoshop.php',
     'OC\\Preview\\Postscript' => $baseDir . '/lib/private/Preview/Postscript.php',
     'OC\\Preview\\PreviewMigrationService' => $baseDir . '/lib/private/Preview/PreviewMigrationService.php',
+    'OC\\Preview\\PreviewProviderDefaults' => $baseDir . '/lib/private/Preview/PreviewProviderDefaults.php',
     'OC\\Preview\\PreviewService' => $baseDir . '/lib/private/Preview/PreviewService.php',
     'OC\\Preview\\ProviderV2' => $baseDir . '/lib/private/Preview/ProviderV2.php',
     'OC\\Preview\\SGI' => $baseDir . '/lib/private/Preview/SGI.php',

@@ -2212,6 +2212,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OC\\Preview\\Photoshop' => __DIR__ . '/../../..' . '/lib/private/Preview/Photoshop.php',
         'OC\\Preview\\Postscript' => __DIR__ . '/../../..' . '/lib/private/Preview/Postscript.php',
         'OC\\Preview\\PreviewMigrationService' => __DIR__ . '/../../..' . '/lib/private/Preview/PreviewMigrationService.php',
+        'OC\\Preview\\PreviewProviderDefaults' => __DIR__ . '/../../..' . '/lib/private/Preview/PreviewProviderDefaults.php',
         'OC\\Preview\\PreviewService' => __DIR__ . '/../../..' . '/lib/private/Preview/PreviewService.php',
         'OC\\Preview\\ProviderV2' => __DIR__ . '/../../..' . '/lib/private/Preview/ProviderV2.php',
         'OC\\Preview\\SGI' => __DIR__ . '/../../..' . '/lib/private/Preview/SGI.php',

@@ -349,60 +349,74 @@ private function getMaxPreview(array $previews, File $file, string $mimeType, ?s
 	 * @throws NotFoundException
 	 */
 	private function generateProviderPreview(File $file, int $width, int $height, bool $crop, bool $max, string $mimeType, ?string $version): Preview {
-		$previewProviders = $this->previewManager->getProviders();
-		foreach ($previewProviders as $supportedMimeType => $providers) {
-			// Filter out providers that does not support this mime
+		$entries = [];
+		foreach ($this->previewManager->getProviders() as $supportedMimeType => $providers) {
 			if (!preg_match($supportedMimeType, $mimeType)) {
 				continue;
 			}
 
 			foreach ($providers as $providerClosure) {
-
 				$provider = $this->helper->getProvider($providerClosure);
 				if (!$provider) {
 					continue;
 				}
-
 				if (!$provider->isAvailable($file)) {
 					continue;
 				}
+				$entries[] = [
+					'class' => ltrim($provider::class, '\\'),
+					'provider' => $provider,
+				];
+			}
+		}
 
-				$previewConcurrency = $this->getNumConcurrentPreviews('preview_concurrency_new');
-				$sem = self::guardWithSemaphore(self::SEMAPHORE_ID_NEW, $previewConcurrency);
-				try {
-					$this->logger->debug('Calling preview provider for {mimeType} with width={width}, height={height}', [
-						'mimeType' => $mimeType,
-						'width' => $width,
-						'height' => $height,
-					]);
-					$preview = $this->helper->getThumbnail($provider, $file, $width, $height);
-				} finally {
-					self::unguardWithSemaphore($sem);
-				}
+		foreach ($entries as $entry) {
+			$provider = $entry['provider'];
+			$class = $entry['class'];
 
-				if (!($preview instanceof IImage)) {
-					continue;
-				}
+			$previewConcurrency = $this->getNumConcurrentPreviews('preview_concurrency_new');
+			$sem = self::guardWithSemaphore(self::SEMAPHORE_ID_NEW, $previewConcurrency);
+			try {
+				$this->logger->debug('Calling preview provider {provider} for {mimeType} with width={width}, height={height}', [
+					'provider' => $class,
+					'mimeType' => $mimeType,
+					'width' => $width,
+					'height' => $height,
+				]);
+				$preview = $this->helper->getThumbnail($provider, $file, $width, $height);
+			} catch (\Throwable $e) {
+				$this->logger->warning('Preview provider {provider} failed for {mimeType}', [
+					'provider' => $class,
+					'mimeType' => $mimeType,
+					'exception' => $e,
+				]);
+				continue;
+			} finally {
+				self::unguardWithSemaphore($sem);
+			}
 
-				try {
-					$previewEntry = new Preview();
-					$previewEntry->generateId();
-					$previewEntry->setFileId($file->getId());
-					$previewEntry->setStorageId($file->getMountPoint()->getNumericStorageId());
-					$previewEntry->setSourceMimeType($file->getMimeType());
-					$previewEntry->setWidth($preview->width());
-					$previewEntry->setHeight($preview->height());
-					$previewEntry->setVersion($version);
-					$previewEntry->setMax($max);
-					$previewEntry->setCropped($crop);
-					$previewEntry->setEncrypted(false);
-					$previewEntry->setMimetype($preview->dataMimeType());
-					$previewEntry->setEtag($file->getEtag());
-					$previewEntry->setMtime((new \DateTime())->getTimestamp());
-					return $this->savePreview($previewEntry, $preview);
-				} catch (NotPermittedException) {
-					throw new NotFoundException();
-				}
+			if (!($preview instanceof IImage)) {
+				continue;
+			}
+
+			try {
+				$previewEntry = new Preview();
+				$previewEntry->generateId();
+				$previewEntry->setFileId($file->getId());
+				$previewEntry->setStorageId($file->getMountPoint()->getNumericStorageId());
+				$previewEntry->setSourceMimeType($file->getMimeType());
+				$previewEntry->setWidth($preview->width());
+				$previewEntry->setHeight($preview->height());
+				$previewEntry->setVersion($version);
+				$previewEntry->setMax($max);
+				$previewEntry->setCropped($crop);
+				$previewEntry->setEncrypted(false);
+				$previewEntry->setMimetype($preview->dataMimeType());
+				$previewEntry->setEtag($file->getEtag());
+				$previewEntry->setMtime((new \DateTime())->getTimestamp());
+				return $this->savePreview($previewEntry, $preview);
+			} catch (NotPermittedException) {
+				throw new NotFoundException();
 			}
 		}
 

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OC\Preview;
+
+/**
+ * Default and recommended `enabledPreviewProviders` lists, shared between
+ * {@see \OC\PreviewManager} and the admin settings UI.
+ */
+class PreviewProviderDefaults {
+	/**
+	 * Built-in defaults when ``enabledPreviewProviders`` is unset.
+	 *
+	 * @return list<class-string>
+	 */
+	public static function getBuiltinDefaultProviders(): array {
+		return [
+			MarkDown::class,
+			TXT::class,
+			OpenDocument::class,
+			PNG::class,
+			JPEG::class,
+			GIF::class,
+			BMP::class,
+			XBitmap::class,
+			Krita::class,
+			WebP::class,
+			AVIF::class,
+		];
+	}
+
+	/**
+	 * Nextcloud-encouraged provider list.
+	 *
+	 * Matches core defaults, plus Imaginary first when it is configured (server
+	 * tuning / AIO). Native HEIC is appended as a fallback because Imaginary
+	 * does not handle every HEIC/HEIF file.
+	 *
+	 * @return list<class-string>
+	 */
+	public static function getRecommendedEnabledProviders(bool $imaginaryConfigured, bool $heicFallback = false): array {
+		$providers = self::getBuiltinDefaultProviders();
+		if (!$imaginaryConfigured) {
+			return $providers;
+		}
+		$providers = array_merge([Imaginary::class], $providers);
+		if ($heicFallback) {
+			$providers[] = HEIC::class;
+		}
+		return array_values(array_unique($providers));
+	}
+}
@@ -41,6 +41,7 @@
 use OC\Preview\PNG;
 use OC\Preview\Postscript;
 use OC\Preview\PreviewMigrationService;
+use OC\Preview\PreviewProviderDefaults;
 use OC\Preview\SGI;
 use OC\Preview\StarOffice;
 use OC\Preview\Storage\StorageFactory;
@@ -77,6 +78,14 @@ class PreviewManager implements IPreview {
 	/** @var array<string, list<ProviderClosure>> $providers */
 	protected array $providers = [];
 
+	/**
+	 * Registrations in insertion order, rebuilt into {@see $providers} using
+	 * ``enabledPreviewProviders`` as key order (PHP maps keep insertion order).
+	 *
+	 * @var list<array{regex: string, class: ?string, callable: Closure}>
+	 */
+	private array $providerRegistrations = [];
+
 	/** @var array mime type => support status */
 	protected array $mimeTypeSupportMap = [];
 
@@ -111,15 +120,16 @@ public function __construct(
 	 * @param string $mimeTypeRegex Regex with the mime types that are supported by this provider
 	 * @param ProviderClosure $callable
 	 */
-	private function registerProviderClosure(string $mimeTypeRegex, Closure $callable): void {
+	private function registerProviderClosure(string $mimeTypeRegex, Closure $callable, ?string $class = null): void {
 		if (!$this->enablePreviews) {
 			return;
 		}
 
-		if (!isset($this->providers[$mimeTypeRegex])) {
-			$this->providers[$mimeTypeRegex] = [];
-		}
-		$this->providers[$mimeTypeRegex][] = $callable;
+		$this->providerRegistrations[] = [
+			'regex' => $mimeTypeRegex,
+			'class' => $class !== null && $class !== '' ? ltrim($class, '\\') : null,
+			'callable' => $callable,
+		];
 		$this->providerListDirty = true;
 	}
 
@@ -132,21 +142,57 @@ public function getProviders(): array {
 		$this->registerCoreProviders();
 		$this->registerBootstrapProviders();
 		if ($this->providerListDirty) {
-			$keys = array_map('strlen', array_keys($this->providers));
-			array_multisort($keys, SORT_DESC, $this->providers);
+			$this->rebuildProvidersMap();
 			$this->providerListDirty = false;
 		}
 
 		return $this->providers;
 	}
 
+	/**
+	 * Rebuild {@see $providers} so foreach order follows ``enabledPreviewProviders``.
+	 *
+	 * PHP arrays preserve insertion order. Each provider has its own MIME regex
+	 * in core, so visiting map keys in whitelist order is try-order for Generator.
+	 */
+	private function rebuildProvidersMap(): void {
+		$priority = [];
+		foreach ($this->getEnabledDefaultProvider() as $index => $class) {
+			if (!is_string($class) || $class === '') {
+				continue;
+			}
+			$priority[ltrim($class, '\\')] = $index;
+		}
+
+		$registrations = [];
+		foreach ($this->providerRegistrations as $index => $registration) {
+			$registration['index'] = $index;
+			$registrations[] = $registration;
+		}
+		usort($registrations, function (array $left, array $right) use ($priority): int {
+			$leftClass = $left['class'];
+			$rightClass = $right['class'];
+			$leftPriority = is_string($leftClass) && isset($priority[$leftClass]) ? $priority[$leftClass] : PHP_INT_MAX;
+			$rightPriority = is_string($rightClass) && isset($priority[$rightClass]) ? $priority[$rightClass] : PHP_INT_MAX;
+			if ($leftPriority !== $rightPriority) {
+				return $leftPriority <=> $rightPriority;
+			}
+			return $left['index'] <=> $right['index'];
+		});
+
+		$this->providers = [];
+		foreach ($registrations as $registration) {
+			$this->providers[$registration['regex']][] = $registration['callable'];
+		}
+	}
+
 	/**
 	 * Does the manager have any providers
 	 */
 	#[\Override]
 	public function hasProviders(): bool {
 		$this->registerCoreProviders();
-		return !empty($this->providers);
+		return $this->providerRegistrations !== [];
 	}
 
 	private function getGenerator(): Generator {
@@ -279,11 +325,15 @@ protected function getEnabledDefaultProvider(): array {
 			AVIF::class,
 		];
 
-		$this->defaultProviders = $this->config->getSystemValue('enabledPreviewProviders', array_merge([
-			MarkDown::class,
-			TXT::class,
-			OpenDocument::class,
-		], $imageProviders));
+		$configured = $this->config->getSystemValue('enabledPreviewProviders', null);
+		if (!is_array($configured)) {
+			$this->defaultProviders = PreviewProviderDefaults::getRecommendedEnabledProviders(
+				$this->config->getSystemValueString('preview_imaginary_url', '') !== '',
+				$this->imagickSupport->hasExtension() && $this->imagickSupport->supportsFormat('HEIC'),
+			);
+		} else {
+			$this->defaultProviders = $configured;
+		}
 
 		if (in_array(Image::class, $this->defaultProviders, true)) {
 			$this->defaultProviders = array_merge($this->defaultProviders, $imageProviders);
@@ -302,7 +352,7 @@ protected function registerCoreProvider(string $class, string $mimeType, array $
 			$this->registerProviderClosure($mimeType, function () use ($class, $options): IProviderV2 {
 				/** @var IProviderV2 $class */
 				return new $class($options);
-			});
+			}, $class);
 		}
 	}
 
@@ -429,13 +479,17 @@ private function registerBootstrapProviders(): void {
 			}
 			$this->loadedBootstrapProviders[$key] = null;
 
-			$this->registerProviderClosure($provider->getMimeTypeRegex(), function () use ($provider): IProviderV2|false {
-				try {
-					return $this->container->get($provider->getService());
-				} catch (NotFoundExceptionInterface) {
-					return false;
-				}
-			});
+			$this->registerProviderClosure(
+				$provider->getMimeTypeRegex(),
+				function () use ($provider): IProviderV2|false {
+					try {
+						return $this->container->get($provider->getService());
+					} catch (NotFoundExceptionInterface) {
+						return false;
+					}
+				},
+				$provider->getService(),
+			);
 		}
 	}