Debian PHP API Development Guide

This guide provides a step-by-step approach to setting up a PHP API development environment on Debian, along with best practices for building robust, secure, and maintainable APIs.

1. Environment Setup

Install PHP and Required Extensions

PHP is the core language for API development. On Debian, install PHP (version 7.3 or higher recommended) and essential extensions for database connectivity, JSON processing, and performance:

sudo apt update
sudo apt install php php-cli php-fpm php-json php-mysql php-curl php-gd php-mbstring php-xml php-bcmath

These extensions enable features like MySQL database interactions (php-mysql), RESTful API routing (php-curl), and JSON response handling (php-json).

Configure a Web Server

Choose between Apache (simpler setup) or Nginx (better performance) as your web server.

For Apache:

Install Apache and the PHP module, then enable them:

sudo apt install apache2 libapache2-mod-php
sudo systemctl start apache2
sudo systemctl enable apache2

For Nginx:

Install Nginx and PHP-FPM (FastCGI Process Manager), then configure Nginx to pass PHP requests to PHP-FPM. Create a new configuration file (e.g., /etc/nginx/sites-available/api) with these directives:

server {
    listen 80;
    server_name your_domain.com;
    root /var/www/api;
    index index.php index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock; # Adjust for your PHP version
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

Enable the site and restart Nginx:

sudo ln -s /etc/nginx/sites-available/api /etc/nginx/sites-enabled/
sudo nginx -t  # Test configuration
sudo systemctl restart nginx

Install Composer (PHP Dependency Manager)

Composer manages PHP dependencies (e.g., frameworks like Laravel). Install it globally:

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

2. Basic API Development (Without Framework)

For simple APIs, you can use plain PHP. Follow these steps:

Create an API File

Place a PHP file (e.g., api.php) in your web root (e.g., /var/www/api). Set the response content type to JSON and define a basic endpoint:

<?php
header('Content-Type: application/json; charset=utf-8');

// Sample data (replace with database calls)
$users = [
    1 => ['id' => 1, 'name' => 'John Doe', 'email' => 'john@example.com'],
    2 => ['id' => 2, 'name' => 'Jane Smith', 'email' => 'jane@example.com']
];

// Get request method and parameters
$method = $_SERVER['REQUEST_METHOD'];
$id = isset($_GET['id']) ? intval($_GET['id']) : null;

// Handle GET requests
if ($method === 'GET') {
    if ($id) {
        $user = $users[$id] ?? null;
        echo json_encode(['data' => $user ?: ['error' => 'User not found'], 'status' => 200]);
    } else {
        echo json_encode(['data' => array_values($users), 'status' => 200]);
    }
} else {
    echo json_encode(['error' => 'Method not allowed', 'status' => 405]);
}

This script handles GET requests to retrieve all users or a specific user by ID, returning JSON responses.

Test the API

Use curl or tools like Postman to test the endpoint:

curl http://your_domain.com/api.php
curl http://your_domain.com/api.php?id=1

You should receive a JSON response with user data.

3. Advanced API Development (With Laravel)

For complex APIs, use the Laravel framework (follows MVC architecture and provides built-in tools for routing, authentication, and validation).

Install Laravel

Create a new Laravel project using Composer:

composer create-project --prefer-dist laravel/laravel your_project_name
cd your_project_name

Laravel includes an Artisan CLI for managing tasks like route generation and database migrations.

Configure the Database

Edit the .env file to set up your database connection (replace placeholders with your credentials):

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password

Run migrations to create database tables (Laravel includes default migrations for users and password resets):

php artisan migrate

Create a new table (e.g., products) with a migration:

php artisan make:migration create_products_table

Edit the migration file (in database/migrations/) to define the schema, then run php artisan migrate.

Create API Routes

Define API routes in routes/api.php. For example, to create a route for retrieving all products:

use App\Http\Controllers\API\ProductController;

Route::get('/products', [ProductController::class, 'index']);

This maps the /api/products endpoint to the index method in ProductController.

Create a Controller

Generate a controller to handle API logic:

php artisan make:controller API/ProductController --api

The --api flag creates a controller without unnecessary methods (e.g., views). Add logic to the index method:

namespace App\Http\Controllers\API;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use App\Models\Product;

class ProductController extends Controller
{
    public function index()
    {
        $products = Product::all();
        return response()->json(['data' => $products, 'status' => 200]);
    }
}

This retrieves all products from the database and returns them as JSON.

Test the API

Start Laravel’s development server:

php artisan serve

Test the endpoint with curl or Postman:

curl http://localhost:8000/api/products

You should receive a JSON response with product data.

4. Best Practices for PHP API Development

Follow RESTful Conventions

Use standard HTTP methods (GET, POST, PUT, DELETE) to perform CRUD operations. Structure URLs to represent resources (e.g., /api/users for all users, /api/users/1 for a specific user).

Use Consistent Response Formats

Return JSON responses with a uniform structure:

{
    "code": 200,
    "message": "Success",
    "data": {
        "id": 1,
        "name": "John Doe"
    }
}

This makes it easier for frontend developers to parse responses.

Implement Authentication and Authorization

Secure your API using token-based authentication (e.g., JWT) or OAuth. Laravel provides built-in support for Passport (OAuth2) and Sanctum (API tokens). For example, to protect a route with Sanctum:

Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
    return $request->user();
});

This ensures only authenticated users can access the /user endpoint.

Validate Input Data

Use Laravel’s request validation or manual checks to prevent invalid or malicious input. For example, to validate a POST request for creating a product:

public function store(Request $request)
{
    $validated = $request->validate([
        'name' => 'required|string|max:255',
        'price' => 'required|numeric|min:0'
    ]);

    $product = Product::create($validated);
    return response()->json(['data' => $product, 'status' => 201]);
}

This ensures the name and price fields are present and valid before creating a product.

Handle Errors Gracefully

Use try-catch blocks to catch exceptions and return meaningful error messages. For example:

public function show($id)
{
    try {
        $product = Product::findOrFail($id);
        return response()->json(['data' => $product, 'status' => 200]);
    } catch (\Illuminate\Database\Eloquent\ModelNotFoundException $e) {
        return response()->json(['error' => 'Product not found', 'status' => 404], 404);
    }
}

This returns a 404 status code and error message if the product is not found.

Optimize Performance

Use caching (e.g., Redis, Memcached) to reduce database load and improve response times. For example, cache the result of a frequently accessed query:

public function index()
{
    $products = Cache::remember('products', 60, function () {
        return Product::all();
    });
    return response()->json(['data' => $products, 'status' => 200]);
}

This caches the products for 60 seconds, reducing the number of database queries.

Document Your API

Use tools like Swagger (via Laravel Swagger packages) or Postman to generate API documentation. Documentation helps frontend developers understand how to use your API and reduces integration time.

By following this guide, you can set up a PHP API development environment on Debian and build secure, scalable, and maintainable APIs using either plain PHP or the Laravel framework.