fix(API): Use a distinct exception so apps can react to it and custom…

lib/composer/composer/autoload_classmap.php

@@ -66,6 +66,7 @@
     'OCP\\AppFramework\\Http\\IOutput' => $baseDir . '/lib/public/AppFramework/Http/IOutput.php',
     'OCP\\AppFramework\\Http\\JSONResponse' => $baseDir . '/lib/public/AppFramework/Http/JSONResponse.php',
     'OCP\\AppFramework\\Http\\NotFoundResponse' => $baseDir . '/lib/public/AppFramework/Http/NotFoundResponse.php',
+    'OCP\\AppFramework\\Http\\ParameterOutOfRangeException' => $baseDir . '/lib/public/AppFramework/Http/ParameterOutOfRangeException.php',
     'OCP\\AppFramework\\Http\\RedirectResponse' => $baseDir . '/lib/public/AppFramework/Http/RedirectResponse.php',
     'OCP\\AppFramework\\Http\\RedirectToDefaultAppResponse' => $baseDir . '/lib/public/AppFramework/Http/RedirectToDefaultAppResponse.php',
     'OCP\\AppFramework\\Http\\Response' => $baseDir . '/lib/public/AppFramework/Http/Response.php',

lib/composer/composer/autoload_static.php

@@ -99,6 +99,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OCP\\AppFramework\\Http\\IOutput' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/IOutput.php',
         'OCP\\AppFramework\\Http\\JSONResponse' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/JSONResponse.php',
         'OCP\\AppFramework\\Http\\NotFoundResponse' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/NotFoundResponse.php',
+        'OCP\\AppFramework\\Http\\ParameterOutOfRangeException' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/ParameterOutOfRangeException.php',
         'OCP\\AppFramework\\Http\\RedirectResponse' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/RedirectResponse.php',
         'OCP\\AppFramework\\Http\\RedirectToDefaultAppResponse' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/RedirectToDefaultAppResponse.php',
         'OCP\\AppFramework\\Http\\Response' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Response.php',

lib/private/AppFramework/Http/Dispatcher.php

@@ -38,11 +38,11 @@
 use OC\DB\ConnectionAdapter;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http\DataResponse;
+use OCP\AppFramework\Http\ParameterOutOfRangeException;
 use OCP\AppFramework\Http\Response;
 use OCP\Diagnostics\IEventLogger;
 use OCP\IConfig;
 use OCP\IRequest;
-use OutOfRangeException;
 use Psr\Container\ContainerInterface;
 use Psr\Log\LoggerInterface;
 
@@ -255,18 +255,18 @@ private function executeController(Controller $controller, string $methodName):
 
 	/**
 	 * @psalm-param mixed $value
-	 * @throws OutOfRangeException
+	 * @throws ParameterOutOfRangeException
 	 */
 	private function ensureParameterValueSatisfiesRange(string $param, $value): void {
 		$rangeInfo = $this->reflector->getRange($param);
 		if ($rangeInfo) {
 			if ($value < $rangeInfo['min'] || $value > $rangeInfo['max']) {
-				throw new OutOfRangeException(sprintf(
-					'Parameter %s must be between %d and %d',
+				throw new ParameterOutOfRangeException(
 					$param,
+					$value,
 					$rangeInfo['min'],
 					$rangeInfo['max'],
-				));
+				);
 			}
 		}
 	}

lib/public/AppFramework/Http/ParameterOutOfRangeException.php

@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Joas Schilling <coding@schilljs.com>
+ *
+ * @author Joas Schilling <coding@schilljs.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\AppFramework\Http;
+
+/**
+ * @since 29.0.0
+ */
+class ParameterOutOfRangeException extends \OutOfRangeException {
+	/**
+	 * @since 29.0.0
+	 */
+	public function __construct(
+		protected string $parameterName,
+		protected int $actualValue,
+		protected int $minValue,
+		protected int $maxValue,
+	) {
+		parent::__construct(
+			sprintf(
+				'Parameter %s must be between %d and %d',
+				$this->parameterName,
+				$this->minValue,
+				$this->maxValue,
+			)
+		);
+	}
+
+	/**
+	 * @since 29.0.0
+	 */
+	public function getParameterName(): string {
+		return $this->parameterName;
+	}
+
+	/**
+	 * @since 29.0.0
+	 */
+	public function getActualValue(): int {
+		return $this->actualValue;
+	}
+
+	/**
+	 * @since 29.0.0
+	 */
+	public function getMinValue(): int {
+		return $this->minValue;
+	}
+
+	/**
+	 * @since 29.0.0
+	 */
+	public function getMaxValue(): int {
+		return $this->maxValue;
+	}
+}

tests/lib/AppFramework/Http/DispatcherTest.php

@@ -31,6 +31,7 @@
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\Http\JSONResponse;
+use OCP\AppFramework\Http\ParameterOutOfRangeException;
 use OCP\AppFramework\Http\Response;
 use OCP\Diagnostics\IEventLogger;
 use OCP\IConfig;
@@ -560,7 +561,7 @@ public function testEnsureParameterValueSatisfiesRange(int $min, int $max, int $
 		);
 
 		if ($throw) {
-			$this->expectException(\OutOfRangeException::class);
+			$this->expectException(ParameterOutOfRangeException::class);
 		}
 
 		$this->invokePrivate($this->dispatcher, 'ensureParameterValueSatisfiesRange', ['myArgument', $input]);