Merge pull request #871 from noplanman/bot_api_4.0_passport

Bot API 4.0 & 4.1 - Telegram Passport (without decryption helpers)

Author: noplanman

CHANGELOG.md

@@ -6,7 +6,7 @@ Exclamation symbols (:exclamation:) note something of importance e.g. breaking c
 ## [Unreleased]
 :exclamation: After updating to this version, you will need to execute the [SQL migration script][unreleased-sql-migration] on your database.
 ### Added
-- Bot API 4.0 (without Passport)
+- Bot API 4.0
 ### Changed
 - [:exclamation:][unreleased-bc-move-animation-out-of-games-namespace] Move Animation entity out of Games namespace.
 ### Deprecated

src/DB.php

@@ -833,15 +833,15 @@ public static function insertMessageRequest(Message $message)
                     `location`, `venue`, `new_chat_members`, `left_chat_member`,
                     `new_chat_title`,`new_chat_photo`, `delete_chat_photo`, `group_chat_created`,
                     `supergroup_chat_created`, `channel_chat_created`,
-                    `migrate_from_chat_id`, `migrate_to_chat_id`, `pinned_message`, `connected_website`
+                    `migrate_from_chat_id`, `migrate_to_chat_id`, `pinned_message`, `connected_website`, `passport_data`
                 ) VALUES (
                     :message_id, :user_id, :chat_id, :date, :forward_from, :forward_from_chat, :forward_from_message_id,
                     :forward_date, :reply_to_chat, :reply_to_message, :media_group_id, :text, :entities, :audio, :document,
                     :animation, :game, :photo, :sticker, :video, :voice, :video_note, :caption, :contact,
                     :location, :venue, :new_chat_members, :left_chat_member,
                     :new_chat_title, :new_chat_photo, :delete_chat_photo, :group_chat_created,
                     :supergroup_chat_created, :channel_chat_created,
-                    :migrate_from_chat_id, :migrate_to_chat_id, :pinned_message, :connected_website
+                    :migrate_from_chat_id, :migrate_to_chat_id, :pinned_message, :connected_website, :passport_data
                 )
             ');
 
@@ -904,6 +904,7 @@ public static function insertMessageRequest(Message $message)
             $sth->bindValue(':migrate_to_chat_id', $message->getMigrateToChatId());
             $sth->bindValue(':pinned_message', $message->getPinnedMessage());
             $sth->bindValue(':connected_website', $message->getConnectedWebsite());
+            $sth->bindValue(':passport_data', $message->getPassportData());
 
             return $sth->execute();
         } catch (PDOException $e) {

src/Entities/Message.php

@@ -13,6 +13,7 @@
 use Longman\TelegramBot\Entities\Games\Game;
 use Longman\TelegramBot\Entities\Payments\Invoice;
 use Longman\TelegramBot\Entities\Payments\SuccessfulPayment;
+use Longman\TelegramBot\Entities\TelegramPassport\PassportData;
 
 /**
  * Class Message
@@ -56,6 +57,7 @@
  * @method Invoice           getInvoice()               Optional. Message is an invoice for a payment, information about the invoice.
  * @method SuccessfulPayment getSuccessfulPayment()     Optional. Message is a service message about a successful payment, information about the payment.
  * @method string            getConnectedWebsite()      Optional. The domain name of the website on which the user has logged in.
+ * @method PassportData      getPassportData()          Optional. Telegram Passport data
  */
 class Message extends Entity
 {
@@ -90,6 +92,7 @@ protected function subEntities()
             'pinned_message'     => Message::class,
             'invoice'            => Invoice::class,
             'successful_payment' => SuccessfulPayment::class,
+            'passport_data'      => PassportData::class,
         ];
     }
 
@@ -304,6 +307,7 @@ public function getType()
             'pinned_message',
             'invoice',
             'successful_payment',
+            'passport_data',
         ];
 
         $is_command = strlen($this->getCommand()) > 0;

src/Entities/TelegramPassport/EncryptedCredentials.php

