Feature/voice machine detection (#404)

* Outbound call PHP8 cleanup

* Advanced machine detection in outbound call

* Add advanced machine detection to NCCO

Author: SecondeJK

phpunit.xml.dist

@@ -23,6 +23,9 @@
     <testsuite name="verify2">
       <directory>test/Verify2</directory>
     </testsuite>
+    <testsuite name="voice">
+      <directory>test/Voice</directory>
+    </testsuite>
     <testsuite name="messages">
       <directory>test/Messages</directory>
     </testsuite>

src/Voice/Client.php

@@ -84,6 +84,10 @@ public function createOutboundCall(OutboundCall $call): Event
             $json['ringing_timer'] = (string)$call->getRingingTimer();
         }
 
+        if (!is_null($call->getAdvancedMachineDetection())) {
+            $json['advanced_machine_detection'] = $call->getAdvancedMachineDetection()->toArray();
+        }
+
         $event = $this->api->create($json);
         $event['to'] = $call->getTo()->getId();
         if ($call->getFrom()) {

src/Voice/NCCO/Action/Connect.php

@@ -13,6 +13,7 @@
 
 use InvalidArgumentException;
 use Vonage\Voice\Endpoint\EndpointInterface;
+use Vonage\Voice\VoiceObjects\AdvancedMachineDetection;
 use Vonage\Voice\Webhook;
 
 class Connect implements ActionInterface
@@ -21,40 +22,15 @@ class Connect implements ActionInterface
     public const MACHINE_CONTINUE = 'continue';
     public const MACHINE_HANGUP = 'hangup';
 
-    /**
-     * @var ?string
-     */
-    protected $from;
-
-    /**
-     * @var ?string
-     */
-    protected $eventType;
+    protected ?string $from = '';
+    protected ?string $eventType = '';
 
-    /**
-     * @var int
-     */
-    protected $timeout;
-
-    /**
-     * @var int
-     */
-    protected $limit;
-
-    /**
-     * @var string
-     */
-    protected $machineDetection;
-
-    /**
-     * @var ?Webhook
-     */
-    protected $eventWebhook;
-
-    /**
-     * @var ?string
-     */
-    protected $ringbackTone;
+    protected int $timeout = 0;
+    protected int $limit = 0;
+    protected $machineDetection = '';
+    protected ?Webhook $eventWebhook = null;
+    protected ?string $ringbackTone = '';
+    protected ?AdvancedMachineDetection $advancedMachineDetection = null;
 
     public function __construct(protected EndpointInterface $endpoint)
     {
@@ -93,6 +69,10 @@ public function toNCCOArray(): array
             $data['machineDetection'] = $this->getMachineDetection();
         }
 
+        if ($this->getAdvancedMachineDetection()) {
+            $data['advancedMachineDetection'] = $this->getAdvancedMachineDetection()->toArray();
+        }
+
         $from = $this->getFrom();
 
         if ($from) {
@@ -236,4 +216,16 @@ public function setRingbackTone(string $ringbackTone): self
 
         return $this;
     }
+
+    public function getAdvancedMachineDetection(): ?AdvancedMachineDetection
+    {
+        return $this->advancedMachineDetection;
+    }
+
+    public function setAdvancedMachineDetection(AdvancedMachineDetection $advancedMachineDetection): static
+    {
+        $this->advancedMachineDetection = $advancedMachineDetection;
+
+        return $this;
+    }
 }

src/Voice/OutboundCall.php

@@ -15,61 +15,46 @@
 use Vonage\Voice\Endpoint\EndpointInterface;
 use Vonage\Voice\Endpoint\Phone;
 use Vonage\Voice\NCCO\NCCO;
