Merge pull request #677 from defstudio/#310-venue

#310 venue  Implemented SendVenue Method and Venue DTO

docs/12.features/7.attachments.md

@@ -154,6 +154,14 @@ Telegraph::sticker($telegramFileId)->send();
 
 Where `$telegramFileId` is file_id from telegram sticker set. File_id can obtain from Telegram Raw Bot (@RawDataBot). Just simply send a sticker to bot and you receive json data in answer. The required value is contained in 'message > sticker > file_id'.
 
+### Venue
+
+Venue can be sent through Telegraph `->venue()` method:
+
+```php
+Telegraph::venue(10, 10, 'title', 'address')->send();
+```
+
 ## Options
 
 When sending files, some options are available:

docs/12.features/9.dto.md

@@ -43,6 +43,7 @@ contains incoming data (a message or a callback query)
 - `->contact()` (optional) an instance of [`Contact`](#contact) holding data about the contained contact data
 - `->voice()` (optional) an instance of [`Voice`](#voice) holding data about the contained voical message
 - `->sticker()` (optional) an instance of [`Sticker`](#sticker) holding data about the contained sticker
+- `->venue()` (optional) an instance of [`Venue`](#venue) holding data about the contained sticker
 - `->entities()` (optional) a collection of [`Entity`](#entity) holding data about the contained entity
 - `->newChatMembers()` a collection of [`User`](#user) holding the list of users that joined the group/supergroup
 - `->leftChatMember()` (optional) an instance of [`User`](#user) holding data about the user that left the group/supergroup
@@ -166,6 +167,16 @@ contains incoming data (a message or a callback query)
 - `->filesize()` (optional) sticker file size in Bytes
 - `->thumbnail()` (optional) an instance of the [`Photo`](#photo) that holds data about the thumbnail
 
+## `Venue`
+
+- `->location()` Venue location. Can't be a live location
+- `->title()` Name of the venue
+- `->address()` Address of the venue
+- `->foursquareId()` (optional) Foursquare identifier of the venue
+- `->foursquareType()` (optional) Foursquare type of the venue
+- `->googlePlaceId()` 	(optional) Google Places identifier of the venue
+- `->googlePlaceType()` (optional) Google Places type of the venue (consult https://developers.google.com/maps/documentation/places/web-service/supported_types)
+
 ## `Entity`
 
 - `->type()` type of the entity

docs/14.models/2.telegraph-chat.md

@@ -678,6 +678,15 @@ A sticker attachment can be sent through Telegraph `->sticker()` method:
 $telegraphChat->sticker()->send();
 ```
 
+### `venue`
+
+A Venue attachment can be sent through Telegraph `->venue()` method:
+
+```php
+/** @var DefStudio\Telegraph\Models\TelegraphChat $telegraphChat */
+$telegraphChat->venue(10, 10, 'title', 'address')->send();
+```
+
 ### `media group`
 
 Group of photos, videos, documents or audios as an album can be sent through Telegraph `->mediaGroup()` method:

src/Concerns/SendsAttachments.php

@@ -317,6 +317,21 @@ public function sticker(string $path, ?string $filename = null): self
         return $telegraph;
     }
 
+    public function venue(float $latitude, float $longitude, string $title, string $address): self
+    {
+        $telegraph = clone $this;
+
+        $telegraph->endpoint = self::ENDPOINT_SEND_VENUE;
+        $telegraph->data['chat_id'] = $telegraph->getChatId();
+
+        $telegraph->data['latitude'] = $latitude;
+        $telegraph->data['longitude'] = $longitude;
+        $telegraph->data['title'] = $title;
+        $telegraph->data['address'] = $address;
+
+        return $telegraph;
+    }
+
     protected function attachPhoto(self $telegraph, string $path, ?string $filename): void
     {
         if (File::exists($path)) {

src/DTO/Message.php

@@ -50,6 +50,7 @@ class Message implements Arrayable
     private ?Contact $contact = null;
     private ?Voice $voice = null;
     private ?Sticker $sticker = null;
+    private ?Venue $venue = null;
 
     private ?WriteAccessAllowed $writeAccessAllowed = null;
 
@@ -84,6 +85,7 @@ private function __construct()
      *     video?: array<string, mixed>,
      *     photo?: array<string, mixed>,
      *     location?: array<string, mixed>,
+     *     venue?: array<string, mixed>,
      *     contact?: array<string, mixed>,
      *     new_chat_members?: array<string, mixed>,
      *     left_chat_member?: array<string, mixed>,
@@ -183,6 +185,11 @@ public static function fromArray(array $data): Message
             $message->sticker = Sticker::fromArray($data['sticker']);
         }
 
+        if (isset($data['venue'])) {
+            /* @phpstan-ignore-next-line */
+            $message->venue = Venue::fromArray($data['venue']);
+        }
+
         /* @phpstan-ignore-next-line */
         $message->newChatMembers = collect($data['new_chat_members'] ?? [])->map(fn (array $userData) => User::fromArray($userData));
 
@@ -318,6 +325,11 @@ public function sticker(): ?Sticker
         return $this->sticker;
     }
 
+    public function venue(): ?Venue
+    {
+        return $this->venue;
+    }
+
     /**
      * @return Collection<array-key, User>
      */
@@ -372,6 +384,7 @@ public function toArray(): array
             'contact' => $this->contact?->toArray(),
             'voice' => $this->voice?->toArray(),
             'sticker' => $this->sticker?->toArray(),
+            'venue' => $this->venue?->toArray(),
             'new_chat_members' => $this->newChatMembers->toArray(),
             'left_chat_member' => $this->leftChatMember,
             'web_app_data' => $this->webAppData,

src/DTO/Venue.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace DefStudio\Telegraph\DTO;
+
+use Illuminate\Contracts\Support\Arrayable;
+
+/**
+ * @implements Arrayable<string, float>
+ */
+class Venue implements Arrayable
+{
+    private Location $location;
+    private string $title;
+    private string $address;
+    private ?string $foursquareId = null;
+    private ?string $foursquareType = null;
+    private ?string $googlePlaceId = null;
+    private ?string $googlePlaceType = null;
+
+    private function __construct()
+    {
+    }
+
+    /**
+     * @param array{
+     *     location: array{longitude: float, latitude: float, horizontal_accuracy?: float},
+     *     title: string,
+     *     address: string,
+     *     foursquare_id?: string,
+     *     foursquare_type?: string,
+     *     google_place_id?: string,
+     *     google_place_type?: string
+     * } $data
+     */
+    public static function fromArray(array $data): Venue
+    {
+        $venue = new self();
+
+        $venue->location = Location::fromArray($data['location']);
+        $venue->title = $data['title'];
+        $venue->address = $data['address'];
+        $venue->foursquareId = $data['foursquare_id'] ?? null;
+        $venue->foursquareType = $data['foursquare_type'] ?? null;
+        $venue->googlePlaceId = $data['google_place_id'] ?? null;
+        $venue->googlePlaceType = $data['google_place_type'] ?? null;
+
+        return $venue;
+    }
+
+    public function location(): Location
+    {
+        return $this->location;
+    }
+
+    public function title(): string
+    {
+        return $this->title;
+    }
+
+    public function address(): string
+    {
+        return $this->address;
+    }
+
+    public function foursquareId(): ?string
+    {
+        return $this->foursquareId;
+    }
+
+    public function foursquareType(): ?string
+    {
+        return $this->foursquareType;
+    }
+
+    public function googlePlaceId(): ?string
+    {
+        return $this->googlePlaceId;
+    }
+
+    public function googlePlaceType(): ?string
+    {
+        return $this->googlePlaceType;
+    }
+
+    public function toArray(): array
+    {
+        return array_filter([
+            'location' => $this->location,
+            'title' => $this->title,
+            'address' => $this->address,
+            'foursquare_id' => $this->foursquareId,
+            'foursquare_type' => $this->foursquareType,
+            'google_place_id' => $this->googlePlaceId,
+            'google_place_type' => $this->googlePlaceType,
+        ], fn ($value) => $value !== null);
+    }
+}

src/Models/TelegraphChat.php

@@ -247,6 +247,11 @@ public function sticker(string $path, string $filename = null): Telegraph
         return TelegraphFacade::chat($this)->sticker($path, $filename);
     }
 
+    public function venue(float $latitude, float $longitude, string $title, string $address): Telegraph
+    {
+        return TelegraphFacade::chat($this)->venue($latitude,  $longitude,  $title,  $address);
+    }
+
     public function animation(string $path, string $filename = null): Telegraph
     {
         return TelegraphFacade::chat($this)->animation($path, $filename);

src/Telegraph.php

@@ -112,6 +112,8 @@ class Telegraph
     public const ENDPOINT_GET_CHAT_MENU_BUTTON = 'getChatMenuButton';
     public const ENDPOINT_DICE = 'sendDice';
     public const ENDPOINT_SEND_STICKER = 'sendSticker';
+    public const ENDPOINT_SEND_VENUE = 'sendVenue';
+
     public const ENDPOINT_APPROVE_CHAT_JOIN_REQUEST = 'approveChatJoinRequest';
     public const ENDPOINT_DECLINE_CHAT_JOIN_REQUEST = 'declineChatJoinRequest';
 

tests/.pest/snapshots/Unit/Concerns/SendsAttachmentsTest/it_can_send_a_venue_message.snap

@@ -0,0 +1,11 @@
+{
+    "url": "https:\/\/api.telegram.org\/bot3f3814e1-5836-3d77-904e-60f64b15df36\/sendVenue",
+    "payload": {
+        "chat_id": "-123456789",
+        "latitude": 12.345,
+        "longitude": -54.321,
+        "title": "title",
+        "address": "address"
+    },
+    "files": []
+}

tests/Unit/Concerns/SendsAttachmentsTest.php

@@ -276,6 +276,11 @@
         ->toMatchTelegramSnapshot();
 });
 
+it('can send a venue message', function () {
+    expect(fn (Telegraph $telegraph) => $telegraph->venue(12.345, -54.321, 'title', 'address'))
+        ->toMatchTelegramSnapshot();
+});
+
 it('can send a contact', function () {
     expect(fn (Telegraph $telegraph) => $telegraph->contact('3331122333', 'testFirstName'))
         ->toMatchTelegramSnapshot();

tests/Unit/DTO/MessageTest.php

@@ -256,6 +256,15 @@
             'longitude' => 98765431,
             'horizontal_accuracy' => 3,
         ],
+        'venue' => [
+            'location' => [
+                'latitude' => 12456789,
+                'longitude' => 98765431,
+                'horizontal_accuracy' => 3,
+            ],
+            'title' => 'test title',
+            'address' => 'test address',
+        ],
         'contact' => [
             'phone_number' => '123456789',
             'first_name' => 'John',
@@ -345,7 +354,7 @@
         1,
         "string",
         [
-          "a" => "b",
+            "a" => "b",
         ],
-      ]);
+    ]);
 });

tests/Unit/DTO/VenueTest.php

@@ -0,0 +1,29 @@
+<?php
+
+/** @noinspection PhpUnhandledExceptionInspection */
+
+use DefStudio\Telegraph\DTO\Venue;
+use Illuminate\Support\Str;
+
+it('export all properties to array', function () {
+    $dto = Venue::fromArray([
+        'location' => [
+            'latitude' => 10,
+            'longitude' => 10,
+            'horizontal_accuracy' => 10,
+        ],
+        'title' => 'test title',
+        'address' => 'test address',
+        'foursquare_id' => 'test foursquare_id',
+        'foursquare_type' => 'test foursquare_type',
+        'google_place_id' => 'test google_place_id',
+        'google_place_type' => 'test google_place_type',
+    ]);
+
+    $array = $dto->toArray();
+
+    $reflection = new ReflectionClass($dto);
+    foreach ($reflection->getProperties() as $property) {
+        expect($array)->toHaveKey(Str::of($property->name)->snake());
+    }
+});