🚿 replaced generic exceptions

src/Decoder/Binarizer.php

@@ -11,7 +11,6 @@
 
 namespace chillerlan\QRCode\Decoder;
 
-use RuntimeException;
 use function array_fill, count, max;
 
 /**
@@ -55,7 +54,7 @@ final class Binarizer{
 	}
 
 	/**
-	 * @throws \RuntimeException
+	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException
 	 */
 	private function estimateBlackPoint(array $buckets):int{
 		// Find the tallest peak in the histogram.
@@ -101,7 +100,7 @@ final class Binarizer{
 		// If there is too little contrast in the image to pick a meaningful black point, throw rather
 		// than waste time trying to decode the image, and risk false positives.
 		if($secondPeak - $firstPeak <= $numBuckets / 16){
-			throw new RuntimeException('no meaningful dark point found');
+			throw new QRCodeDecoderException('no meaningful dark point found');
 		}
 
 		// Find a valley between them that is low and closer to the white peak.

src/Decoder/BitMatrix.php

@@ -12,7 +12,6 @@
 namespace chillerlan\QRCode\Decoder;
 
 use chillerlan\QRCode\Common\{FormatInformation, Version};
-use InvalidArgumentException, RuntimeException;
 use function array_fill, count;
 use const PHP_INT_MAX, PHP_INT_SIZE;
 
@@ -74,23 +73,23 @@ final class BitMatrix{
 	 * @param int $width  ;  The width of the region
 	 * @param int $height ;  The height of the region
 	 *
-	 * @throws \InvalidArgumentException
+	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException
 	 */
 	public function setRegion(int $left, int $top, int $width, int $height):self{
 
 		if($top < 0 || $left < 0){
-			throw new InvalidArgumentException('Left and top must be nonnegative');
+			throw new QRCodeDecoderException('Left and top must be non-negative');
 		}
 
 		if($height < 1 || $width < 1){
-			throw new InvalidArgumentException('Height and width must be at least 1');
+			throw new QRCodeDecoderException('Height and width must be at least 1');
 		}
 
 		$right  = $left + $width;
 		$bottom = $top + $height;
 
 		if($bottom > $this->dimension || $right > $this->dimension){
-			throw new InvalidArgumentException('The region must fit inside the matrix');
+			throw new QRCodeDecoderException('The region must fit inside the matrix');
 		}
 
 		for($y = $top; $y < $bottom; $y++){
@@ -256,7 +255,7 @@ final class BitMatrix{
 	 * QR Code.
 	 *
 	 * @return array bytes encoded within the QR Code
-	 * @throws \RuntimeException if the exact number of bytes expected is not read
+	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException if the exact number of bytes expected is not read
 	 */
 	public function readCodewords():array{
 		$this->formatInfo = $this->readFormatInformation();
@@ -308,7 +307,7 @@ final class BitMatrix{
 		}
 
 		if($resultOffset !== $this->version->getTotalCodewords()){
-			throw new RuntimeException('offset differs from total codewords for version');
+			throw new QRCodeDecoderException('offset differs from total codewords for version');
 		}
 
 		return $result;
@@ -317,9 +316,9 @@ final class BitMatrix{
 	/**
 	 * Reads format information from one of its two locations within the QR Code.
 	 *
-	 * @return \chillerlan\QRCode\Common\FormatInformation encapsulating the QR Code's format info
-	 * @throws \RuntimeException                           if both format information locations cannot be parsed as
-	 *                                                     the valid encoding of format information
+	 * @return \chillerlan\QRCode\Common\FormatInformation       encapsulating the QR Code's format info
+	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException if both format information locations cannot be parsed as
+	 *                                                           the valid encoding of format information
 	 */
 	private function readFormatInformation():FormatInformation{
 
@@ -372,7 +371,7 @@ final class BitMatrix{
 			return $this->formatInfo;
 		}
 
-		throw new RuntimeException('failed to read format info');
+		throw new QRCodeDecoderException('failed to read format info');
 	}
 
 	/**
@@ -424,9 +423,9 @@ final class BitMatrix{
 	/**
 	 * Reads version information from one of its two locations within the QR Code.
 	 *
-	 * @return \chillerlan\QRCode\Common\Version encapsulating the QR Code's version
-	 * @throws \RuntimeException                 if both version information locations cannot be parsed as
-	 *                                           the valid encoding of version information
+	 * @return \chillerlan\QRCode\Common\Version                 encapsulating the QR Code's version
+	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException if both version information locations cannot be parsed as
+	 *                                                           the valid encoding of version information
 	 */
 	private function readVersion():Version{
 
@@ -471,7 +470,7 @@ final class BitMatrix{
 			return $this->version;
 		}
 
-		throw new RuntimeException('failed to read version');
+		throw new QRCodeDecoderException('failed to read version');
 	}
 
 	/**

src/Decoder/Decoder.php

@@ -11,7 +11,7 @@
 
 namespace chillerlan\QRCode\Decoder;
 
-use InvalidArgumentException, RuntimeException, Throwable;
+use Throwable;
 use chillerlan\QRCode\Common\{BitBuffer, EccLevel, Mode, ReedSolomonDecoder, Version};
 use chillerlan\QRCode\Data\{AlphaNum, Byte, ECI, Kanji, Number};
 use chillerlan\QRCode\Detector\Detector;
@@ -33,8 +33,8 @@ final class Decoder{
 	 *
 	 * @param \chillerlan\QRCode\Decoder\LuminanceSourceInterface $source
 	 *
-	 * @return \chillerlan\QRCode\Decoder\DecoderResult text and bytes encoded within the QR Code
-	 * @throws \Throwable if the QR Code cannot be decoded
+	 * @return \chillerlan\QRCode\Decoder\DecoderResult                     text and bytes encoded within the QR Code
+	 * @throws \Throwable|\chillerlan\QRCode\Decoder\QRCodeDecoderException if the QR Code cannot be decoded
 	 */
 	public function decode(LuminanceSourceInterface $source):DecoderResult{
 		$bitMatrix = (new Detector($source))->detect();
@@ -66,9 +66,7 @@ final class Decoder{
 	}
 
 	/**
-	 * @param \chillerlan\QRCode\Decoder\BitMatrix $bitMatrix
-	 *
-	 * @return \chillerlan\QRCode\Decoder\DecoderResult
+	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException
 	 */
 	private function decodeMatrix(BitMatrix $bitMatrix):DecoderResult{
 		// Read raw codewords
@@ -78,7 +76,7 @@ final class Decoder{
 
 		// technically this shouldn't happen as the respective read meathods would throw first
 		if($version === null || $formatInfo === null){
-			throw new RuntimeException('unable to read version or ecc level');
+			throw new QRCodeDecoderException('unable to read version or ecc level');
 		}
 
 		$eccLevel = $formatInfo->getErrorCorrectionLevel();
@@ -114,12 +112,12 @@ final class Decoder{
 	 * @param \chillerlan\QRCode\Common\EccLevel $eccLevel     error-correction level of the QR Code
 	 *
 	 * @return array DataBlocks containing original bytes, "de-interleaved" from representation in the QR Code
-	 * @throws \InvalidArgumentException
+	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException
 	 */
 	private function getDataBlocks(array $rawCodewords, Version $version, EccLevel $eccLevel):array{
 
 		if(count($rawCodewords) !== $version->getTotalCodewords()){
-			throw new InvalidArgumentException('$rawCodewords differ from total codewords for version');
+			throw new QRCodeDecoderException('$rawCodewords differ from total codewords for version');
 		}
 
 		// Figure out the number and size of data blocks used by this version and
@@ -210,7 +208,7 @@ final class Decoder{
 	}
 
 	/**
-	 * @throws \RuntimeException
+	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException
 	 */
 	private function decodeBitStream(array $bytes, Version $version, EccLevel $ecLevel):DecoderResult{
 		$bits           = new BitBuffer($bytes);
@@ -242,7 +240,7 @@ final class Decoder{
 			}
 			elseif($datamode === Mode::STRCTURED_APPEND){
 				if($bits->available() < 16){
-					throw new RuntimeException('structured append: not enough bits left');
+					throw new QRCodeDecoderException('structured append: not enough bits left');
 				}
 				// sequence number and parity is added later to the result metadata
 				// Read next 8 bits (symbol sequence #) and 8 bits (parity data), then continue
@@ -312,7 +310,7 @@ final class Decoder{
 						$result .= Kanji::decodeSegment($bits, $versionNumber);
 					}
 					else{
-						throw new RuntimeException('invalid data mode');
+						throw new QRCodeDecoderException('invalid data mode');
 					}
 #				}
 			}

src/Decoder/GDLuminanceSource.php

@@ -13,7 +13,6 @@
 
 namespace chillerlan\QRCode\Decoder;
 
-use InvalidArgumentException;
 use function file_get_contents, get_resource_type, imagecolorat, imagecolorsforindex,
 	imagecreatefromstring, imagesx, imagesy, is_resource;
 use const PHP_MAJOR_VERSION;
@@ -34,7 +33,7 @@ final class GDLuminanceSource extends LuminanceSourceAbstract{
 	 *
 	 * @param resource|\GdImage $gdImage
 	 *
-	 * @throws \InvalidArgumentException
+	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException
 	 */
 	public function __construct($gdImage){
 
@@ -43,7 +42,7 @@ final class GDLuminanceSource extends LuminanceSourceAbstract{
 			(PHP_MAJOR_VERSION >= 8 && !$gdImage instanceof \GdImage)
 			|| (PHP_MAJOR_VERSION < 8 && (!is_resource($gdImage) || get_resource_type($gdImage) !== 'gd'))
 		){
-			throw new InvalidArgumentException('Invalid GD image source.');
+			throw new QRCodeDecoderException('Invalid GD image source.');
 		}
 
 		parent::__construct(imagesx($gdImage), imagesy($gdImage));

src/Decoder/LuminanceSourceAbstract.php

@@ -11,7 +11,6 @@
 
 namespace chillerlan\QRCode\Decoder;
 
-use InvalidArgumentException;
 use function array_slice, array_splice, file_exists, is_file, is_readable, realpath;
 
 /**
@@ -59,7 +58,7 @@ abstract class LuminanceSourceAbstract implements LuminanceSourceInterface{
 	public function getRow(int $y):array{
 
 		if($y < 0 || $y >= $this->getHeight()){
-			throw new InvalidArgumentException('Requested row is outside the image: '.$y);
+			throw new QRCodeDecoderException('Requested row is outside the image: '.$y);
 		}
 
 		$arr = [];
@@ -81,19 +80,19 @@ abstract class LuminanceSourceAbstract implements LuminanceSourceInterface{
 	}
 
 	/**
-	 *
+	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException
 	 */
 	protected static function checkFile(string $path):string{
 		$path = trim($path);
 
 		if(!file_exists($path) || !is_file($path) || !is_readable($path)){
-			throw new InvalidArgumentException('invalid file: '.$path);
+			throw new QRCodeDecoderException('invalid file: '.$path);
 		}
 
 		$realpath = realpath($path);
 
 		if($realpath === false){
-			throw new InvalidArgumentException('unable to resolve path: '.$path);
+			throw new QRCodeDecoderException('unable to resolve path: '.$path);
 		}
 
 		return $realpath;

src/Decoder/LuminanceSourceInterface.php

@@ -44,6 +44,7 @@ interface LuminanceSourceInterface{
 	 * @param int $y  The row to fetch, which must be in [0,getHeight())
 	 *
 	 * @return array An array containing the luminance data.
+	 * @throws \chillerlan\QRCode\Decoder\QRCodeDecoderException
 	 */
 	public function getRow(int $y):array;
 

src/Decoder/QRCodeDecoderException.php

@@ -0,0 +1,15 @@
+<?php
+/**
+ * Class QRCodeDecoderException
+ *
+ * @created      01.12.2021
+ * @author       smiley <smiley@chillerlan.net>
+ * @copyright    2021 smiley
+ * @license      MIT
+ */
+
+namespace chillerlan\QRCode\Decoder;
+
+use chillerlan\QRCode\QRCodeException;
+
+class QRCodeDecoderException extends QRCodeException{}