add APL support (#97)

* add APL support

* cs fix

* add additional tests

* optimize code

* add additional tests

Author: maxbeckers

.php-cs-fixer.cache

@@ -1,5 +1,11 @@
 # Change Log
 
+## [2.1.0](https://github.com/maxbeckers/amazon-alexa-php/tree/2.1.0) (TBD)
+[Full Changelog](https://github.com/maxbeckers/amazon-alexa-php/compare/2.0.0...2.1.0)
+
+**Added:**
+- **APL Support**: Alexa Presentation Language (directives, documents, components, commands, gestures) now supported for building multimodal experiences.
+
 ## [2.0.0](https://github.com/maxbeckers/amazon-alexa-php/tree/2.0.0) (TBD)
 [Full Changelog](https://github.com/maxbeckers/amazon-alexa-php/compare/1.13.0...2.0.0)
 

CHANGELOG.md

@@ -13,6 +13,7 @@ A modern PHP library for building Amazon Alexa skills with clean, maintainable c
 - **Request Validation**: Automatic verification of Amazon request signatures
 - **Flexible Handler System**: Easy-to-extend request handler architecture
 - **SSML Support**: Built-in Speech Synthesis Markup Language generator
+- **APL Support**: Create and send Alexa Presentation Language documents, components, directives, gestures and commands
 - **Device Address API**: Helper for accessing user location data
 - **PHP 8.2+ Ready**: Leverages modern PHP features and type safety
 - **Symfony Integration**: Available bundle for Symfony applications
@@ -162,6 +163,58 @@ $ssml = $ssmlGenerator->getSsml();
 // Result: <speak>Welcome to our cooking skill! <break strength="medium" /> Today we will learn about <emphasis level="strong">amazing</emphasis> pasta recipes. <break time="2s" /> Let's get started!</speak>
 ```
 
+## 🖼 APL (Alexa Presentation Language)
+
+Build multimodal experiences with the included APL directive, component, command, and gesture classes:
+
+```php
+<?php
+
+use MaxBeckers\AmazonAlexa\Response\Directives\APL\RenderDocumentDirective;
+use MaxBeckers\AmazonAlexa\Response\Response;
+use MaxBeckers\AmazonAlexa\ResponseHelper;
+
+// Inside a request handler:
+$document = [
+    'type' => 'APL',
+    'version' => '1.8',
+    'mainTemplate' => [
+        'items' => [
+            [
+                'type' => 'Text',
+                'text' => '${payload.data.message}',
+                'style' => 'textStylePrimary1'
+            ]
+        ]
+    ],
+];
+
+$dataSources = [
+    'data' => [
+        'message' => 'Hello from APL!'
+    ],
+];
+
+$aplDirective = new RenderDocumentDirective(
+    token: 'mainScreen',
+    document: $document,
+    datasources: $dataSources
+);
+
+// Using the response helper (if available in your handler base)
+$response = $this->responseHelper->respond(
+    outputSpeech: 'Showing a visual response.',
+    directives: [$aplDirective],
+    shouldEndSession: false
+);
+
+// Or manually:
+$alexaResponse = new Response();
+$alexaResponse->response->directives[] = $aplDirective;
+```
+
+You can also leverage the rich PHP class model (components, commands, gestures, layouts) instead of raw arrays for stronger typing when building complex documents.
+
 ## 📍 Device Address Information
 
 Access user location data with proper permissions:

README.md

@@ -19,7 +19,8 @@
     "skill",
     "alexa-custom-skill",
     "library",
-    "ssml"
+    "ssml",
+    "apl"
   ],
   "license": "MIT",
   "support": {

composer.json

@@ -17,6 +17,7 @@ class AskForPermissionsConsentCardResponseRequestHandler extends AbstractRequest
     public function __construct(
         private readonly ResponseHelper $responseHelper
     ) {
+        parent::__construct();
         $this->supportedApplicationIds = ['my_amazon_skill_id'];
     }
 

examples/Handlers/AskForPermissionsConsentCardResponseRequestHandler.php

@@ -18,6 +18,7 @@ class CardResponseRequestHandler extends AbstractRequestHandler
     public function __construct(
         private readonly ResponseHelper $responseHelper
     ) {
+        parent::__construct();
         $this->supportedApplicationIds = ['my_amazon_skill_id'];
     }
 

examples/Handlers/CardResponseRequestHandler.php

@@ -16,6 +16,7 @@ class SimpleIntentRequestHandler extends AbstractRequestHandler
     public function __construct(
         private readonly ResponseHelper $responseHelper
     ) {
+        parent::__construct();
         $this->supportedApplicationIds = ['my_amazon_skill_id'];
     }
 

examples/Handlers/SimpleIntentRequestHandler.php

@@ -49,5 +49,4 @@
 } else {
     http_response_code(400);
 }
-
 exit();

examples/ask-for-permissions-card-response.php

@@ -49,5 +49,4 @@
 } else {
     http_response_code(400);
 }
-
 exit();

examples/card-response.php

@@ -49,5 +49,4 @@
 } else {
     http_response_code(400);
 }
-
 exit();