Merge pull request #1931 from brefphp/public-events-api

Mark the Bref events API as stable

Author: mnapoli

src/Bref.php

@@ -12,9 +12,7 @@ class Bref
 {
     private static ?Closure $containerProvider = null;
     private static ?ContainerInterface $container = null;
-    /**
-     * TODO deprecate hooks when the event dispatcher is stable.
-     */
+    /** @deprecated Use Bref::events()->subscribe() instead */
     private static array $hooks = [
         'beforeStartup' => [],
         'beforeInvoke' => [],
@@ -31,9 +29,6 @@ public static function setContainer(Closure $containerProvider): void
         self::$containerProvider = $containerProvider;
     }
 
-    /**
-     * @internal This API is experimental and may change at any time.
-     */
     public static function events(): EventDispatcher
     {
         if (! isset(self::$eventDispatcher)) {
@@ -48,6 +43,8 @@ public static function events(): EventDispatcher
      * Warning: hooks are low-level extension points to be used by framework
      * integrations. For user code, it is not recommended to use them. Use your
      * framework's extension points instead.
+     *
+     * @deprecated Use Bref::events()->subscribe() instead.
      */
     public static function beforeStartup(Closure $hook): void
     {
@@ -60,6 +57,8 @@ public static function beforeStartup(Closure $hook): void
      * Warning: hooks are low-level extension points to be used by framework
      * integrations. For user code, it is not recommended to use them. Use your
      * framework's extension points instead.
+     *
+     * @deprecated Use Bref::events()->subscribe() instead.
      */
     public static function beforeInvoke(Closure $hook): void
     {

src/Listener/BrefEventSubscriber.php

@@ -13,8 +13,6 @@
  * Warning: Bref events are low-level extension points to be used by framework
  * integrations. For user code, it is not recommended to use them. Use your
  * framework's extension points instead.
- *
- * @internal This API is experimental and may change at any time.
  */
 abstract class BrefEventSubscriber
 {

src/Listener/EventDispatcher.php

@@ -7,13 +7,12 @@
 use Bref\Event\Handler;
 use Psr\Http\Server\RequestHandlerInterface;
 
-/**
- * @internal This API is experimental and may change at any time.
- */
 final class EventDispatcher extends BrefEventSubscriber
 {
     /**
      * @param BrefEventSubscriber[] $subscribers
+     *
+     * @internal This method is called by Bref and should not be called by user code.
      */
     public function __construct(
         private array $subscribers = [],