+use Vonage\Voice\VoiceObjects\AdvancedMachineDetection;
 
 class OutboundCall
 {
     public const MACHINE_CONTINUE = 'continue';
     public const MACHINE_HANGUP = 'hangup';
-
-    /**
-     * @var Webhook
-     */
-    protected $answerWebhook;
-
-    /**
-     * @var Webhook
-     */
-    protected $eventWebhook;
+    protected ?Webhook $answerWebhook = null;
+    protected ?Webhook $eventWebhook = null;
 
     /**
      * Length of seconds before Vonage hangs up after going into `in_progress` status
-     *
-     * @var int
      */
-    protected $lengthTimer;
+    protected int $lengthTimer = 7200;
 
     /**
      * What to do when Vonage detects an answering machine.
-     *
-     * @var ?string
      */
-    protected $machineDetection;
+    protected ?string $machineDetection = '';
+
     /**
-     * @var NCCO
+     * Overrides machine detection if used for more configuration options
      */
-    protected $ncco;
+    protected ?AdvancedMachineDetection $advancedMachineDetection = null;
+
+    protected ?NCCO $ncco = null;
 
     /**
-     * Whether or not to use random numbers linked on the application
-     *
-     * @var bool
+     * Whether to use random numbers linked on the application
      */
-    protected $randomFrom = false;
+    protected bool $randomFrom = false;
 
     /**
      * Length of time Vonage will allow a phone number to ring before hanging up
-     *
-     * @var int
      */
-    protected $ringingTimer;
+    protected int $ringingTimer = 60;
 
     /**
      * Creates a new Outbound Call object
      * If no `$from` parameter is passed, the system will use a random number
      * that is linked to the application instead.
-     *
-     *
-     * @return void
      */
     public function __construct(protected EndpointInterface $to, protected ?Phone $from = null)
     {
@@ -118,39 +103,27 @@ public function getTo(): EndpointInterface
         return $this->to;
     }
 
-    /**
-     * @return $this
-     */
     public function setAnswerWebhook(Webhook $webhook): self
     {
         $this->answerWebhook = $webhook;
 
         return $this;
     }
 
-    /**
-     * @return $this
-     */
     public function setEventWebhook(Webhook $webhook): self
     {
         $this->eventWebhook = $webhook;
 
         return $this;
     }
 
-    /**
-     * @return $this
-     */
     public function setLengthTimer(int $timer): self
     {
         $this->lengthTimer = $timer;
 
         return $this;
     }
 
-    /**
-     * @return $this
-     */
     public function setMachineDetection(string $action): self
     {
         if ($action === self::MACHINE_CONTINUE || $action === self::MACHINE_HANGUP) {
@@ -162,19 +135,13 @@ public function setMachineDetection(string $action): self
         throw new InvalidArgumentException('Unknown machine detection action');
     }
 
-    /**
-     * @return $this
-     */
     public function setNCCO(NCCO $ncco): self
     {
         $this->ncco = $ncco;
 
         return $this;
     }
 
-    /**
-     * @return $this
-     */
     public function setRingingTimer(int $timer): self
     {
         $this->ringingTimer = $timer;
@@ -186,4 +153,16 @@ public function getRandomFrom(): bool
     {
         return $this->randomFrom;
     }
+
+    public function getAdvancedMachineDetection(): ?AdvancedMachineDetection
+    {
+        return $this->advancedMachineDetection;
+    }
+
+    public function setAdvancedMachineDetection(?AdvancedMachineDetection $advancedMachineDetection): static
+    {
+        $this->advancedMachineDetection = $advancedMachineDetection;
+
+        return $this;
+    }
 }

src/Voice/VoiceObjects/AdvancedMachineDetection.php

@@ -0,0 +1,104 @@
+<?php
+
+namespace Vonage\Voice\VoiceObjects;
+
+use Vonage\Entity\Hydrator\ArrayHydrateInterface;
+
+class AdvancedMachineDetection implements ArrayHydrateInterface
+{
+    public const MACHINE_BEHAVIOUR_CONTINUE = 'continue';
+    public const MACHINE_BEHAVIOUR_HANGUP = 'hangup';
+    public const MACHINE_MODE_DETECT = 'detect';
+    public const MACHINE_MODE_DETECT_BEEP = 'detect_beep';
+    public const BEEP_TIMEOUT_MIN = 45;
+    public const BEEP_TIMEOUT_MAX = 120;
+    protected array $permittedBehaviour = [self::MACHINE_BEHAVIOUR_CONTINUE, self::MACHINE_BEHAVIOUR_HANGUP];
+    protected array $permittedModes = [self::MACHINE_MODE_DETECT, self::MACHINE_MODE_DETECT_BEEP];
+
+    public function __construct(
+        protected string $behaviour,
+        protected int $beepTimeout,
+        protected string $mode = 'detect'
+    ) {
+        if (!$this->isValidBehaviour($behaviour)) {
+            throw new \InvalidArgumentException($behaviour . ' is not a valid behavior string');
+        }
+
+        if (!$this->isValidMode($mode)) {
+            throw new \InvalidArgumentException($mode . ' is not a valid mode string');
+        }
+
+        if (!$this->isValidTimeout($beepTimeout)) {
+            throw new \OutOfBoundsException('Timeout ' . $beepTimeout . ' is not valid');
+        }
+    }
+
+    protected function isValidBehaviour(string $behaviour): bool
+    {
+        if (in_array($behaviour, $this->permittedBehaviour, true)) {
+            return true;
+        }
+
+        return false;
+    }
+
+    protected function isValidMode(string $mode): bool
+    {
+        if (in_array($mode, $this->permittedModes, true)) {
+            return true;
+        }
+
+        return false;
+    }
+
+    protected function isValidTimeout(int $beepTimeout): bool
+    {
+        $range = [
+            'options' => [
+                'min_range' => self::BEEP_TIMEOUT_MIN,
+                'max_range' => self::BEEP_TIMEOUT_MAX
+            ]
+        ];
+
+        if (filter_var($beepTimeout, FILTER_VALIDATE_INT, $range)) {
+            return true;
+        }
+
+        return false;
+    }
+
+    public function fromArray(array $data): static
+    {
+        $this->isArrayValid($data);
+
+        $this->behaviour = $data['behaviour'];
+        $this->mode = $data['mode'];
+        $this->beepTimeout = $data['beep_timeout'];
+
+        return $this;
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'behaviour' => $this->behaviour,
+            'mode' => $this->mode,
+            'beep_timeout' => $this->beepTimeout
+        ];
+    }
+
+    protected function isArrayValid(array $data): bool
+    {
+        if (
+            !array_key_exists('behaviour', $data)
+            || !array_key_exists('mode', $data)
+            || !array_key_exists('beep_timeout', $data)
+        ) {
+            return false;
+        }
+
+        return $this->isValidBehaviour($data['behaviour'])
+               || $this->isValidMode($data['mode'])
+               || $this->isValidTimeout($data['beep_timeout']);
+    }
+}