Add Image aspect ratio helper (#51)

* Add image_aspect_ratio to generic template [square]

* Add image_aspect_ratio param

* Add ImageAspectRatio Enum

* Add description of imageAspectRatio to README

* Fix styling

Author: dostrog

README.md

@@ -165,6 +165,7 @@ public function routeNotificationForFacebook()
 - `buttons($buttons = [])`: (array) An array of "Call to Action" buttons (Created using `NotificationChannels\Facebook\Components\Button::create()`). You can add up to 3 buttons of one of the following types: `web_url`, `postback` or `phone_number`. See Button methods below for more details.
 - `cards($cards = [])`: (array) An array of item cards to be displayed in a carousel (Created using `NotificationChannels\Facebook\Components\Card::create()`). You can add up to 10 cards. See Card methods below for more details.
 - `notificationType('')`: (string) Push Notification type: `REGULAR` will emit a sound/vibration and a phone notification; `SILENT_PUSH` will just emit a phone notification, `NO_PUSH` will not emit either. You can make use of `NotificationType::REGULAR`, `NotificationType::SILENT_PUSH` and `NotificationType::NO_PUSH` to make it easier to work with the type. This is an optional method, defaults to `REGULAR` type.
+- `imageAspectRatio('')`: (string) Image Aspect Ratio if Card with `image_url` present. You can use of `ImageAspectRatioType::SQUARE` or  `ImageAspectRatioType::HORIZONTAL`. This is an optional method, defaults to `ImageAspectRatioType::HORIZONTAL` aspect ratio (image should be 1.91:1).
 - `isTypeRegular()`: Helper method to create a notification type: `REGULAR`.
 - `isTypeSilentPush()`: Helper method to create a notification type: `SILENT_PUSH`.
 - `isTypeNoPush()`: Helper method to create a notification type: `NO_PUSH`.

src/Components/Card.php

@@ -79,7 +79,7 @@ public function url(string $itemUrl): self
     /**
      * Set Card Image Url.
      *
-     * @param  string  $imageUrl  Image ratio should be 1.91:1
+     * @param  string  $imageUrl  Default image ratio is 1.91:1
      *
      * @return $this
      */

src/Enums/ImageAspectRatioType.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace NotificationChannels\Facebook\Enums;
+
+/**
+ * Class ImageAspectRatioType.
+ *
+ * The aspect ratio used to render images specified by element.image_url
+ *
+ * @see https://developers.facebook.com/docs/messenger-platform/reference/templates/generic#payload
+ */
+class ImageAspectRatioType
+{
+    /**
+     * Aspect ratio of image should be 1.91:1.
+     */
+    public const HORIZONTAL = 'horizontal';
+    /**
+     * Aspect ratio of image should be 1:1.
+     */
+    public const SQUARE = 'square';
+}

src/Exceptions/CouldNotCreateMessage.php

@@ -19,6 +19,16 @@ public static function textTooLong(): self
         return new static('Message text is too long, A 320 character limited string should be provided.');
     }
 
+    /**
+     * Thrown when invalid image aspect ratio provided.
+     *
+     * @return static
+     */
+    public static function invalidImageAspectRatio(): self
+    {
+        return new static('Image Aspect Ratio provided is invalid.');
+    }
+
     /**
      * Thrown when invalid notification type provided.
      *

src/FacebookMessage.php

@@ -4,6 +4,7 @@
 
 use JsonSerializable;
 use NotificationChannels\Facebook\Enums\AttachmentType;
+use NotificationChannels\Facebook\Enums\ImageAspectRatioType;
 use NotificationChannels\Facebook\Enums\MessagingType;
 use NotificationChannels\Facebook\Enums\NotificationType;
 use NotificationChannels\Facebook\Enums\RecipientType;
@@ -47,9 +48,15 @@ class FacebookMessage implements JsonSerializable
     /** @var bool */
     protected $hasText = false;
 
+    /** @var bool There is card with 'image_url' in attachment */
+    protected $hasImageUrl = false;
+
     /** @var string Message tag used with messaging type MESSAGE_TAG */
     protected $messageTag;
 
+    /** @var string The aspect ratio for */
+    protected $imageAspectRatio = ImageAspectRatioType::HORIZONTAL;
+
     /**
      * @param  string  $text
      *
@@ -177,6 +184,33 @@ public function notificationType(string $notificationType): self
         return $this;
     }
 
+    public function imageAspectRatio(string $imageAspectRatio): self
+    {
+        $imageAspectRatios = [
+            ImageAspectRatioType::SQUARE,
+            ImageAspectRatioType::HORIZONTAL,
+        ];
+
+        if (! in_array($imageAspectRatio, $imageAspectRatios, false)) {
+            throw CouldNotCreateMessage::invalidImageAspectRatio();
+        }
+
+        foreach ($this->cards as $card) {
+            if (array_key_exists('image_url', $card->toArray())) {
+                $this->hasImageUrl = true;
+                break;
+            }
+        }
+
+        if (! $this->hasImageUrl) {
+            return $this;
+        }
+
+        $this->imageAspectRatio = $imageAspectRatio;
+
+        return $this;
+    }
+
     /**
      * Helper to set notification type as REGULAR.
      *
@@ -376,6 +410,10 @@ protected function genericMessageToArray(): array
         $message['message']['attachment']['payload']['elements'] = $this->cards;
         $message['messaging_type'] = $this->messagingType;
 
+        if ($this->hasImageUrl) {
+            $message['message']['attachment']['payload']['image_aspect_ratio'] = $this->imageAspectRatio;
+        }
+
         if (filled($this->messageTag)) {
             $message['tag'] = $this->messageTag;
         }