initial commit

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = tab
+tab_width = 2
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false
+indent_style = space
+indent_size = 2
+
+[*.php]
+tab_width = 4

.gitattributes

@@ -0,0 +1,8 @@
+.gitattributes export-ignore
+.gitignore export-ignore
+.editorconfig export-ignore
+composer.lock export-ignore
+.php-cs-fixer.php export-ignore
+
+.cache/ export-ignore
+.github/ export-ignore

.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+*.cache
+composer.lock
+/vendor

.php-cs-fixer.php

@@ -0,0 +1,77 @@
+<?php
+
+	$finder = PhpCsFixer\Finder::create()
+		->exclude('vendor')
+		->ignoreDotFiles(true)
+		->in(__DIR__);
+
+	$config = new PhpCsFixer\Config();
+	return $config
+		->setUsingCache(true)
+		->setCacheFile(__DIR__ . '/.cache/.php-cs-fixer.cache')
+		->setRules([
+			'@PSR12' => true,
+			'align_multiline_comment' => ['comment_type' => 'phpdocs_only'],
+			'array_indentation' => true,
+			'array_syntax' => ['syntax' => 'short'],
+			'assign_null_coalescing_to_coalesce_equal' => true,
+			'blank_line_after_opening_tag' => true,
+			'cast_spaces' => ['space' => 'none'],
+			'combine_consecutive_issets' => true,
+			'combine_consecutive_unsets' => true,
+			'combine_nested_dirname' => true,
+			'concat_space' => ['spacing' => 'one'],
+			'declare_equal_normalize' => ['space' => 'single'],
+			'dir_constant' => true,
+			'explicit_string_variable' => true,
+			'full_opening_tag' => true,
+			'function_declaration' => ['closure_function_spacing' => 'one', 'closure_fn_spacing' => 'one'],
+			'function_typehint_space' => true,
+			'include' => true,
+			'logical_operators' => true,
+			'magic_constant_casing' => true,
+			'magic_method_casing' => true,
+			'method_chaining_indentation' => true,
+			'modernize_types_casting' => true,
+			'multiline_comment_opening_closing' => true,
+			'native_function_casing' => true,
+			'native_function_type_declaration_casing' => true,
+			'new_with_braces' => true,
+			'no_blank_lines_after_phpdoc' => true,
+			'no_empty_comment' => true,
+			'no_empty_phpdoc' => true,
+			'no_empty_statement' => true,
+			'no_leading_namespace_whitespace' => true,
+			'no_mixed_echo_print' => ['use' => 'echo'],
+			'no_short_bool_cast' => true,
+			'no_superfluous_elseif' => true,
+			'no_superfluous_phpdoc_tags' => ['allow_unused_params' => true],
+			'no_unneeded_braces' => true,
+			'no_unneeded_control_parentheses' => true,
+			'no_unneeded_import_alias' => true,
+			'no_unused_imports' => true,
+			'no_useless_else' => true,
+			'no_useless_nullsafe_operator' => true,
+			'no_useless_return' => true,
+			'no_whitespace_before_comma_in_array' => true,
+			'nullable_type_declaration_for_default_null_value' => true,
+			'nullable_type_declaration' => ['syntax' => 'union'],
+			'object_operator_without_whitespace' => true,
+			'operator_linebreak' => ['position' => 'end', 'only_booleans' => true],
+			'ordered_imports' => ['sort_algorithm' => 'alpha'],
+			'ordered_types' => ['sort_algorithm' => 'none', 'null_adjustment' => 'always_last'],
+			'phpdoc_align' => ['align' => 'left'],
+			'phpdoc_indent' => true,
+			'phpdoc_param_order' => true,
+			'phpdoc_scalar' => true,
+			'phpdoc_trim' => true,
+			'single_line_comment_style' => true,
+			'single_quote' => true,
+			'statement_indentation' => ['stick_comment_to_next_continuous_control_statement' => true],
+			'ternary_to_null_coalescing' => true,
+			'trim_array_spaces' => true,
+			'whitespace_after_comma_in_array' => true
+		])
+		->setRiskyAllowed(true)
+		->setIndent("\t")
+		->setFinder($finder);

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Tim Narr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,33 @@
+# Kirby Helpers
+
+Kirby Helpers is a collection of useful helper functions for Kirby CMS.
+
+## Installation via Composer
+To install Kirby Helpers via Composer, run the following command:
+
+```bash
+composer require timnarr/kirby-helpers
+```
+
+## Options
+The following options are available for customization:
+
+| Option | Default | Type | Description |
+| ------ | ------- | ---- | ----------- |
+| `vite.manifestPath` | `kirby()->root() . '/build/manifest.json'` | string | Path to vites manifest file to determine dev mode. Used by `isViteDevMode()` |
+
+## Translations
+Translations are required for the labels returned by the `linkLabel()` function. This plugin provides translations for English and German. The following translation keys are available for customization:
+
+| Key | Default |
+| --- | ------- |
+| `link_label_internal_home` | `Link to homepage: { title }` |
+| `link_label_internal` | `Link to page: { title }` |
+| `link_label_document` | `Download file: { filename }` |
+| `link_label_external` | `External link: { url } (Opens new tab)` |
+| `link_label_mail` | `Send email to: { mail } (Opens new window of your email program)` |
+| `link_label_tel` | `Call phone number: { tel } (Opens new window/program)` |
+
+
+## License
+Kirby Helpers is licensed under the [MIT License](./LICENSE). © 2024-present Tim Narr

