CloudObjects / Blog / Introducing phpMAE

Introducing phpMAE

I’m happy to announce that CloudObjects has just launched phpMAE 0.2 and a public preview version of serverless phpMAE hosting. As mentioned in “The Micro API Design Pattern”, phpMAE is our PHP-based implementation of a Micro API engine (and that’s what the name phpMAE stands for, PHP Micro API Engine). The objective of a Micro API engine is to get developers up and running with a standardized set of dependencies that empowers them to quickly build and deploy integration code without managing infrastructure. You can download phpMAE from GitHub, run it on your computer and then use phpMAE in combination with the CloudObjects CLI Tool to deploy the code to our cloud-based hosting. During the current stage hosting is free for developers!

This introduction post is a hands-on tutorial because any developer tool is much better experienced than just heard or read about, thus I’m showing you how to get from zero to a deployed “Hello World” API in less than 15 minutes. Ready to start?!

Signing up

If you haven’t done so yet, sign up to CloudObjects. It’s free and fast, especially when you use an existing third party account, e.g. your Twitter account. Go to our homepage and click the Dashboard button. If you’re not signed in yet a sign-in dialog will open. Choosing any of the listed identity providers will take you to an authorization page and then redirect you to the dashboard. If you sign in via email you’ll receive a “magic” link via email so you don’t need a password. If you have a personal website you can also sign in with IndieAuth.

Adding a domain

CloudObjects organizes all objects into namespaces based on domains. You can add any of your domains, including subdomains, to CloudObjects, and you can also get one test domain based on your user ID (AAUID). While test domains cannot be used for publishing objects to the directory, for the purpose of this tutorial they are doing just fine. Simply go the the “Add a domain” page of your dashboard and click Enable Test Domain.

Installing the CLI Tool

phpMAE requires the CloudObjects CLI Tool to create object configurations on your behalf and upload the source code of your Micro APIs as object attachments to CloudObjects Core. To install, go to the CLI Tool page and follow the instructions under “Get Started”, which provide the commands for installing and authorizing the tool with your account.

Installing phpMAE locally

As of now the best way to get started with building and testing Micro APIs with phpMAE is to have a copy of phpMAE installed on your computer, and the recommended way to install phpMAE for this purpose is as a single file PHAR (PHp ARchive). You can download the PHAR file from phpMAE Releases on GitHub.

After download you can immediately run phpMAE commands through php phpmae.phar from the directory to which you’ve downloaded it. It’s much more comfortable however to have phpMAE available as a simple phpmae command everywhere on your computer. To enable this, execute the following two commands from a terminal in the directory to which you’ve downloaded phpmae.phar:

cp phpmae.phar /usr/local/bin/phpmae
chmod +x /usr/local/bin/phpmae

Note that these commands work on macOS and Linux only. You may have to prefix them with sudo. Currently we do not provide a way to get a global install on Windows-based computer. For some Linux distributions you may have to provide a different path instead of /usr/local/bin.

Create a MicroAPI controller

phpMAE provides two types of Micro APIs, functions and controllers. Controllers are based on Silex controller providers and allow you to define multiple API operations. Functions are a simpler way to build Micro APIs with a single POST endpoint and are useful e.g. for webhooks. In this tutorial we’ll build a controller.

Controllers are objects in CloudObjects Core with the phpmae:ControllerClass type and are uniquely identified with COIDs (Cloud Object IDentifiers). COIDs are namespaced, so you’ll need the name of the test domain you’ve enabled previously, which you can copy and paste from the dashboard.

Create a directory in which you want to store the source code and configuration of your controller locally, then navigate to this directory in a command prompt. Let’s create a controller called MyTestController at version 0.1 by entering the following command - replacing XXXX.aauid.net with your actual test domain:

phpmae controller:create --confjob=true coid://XXXX.aauid.net/MyTestController/0.1

You’ll notice that two files have been created in your directory, MyTestController.0.1.xml and MyTestController.0.1.php. The .xml file contains the basic object description for CloudObjects in RDF/XML format; this file is managed by phpMAE and rarely needs to be edited manually. The .php file contains the skeleton code for the PHP class, and this is where our API’s implementation code goes.

Open MyTestController.0.1.php in your favorite editor or IDE. If you’ve ever worked with Silex - or even just similar microframeworks such as Slim or Lumen - you’ll immediately feel at home: Routes are added by calling a method on a framework object and the implementation code goes into a closure.

We’ll create a simple “Hello Name” route which simply echoes back a path segment from the URL. Locate the line which says // Add methods here ... and replace it with the following code:

$controllers->get('/hello/{name}', function($name) {
    return "Hello ".$name.", nice to see you :)";
});

Test the controller locally

Open a second command tab or window and enter the following line to start a test environment:

phpmae testenv:start

Go back to the first tab and push your controller into the test environment - replacing the domain as before:

phpmae controller:testenv coid://XXXX.aauid.net/MyTestController/0.1

If you have any coding errors they will be shown to you and you need to fix them before continuing. If everything is fine you’ll see a success message and a test environment URL. This URL is the base URL to your controller so you have to add your route and path parameter to it. You can now test with curl directly from your command line - again replacing the domain (and also my name with yours, if you want):

curl http://localhost:9000/run/XXXX.aauid.net/MyTestController/0.1/hello/Lukas

The same URL also works in your favorite browser.

Deploy and test the controller in the cloud

Deploy your code with a single command:

phpmae controller:deploy coid://XXXX.aauid.net/MyTestController/0.1

What this command does under the hood is call the CloudObjects CLI Tool to add the source code file as an attachment to the object representing your controller and update the configuration. You’ll notice that the command shows you the URL to access your controller in our hosted phpMAE instances as well as the required authentication information. At the time of writing it is required to provide authentication with every call to your deployed controller, however we’ll add and document the option to make controllers publicly accessible very soon.

Next, run the command which is shown to you for getting the secret value. It will look something like this:

cloudobjects domain-providers:secret XXXX.aauid.net phpmae.cloudobjects.io

Now you can finally call your API:

curl https://XXXX.aauid.net:SECRET@phpmae.cloudobjects.io/run/XXXX.aauid.net/MyTestController/0.1/hello/Lukas

Congratulations, you have just deployed and tested your first serverless PHP code! Note that the authentication information has been provided as part of the URL. Feel free to experiment and add more routes to your controller. What about a route to return a message in JSON instead of plain text?

$controllers->get('/helloJson/{name}', function($name) use ($app) {
    return $app->json([ 'message' => "Hello ".$name.", nice to see you :)" ]);
});

Run phpmae controller:testenv to test your changes locally and phpmae controller:deploy to publish your changes to the cloud whenever you’re ready. Just be aware that, because there’s short-lived caching in CloudObjects Core and on phpMAE instances, it can take around a minute for your changes to go live. Happy coding and deploying!

Questions?

Leave your questions as comments on this blog post below or join our chat on Gitter. Make sure to stay tuned to this blog and @CloudObjectsIO on Twitter for future announcements and more tutorials about phpMAE.

by Lukas Rosenstock

Show Disqus Comment Thread
Privacy Notice: Your IP address will be sent to Disqus when you enable comments.