Added option to prevent a snippet from rendering

Author: lukaskleinschmidt

PreventSnippetException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace LukasKleinschmidt;
+
+use Exception;
+
+class PreventSnippetException extends Exception
+{
+    //
+}

README.md

@@ -97,6 +97,25 @@ return function (Field|string $size = null) {
 };
 ```
 
+> **Note**
+> Since version [`2.2.0`](https://github.com/lukaskleinschmidt/kirby-snippet-controller/releases/tag/2.2.0) you can prevent a snippet from rendering in a controller callback.
+
+```php
+snippet('header', data: ['size' => $page->size()])
+
+// header.controller.php
+
+return function (Field|string $size = null) {
+    if (is_null($size)) {
+        snippet_prevent();
+    }
+
+    return [
+        'size' => $size,
+    ];
+};
+```
+
 ### Naming convention
 By default, the plugin searches for controllers by appending `.controller` to the snippet name.
 You can change the name resolver in the options. Changing the name also affects plugin-defined controllers.

composer.json

@@ -10,6 +10,7 @@
 		}
 	],
 	"require": {
+        "php": "^8.1",
 		"getkirby/composer-installer": "^1.2"
 	},
 	"config": {

helpers.php

@@ -4,8 +4,12 @@
 use Kirby\Filesystem\F;
 use Kirby\Toolkit\A;
 use Kirby\Toolkit\Controller;
+use LukasKleinschmidt\PreventSnippetException;
 
 if (! function_exists('snippet_controller_value')) {
+    /**
+     * Returns the snippet controller value.
+     */
     function snippet_controller_value(string|array $name): mixed
     {
         $kirby = App::instance();
@@ -30,6 +34,9 @@ function snippet_controller_value(string|array $name): mixed
 }
 
 if (! function_exists('snippet_controller')) {
+    /**
+     * Aggregates snippet data.
+     */
     function snippet_controller(string|array $name, array $data = []): array
     {
         if (is_null($value = snippet_controller_value($name))) {
@@ -51,3 +58,16 @@ function snippet_controller(string|array $name, array $data = []): array
         return is_array($value) ? array_merge($data, $value) : $data;
     }
 }
+
+if (! function_exists('snippet_prevent')) {
+    /**
+     * Prevent a snippet from rendering.
+     * Should only be used in snippet controller callbacks.
+     *
+     * @throws \LukasKleinschmidt\PreventSnippetException
+     */
+    function snippet_prevent(): never
+    {
+        throw new PreventSnippetException;
+    }
+}

index.php

@@ -1,16 +1,24 @@
 <?php
 
 use Kirby\Cms\App;
+use Kirby\Template\Snippet;
+use LukasKleinschmidt\PreventSnippetException;
 
 @include_once __DIR__ . '/helpers.php';
+@include_once __DIR__ . '/PreventSnippetException.php';
 
 App::plugin('lukaskleinschmidt/snippet-controller', [
     'options' => [
         'name' => fn (string $name) => $name . '.controller',
     ],
     'components' => [
-        'snippet' => function (App $kirby, $name, array $data = [], bool $slots = false) {
-            $data = snippet_controller($name, $data);
+        'snippet' => function (App $kirby, $name, array $data = [], bool $slots = false): Snippet|string
+        {
+            try {
+                $data = snippet_controller($name, $data);
+            } catch (PreventSnippetException) {
+                return '';
+            }
 
             return $kirby->nativeComponent('snippet')(
                 $kirby,