Amazon Alexa Php Laravel Package

Getting Started

Install via Composer and point a single HTTPS endpoint at one entry script — this package is a request/response mapper, not a framework, so there is no routing or bootstrap magic to learn.

composer require maxbeckers/amazon-alexa-php

// public/index.php
require __DIR__ . '/../vendor/autoload.php';

use MaxBeckers\AmazonAlexa\Request\Request;
use MaxBeckers\AmazonAlexa\Response\Response;

$body = file_get_contents('php://input');
$request = Request::fromAmazonRequest(
    $body,
    $_SERVER['HTTP_SIGNATURECERTCHAINURL'] ?? '',
    $_SERVER['HTTP_SIGNATURE'] ?? ''
);

$response = new Response();
$response->addOutputSpeech(new \MaxBeckers\AmazonAlexa\Response\OutputSpeech(
    'Hello from PHP',
    \MaxBeckers\AmazonAlexa\Response\OutputSpeech::TYPE_PLAIN_TEXT
));
$response->shouldEndSession = true;

header('Content-Type: application/json');
echo $response->toJson();

Where to look first:

1. MaxBeckers\AmazonAlexa\Request\Request — how the incoming JSON is deserialized into typed objects ($request->request->type, $request->request->intent, $request->session, $request->context).
2. MaxBeckers\AmazonAlexa\Response\Response — what you are legally allowed to return (speech, cards, reprompt, directives, session attributes, shouldEndSession).
3. MaxBeckers\AmazonAlexa\RequestHandler\* — the AbstractRequestHandler / RequestHandlerRegistry pair, which is the idiomatic way to structure anything beyond a toy skill.

First real use case: a LaunchRequest → IntentRequest → SessionEndedRequest flow for a single intent. Wire a Launch handler that greets and keeps the session open, one Intent handler that does the work, and a fallback handler for AMAZON.HelpIntent, AMAZON.StopIntent, and AMAZON.CancelIntent — Alexa will hit those whether you plan for them or not.

Implementation Patterns

Handler registry as your router. Extend AbstractRequestHandler, implement supportsRequest(Request $request): bool and handleRequest(Request $request): void, then register every handler on a RequestHandlerRegistry. This keeps intent logic testable and mirrors how Alexa's own request types are grouped. Put supportsRequest checks on $request->request->type and, for intents, on $request->request->intent->name.

One handler per intent, not per skill. Resist a giant handleRequest with a switch on intent name — the registry is cheap and a new intent should mean a new class plus one line in the registry.

Centralize response construction. Wrap speech + card + reprompt + shouldEndSession in a small Responder service so handlers never construct OutputSpeech or Card directly. This is the single biggest ergonomic win with this library, because Response is a mutable bag you keep appending to.

Session attributes as the conversation state machine. Read from $request->session->attributes (a plain array on the deserialized object) and write back via the response's session attributes. Keep the payload small — Alexa echoes it on every turn and there is a hard size limit.

Slot handling. Read slots from $request->request->intent->slots (name → Slot with value and resolutions). Normalize and validate before touching business logic; Alexa does not guarantee a slot has a value just because the intent matched.

Directive helpers for audio. For AudioPlayer skills, the DirectiveHelper namespace is where you build PlayDirective, StopDirective, and AudioItem instead of hand-rolling the JSON — this is the main place the package saves you real time.

Validation in the pipeline, not the handler. Do signature/cert-chain validation and application-ID checking at the top of index.php before parsing intent logic. Fail fast with a 400; never let an unvalidated request reach a handler.

Testing with fixtures. Export real request JSON from the Alexa developer console's test tab, drop them in tests/fixtures/, and feed them through Request::fromAmazonRequest into the registry in PHPUnit. Because handlers only depend on the Request object and produce a Response, this is straightforward and fast — no HTTP server needed.

Gotchas and Tips

Signature verification is not optional in production and is not on by default. Amazon will send Signature and SignatureCertChainUrl headers; you must validate them (the package ships a validator) and reject requests older than ~150 seconds to prevent replay. Many developers skip this locally and forget to re-enable it before certification review.

ApplicationId must be pinned. After parsing, compare $request->session->application->applicationId (or $request->context->system->application->applicationId for context-only requests) against your skill ID. Without this, anyone who finds your endpoint can invoke it.

shouldEndSession and reprompt interact. A reprompt on a session-ending response is silently ignored by Alexa; conversely, ending the session with shouldEndSession = true but no speech leaves the device hanging. Decide the pair together, usually in one place in your Responder.

SSML is a string, not a builder. If you pass SSML, escape user-supplied values yourself — unescaped & or < in a slot value will make Alexa reject or garble the response. The library will happily serialize broken markup.

Response timeout is ~8 seconds. Long-running work (DB, external API) must be fast or moved to a Lambda/queue — nothing in this package helps you with async, so budget accordingly.

Content type and HTTP status matter. Return 200 with Content-Type: application/json for valid requests, 400 for invalid signatures, and never return a PHP warning or HTML error page — Alexa surfaces those as opaque "skill response was invalid" errors that are painful to debug from the console.

The registry throws on no matching handler. Always register a fallback handler that supports any IntentRequest, otherwise an unexpected AMAZON.NavigateHomeIntent or similar will blow up the request.

Local debugging shortcut. Point curl at your endpoint with a saved request body and the two signature headers omitted, and temporarily bypass validation in a dev-only branch. Keep that branch behind an env flag — it is very easy to ship.

Version pinning. The package's minimum PHP version has tracked PHP releases over time; check composer.json before upgrading, especially if you are still on PHP 7.x. The changelog is more informative than the README for breaking changes to the handler interfaces.

Escape hatch. Because every request object is a typed wrapper over the raw JSON, if Amazon adds a field the package doesn't model yet, you can usually reach it through the request's raw data rather than waiting for a release — check for an accessor before patching the library.