README

Amazon Alexa PHP Library

A modern PHP library for building Amazon Alexa skills with clean, maintainable code. This library simplifies handling Alexa requests by providing a robust validation system, flexible request handlers, and helper utilities for common tasks.

???? Features

• 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

???? Requirements

• PHP 8.2 or higher
• Composer

???? Installation

composer require maxbeckers/amazon-alexa-php

???? Quick Start

Basic Request Handling

<?php use MaxBeckers\AmazonAlexa\Request\Request; use MaxBeckers\AmazonAlexa\Validation\RequestValidator; use MaxBeckers\AmazonAlexa\RequestHandler\RequestHandlerRegistry; // 1. Parse incoming request $requestBody = file_get_contents('php://input'); $alexaRequest = Request::fromAmazonRequest( $requestBody, $_SERVER['HTTP_SIGNATURECERTCHAINURL'] ?? '', $_SERVER['HTTP_SIGNATURE'] ?? '' ); // 2. Validate request authenticity $validator = new RequestValidator(); $validator->validate($alexaRequest); // 3. Handle request $registry = new RequestHandlerRegistry(); $registry->addHandler(new MyIntentHandler()); $handler = $registry->getSupportingHandler($alexaRequest); $response = $handler->handleRequest($alexaRequest); // 4. Send response header('Content-Type: application/json'); echo json_encode($response);

???? Creating Request Handlers

Simple Intent Handler (PHP 8.2+)

<?php use MaxBeckers\AmazonAlexa\Request\Request; use MaxBeckers\AmazonAlexa\Response\Response; use MaxBeckers\AmazonAlexa\RequestHandler\AbstractRequestHandler; use MaxBeckers\AmazonAlexa\Request\Request\Standard\IntentRequest; class WelcomeIntentHandler extends AbstractRequestHandler { public function __construct( private readonly array $supportedApplicationIds = ['amzn1.ask.skill.your-skill-id'] ) { parent::__construct(); } public function supportsRequest(Request $request): bool { return $request->request instanceof IntentRequest && $request->request->intent->name === 'WelcomeIntent'; } public function handleRequest(Request $request): Response { return $this->responseHelper->respond( outputSpeech: 'Welcome to our amazing skill!', shouldEndSession: false ); } }

Advanced Handler with Slots

<?php use MaxBeckers\AmazonAlexa\Request\Request; use MaxBeckers\AmazonAlexa\Response\Response; use MaxBeckers\AmazonAlexa\RequestHandler\AbstractRequestHandler; use MaxBeckers\AmazonAlexa\Request\Request\Standard\IntentRequest; class UserInfoHandler extends AbstractRequestHandler { public function __construct( private readonly array $supportedApplicationIds = ['amzn1.ask.skill.your-skill-id'] ) { parent::__construct(); } public function supportsRequest(Request $request): bool { return $request->request instanceof IntentRequest && $request->request->intent->name === 'GetUserInfoIntent'; } public function handleRequest(Request $request): Response { $intentRequest = $request->request; $userName = $intentRequest->intent->slots['userName']->value ?? 'friend'; $message = match($userName) { 'admin' => 'Hello administrator! You have special privileges.', 'guest' => 'Welcome, guest user. Limited features available.', default => "Nice to meet you, {$userName}!" }; return $this->responseHelper->respond($message); } }

???? SSML Generation

Create rich speech responses with the SSML generator:

<?php use MaxBeckers\AmazonAlexa\Helper\SsmlGenerator; $ssmlGenerator = new SsmlGenerator(); $ssmlGenerator ->say('Welcome to our cooking skill!') ->pauseStrength(SsmlGenerator::BREAK_STRENGTH_MEDIUM) ->say('Today we will learn about') ->emphasis('amazing', SsmlGenerator::EMPHASIS_STRONG) ->say('pasta recipes.') ->pauseTime('2s') ->say('Let\'s get started!'); $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 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:

<?php use MaxBeckers\AmazonAlexa\Helper\DeviceAddressInformationHelper; $addressHelper = new DeviceAddressInformationHelper(); try { // Get full address (requires "read::alexa:device:all:address" permission) $fullAddress = $addressHelper->getAddress($request); // Get country and postal code only (requires "read::alexa:device:all:address:country_and_postal_code" permission) $countryAndPostalCode = $addressHelper->getCountryAndPostalCode($request); $response = $this->responseHelper->respond( "I found your location in {$fullAddress->city}, {$fullAddress->stateOrRegion}" ); } catch (Exception $e) { $response = $this->responseHelper->respond( 'I need permission to access your address. Please check your Alexa app.' ); }

????️ Error Handling

Implement robust error handling:

<?php use MaxBeckers\AmazonAlexa\Exception\ValidationException; try { $validator = new RequestValidator(); $validator->validate($alexaRequest); } catch (ValidationException $e) { http_response_code(400); echo json_encode(['error' => 'Invalid request signature']); exit; } catch (Exception $e) { http_response_code(500); error_log('Alexa skill error: ' . $e->getMessage()); echo json_encode(['error' => 'Internal server error']); exit; }

???? Advanced Usage

Custom Response Builder

<?php use MaxBeckers\AmazonAlexa\Response\Response; use MaxBeckers\AmazonAlexa\Response\OutputSpeech; use MaxBeckers\AmazonAlexa\Response\Card; public function handleRequest(Request $request): Response { $outputSpeech = new OutputSpeech(); $outputSpeech->type = OutputSpeech::TYPE_SSML; $outputSpeech->ssml = '<speak>Custom SSML response</speak>'; $card = new Card(); $card->type = Card::TYPE_SIMPLE; $card->title = 'Skill Response'; $card->content = 'This appears in the Alexa app'; $response = new Response(); $response->outputSpeech = $outputSpeech; $response->card = $card; $response->shouldEndSession = false; return $response; }

Registry with Multiple Handlers

<?php $registry = new RequestHandlerRegistry(); $registry->addHandler(new LaunchRequestHandler()); $registry->addHandler(new WelcomeIntentHandler()); $registry->addHandler(new HelpIntentHandler()); $registry->addHandler(new StopIntentHandler()); $registry->addHandler(new SessionEndedRequestHandler());

????️ Symfony Integration

For Symfony applications, use the dedicated bundle:

composer require maxbeckers/amazon-alexa-bundle

Visit maxbeckers/amazon-alexa-bundle for detailed integration instructions.

???? Documentation

• Amazon Alexa Skills Kit Documentation
• Device Address API
• SSML Reference

???? Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

???? License

This project is licensed under the MIT License - see the LICENSE file for details.