CloudObjects / Blog / Launching phpMAE 1.0.0

Launching phpMAE 1.0.0

After a long time with no release, phpMAE 1.0.0 is now finally ready for you to test! While this version still follows the basic ideas outlined in “The Micro API Design Pattern”, it is a breaking change from the previous version (0.2). I will elaborate on those changes in a future article on this blog, but this tutorial is targeted at beginners and will assume you’ve never heard of phpMAE anyway.

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 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. As of now, hosting is free for developers for testing and evaluation purposes!

This article is a hands-on tutorial because I believe you should experience rather than just hear or read about it. 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 for CloudObjects. It’s free and fast, especially when you use an existing third-party account, such as your GitHub 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 in your inbox, 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 this tutorial they are doing just fine. Go to 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 phpMAE classes 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

The best way to get started 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 latest PHAR file from phpMAE Releases on GitHub.

After download, you can immediately run phpMAE commands through php phpmae.phar from the directory where you’ve downloaded it. It’s handy, however, to have phpMAE available as a global 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:

mv 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 computers. For some Linux distributions, you may have to give a different path instead of /usr/local/bin.

Create a phpMAE Class

On the surface, a phpMAE class is just a basic PHP file that contains a class definition. The implementation of each class can use a whitelisted subset of PHP functions and whitelisted classes from a set of composer packages. It can also have dependencies on other phpMAE classes and other objects from the CloudObjects directory, but we will touch upon those another time. The phpMAE exposes every public method from the class through JSON-RPC (with other ways of calling it a added in the future).

Classes are objects in CloudObjects Core with the phpmae:Class 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 class locally, then navigate to this directory in a command prompt. Let’s create one called MyTestClass at version 0.1 by entering the following command - replacing XXXX.aauid.net with your actual test domain:

phpmae class:create --confjob coid://XXXX.aauid.net/MyTestClass/0.1

You’ll notice that two files have been created in your directory, MyTestClass.0.1.xml and MyTestClass.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 MyTestClass.0.1.php in your favorite editor or IDE, and you’ll see an empty PHP class called MyTestClass.

We’ll create a helloName() function which does nothing special except echoing a parameter from the request. Locate the line which says // Add methods here ... and replace it with the following code:

    function helloName($name) {
        return "Hello ".$name.", nice to see you :)";
    }

Test the Class 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 class into the test environment - replacing the domain as before:

phpmae class:testenv coid://XXXX.aauid.net/MyTestClass/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. You can send a JSON-RPC request to this URL. First, we’ll do this with the phpMAE CLI:

phpmae class:testenv-rpc coid://XXXX.aauid.net/MyTestClass/0.1 helloName Alice

Make sure to replace XXXX.aauid.net with your test domain and try with various names other than Alice.

Of course, you’re not reliant on the phpMAE CLI, you can also make requests with a generic HTTP client such as curl (which comes preinstalled on most operating systems):

curl -d '{ "jsonrpc" : "2.0", "id" : 0, "method" : "helloName", "params" : [ "Alice" ] }' \
    http://localhost:9000/XXXX.aauid.net/MyTestClass/0.1

The JSON-RPC request specification will help you understand the format of this request.

Deploy and test the Class in the cloud

Deploy your code with the following single command:

phpmae class:deploy coid://XXXX.aauid.net/MyTestClass/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 class and update the configuration. You’ll notice that the command shows you the URL to access your class in our hosted phpMAE instances as well as the required authentication information (we’ll explain how to make public phpMAE classes that require no authentication in a future post).

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 -d '{ "jsonrpc" : "2.0", "id" : 0, "method" : "helloName", "params" : [ "Alice" ] }' \
    https://XXXX.aauid.net:SECRET@phpmae.cloudobjects.io/XXXX.aauid.net/MyTestClass/0.1

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 modify this function or add other functions to your class.

If you’ve made changes, run phpmae class:testenv to test them locally and phpmae class: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?

Please 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.