feat: Allow url-encoding source URLs

src/Options.php

@@ -863,10 +863,15 @@ public function getCacheBuster(): ?string
 
 	/**
 	 * Set filename
+	 *
+	 * @param bool $encode Whether to base64 encode the filename. If true, the filename is base64 encoded. Otherwise, the filename is url-encoded.
+	 *
+	 * Note: This diverges from the imgproxy arguments.
 	 */
-	public function setFilename(string $filename): self
+	public function setFilename(string $filename, bool $encode = true): self
 	{
-		$this->options['filename'] = [base64_encode($filename), true];
+		$this->options['filename'] = $encode ? [base64_encode($filename), true] : [urlencode($filename), false];
+
 		return $this;
 	}
 
@@ -877,8 +882,17 @@ public function getFilename(): ?string
 	{
 		/** @var ?string $value */
 		$value = $this->options['filename'][0] ?? null;
+		$encoded = $this->options['filename'][1] ?? null;
 
-		return $value !== null ? (base64_decode($value, true) ?: null) : null;
+		if ($value === null) {
+			return null;
+		}
+
+		if ($encoded === true) {
+			return base64_decode($value, true) ?: null;
+		}
+
+		return urldecode($value);
 	}
 
 	/**

tests/Unit/OptionsTest.php

@@ -97,3 +97,23 @@
 	expect($options->toString())->toContain("filename:{$encodedFilename}:1");
 	expect($options->getFilename())->toBe($filename);
 });
+
+test('setFilename encodes and decodes correctly with encode=true', function (): void {
+	$options = createOptions();
+	$filename = 'test image @ 2024.png';
+	$options->setFilename($filename, true);
+
+	$encoded = base64_encode($filename);
+	expect($options->toString())->toContain("filename:{$encoded}:1");
+	expect($options->getFilename())->toBe($filename);
+});
+
+test('setFilename stores and decodes correctly with encode=false', function (): void {
+	$options = createOptions();
+	$filename = 'test image @ 2024.png';
+	$options->setFilename($filename, false);
+
+	$urlEncoded = urlencode($filename);
+	expect($options->toString())->toContain("filename:{$urlEncoded}:0");
+	expect($options->getFilename())->toBe($filename);
+});