Getting Started - Mash-Coding/alexa-php-framework GitHub Wiki

For using this framework you will need at least the following:

• PHP >= 5.6
• cURL (if you want to make use of remote functionality of the DOMHelper and/or FileHelper)

After having created/updated your composer.json, run composer install (or composer update) and composer should do all the work for you!

Note: Currently this repository isn't listed in Packagist, which is why you have to specify the git-repository manually (and as dev-master).

For easiest setup (without changing the configs too much), we recommend you to use the following project structure:

.
|-- composer.json                        -- your projects composer config
|-- config/
|   `-- alexa.json                       -- your projects config
|-- lang/
|   `-- <languageCode>.json              -- your projects localization/translation config (optional)
|   `-- <skillAlias>/                    -- <skillAlias> is in lowercase with underscores instead of spaces
|       `-- <languageCode>.json          -- a skills localization/translation config (optional)
|-- src/
|   `-- skills/
|       `-- <skillAlias>/                 -- a skills PHP source directory
|           `-- intents/
|               `-- <intentClass>.php    -- a skills intent PHP class
|-- vendor/                              -- composer-generated vendor directory
|   |-- mash-coding/
|   |   `-- alexa-php-framework/         -- this frameworks directory
|-- views/                               -- directory for views
`-- web/                                 -- your projects public directory
    `-- index.php

You can implement/execute the framework with the following lines:

<?php
    require __DIR__ . '/../vendor/autoload.php';
    define('DEBUG', false);
    \MashCoding\AlexaPHPFramework\Request::run('/config/alexa.json');

Yes, it really is just that simple! The most work is done in the config-file and in the intent-classes, though even there you haven't necessarily that much work!

1. setup your skill on developer.amazon.com
2. edit the alexa.json
3. create the IntentClass
4. then test your skill

• Skill Type: specifies the interaction model you want use (in our case you have to choose Custom)
• Language: obviously the language of your skill (you may add additional ones later)
• Application Id: you can't change it, but it is important for the framework (in the following we will refer to this Id with <skillId>)
• Name: the name of the skill that is displayed to customers
• Invocation Name: voice activiation command for the skill, Alexa, ask <invocation name>...
• Global Fields (apply to all languages)
  • Audio Player: set to true if your skill will play audio as response (currently not supported by the framework)

• Intent Schema: kind of the config for the skill on the amazon server, f.e.:

  {
    "intents": [
      {
        "intent": "<intentName>",
        "slots": [
          {
              "name": "<possibleArgument>",
              "type": "<type>"
          }
        ]
      },
      {
        "intent": "AMAZON.HelpIntent"
      }
    ]
  }

• Custom Slot Types: if you use custom slot types, insert them here (see this for more details)

• Sample Utterances: basically possible sentences/commands to use for users, f.e.:

  <intentName> say {<possibleArgument>}
  

  which makes it possible to say Alexa, ask <skillName> to say hello world. Be advised that you should use clear differences for saying different intents (adding another intent like <anotherIntent> make {<anotherArgument>} will surely cause trouble to Alexa).

• Service Endpoint Type: since we want to use the this PHP framework on our own server, choose HTTPS
  • Geographical region: you may choose different servers for the regions (might be important for performance)
  • Region input: insert the url to your projects public folder
• Account Linking: choose this if the user will be required to be authenticated in order to use functions of your skill (not supported by this framework yet)

• Certificate for Endpoint: choose what fits for your server (be advised though that publishing a skill is not possible when providing a self-signed certificate)

• Global Fields (apply to all languages)
  • Category: choose category which fits/describes your skill best
  • Sub Category: kind of self-explanatory, right?
  • Testing Instructions: these are special comments and/or instructions for the testing personal of Amazon, which will not be published to users
  • Countries & Region: select for which countries/regions you want your skill be available for
• Short Skill Description: this text will be displayed in the skill list of the Alexa App
• Full Skill Description: A much more detailed text about all features and requirements or even some instructions of how to set this skill up (f.e. if you want the user to register on your page in order to use the skill)
• Example Phrases: give users a quick start about what to say in order to get your skill functioning
• Keywords (Optional): specify some keywords, so users find your skill much easier
• Images (will be inserted into the grey speech bubble)
  • Small Icon: 108 x 108 pixel image for smaller displays
  • Large Icon: 512 x 512 pixel image for larger displays

• Global Fields
  • Privacy
    • in-skill purchases: can the user do purchases from within the skill (f.e. Alexa, ask <skill> to buy a game)
    • information collection: will you use the requests send to your server to f.e. save search habits or personal information?
    • children under 13: does your skill target children under the age of 13?
  • Compliance
    • Export compliance: may your skill be used wherever Amazon likes / as you selected in Publishing Information?
• Privacy Policy URL (Optional): if you have a privacy policy, you may link it here
• Terms of Use URL (Optional): if you have terms of use, you may link them here

  "help": {
    "text": "<basic description of your skill, read by Alexa when intent 'AMAZON.HelpIntent' is defined and user says 'Alexa, ask <skillInvocationName> help",
    "examples": [
      "<you may provide example sentences here>",
      "<additionally you can use '{{}}' to get basic skill details>",
      "Alexa, ask {{invocationName}} to say hello world"
    ]
  },

  "intents": {
    "<intentName>": {
      "intentClass": "<phpClassOfTheIntent>",
      "actions": {
        "<actionName>": ["<arguments>"],
        "<you may define multiple actions>": ["<possibleArgument>"],
        "<they may not use the exact same arguments though>": ["<possibleArgument, framework will call first action>"],
        "<you may specify no argument>": []
      }
    },

    "<anotherIntent>": {
      "intentClass": "<...>",
      "actions": "{
        <...> 
      }"
    }
  }
}

} }

_Note: Be advised that the framework will automatically append `Intent` to the `<phpClassOfTheIntent>`!_

-----

<br>
### IntentClass ###
After having set up our basic config, we can now go on with writing our PHP-class, which should be located, by default, in `/src/skills/<skillAlias>/<phpClassOfTheIntent>Intent.php`:
```PHP
<?php
    namespace <config.namespace.skills, default.json: 'app\skills\'>\<skillAlias>\intents;

    class <phpClassOfTheIntent>Intent extends Intent
    {
        public function action<actionName> ($slots) {
            // you can access the currently executed skills details
            $Skill = $this->Skill;

            // $this->Response is the object which will return the answer to Alexa
            $this->Response
                ->respond("action '<actionName>' from skill '" . $Skill->name . "' called with: " . $slots['<possibleArgument>']);
        }
    }