Merge pull request #593 from rollbar/4.0/updated-transformer-interface

Updated the `TransformerInterface`

src/Config.php

@@ -795,7 +795,7 @@ public function transform(
         Level|string $level,
         mixed $toLog,
         array $context = array ()
-    ): ?Payload {
+    ): Payload {
         if (count($this->custom) > 0) {
             $this->verboseLogger()->debug("Adding custom data to the payload.");
             $data = $payload->getData();

src/RollbarLogger.php

@@ -370,14 +370,14 @@ protected function send(EncodedPayload $payload, string $accessToken): Response
      * @param string|Stringable $toLog       The message or error to be sent to Rollbar.
      * @param array             $context     Additional data to send with the message.
      *
-     * @return Payload|null
+     * @return Payload
      */
     protected function getPayload(
         string $accessToken,
         string $level,
         string|Stringable $toLog,
         array $context,
-    ): ?Payload {
+    ): Payload {
         $data    = $this->config->getRollbarData($level, $toLog, $context);
         $payload = new Payload($data, $accessToken);
         return $this->config->transform($payload, $level, $toLog, $context);

src/TransformerInterface.php

@@ -4,14 +4,37 @@
 
 use Rollbar\Payload\Level;
 use Rollbar\Payload\Payload;
-use Throwable;
 
+/**
+ * The scrubber interface allows changes to be made to the error or log {@see Payload} before it is checked to see if
+ * it will be ignored, is serialized, scrubbed of PII or many other processes. The transform method is executed
+ * directly after the payload is created.
+ *
+ * Note: transforms are only applied to payloads that were created through calling one of the {@see Rollbar} or
+ * {@see RollbarLogger} logging methods or for errors and exceptions that where caught by Rollbar.
+ *
+ * An optional constructor can be included in the implementing class. The constructor should accept a single array
+ * argument. The value of the argument will be the value of `transformerOptions` from the configs array, or an empty
+ * array if `transformerOptions` does not exist.
+ */
 interface TransformerInterface
 {
+    /**
+     * The transform method allows changes to be made to a {@see Payload} just after it is created and before it is
+     * passed to anything else in the standard logging and error catching process.
+     *
+     * @param Payload      $payload The payload that has just been created.
+     * @param Level|string $level   The severity of the log message or error.
+     * @param mixed        $toLog   The error or message that is being logged.
+     * @param array        $context Additional context data that may be sent with the message. In accordance with
+     *                              PSR-3 an exception may be in $context['exception'] not $toLog.
+     *
+     * @return Payload
+     */
     public function transform(
         Payload $payload,
         Level|string $level,
         mixed $toLog,
-        array $context = array ()
-    ): ?Payload;
+        array $context = array()
+    ): Payload;
 }

tests/TestHelpers/MalformedPayloadDataTransformer.php

@@ -3,15 +3,16 @@
 use Rollbar\Payload\Level;
 use Rollbar\Payload\Payload;
 use Rollbar\Payload\Data;
+use Rollbar\TransformerInterface;
 
-class MalformedPayloadDataTransformer implements \Rollbar\TransformerInterface
+class MalformedPayloadDataTransformer implements TransformerInterface
 {
     public function transform(
         Payload $payload,
         Level|string $level,
         mixed $toLog,
         array $context = array()
-    ): ?Payload {
+    ): Payload {
         $mock = \Mockery::mock(Data::class)->makePartial();
         $mock->shouldReceive("serialize")->andReturn(array());
         $mock->setLevel(\Rollbar\LevelFactory::fromName($level));