@@ -0,0 +1,29 @@
+<?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\TelegramPassport;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class EncryptedCredentials
+ *
+ * Contains data required for decrypting and authenticating EncryptedCredentials. See the Telegram Passport Documentation for a complete description of the data decryption and authentication processes.
+ *
+ * @link https://core.telegram.org/bots/api#encryptedcredentials
+ *
+ * @method string getData()   Base64-encoded encrypted JSON-serialized data with unique user's payload, data hashes and secrets required for EncryptedPassportElement decryption and authentication
+ * @method string getHash()   Base64-encoded data hash for data authentication
+ * @method string getSecret() Base64-encoded secret, encrypted with the bot's public RSA key, required for data decryption
+ **/
+class EncryptedCredentials extends Entity
+{
+
+}

src/Entities/TelegramPassport/EncryptedPassportElement.php

@@ -0,0 +1,76 @@
+<?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\TelegramPassport;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class EncryptedPassportElement
+ *
+ * Contains information about documents or other Telegram Passport elements shared with the bot by the user.
+ *
+ * @link https://core.telegram.org/bots/api#encryptedpassportelement
+ *
+ * @method string       getType()        Element type. One of “personal_details”, “passport”, “driver_license”, “identity_card”, “internal_passport”, “address”, “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration”, “temporary_registration”, “phone_number”, “email”.
+ * @method string       getData()        Optional. Base64-encoded encrypted Telegram Passport element data provided by the user, available for “personal_details”, “passport”, “driver_license”, “identity_card”, “identity_passport” and “address” types. Can be decrypted and verified using the accompanying EncryptedCredentials.
+ * @method string       getPhoneNumber() Optional. User's verified phone number, available only for “phone_number” type
+ * @method string       getEmail()       Optional. User's verified email address, available only for “email” type
+ * @method PassportFile getFrontSide()   Optional. Encrypted file with the front side of the document, provided by the user. Available for “passport”, “driver_license”, “identity_card” and “internal_passport”. The file can be decrypted and verified using the accompanying EncryptedCredentials.
+ * @method PassportFile getReverseSide() Optional. Encrypted file with the reverse side of the document, provided by the user. Available for “driver_license” and “identity_card”. The file can be decrypted and verified using the accompanying EncryptedCredentials.
+ * @method PassportFile getSelfie()      Optional. Encrypted file with the selfie of the user holding a document, provided by the user; available for “passport”, “driver_license”, “identity_card” and “internal_passport”. The file can be decrypted and verified using the accompanying EncryptedCredentials.
+ * @method string       getHash()        Base64-encoded element hash for using in PassportElementErrorUnspecified
+ **/
+class EncryptedPassportElement extends Entity
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function subEntities()
+    {
+        return [
+            'files'        => PassportFile::class,
+            'front_side'   => PassportFile::class,
+            'reverse_side' => PassportFile::class,
+            'selfie'       => PassportFile::class,
+            'translation'  => PassportFile::class,
+        ];
+    }
+
+    /**
+     * Optional. Array of encrypted files with documents provided by the user, available for “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration” and “temporary_registration” types. Files can be decrypted and verified using the accompanying EncryptedCredentials.
+     *
+     * This method overrides the default getFiles method
+     * and returns a nice array of PassportFile objects.
+     *
+     * @return null|PassportFile[]
+     */
+    public function getFiles()
+    {
+        $pretty_array = $this->makePrettyObjectArray(PassportFile::class, 'files');
+
+        return empty($pretty_array) ? null : $pretty_array;
+    }
+
+    /**
+     * Optional. Array of encrypted files with translated versions of documents provided by the user. Available if requested for “passport”, “driver_license”, “identity_card”, “internal_passport”, “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration” and “temporary_registration” types. Files can be decrypted and verified using the accompanying EncryptedCredentials.
+     *
+     * This method overrides the default getTranslation method
+     * and returns a nice array of PassportFile objects.
+     *
+     * @return null|PassportFile[]
+     */
+    public function getTranslation()
+    {
+        $pretty_array = $this->makePrettyObjectArray(PassportFile::class, 'translation');
+
+        return empty($pretty_array) ? null : $pretty_array;
+    }
+}

src/Entities/TelegramPassport/PassportData.php

