Added initial functionality

Author: ruslansteiger

LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) Codebar AG <ruslan.steiger@codebar.ch>
+Copyright (c) Codebar AG <info@codebar.ch>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -6,64 +6,203 @@
 [![Psalm](https://github.com/codebar-ag/laravel-twilio-verify/actions/workflows/psalm.yml/badge.svg)](https://github.com/codebar-ag/laravel-twilio-verify/actions/workflows/psalm.yml)
 [![Check & fix styling](https://github.com/codebar-ag/laravel-twilio-verify/actions/workflows/php-cs-fixer.yml/badge.svg)](https://github.com/codebar-ag/laravel-twilio-verify/actions/workflows/php-cs-fixer.yml)
 
-This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
+This package was developed to give you a quick start to communicate start and
+check a verification with Twilio Verify.
 
-## Installation
+⚠️ This package is not designed as a replacement of the official 
+[Twilio REST API](https://www.twilio.com/docs/verify/api). 
+See the documentation if you need further functionality. ⚠️
+
+## 💡 What is Twilio Verify?
+An elegant third-party integration to validate users with SMS, Voice, Email and
+Push. Add verification to any step of your user‘s journey with a single API.
+
+## 🛠 Requirements
+
+- PHP: `^8.0`
+- Laravel: `^8.12`
+- Twilio Account
+
+## ⚙️ Installation
 
 You can install the package via composer:
 
 ```bash
-composer require codebar-ag/laravel_twilio_verify
+composer require codebar-ag/laravel-twilio-verify
 ```
 
-You can publish and run the migrations with:
+Add the following environment variables to your `.env` file:
 
 ```bash
-php artisan vendor:publish --provider="CodebarAg\TwilioVerify\TwilioVerifyServiceProvider" --tag="laravel_twilio_verify-migrations"
-php artisan migrate
+TWILIO_ACCOUNT_SID=ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+TWILIO_AUTH_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+TWILIO_SERVICE_SID=VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+```
+
+## 🏗 Usage
+
+```php
+use CodebarAg\TwilioVerify\Facades\TwilioVerify;
+
+/**
+ * Start a new SMS verification to the phone number.
+ */
+$verificationStart = TwilioVerify::start(to: '+12085059915');
+
+/**
+ * Check a verification code.
+ */
+$verificationCheck = TwilioVerify::check(to: '+12085059915', code: '1337');
 ```
 
+### 🔢 Verification Code Limits
+
+- The generated code is valid for (10 minutes)[ https://www.twilio.com/docs/verify/api/rate-limits-and-timeouts].
+- You have attempted to send the verification code more than 5 times and have
+  (reached the limit)[https://www.twilio.com/docs/api/errors/60203].
+  
+## 🏋️ DTO showcase
+
+```php
+CodebarAg\TwilioVerify\DTO\SendCodeAttempt {
+  +time: Illuminate\Support\Carbon                      // Carbon
+  +channel: "sms"                                       // string
+  +attempt_sid: "VLMn1NOnmIVWMITO4FbVGxNmEMJ72KKaB2"    // string
+}
+```
+
+```php 
+CodebarAg\TwilioVerify\DTO\Lookup {
+  +carrier: CodebarAg\TwilioVerify\DTO\Carrier {
+    +error_code: null           // ?string
+    +name: "Carrier Name"       // string
+    +mobile_country_code: "310" // string
+    +mobile_network_code: "150" // string
+    +type: "150"                // string
+  }
+}
+```
+
+```php
+CodebarAg\TwilioVerify\DTO\VerificationStart
+  +sid: "VEkEJNNkLugY4hietPDbcqUUZz3G5NoTTZ"            // string
+  +service_sid: "VAssMsB84NdN0aJJceYsExX1223qAmrubx"    // string
+  +account_sid: "ACizUsoInA3dbKR5LA9tOqqA0O3NFSHSNc"    // string
+  +to: "+41795555825"                                   // string
+  +channel: "sms"                                       // string
+  +status: "pending"                                    // string
+  +valid: false                                         // bool
+  +created_at: Illuminate\Support\Carbon                // Carbon
+  +updated_at: Illuminate\Support\Carbon                // Carbon
+  +lookup: CodebarAg\TwilioVerify\DTO\Lookup {...}      // Lookup
+  +send_code_attempts: Illuminate\Support\Collection {  // Collection
+      0 => CodebarAg\TwilioVerify\DTO\SendCodeAttempt {
+        +time: Illuminate\Support\Carbon                    // Carbon
+        +channel: "sms"                                     // string
+        +attempt_sid: "VLTvj9jhh76cI78Hc1x0c3UORWJwwqVeTN"  // string
+      }
+    ]
+  }
+  +url: "https://verify.twilio.com/v2/Services/VAssMsB84NdN0aJJceYsExX1223qAmrubx/Verifications" // string
+}
+```
+
+```php
+CodebarAg\TwilioVerify\DTO\VerificationCheck {
+  +sid: "VEvRzh4hPUqmAjeC6li092VNT0yfd23lag"            // string
+  +service_sid: "VAxSR0Wq91djjG9PAYtrtjt11f0I4lqdwa"    // string
+  +account_sid: "ACcI5zbEYvLr0vPIUTQzWkTpP5DPqTCYDK"    // string
+  +to: "+41795555825"                                   // string
+  +channel: "sms"                                       // string
+  +status: "approved"                                   // string
+  +valid: true                                          // bool
+  +created_at: Illuminate\Support\Carbon                // Carbon
+  +updated_at: Illuminate\Support\Carbon                // Carbon
+}
+```
+
+## 🔧 Configuration file
+
 You can publish the config file with:
 ```bash
-php artisan vendor:publish --provider="CodebarAg\TwilioVerify\TwilioVerifyServiceProvider" --tag="laravel_twilio_verify-config"
+php artisan vendor:publish --provider="CodebarAg\TwilioVerify\TwilioVerifyServiceProvider" --tag="laravel-twilio-verify-config"
 ```
 
 This is the contents of the published config file:
 
 ```php
+
 return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Twilio Verify Configuration
+    |--------------------------------------------------------------------------
+    |
+    | You can find your Account SID and Auth Token in the Console Dashboard.
+    | Additionally you should create a new Verify service and paste it in
+    | here. Afterwards you are ready to communicate with Twilio Verify.
+    |
+    */
+
+    'url' => env('TWILIO_URL', 'https://verify.twilio.com/v2/Services'),
+    'account_sid' => env('TWILIO_ACCOUNT_SID', 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'),
+    'auth_token' => env('TWILIO_AUTH_TOKEN', 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'),
+    'service_sid' => env('TWILIO_SERVICE_SID', 'VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'),
+
 ];
 ```
 
-## Usage
+## ✨ Events
 
-```php
-$laravel_twilio_verify = new CodebarAg\TwilioVerify();
-echo $laravel_twilio_verify->echoPhrase('Hello, Spatie!');
+Following events are fired:
+
+```php 
+use CodebarAg\TwilioVerify\Events\TwilioVerifyResponseLog;
+
+// Log each response from the Twilio REST API.
+TwilioVerifyResponseLog::class => [
+    //
+],
+```
+
+## 🚧 Testing
+
+Copy your own phpunit.xml-file.
+```bash
+cp phpunit.xml.dist phpunit.xml
 ```
 
-## Testing
+Modify environment variables in the phpunit.xml-file:
+```xml
+<env name="TWILIO_ACCOUNT_SID" value="ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"/>
+<env name="TWILIO_AUTH_TOKEN" value="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"/>
+<env name="TWILIO_SERVICE_SID" value="VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"/>
+```
 
+Run the tests:
 ```bash
 composer test
 ```
 
-## Changelog
+## 📝 Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
 
-## Contributing
+## ✏️ Contributing
 
 Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.
 
-## Security Vulnerabilities
+## 🧑‍💻 Security Vulnerabilities
 
 Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
 
-## Credits
+## 🙏 Credits
 
 - [Ruslan Steiger](https://github.com/SuddenlyRust)
 - [All Contributors](../../contributors)
+- [Skeleton Repository from Spatie](https://github.com/spatie/package-skeleton-laravel)
+- [Laravel Package Training from Spatie](https://spatie.be/videos/laravel-package-training)
 
 ## License
 

composer.json

@@ -19,6 +19,7 @@
     "require": {
         "php": "^8.0",
         "friendsofphp/php-cs-fixer": "^2.18",
+        "guzzlehttp/guzzle": "^7.0.1",
         "illuminate/contracts": "^8.0",
         "spatie/laravel-package-tools": "^1.4.3"
     },

config/twilio-verify.php

@@ -0,0 +1,21 @@
+<?php
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Twilio Verify Configuration
+    |--------------------------------------------------------------------------
+    |
+    | You can find your Account SID and Auth Token in the Console Dashboard.
+    | Additionally you should create a new Verify service and paste it in
+    | here. Afterwards you are ready to communicate with Twilio Verify.
+    |
+    */
+
+    'url' => env('TWILIO_URL', 'https://verify.twilio.com/v2/Services'),
+    'account_sid' => env('TWILIO_ACCOUNT_SID', 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'),
+    'auth_token' => env('TWILIO_AUTH_TOKEN', 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'),
+    'service_sid' => env('TWILIO_SERVICE_SID', 'VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'),
+
+];

config/twilio_verify.php

@@ -36,4 +36,10 @@
     <logging>
         <junit outputFile="build/report.junit.xml"/>
     </logging>
+    <php>
+        <env name="TWILIO_URL" value="https://verify.twilio.com/v2/Services"/>
+        <env name="TWILIO_ACCOUNT_SID" value="ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"/>
+        <env name="TWILIO_AUTH_TOKEN" value="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"/>
+        <env name="TWILIO_SERVICE_SID" value="VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"/>
+    </php>
 </phpunit>

phpunit.xml.dist

@@ -0,0 +1,42 @@
+<?php
+
+namespace CodebarAg\TwilioVerify\DTO;
+
+class Carrier
+{
+    public static function fromJson(array $data): self
+    {
+        return new static(
+            error_code: $data['error_code'],
+            name: $data['name'],
+            mobile_country_code: $data['mobile_country_code'],
+            mobile_network_code: $data['mobile_network_code'],
+            type: $data['type'],
+        );
+    }
+
+    public function __construct(
+        public ?string $error_code,
+        public string $name,
+        public string $mobile_country_code,
+        public string $mobile_network_code,
+        public string $type,
+    ) {
+    }
+
+    public static function fake(
+        ?string $error_code = null,
+        ?string $name = null,
+        ?string $mobile_country_code = null,
+        ?string $mobile_network_code = null,
+        ?string $type = null,
+    ): self {
+        return new static(
+            error_code: $error_code ?? null,
+            name: $name ?? 'Carrier Name',
+            mobile_country_code: $mobile_country_code ?? '310',
+            mobile_network_code: $mobile_network_code ?? '150',
+            type: $type ?? '150',
+        );
+    }
+}

src/DTO/Carrier.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace CodebarAg\TwilioVerify\DTO;
+
+class Lookup
+{
+    public static function fromJson(array $lookup): self
+    {
+        return new static(
+            carrier: Carrier::fromJson($lookup['carrier']),
+        );
+    }
+
+    public function __construct(public Carrier $carrier)
+    {
+    }
+
+    public static function fake(?Carrier $carrier = null): self
+    {
+        return new static(
+            carrier: $carrier ?? Carrier::fake(),
+        );
+    }
+}

src/DTO/Lookup.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace CodebarAg\TwilioVerify\DTO;
+
+use Carbon\Carbon;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Str;
+
+class SendCodeAttempt
+{
+    public static function fromJson(array $attempts): Collection
+    {
+        return collect($attempts)->map(function (array $attempt) {
+            return new static(
+                time: Carbon::parse($attempt['time']),
+                channel: $attempt['channel'],
+                attempt_sid: $attempt['attempt_sid'],
+            );
+        });
+    }
+
+    public function __construct(
+        public Carbon $time,
+        public string $channel,
+        public string $attempt_sid,
+    ) {
+    }
+
+    public static function fake(
+        ?Carbon $time = null,
+        ?string $channel = null,
+        ?string $attempt_sid = null,
+    ): self {
+        return new static(
+            time: $time ?? now(),
+            channel: $channel ?? 'sms',
+            attempt_sid: $attempt_sid ?? 'VL' . Str::random(32),
+        );
+    }
+}