Add new payment entities and update types.

CHANGELOG.md

@@ -8,6 +8,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 - Documents can be sent by providing its contents via Psr7 stream (as opposed to passing a file path).
 - Allow setting a custom Guzzle HTTP Client for requests (#511).
 - First implementations towards Bots API 3.0.
+- New entities and update types for Payments.
 ### Changed
 - [:exclamation:][unreleased-bc-chats-params-array] `Request::sendToActiveChats` and `DB::selectChats` now accept parameters as an options array.
 ### Deprecated

src/Entities/Payments/Invoice.php

+<?php
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <akalongman@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\Payments;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class Invoice
+ *
+ * This object contains basic information about an invoice.
+ *
+ * @link https://core.telegram.org/bots/api#invoice
+ *
+ * @method string getTitle()          Product name
+ * @method string getDescription()    Product description
+ * @method string getStartParameter() Unique bot deep-linking parameter that can be used to generate this invoice
+ * @method string getCurrency()       Three-letter ISO 4217 currency code
+ * @method int    getTotalAmount()    Total price in the smallest units of the currency (integer, not float/double).
+ **/
+class Invoice extends Entity
+{
+
+}

src/Entities/Payments/LabeledPrice.php

+<?php
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <akalongman@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\Payments;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class LabeledPrice
+ *
+ * This object represents a portion of the price for goods or services.
+ *
+ * @link https://core.telegram.org/bots/api#labeledprice
+ *
+ * @method string getLabel()  Portion label
+ * @method int    getAmount() Price of the product in the smallest units of the currency (integer, not float/double).
+ **/
+class LabeledPrice extends Entity
+{
+
+}

src/Entities/Payments/OrderInfo.php

+<?php
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <akalongman@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\Payments;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class OrderInfo
+ *
+ * This object represents information about an order.
+ *
+ * @link https://core.telegram.org/bots/api#orderinfo
+ *
+ * @method string          getName()            Optional. User name
+ * @method string          getPhoneNumber()     Optional. User's phone number
+ * @method string          getEmail()           Optional. User email
+ * @method ShippingAddress getShippingAddress() Optional. User shipping address
+ **/
+class OrderInfo extends Entity
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function subEntities()
+    {
+        return [
+            'shipping_address' => ShippingAddress::class,
+        ];
+    }
+}

src/Entities/Payments/PreCheckoutQuery.php

+<?php
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <akalongman@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\Payments;
+
+use Longman\TelegramBot\Entities\Entity;
+use Longman\TelegramBot\Entities\User;
+
+/**
+ * Class PreCheckoutQuery
+ *
+ * This object contains information about an incoming pre-checkout query.
+ *
+ * @link https://core.telegram.org/bots/api#precheckoutquery
+ *
+ * @method string    getId()               Unique query identifier
+ * @method User      getFrom()             User who sent the query
+ * @method string    getCurrency()         Three-letter ISO 4217 currency code
+ * @method int       getTotalAmount()      Total price in the smallest units of the currency (integer, not float/double).
+ * @method string    getInvoicePayload()   Bot specified invoice payload
+ * @method string    getShippingOptionId() Optional. Identifier of the shipping option chosen by the user
+ * @method OrderInfo getOrderInfo()        Optional. Order info provided by the user
+ **/
+class PreCheckoutQuery extends Entity
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function subEntities()
+    {
+        return [
+            'user' => User::class,
+            'order_info' => OrderInfo::class,
+        ];
+    }
+}

src/Entities/Payments/ShippingAddress.php

+<?php
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <akalongman@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\Payments;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class ShippingAddress
+ *
+ * This object represents a shipping address.
+ *
+ * @link https://core.telegram.org/bots/api#shippingaddress
+ *
+ * @method string getCountryCode() ISO 3166-1 alpha-2 country code
+ * @method string getState()       State, if applicable
+ * @method string getCity()        City
+ * @method string getStreetLine1() First line for the address
+ * @method string getStreetLine2() Second line for the address
+ * @method string getPostCode()    Address post code
+ **/
+class ShippingAddress extends Entity
+{
+
+}

src/Entities/Payments/ShippingOption.php