composer.json

@@ -0,0 +1,45 @@
+{
+	"name": "timnarr/kirby-helpers",
+	"description": "This plugin provides a collection of helper functions for Kirby",
+	"type": "kirby-plugin",
+	"version": "0.1.0",
+	"license": "MIT",
+	"homepage": "https://github.com/timnarr/kirby-helpers",
+	"authors": [
+		{
+			"name": "Tim Narr",
+			"email": "[email protected]",
+			"homepage": "https://tim-narr.com"
+		}
+	],
+	"require": {
+		"php": "^8.2",
+		"getkirby/composer-installer": "^1.2"
+	},
+	"require-dev": {
+		"friendsofphp/php-cs-fixer": "^3",
+		"getkirby/cms": "^4.0"
+
+	},
+	"scripts": {
+		"lint": ["php-cs-fixer fix --dry-run --diff"],
+		"lint:fix": ["php-cs-fixer fix"]
+	},
+	"autoload": {
+		"files": [
+			"src/css.php",
+			"src/ensure.php",
+			"src/misc.php",
+			"src/vite.php"
+		]
+	},
+	"config": {
+		"optimize-autoloader": true,
+		"allow-plugins": {
+			"getkirby/composer-installer": true
+		}
+	},
+	"extra": {
+		"kirby-cms-path": false
+	}
+}

index.php

