Building a Pokémon API in PHP: A Beginner's Guide

In this guide, we will go through the steps to create a basic PHP project that uses the Pokémon API with the Flight framework and additional packages like Zebra_cURL and Latte. We will explore setting up the project, adding routes, and rendering views.

tl;dr: It's not hard to make a simple API based project in Flight. Check out the code used in this guide.

Step 1: Setting up the Environment

First, we need to set up a new project folder. Open your terminal, navigate to your desired location, and run the following commands to create a new directory and enter it.

mkdir flight-pokeapi
cd flight-pokeapi

Step 2: Installing Composer

Before we dive into the code, we need to make sure that Composer is installed. Composer is the dependency manager for PHP, and it will help us include the necessary libraries.

If you don’t have Composer installed, you can install it using:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
php -r "unlink('composer-setup.php');"

Now that Composer is installed in a current file called ./composer.phar, let’s manage our dependencies.

Step 3: Installing Dependencies

To manage the required packages, we just need to add them with composer.

./composer.phar require flightphp/core stefangabos/zebra_curl latte/latte

This will install:

• Flight PHP: A lightweight PHP framework.
• Zebra_cURL: A cURL wrapper to handle HTTP requests.
• Latte: A templating engine for rendering views.

Step 4: Setting Up index.php

Next, let’s create the entry point for our application: public/index.php. This file will set up our app, configure routes, and handle the rendering of views.

Create the public directory and the index.php file:

mkdir public
touch public/index.php

Now add the following content to index.php:

<?php

use flight\net\Router;
use Latte\Engine;

require __DIR__ . '/../vendor/autoload.php'; // Autoload the installed packages

// Setup Latte for view rendering
$Latte = new Engine;
$Latte->setTempDirectory(__DIR__ . '/../temp');
Flight::map('render', function(string $template_path, array $data = []) use ($Latte) {
  $Latte->render(__DIR__ . '/../views/' . $template_path, $data);
});

// Setup Zebra_cURL for handling HTTP requests
$Curl = new Zebra_cURL();
$Curl->cache(__DIR__ . '/../temp');
Flight::map('curl', function() use ($Curl) { 
    return $Curl; 
});

// Define a simple route
Flight::route('/', function() {
  echo 'hello world!';
});

Flight::start();

In this file:

• We load Composer’s autoloader.
• Set up Latte for rendering views.
• Map a custom render method that uses Latte to render templates from the /views folder.
• Set up Zebra_cURL to handle API requests and map it to use Flight::curl() when we want to invoke it.
• Define a simple route for the homepage (/) which just returns "hello world!"

If you want to test this setup, you can start a PHP server from the public directory:

php -S localhost:8000 -t public/

Now, visit http://localhost:8000/ in your browser, and you should see "hello world!". Cool eh?

Step 5: Adding Routes

Now that we have a basic route set up, let’s add a more complex route that uses the Pokémon API. Update public/index.php to include the following code:

Flight::group('/pokemon', function(Router $router) {
    // Route to list all Pokémon types
    $router->get('/', function() {
        $types_response = json_decode(Flight::curl()->scrap('https://pokeapi.co/api/v2/type/', true));
        $results = [];
        while ($types_response->next) {
            $results = array_merge($results, $types_response->results);
            $types_response = json_decode(Flight::curl()->scrap($types_response->next, true));
        }
        $results = array_merge($results, $types_response->results);
        Flight::render('home.latte', [ 'types' => $results ]);
    });
});

• We created a /pokemon route group. A route group "surrounds" the routes and allows us to define common functionality for all routes within the group.
• The /pokemon route lists all available Pokémon types by fetching them from the Pokémon API using Zebra_cURL.
• This won't work just yet as we need to add the home.latte view to display the Pokémon types.

Step 6: Rendering Views with Latte

Now that we are fetching data, let's set up views to display it. Create the views directory and add a Latte template file for displaying the Pokémon types.

mkdir views
touch views/home.latte

Add the following code to views/home.latte:

<p>Welcome to the Pokemon World!</p>

<p>Types of Pokemon</p>
<ul>
    {foreach $types as $type}
        <li><a href="/pokemon/type/{$type->name}">{$type->name|firstUpper}</a></li>
    {/foreach}
</ul>

In this file:

• We loop through the $types array passed from our route and display the name of each Pokémon type.

Now, visiting /pokemon will display a list of all Pokémon types!

Step 7: Grouping and Adding More Routes

Let's extend our Pokémon routes to fetch more details for specific types and individual Pokémon. Add the following routes to your /pokemon group:

// Route to fetch a specific Pokémon type and list all associated Pokémon
$router->get('/type/@type', function(string $type) {
    $Curl = Flight::curl();
    $type_response = json_decode($Curl->scrap('https://pokeapi.co/api/v2/type/' . $type, true));
    $pokemon_urls = [];
    foreach($type_response->pokemon as $pokemon_data) {
        $pokemon_urls[] = $pokemon_data->pokemon->url;
    }
    $pokemon_data = [];

    // The little & here is important to pass the variable by reference.
    // In other words it allows us to modify the variable inside the closure.
    $Curl->get($pokemon_urls, function(stdClass $result) use (&$pokemon_data) {
        $pokemon_data[] = json_decode($result->body);
    });

    Flight::render('type.latte', [ 
        'type' => $type_response->name,
        'pokemons' => $pokemon_data
    ]);
});

In this route, we:

• Fetch details for a specific Pokémon type, including all associated Pokémon.
• Send multiple API requests to fetch details for each Pokémon.
• Render the data using a template (type.latte).

Next, create the type.latte view:

touch views/type.latte

Add the following content to type.latte:

<h1>{$type|firstUpper}</h1>
<ul>
    {foreach $pokemons as $pokemon}
        <li><a href="/pokemon/{$pokemon->id}">{$pokemon->name|firstUpper}</a></li>
    {/foreach}
</ul>

This template displays the name of each Pokémon associated with a specific type.

Step 8: Does it work?

At this point, you have a basic Pokémon API consumer set up using Flight PHP, Zebra_cURL for API requests, and Latte for view rendering. You can further expand this project by adding more routes and refining the templates.

To view your project, start the PHP server from the public directory:

php -S localhost:8000 -t public/

Now, visit http://localhost:8000/pokemon in your browser, and you should see a list of Pokémon types.

Troubleshooting

If you need help or encounter issues, you can check the full code out in Github to see where you may have made a misstep.

Hopefully you enjoyed this little tutorial. If you have any questions or need help, feel free to ask in the comments below. Happy coding!