From a7092212233668189db51c623198e42be1ccd3b2 Mon Sep 17 00:00:00 2001
From: crazywhalecc <jesse2061@outlook.com>
Date: Mon, 26 Jan 2026 00:43:57 +0800
Subject: [PATCH] Add skip helper function for calling events

---
 src/StaticPHP/DI/CallbackInvoker.php      |  8 +++++++-
 src/StaticPHP/Exception/SkipException.php |  7 +++++++
 src/globals/functions.php                 | 14 ++++++++++++++
 3 files changed, 28 insertions(+), 1 deletion(-)
 create mode 100644 src/StaticPHP/Exception/SkipException.php

diff --git a/src/StaticPHP/DI/CallbackInvoker.php b/src/StaticPHP/DI/CallbackInvoker.php
index 0d77f7aa..5b70d7b2 100644
--- a/src/StaticPHP/DI/CallbackInvoker.php
+++ b/src/StaticPHP/DI/CallbackInvoker.php
@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace StaticPHP\DI;
 
 use DI\Container;
+use StaticPHP\Exception\SkipException;
 use StaticPHP\Exception\SPCInternalException;
 
 /**
@@ -92,7 +93,12 @@ readonly class CallbackInvoker
             );
         }
 
-        return $callback(...$args);
+        try {
+            return $callback(...$args);
+        } catch (SkipException $e) {
+            logger()->debug("Skipped invocation: {$e->getMessage()}");
+            return null;
+        }
     }
 
     /**
diff --git a/src/StaticPHP/Exception/SkipException.php b/src/StaticPHP/Exception/SkipException.php
new file mode 100644
index 00000000..af25b6da
--- /dev/null
+++ b/src/StaticPHP/Exception/SkipException.php
@@ -0,0 +1,7 @@
+<?php
+
+declare(strict_types=1);
+
+namespace StaticPHP\Exception;
+
+class SkipException extends SPCException {}
diff --git a/src/globals/functions.php b/src/globals/functions.php
index bb22f3a7..e04bad5e 100644
--- a/src/globals/functions.php
+++ b/src/globals/functions.php
@@ -331,6 +331,20 @@ function spc_container(): DI\Container
     return \StaticPHP\DI\ApplicationContext::getContainer();
 }
 
+/**
+ * Skip the current operation if the condition is true.
+ * You should ALWAYS use this function inside an attribute callback.
+ *
+ * @param bool   $condition Condition to evaluate
+ * @param string $message   Optional message for the skip exception
+ */
+function spc_skip_if(bool $condition, string $message = ''): void
+{
+    if ($condition) {
+        throw new StaticPHP\Exception\SkipException($message);
+    }
+}
+
 /**
  * Parse extension list from string, replace alias and filter internal extensions.
  *