+<?php
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <akalongman@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\Payments;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class ShippingOption
+ *
+ * This object represents one shipping option.
+ *
+ * @link https://core.telegram.org/bots/api#shippingoption
+ *
+ * @method string getId()    Shipping option identifier
+ * @method string getTitle() Option title
+ **/
+class ShippingOption extends Entity
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function subEntities()
+    {
+        return [
+            'prices' => LabeledPrice::class,
+        ];
+    }
+
+    /**
+     * List of price portions
+     *
+     * This method overrides the default getPrices method and returns a nice array
+     *
+     * @return LabeledPrice[]
+     */
+    public function getPrices()
+    {
+        $all_prices = [];
+
+        if ($these_prices = $this->getProperty('prices')) {
+            foreach ($these_prices as $prices) {
+                $new_prices = [];
+                foreach ($prices as $price) {
+                    $new_prices[] = new LabeledPrice($price);
+                }
+                $all_prices[] = $new_prices;
+            }
+        }
+
+        return $all_prices;
+    }
+}

src/Entities/Payments/ShippingQuery.php

+<?php
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <akalongman@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\Payments;
+
+use Longman\TelegramBot\Entities\Entity;
+use Longman\TelegramBot\Entities\User;
+
+/**
+ * Class ShippingQuery
+ *
+ * This object contains information about an incoming shipping query.
+ *
+ * @link https://core.telegram.org/bots/api#shippingquery
+ *
+ * @method string          getId()              Unique query identifier
+ * @method User            getFrom()            User who sent the query
+ * @method string          getInvoicePayload()  Bot specified invoice payload
+ * @method ShippingAddress getShippingAddress() User specified shipping address
+ **/
+class ShippingQuery extends Entity
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function subEntities()
+    {
+        return [
+            'user' => User::class,
+            'shipping_address' => ShippingAddress::class,
+        ];
+    }
+}

src/Entities/Payments/SuccessfulPayment.php

+<?php
+/**
+ * This file is part of the TelegramBot package.
+ *
+ * (c) Avtandil Kikabidze aka LONGMAN <akalongman@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Longman\TelegramBot\Entities\Payments;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class SuccessfulPayment
+ *
+ * This object contains basic information about a successful payment.
+ *
+ * @link https://core.telegram.org/bots/api#successfulpayment
+ *
+ * @method string    getCurrency()                Three-letter ISO 4217 currency code
+ * @method int       getTotalAmount()             Total price in the smallest units of the currency (integer, not float/double).
+ * @method string    getInvoicePayload()          Bot specified invoice payload
+ * @method string    getShippingOptionId()        Optional. Identifier of the shipping option chosen by the user
+ * @method OrderInfo getOrderInfo()               Optional. Order info provided by the user
+ * @method string    getTelegramPaymentChargeId() Telegram payment identifier
+ * @method string    getProviderPaymentChargeId() Provider payment identifier
+ **/
+class SuccessfulPayment extends Entity
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function subEntities()
+    {
+        return [
+            'order_info' => OrderInfo::class,
+        ];
+    }
+}

src/Entities/Update.php

@@ -10,6 +10,9 @@
 
 namespace Longman\TelegramBot\Entities;
 
+use Longman\TelegramBot\Entities\Payments\PreCheckoutQuery;
+use Longman\TelegramBot\Entities\Payments\ShippingQuery;
+
 /**
  * Class Update
  *
@@ -23,6 +26,8 @@ namespace Longman\TelegramBot\Entities;
  * @method InlineQuery         getInlineQuery()        Optional. New incoming inline query
  * @method ChosenInlineResult  getChosenInlineResult() Optional. The result of an inline query that was chosen by a user and sent to their chat partner.
  * @method CallbackQuery       getCallbackQuery()      Optional. New incoming callback query
+ * @method ShippingQuery       getShippingQuery()      Optional. New incoming shipping query. Only for invoices with flexible price
+ * @method PreCheckoutQuery    getPreCheckoutQuery()   Optional. New incoming pre-checkout query. Contains full information about checkout
  */
 class Update extends Entity
 {
@@ -39,6 +44,8 @@ class Update extends Entity
             'inline_query'         => InlineQuery::class,
             'chosen_inline_result' => ChosenInlineResult::class,
             'callback_query'       => CallbackQuery::class,
+            'shipping_query'       => ShippingQuery::class,
+            'pre_checkout_query'   => PreCheckoutQuery::class,
         ];
     }
 
@@ -57,6 +64,8 @@ class Update extends Entity
             'inline_query',
             'chosen_inline_result',
             'callback_query',
+            'shipping_query',
+            'pre_checkout_query',
         ];
         foreach ($types as $type) {
             if ($this->getProperty($type)) {