@@ -0,0 +1,27 @@
+<?php
+
+Kirby::plugin('timnarr/kirby-helpers', [
+	'options' => [
+		'vite' => [
+			'manifestPath' => kirby()->root() . '/build/manifest.json',
+		]
+	],
+	'translations' => [
+		'en' => [
+			'link_label_internal_home' => 'Link to homepage: { title }',
+			'link_label_internal' => 'Link to page: { title }',
+			'link_label_document' => 'Download file: { filename }',
+			'link_label_external' => 'External link: { url } (Opens new tab)',
+			'link_label_mail' => 'Send email to: { mail } (Opens new window of your email program)',
+			'link_label_tel' => 'Call phone number: { tel } (Opens new window/program)',
+		],
+		'de' => [
+			'link_label_internal_home' => 'Link zur Startseite: { title }',
+			'link_label_internal' => 'Link zur Seite: { title }',
+			'link_label_document' => 'Datei herunterladen: { filename }',
+			'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/css.php

@@ -0,0 +1,83 @@
+<?php
+
+use Kirby\Cms\Html;
+
+/**
+ * Load a CSS file lazily.
+ *
+ * @param string $file The CSS file path.
+ * @param bool $omitNoscript Optional. If true, omit the noscript fallback.
+ *
+ * @example
+ * cssLazy('assets/css/carousel.css', true);
+ *
+ * @example with vite
+ * cssLazy(vite()->asset('styles/carousel.scss'), true);
+ */
+if (!function_exists('cssLazy')) {
+	function cssLazy(string $file, bool $omitNoscript = false): void
+	{
+		echo Html::css($file, [
+			'as' => 'style',
+			'rel' => 'preload',
+			'fetchpriority' => 'low',
+			'onload' => "this.onload=null;this.rel='stylesheet'",
+		]);
+
+		if (!$omitNoscript) {
+			echo '<noscript>' . Html::css($file) . '</noscript>';
+		}
+	}
+}
+
+
+/**
+ * Load CSS file only if a defined block is used.
+ *
+ * @param string $file The CSS file path.
+ * @param string $blockType The block type to check.
+ * @param array $usedBlockTypes The array of used block types.
+ * @param bool $lazy Optional. If true, load the CSS file lazily.
+ *
+ * @example
+ * cssIfBlock('assets/css/carousel.css', 'carousel', $pageBlocks, true);
+ *
+ * @example with vite
+ * cssIfBlock(vite()->asset('styles/carousel.scss'), 'carousel', $pageBlocks, true);
+ */
+if (!function_exists('cssIfBlock')) {
+	function cssIfBlock(string $file, string $blockType, array $usedBlockTypes, bool $lazy = false): void
+	{
+		if (in_array($blockType, $usedBlockTypes)) {
+			if ($lazy) {
+				cssLazy($file);
+			} else {
+				Html::css($file);
+			}
+		}
+	}
+}
+
+
+/**
+ * Load a CSS file only for a defined page template or an array of templates.
+ *
+ * @param string $file The CSS file path.
+ * @param string|array $template The page template name or an array of template names.
+ * @param bool $lazy Optional. If true, load the CSS file lazily.
+ */
+if (!function_exists('cssIfTemplate')) {
+	function cssIfTemplate(string $file, string|array $template, bool $lazy = false): void
+	{
+		$templates = (array)$template;
+		$currentTemplate = page()->template();
+
+		if (in_array($currentTemplate, $templates, true)) {
+			if ($lazy) {
+				cssLazy($file);
+			} else {
+				Html::css($file);
+			}
+		}
+	}
+}

src/ensure.php

@@ -0,0 +1,45 @@
+<?php
+
+/**
+ * Ensure that a string starts with the specified prefix.
+ *
+ * @param string $string The input string.
+ * @param string $prefix The prefix to ensure.
+ * @return string The string starting with the prefix.
+ */
+if (!function_exists('ensureLeft')) {
+	function ensureLeft(string $string, string $prefix): string
+	{
+		return str_starts_with($string, $prefix) ? $string : $prefix . $string;
+	}
+}
+
+
+/**
+ * Ensure that a string ends with the specified suffix.
+ *
+ * @param string $string The input string.
+ * @param string $suffix The suffix to ensure.
+ * @return string The string ending with the suffix.
+ */
+if (!function_exists('ensureRight')) {
+	function ensureRight(string $string, string $suffix): string
+	{
+		return str_ends_with($string, $suffix) ? $string : $string . $suffix;
+	}
+}
+
+
+/**
+ * Ensure that a string starts with a hash character (#).
+ * Mainly used to ensure jump-to ids start with a #.
+ *
+ * @param string $string The input string.
+ * @return string The string starting with a hash.
+ */
+if (!function_exists('ensureHashed')) {
+	function ensureHashed(string $string): string
+	{
+		return ensureLeft($string, '#');
+	}
+}