Improvements to Base and WIP listeners

Dogfooding helps.

Author: jeremeamia

composer.lock

@@ -122,8 +122,8 @@ public function withAppConfig(AppConfig $config): self
     /**
      * Sets the callback function for acks.
      *
-     * This does is not needed for all server implementations, but it is, it Should be set by the Server implementation,
-     * and should not be explicitly provided.
+     * This is not needed for all server implementations, but if it is, it should be set by the Server implementation,
+     * and should not be explicitly provided otherwise.
      *
      * @param callable $callback
      * @return $this

src/Context.php

@@ -12,7 +12,7 @@
  * If a sync listener is not provided, then it defaults to an "ack". Either way, defer() is automatically used so that
  * the primary (async) listener will be established correctly for post-"ack" execution.
  */
-class Async implements Listener
+class Async extends Base
 {
     private Listener $asyncListener;
     private ?Listener $syncListener;
@@ -27,13 +27,13 @@ public function __construct(Listener $asyncListener, ?Listener $syncListener = n
         $this->syncListener = $syncListener ?? new Ack();
     }
 
-    public function handle(Context $context): void
+    protected function handleAck(Context $context): void
     {
-        if ($context->isAcknowledged()) {
-            $this->asyncListener->handle($context);
-        } else {
-            $this->syncListener->handle($context);
-            $context->defer();
-        }
+        $this->syncListener->handle($context);
+    }
+
+    protected function handleAfterAck(Context $context): void
+    {
+        $this->asyncListener->handle($context);
     }
 }

src/Listeners/Async.php

@@ -7,44 +7,50 @@
 use SlackPhp\Framework\{Context, Listener};
 
 /**
- * Base class for listener classes that may have both sync (pre-ack) and async (post-ack) logic.
+ * Base class for listener classes that may have both sync (pre-"ack") and async (post-"ack") logic.
  *
- * Note: Does not automatically defer. This allows flexibility to decide if deferring is needed. In many cases, the
- *       logic that happens prior to the ack represents a complete handling of the event. If additional logic must be
- *       performed after the ack, then $context->defer() should be called in the handleAck() method implementation.
+ * By default, the context is set to defer, so that post-ack logic will be executed. In some cases, a complete handling
+ * of an event can be done prior to the ack. In that case, the `handleAck()` method can call `$content->defer(false);`.
  */
 abstract class Base implements Listener
 {
     public function handle(Context $context): void
     {
+        // Handle async logic, if executed post-ack.
         if ($context->isAcknowledged()) {
             $this->handleAfterAck($context);
-        } else {
-            $this->handleAck($context);
+            return;
+        }
+
+        // Handle sync logic, if executed pre-ack.
+        $context->defer(true);
+        $this->handleAck($context);
+        if (!$context->isAcknowledged()) {
+            $context->ack();
         }
     }
 
     /**
      * Handles application logic that must be preformed prior to the "ack" and Slack's 3-second timeout.
      *
-     * By default, this does an ack. You should override this method with your own implementation to do more.
+     * By default, this does nothing. You should override this method with your own implementation.
      *
      * @param Context $context
      */
     protected function handleAck(Context $context): void
     {
-        $context->ack();
+        // No-op. Override as needed.
     }
 
     /**
      * Handles application logic that can or must happen after the "ack" and is not subject to Slack's 3-second timeout.
      *
-     * By default, this does nothing. You should override this method with your own implementation if you use defer().
+     * By default, this does nothing. You should override this method with your own implementation.
      *
      * @param Context $context
      */
     protected function handleAfterAck(Context $context): void
     {
-        // No-op.
+        // No-op. Override as needed.
     }
 }