Add support for image attachment

README.md

@@ -122,6 +122,7 @@ Method | Description
 `time($timestamp)` | Accepts either a `Carbon` object or a UNIX timestamp.
 `url($url[, $title])` | Accepts a string value for a [supplementary url](https://pushover.net/api#urls) and an optional string value for the title of the url.
 `sound($sound)` | Accepts a string value for the [notification sound](https://pushover.net/api#sounds).
+`image($image)` | Accepts a string value for the location of the image file. If there is any error with the file (too big, not an image) it will silently send the message without the image attachment.
 `priority($priority[, $retryTimeout, $expireAfter])` | Accepts an integer value for the priority and, when the priority is set to emergency, also an integer value for the retry timeout and expiry time (in seconds). Priority values are available as constants | `PushoverMessage::LOWEST_PRIORITY`, `PushoverMessage::LOW_PRIORITY`, `PushoverMessage::NORMAL_PRIORITY` and `PushoverMessage::EMERGENCY_PRIORITY`.
 `lowestPriority()` | Sets the priority to the lowest priority.
 `lowPriority()` | Sets the priority to low.

composer.json

@@ -12,6 +12,7 @@
         }
     ],
     "require": {
+        "ext-exif": "*",
         "php": ">=7.3",
         "guzzlehttp/guzzle": "^7.0.1",
         "illuminate/notifications": "^8.0",

src/Pushover.php

@@ -10,6 +10,13 @@
 
 class Pushover
 {
+    /**
+     * Maximum size of the image attachment in bytes accepted by the API (https://pushover.net/api#attachments).
+     *
+     * @var int
+     */
+    protected const IMAGE_SIZE_LIMIT = 2621440;
+
     /**
      * Location of the Pushover API.
      *
@@ -54,9 +61,29 @@ public function __construct(HttpClient $http, $token)
     public function send($params)
     {
         try {
-            return $this->http->post($this->pushoverApiUrl, [
-                'form_params' => $this->paramsWithToken($params),
-            ]);
+            $multipart = [];
+
+            foreach ($this->paramsWithToken($params) as $name => $contents) {
+                if ($name !== 'image') {
+                    $multipart[] = [
+                        'name'     => $name,
+                        'contents' => $contents,
+                    ];
+                } else {
+                    $image = $this->getImageData($contents);
+
+                    if ($image) {
+                        $multipart[] = $image;
+                    }
+                }
+            }
+
+            return $this->http->post(
+                $this->pushoverApiUrl,
+                [
+                    'multipart' => $multipart,
+                ]
+            );
         } catch (RequestException $exception) {
             if ($exception->getResponse()) {
                 throw CouldNotSendNotification::serviceRespondedWithAnError($exception->getResponse());
@@ -79,4 +106,46 @@ protected function paramsWithToken($params)
             'token' => $this->token,
         ], $params);
     }
+
+    /**
+     * Build the multipart array information for the attached image.
+     *
+     * If there is any error (problem with reading the file, file size exceeds the limit, the file is not an image),
+     * silently returns null and sends the message without image attachment.
+     *
+     * @param $file
+     * @return array|null
+     */
+    private function getImageData($file): ?array
+    {
+        try {
+            if (! is_file($file) || ! is_readable($file)) {
+                return null;
+            }
+
+            if (filesize($file) > self::IMAGE_SIZE_LIMIT) {
+                return null;
+            }
+
+            $imageType = exif_imagetype($file);
+            if ($imageType === false) {
+                return null;
+            }
+            $contentType = image_type_to_mime_type($imageType);
+
+            $contents = file_get_contents($file);
+        } catch (Exception $exception) {
+            return null;
+        }
+
+        return [
+            // name of the field holding the image must be 'attachment' (https://pushover.net/api#attachments)
+            'name'     => 'attachment',
+            'contents' => $contents,
+            'filename' => basename($file),
+            'headers'  => [
+                'Content-Type' => $contentType,
+            ],
+        ];
+    }
 }

src/PushoverMessage.php

@@ -81,6 +81,13 @@ class PushoverMessage
      */
     public $sound;
 
+    /**
+     * The (optional) location of an image file to be attached to the message.
+     *
+     * @var string
+     */
+    public $image;
+
     /**
      * Message formats.
      */
@@ -222,6 +229,19 @@ public function sound($sound)
         return $this;
     }
 
+    /**
+     * Set the image file location for attaching to the Pushover message.
+     *
+     * @param string $image
+     * @return $this
+     */
+    public function image($image)
+    {
+        $this->image = $image;
+
+        return $this;
+    }
+
     /**
      * Set the priority of the Pushover message.
      * Retry and expire are mandatory when setting the priority to emergency.
@@ -310,6 +330,7 @@ public function toArray()
             'url' => $this->url,
             'url_title' => $this->urlTitle,
             'sound' => $this->sound,
+            'image' => $this->image,
             'retry' => $this->retry,
             'expire' => $this->expire,
             'html' => $this->format === static::FORMAT_HTML,