@@ -0,0 +1,51 @@
+<?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\TelegramPassport;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class PassportData
+ *
+ * Contains information about Telegram Passport data shared with the bot by the user.
+ *
+ * @link https://core.telegram.org/bots/api#passportdata
+ *
+ * @method EncryptedCredentials getCredentials() Encrypted credentials required to decrypt the data
+ **/
+class PassportData extends Entity
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function subEntities()
+    {
+        return [
+            'data'        => EncryptedPassportElement::class,
+            'credentials' => EncryptedCredentials::class,
+        ];
+    }
+
+    /**
+     * Array with information about documents and other Telegram Passport elements that was shared with the bot
+     *
+     * This method overrides the default getData method
+     * and returns a nice array of EncryptedPassportElement objects.
+     *
+     * @return null|EncryptedPassportElement[]
+     */
+    public function getData()
+    {
+        $pretty_array = $this->makePrettyObjectArray(EncryptedPassportElement::class, 'data');
+
+        return empty($pretty_array) ? null : $pretty_array;
+    }
+}

src/Entities/TelegramPassport/PassportElementError/PassportElementError.php

@@ -0,0 +1,16 @@
+<?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 Entities\TelegramPassport\PassportElementError;
+
+interface PassportElementError
+{
+
+}

src/Entities/TelegramPassport/PassportElementError/PassportElementErrorDataField.php

@@ -0,0 +1,42 @@
+<?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 Entities\TelegramPassport\PassportElementError;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class PassportElementErrorDataField
+ *
+ * Represents an issue in one of the data fields that was provided by the user. The error is considered resolved when the field's value changes.
+ *
+ * @link https://core.telegram.org/bots/api#passportelementerrordatafield
+ *
+ * @method string getSource()    Error source, must be data
+ * @method string getType()      The section of the user's Telegram Passport which has the error, one of “personal_details”, “passport”, “driver_license”, “identity_card”, “internal_passport”, “address”
+ * @method string getFieldName() Name of the data field which has the error
+ * @method string getDataHash()  Base64-encoded data hash
+ * @method string getMessage()   Error message
+ */
+class PassportElementErrorDataField extends Entity implements PassportElementError
+{
+    /**
+     * PassportElementErrorDataField constructor
+     *
+     * @param array $data
+     *
+     * @throws \Longman\TelegramBot\Exception\TelegramException
+     */
+    public function __construct(array $data = [])
+    {
+        $data['source'] = 'data';
+        parent::__construct($data);
+    }
+}

src/Entities/TelegramPassport/PassportElementError/PassportElementErrorFile.php

@@ -0,0 +1,41 @@
+<?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 Entities\TelegramPassport\PassportElementError;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class PassportElementErrorFile
+ *
+ * Represents an issue with a document scan. The error is considered resolved when the file with the document scan changes.
+ *
+ * @link https://core.telegram.org/bots/api#passportelementerrorfile
+ *
+ * @method string getSource()   Error source, must be file
+ * @method string getType()     The section of the user's Telegram Passport which has the issue, one of “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration”, “temporary_registration”
+ * @method string getFileHash() Base64-encoded file hash
+ * @method string getMessage()  Error message
+ */
+class PassportElementErrorFile extends Entity implements PassportElementError
+{
+    /**
+     * PassportElementErrorFile constructor
+     *
+     * @param array $data
+     *
+     * @throws \Longman\TelegramBot\Exception\TelegramException
+     */
+    public function __construct(array $data = [])
+    {
+        $data['source'] = 'file';
+        parent::__construct($data);
+    }
+}

src/Entities/TelegramPassport/PassportElementError/PassportElementErrorFiles.php

@@ -0,0 +1,41 @@
+<?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 Entities\TelegramPassport\PassportElementError;
+
+use Longman\TelegramBot\Entities\Entity;
+
+/**
+ * Class PassportElementErrorFiles
+ *
+ * Represents an issue with a list of scans. The error is considered resolved when the list of files containing the scans changes.
+ *
+ * @link https://core.telegram.org/bots/api#passportelementerrorfiles
+ *
+ * @method string   getSource()     Error source, must be files
+ * @method string   getType()       The section of the user's Telegram Passport which has the issue, one of “utility_bill”, “bank_statement”, “rental_agreement”, “passport_registration”, “temporary_registration”
+ * @method string[] getFileHashes() List of base64-encoded file hashes
+ * @method string   getMessage()    Error message
+ */
+class PassportElementErrorFiles extends Entity implements PassportElementError
+{
+    /**
+     * PassportElementErrorFiles constructor
+     *
+     * @param array $data
+     *
+     * @throws \Longman\TelegramBot\Exception\TelegramException
+     */
+    public function __construct(array $data = [])
+    {
+        $data['source'] = 'files';
+        parent::__construct($data);
+    }
+}