Getting started

First web services

This tutorial will help you create your first set of web services.

Get the code

The first thing you must do is to get a copy of phpREST. This can be achieved by either forking the repository, cloning it or simply downloading a zip with the files. I must recommend that you fork the repo if you are registered at github, because with a fork you can make your own commits and then make a pull request towards phpREST with your changes and this can make phpREST a better product.

Create a web area

Ok, so now we have downloaded a copy of the files. The next step is to put them on a web server so that the browser may access them. The web server I recommend is Apache, but other should work as well. The server must support PHP though. Create a folder under the web root (in linux this is often /var/www) and name it something. In this example we call it "api". So, inside the api folder we put a copy of the "rest" folder from phpREST.

Configure our web folder

This part is specifically for the Apache web server. If you're running something else, you must figure it out your self.

We need to make some web server configurations for our web folder. Inside the api folder we create a file called ".htaccess". This file will tell Apache how request towards this folder should be handled. The content of .htaccess should be this:

# Rewrite rule to enable use of forward slash
RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-s
RewriteCond %{REQUEST_FILENAME} !-l 
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_URI} !^/index\.php$
RewriteRule ^(.*)$ index.php/$1

# Set index file
DirectoryIndex index.php

# Remove indexing
Options -Indexes

We see a file called "index.php" named several times in this settings file. This will be our point of interest from now on.

Creating index.php

index.php should resist inside the api folder together with .htaccess. This file will have the responsibility of setting up the REST implementation.

The basic setup only need three lines of code:

<?php
require_once('rest/Server.php');
$server = new Server();
$server->handleRequest();
?>

The first line makes PHP include the main file of the phpREST library, the second line creates a new instance of phpREST and the third one tells phpREST to handle the request.

After this you may point you browser to http://localhost/api/ and you should see the default phpREST index page with an empty table of web services.

Making web services

Everything up to this has been setting up the base for making web services - boring stuff. Now it's time to add some content.

We start by adding a new file to the api folder; HelloService.php. This file will contain a hello service, the simplest example of web services and a cliche that I couldn't resist using.

The contents of HelloService.php will be this:

<?php
/** @Route('hello') */
class HelloService extends Service {
  /** @Get */
  function sayHello($name) {
    if ($name !== NULL) {
      echo 'Hello ' . $name;
    } else {
      echo 'Hello world';
    }
  }
}
?>

The first line of code introduces something new - annotations. Several annotations are available in phpREST and this one, the @Route, is a way to rename the endpoint for a service. If the @Route is omitted, the endpoint name will be the same as the class name.

The next line is the class header and we can see that it extends the Service class which is a part of phpREST.

Just before our service method we add another annotation; @Get. This annotation tells phpREST that this method should be available for GET requests only. Other choices are @Post, @Put, @Delete and @Any.

The service method itself is pretty straight forward. Arguments are set to NULL if omitted by the request, so we check to see if it's set by checking against NULL.

That's it. We have the first service in place, but wait. It doesn't show up in the list of web services! The next step is to register the service with the server. We go back to index.php and change the contents to this:

<?php
require_once('rest/Server.php');
require_once('HelloService.php');
$server = new Server();
$server->addService(new HelloService());
$server->handleRequest();
?>

We added two lines; the require_once to include our service file and the addService to make phpREST recognize our service. After this change, the HelloService should show in the service table of the index page and the link http://localhost/api/hello should work. To set the name, you can point you browser to http://localhost/api/hello/Vegard and the result should be "Hello Vegard".

404

If you should receive a 404 when trying to reach the service, this means apache is restricting the use of .htaccess and you must change the apache settings to allow our overrides by changing AllowOverride None to AllowOverride All for the web root (look for this in /etc/apache2/sites-enabled/000-default). Remember to reload apache settings after doing the change (/etc/init.d/apache2 reload).