feat: add readAccessible() file method

Author: timnarr

.php-cs-fixer.php

@@ -1,7 +1,10 @@
 <?php
 
 	$finder = PhpCsFixer\Finder::create()
+		->exclude('site/plugins')
+		->exclude('storage')
 		->exclude('vendor')
+		->exclude('node_modules')
 		->ignoreDotFiles(true)
 		->in(__DIR__);
 
@@ -10,6 +13,7 @@
 		->setUsingCache(true)
 		->setCacheFile(__DIR__ . '/.cache/.php-cs-fixer.cache')
 		->setRules([
+			'@PHP84Migration' => true,
 			'@PSR12' => true,
 			'align_multiline_comment' => ['comment_type' => 'phpdocs_only'],
 			'array_indentation' => true,
@@ -26,7 +30,7 @@
 			'explicit_string_variable' => true,
 			'full_opening_tag' => true,
 			'function_declaration' => ['closure_function_spacing' => 'one', 'closure_fn_spacing' => 'one'],
-			'function_typehint_space' => true,
+			'type_declaration_spaces' => true,
 			'include' => true,
 			'logical_operators' => true,
 			'magic_constant_casing' => true,
@@ -35,8 +39,8 @@
 			'modernize_types_casting' => true,
 			'multiline_comment_opening_closing' => true,
 			'native_function_casing' => true,
-			'native_function_type_declaration_casing' => true,
-			'new_with_braces' => true,
+			'native_type_declaration_casing' => true,
+			'new_with_parentheses' => true,
 			'no_blank_lines_after_phpdoc' => true,
 			'no_empty_comment' => true,
 			'no_empty_phpdoc' => true,

composer.json

@@ -2,7 +2,7 @@
 	"name": "timnarr/kirby-helpers",
 	"description": "This plugin provides a collection of helper functions for Kirby",
 	"type": "kirby-plugin",
-	"version": "0.3.5",
+	"version": "0.4.0",
 	"license": "MIT",
 	"homepage": "https://github.com/timnarr/kirby-helpers",
 	"authors": [

index.php

@@ -6,7 +6,7 @@
 	'options' => [
 		'vite' => [
 			'manifestPath' => kirby()->root() . '/build/manifest.json',
-		]
+		],
 	],
 	'fieldMethods' => [
 		'ensureLeft' => function (Field $field, string $prefix): string {
@@ -16,13 +16,18 @@
 			return ensureRight($field->value, $suffix);
 		},
 	],
+	'fileMethods' => [
+		'readAccessible' => function (string $title = '', string $description = '', bool $isDecorative = false) {
+			return readAccessible($this, $title, $description, $isDecorative);
+		},
+	],
 	'pageMethods' => [
 		'hasTranslations' => function (): bool {
 			return !empty(getAvailableTranslations($this));
 		},
 		'getTranslations' => function (): array {
 			return getAvailableTranslations($this);
-		}
+		},
 	],
 	'translations' => [
 		'en' => [
@@ -40,6 +45,6 @@
 			'link_label_external' => 'Externer Link: { url } (Öffnet neuen Tab)',
 			'link_label_mail' => 'E-Mail schreiben an: { mail } (Öffnet neues Fenster Ihres E-Mail Programms)',
 			'link_label_tel' => 'Telefonnummer anrufen: { tel } (Öffnet neues Fenster/Programm)',
-		]
-	]
+		],
+	],
 ]);

src/misc.php

@@ -177,3 +177,64 @@ function getAvailableTranslations(Page $page): array
 		return $availableTranslations;
 	}
 }
+
+
+/**
+ * Reads the SVG content and adds accessibility attributes based on custom fields.
+ *
+ * @param File $file The file object representing the SVG.
+ * @param string $title The title for the SVG (optional).
+ * @param string $description The description for the SVG (optional).
+ * @param bool $isDecorative Whether the SVG is decorative (optional).
+ * @return string The modified SVG content with accessibility attributes.
+ */
+if (!function_exists('readAccessible')) {
+	function readAccessible(File $file, string $title = '', string $description = '', bool $isDecorative = false): string
+	{
+		if ($file->extension() !== 'svg') {
+			return $file->read();
+		}
+
+		$svgContent = $file->read();
+
+		// Try to get values from custom fields if not provided
+		if (empty($title) && $file->svgTitle()->isNotEmpty()) {
+			$title = $file->svgTitle()->value();
+		}
+
+		if (empty($description) && $file->svgDescription()->isNotEmpty()) {
+			$description = $file->svgDescription()->value();
+		}
+
+		// Check if marked as decorative in custom field
+		if ($file->svgDecorative()->toBool()) {
+			$isDecorative = true;
+		}
+
+		if ($isDecorative) {
+			$svgContent = str_replace(
+				'<svg',
+				'<svg aria-hidden="true"',
+				$svgContent
+			);
+		} else {
+			$uniqueId = uniqid('svg-');
+			$finalTitle = $title ?: $file->alt()->or($file->name())->value();
+
+			// aria-labelledby="uniqueTitleID uniqueDescID" (use the title and desc ID’s) – both title and description are included in aria-labelledby because it has better screen-reader support than aria-describedby (see tip #4)
+			$ariaAttributes = 'role="img" aria-labelledby="' . $uniqueId . '-title"';
+			if ($description) {
+				$ariaAttributes = 'role="img" aria-labelledby="' . $uniqueId . '-title ' . $uniqueId . '-desc"';
+			}
+
+			$svgContent = str_replace('<svg', '<svg ' . $ariaAttributes, $svgContent);
+
+			$titleElement = '<title id="' . $uniqueId . '-title">' . Html::encode($finalTitle) . '</title>';
+			$descElement = $description ? '<desc id="' . $uniqueId . '-desc">' . Html::encode($description) . '</desc>' : '';
+
+			$svgContent = preg_replace('/(<svg[^>]*>)/', '$1' . $titleElement . $descElement, $svgContent);
+		}
+
+		return $svgContent;
+	}
+}