Change Translator to replace placeholders by key

- Add ReplaceParameters trait to replace parameters on a message
- Replace DataView exceptions with translation keys

Author: doekenorg

src/Data/CachedDataSource.php

@@ -76,7 +76,7 @@ private function get_cache_key( ...$arguments ): string {
 			return md5( json_encode( $arguments, JSON_THROW_ON_ERROR ) );
 		} catch ( JsonException $e ) {
 			throw new InvalidArgumentException(
-				'The cache key could not be generated based on the provide arguments',
+				'The cache key could not be generated based on the provided arguments.',
 				$e->getCode(),
 				$e,
 			);

src/Data/CsvDataSource.php

@@ -7,8 +7,8 @@
 use Closure;
 use DataKit\DataViews\Data\DataMatcher\ArrayDataMatcher;
 use DataKit\DataViews\Data\Exception\DataNotFoundException;
+use DataKit\DataViews\Data\Exception\DataSourceNotFoundException;
 use DataKit\DataViews\DataView\Sort;
-use InvalidArgumentException;
 use Iterator;
 use LimitIterator;
 use SplFileObject;
@@ -34,6 +34,8 @@ final class CsvDataSource extends BaseDataSource {
 	 * @since $ver$
 	 *
 	 * @param string $file_path The file path to the CSV file.
+	 *
+	 * @throws DataSourceNotFoundException When file is not readable.
 	 */
 	public function __construct(
 		string $file_path,
@@ -44,7 +46,7 @@ public function __construct(
 		if (
 			! file_exists( $file_path )
 			|| ! is_readable( $file_path ) ) {
-			throw new InvalidArgumentException( 'The CSV data source file is not found or readable.' );
+			throw new DataSourceNotFoundException();
 		}
 
 		$this->file = new SplFileObject( $file_path, 'rb' );
@@ -101,7 +103,6 @@ public function get_data_by_id( string $id ): array {
 		throw DataNotFoundException::with_id( $this, $id );
 	}
 
-
 	/**
 	 * Cleans CSV data.
 	 *

src/Data/Exception/ActionForbiddenException.php

@@ -37,7 +37,7 @@ final class ActionForbiddenException extends DataSourceException {
 	 */
 	public function __construct(
 		DataSource $data_source,
-		$message = 'Action is forbidden.',
+		$message = 'datakit.action.forbidden',
 		$code = 403,
 		Throwable $previous = null
 	) {
@@ -84,6 +84,6 @@ public function translate( Translator $translator ): string {
 			return parent::translate( $translator );
 		}
 
-		return $translator->translate( 'This action is forbidden for data set with id "%s".', $this->id );
+		return $translator->translate( 'datakit.action.forbidden.with_id', [ 'id' => $this->id ] );
 	}
 }

src/Data/Exception/DataNotFoundException.php

@@ -37,7 +37,7 @@ final class DataNotFoundException extends DataSourceException {
 	 */
 	public function __construct(
 		DataSource $data_source,
-		$message = 'Dataset for id not found.',
+		$message = 'datakit.data.not_found',
 		$code = 404,
 		Throwable $previous = null
 	) {
@@ -84,6 +84,6 @@ public function translate( Translator $translator ): string {
 			return parent::translate( $translator );
 		}
 
-		return $translator->translate( 'Data set with id "%s" not found.', $this->id );
+		return $translator->translate( 'datakit.data.not_found.with_id', [ 'id' => $this->id ] );
 	}
 }

src/Data/Exception/DataSourceNotFoundException.php

@@ -17,7 +17,7 @@ final class DataSourceNotFoundException extends DataSourceException {
 	 *
 	 * @phpcs:disable Generic.CodeAnalysis.UselessOverridingMethod.Found
 	 */
-	public function __construct( $message = 'Data source not found.', $code = 404, Throwable $previous = null ) {
+	public function __construct( $message = 'datakit.data_source.not_found', $code = 404, Throwable $previous = null ) {
 		parent::__construct( $message, $code, $previous );
 	}
 }

src/DataView/DataViewNotFoundException.php

@@ -19,7 +19,7 @@ final class DataViewNotFoundException extends DataViewException {
 	 * @param string         $message  The message.
 	 * @param Exception|null $previous The previous exception.
 	 */
-	public function __construct( $message = 'The DataView was not found.', Exception $previous = null ) {
+	public function __construct( $message = 'datakit.dataview.not_found', Exception $previous = null ) {
 		parent::__construct( $message, 404, $previous );
 	}
 }

src/Translation/ReplaceParameters.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace DataKit\DataViews\Translation;
+
+/**
+ * Helper trait to replace parameters on a string.
+ *
+ * @since $ver$
+ */
+trait ReplaceParameters {
+	/**
+	 * Replaces any parameters found in square brackets with the value.
+	 *
+	 * @since $ver$
+	 *
+	 * @param string $message    The message.
+	 * @param array  $parameters The parameters to replace.
+	 *
+	 * @return string The message with replaced parameters.
+	 */
+	protected function replace_parameters( string $message, array $parameters = [] ): string {
+		$values = array_values( $parameters );
+		$keys   = array_map( static fn( string $key ): string => '[' . $key . ']', array_keys( $parameters ) );
+
+		return strtr( $message, array_combine( $keys, $values ) );
+	}
+}

src/Translation/Translator.php

@@ -3,7 +3,7 @@
 namespace DataKit\DataViews\Translation;
 
 /**
- * Represents a translator that can translate and format a message based on how `sprintf` would work.
+ * Represents a translator that can translate a message and replace placeholders.
  *
  * @since $ver$
  */
@@ -13,10 +13,10 @@ interface Translator {
 	 *
 	 * @since $ver$
 	 *
-	 * @param string $message   The message to translate.
-	 * @param mixed  ...$values The context needed to complete the translation.
+	 * @param string $message    The message to translate.
+	 * @param array  $parameters An array of parameters for the message.
 	 *
 	 * @return string The translated message with the
 	 */
-	public function translate( string $message, ...$values ): string;
+	public function translate( string $message, array $parameters = [] ): string;
 }

tests/Data/CsvDataSourceTest.php

@@ -4,11 +4,11 @@
 
 use DataKit\DataViews\Data\CsvDataSource;
 use DataKit\DataViews\Data\Exception\DataNotFoundException;
+use DataKit\DataViews\Data\Exception\DataSourceNotFoundException;
 use DataKit\DataViews\DataView\Filter;
 use DataKit\DataViews\DataView\Filters;
 use DataKit\DataViews\DataView\Search;
 use DataKit\DataViews\DataView\Sort;
-use InvalidArgumentException;
 use PHPUnit\Framework\TestCase;
 
 /**
@@ -34,14 +34,13 @@ protected function setUp(): void {
 		$this->data_source = new CsvDataSource( __DIR__ . '/../assets/oscar-example-data.csv' );
 	}
 
-
 	/**
 	 * Test case for missing or unreadable path.
 	 *
 	 * @since $ver$
 	 */
 	public function test_invalid_path(): void {
-		$this->expectException( InvalidArgumentException::class );
+		$this->expectException( DataSourceNotFoundException::class );
 		new CsvDataSource( 'invalid-path' );
 	}
 

tests/Data/Exception/ActionForbiddenExceptionTest.php

@@ -4,7 +4,7 @@
 
 use DataKit\DataViews\Data\ArrayDataSource;
 use DataKit\DataViews\Data\Exception\ActionForbiddenException;
-use DataKit\DataViews\Translation\NoopTranslator;
+use DataKit\DataViews\Translation\ReplaceParameters;
 use DataKit\DataViews\Translation\Translator;
 use PHPUnit\Framework\TestCase;
 
@@ -21,8 +21,10 @@ final class ActionForbiddenExceptionTest extends TestCase {
 	 */
 	public function test_exception(): void {
 		$translator = new class implements Translator {
-			public function translate( string $message, ...$values ): string {
-				return sprintf( $message, ...$values );
+			use ReplaceParameters;
+
+			public function translate( string $message, array $parameters = [] ): string {
+				return $this->replace_parameters( $message, $parameters );
 			}
 		};
 
@@ -34,9 +36,6 @@ public function translate( string $message, ...$values ): string {
 		self::assertSame( $data_source, $with_id->data_source() );
 
 		self::assertSame( 'some message', $custom_message->translate( $translator ) );
-		self::assertSame(
-			'This action is forbidden for data set with id "test-id".',
-			$with_id->translate( $translator )
-		);
+		self::assertSame( 'datakit.action.forbidden.with_id', $with_id->translate( $translator ) );
 	}
 }