What are we going to cover?

In this article, we're going to learn how to work with the framework as a whole by writing a real-world application: making a module, controller, routes, templates (views) and services. In order to achieve this we are will use the Foursquare API, and APC for caching the API lookups. We will plot venues from Foursquare in Google Maps for display.

What functionality will we achieve?

The purpose of this module is to place Foursquare venues on a Google Map based on your current location as a user.

If you are as desperate to try this out as we are, and want to see the code instead of reading the article, you can grab the actual module here: https://github.com/ppi/foursquare-tutorial-module.

Preparing the skeleton app

We assume that you have already set up the skeleton application (details here) and that you have the credentials for the Foursquare API (If not, grab them here: https://developer.foursquare.com).

Creating the Foursquare Module

First of all, let's create the Foursquare module. For that, open your terminal, change to your ppi skeleton app’s directory and run the following command:

This will ask you to confirm the modules directory path. Just press enter and you should see something like this:

Now update your ./app/modules.config.php file by adding FoursquareModule onto the end. It should look something like this:

Creating the Map

Adding the Route

First of all, we need to add a route. Go ahead and edit your ./modules/FoursquareModule/resources/config/routes.yml file

The Controller

Now, we are going to load the Map on our view, so edit your Controller's index action by updating the ./modules/FoursquareModule/Controller/Index.php file.

Creating the Views

Let's edit the ./modules/FoursquareModule/resources/views/index/index.html.php view file and add the following code:

Adding some style

We need to add a height and width for our Map container so go ahead and add the following CSS to the ./public/foursquare/css/index.css file:

Using the Google Maps API

Next, lets use the Google Maps API in order to show the map on our view, add the following Javascript to the ./public/foursquare/js/index.js file:

Now, you can point your browser to http://yourhost/foursquare-tutorial/public/foursquare/. You should see a page similar to Figure 1 below.

We are essentially loading a Google Map with geolocation enabled and you should hopefully be taken to where you live on the map with no Foursquare integration yet.

Figure 1 - Google Maps API

You can see a live demonstration of Figure 1 by clicking here

Setting up Foursquare: Adding Foursquare credentials

First, lets update our config.php file to store your Foursquare secure credentials to talk to the Foursquare API. So in your ./modules/FoursquareModule/resources/config/config.php file add the following code:

Replace the placeholders with your own Foursquare credentials.

Implementing the API calls

The majority of our work will not be done in a framework-specific layer, like a controller. It's will be in a generic PHP class which can be used from any part of the project. You can even take this class and use it in any PHP project as long as you pass in the dependencies it requires — such as config keys and the cache library. Read on to understand more.

In the following ApiHandler class we have pre-selected some random categoryids for you, so you can fetch some venues from Foursquare. In our getVenues() function we're making the calls to Foursquare's API and fetching the venues from a given location. We then store the results in our injected $this->cache object for later re-use.

Go ahead and create the file: ./modules/FoursquareModule/Classes/ApiHandler.php, and put the following contents into it:

Building our service

We're not going to directly access ApiHandler from our controller class, it's going to be set up as a service. In your ./modules/FourSquareModule/Module.php file's getServiceConfig() method add the following code:

Connecting the dots

The controller and routes

We need a route and corresponding controller action that can respond to the user's Ajax call once the Google Map loads. It will initiate API calls to Foursquare and return venues to be placed onto the map.

Here is our new route. Update your ./modules/FoursquareModule/resources/config/routes.yml file by adding:

Here is our updated controller with our new getVenuesAction() action. Update ./modules/FoursquareModule/Controller/Index.php replacing what is already in there:

Plotting the venues on a Google Map

That bit of Javascript code above is pretty simple. Here's what it does:

  1. Get the user's location if it can. If the browser doesn't have those capabilities then use a default location.
  2. Create a Map using the Google Maps API.
  3. Performs an Ajax call to the controller in order to fetch the venues, giving it lat/long coordinates.
  4. After getting a JSON object back from the Ajax call, process it and plot each venue on the map.

Now replace your ./public/foursquare/js/index.js file with the content of the following gist link:

As the size of the Javascript file is now very large we don't want to include it in this article. You can view it here

Let's make it happen!

Now browse to /foursquare/ in your application. This will trigger Foursquare_Index route and load the map for you. An Ajax call occurs in the background. Within a few seconds you'll see the markets drop onto the map. You should see something similar to Figure 2 shown below:

Figure 2 - Plotting Foursquare venues using the Google Maps API.

You can see a live demonstration of Figure 2 by clicking here

What have we learned so far?

To summarise, we have learned how to create and use the modules component. We also learned how to use services in order to encapsulate API code, and how to use them in our Controllers. We have learned how to render views, specify custom css/js templates within them and extend base views. We also learned how to integrate Javascript and run Ajax calls to a controller to get JSON responses back. Hopefully, this article clarifies the development workflow of the PPI framework, and gives you a starting point to improve your development skills in a structured, maintainable and simple way.


Here is a series of links that contain information supplementary to what we covered above: