File Upload APIs

# CHAPTER 22

File Upload APIs #

1. Introduction #

2. Learning Objectives #

• Understand the multipart/form-data Content-Type.

• Process incoming file uploads using the PHP $_FILES superglobal.

• Validate file types (MIME types) and file sizes securely.

• Generate unique filenames to prevent overwriting existing files.

• Return the URL of the newly uploaded file in the JSON response.

3. Beginner-Friendly Explanation #

In HTTP, JSON is the letter. A file upload is the package. To send a package, the client must change the Content-Type header to multipart/form-data. When the PHP server receives this package, it puts it in a temporary holding room (/tmp). Your PHP script must examine the package, make sure it isn't dangerous (like a bomb/virus), and then move it to a permanent storage shelf (/uploads folder).

4. Real-World Examples #

• Instagram API: When you upload a photo, the app sends the binary image data to the server. The server saves the image to an Amazon S3 bucket and saves the *URL of the image* in the MySQL database.

• Slack API: Uploading a PDF document to a chat channel.

5. Detailed Code Examples #

<?php
// Endpoint: POST /api/upload-avatar

// 1. Check if a file was actually uploaded
if (!isset($_FILES[&#039;avatar']) || $_FILES['avatar']['error'] !== UPLOAD_ERR_OK) {
    http_response_code(400);
    echo json_encode(["error" => "No file uploaded or upload error occurred."]);
    exit;
}

$file = $_FILES[&#039;avatar'];

// 2. Validate File Size (e.g., max 2MB)
if ($file[&#039;size'] > 2 * 1024 * 1024) {
    http_response_code(400);
    echo json_encode(["error" => "File too large. Maximum size is 2MB."]);
    exit;
}

// 3. Validate MIME Type (Never trust the file extension!)
$finfo = finfo_open(FILEINFO_MIME_TYPE);
$mimeType = finfo_file($finfo, $file[&#039;tmp_name']);
finfo_close($finfo);

$allowedMimes = [&#039;image/jpeg', 'image/png', 'image/gif'];
if (!in_array($mimeType, $allowedMimes)) {
    http_response_code(400);
    echo json_encode(["error" => "Invalid file type. Only JPG, PNG, and GIF are allowed."]);
    exit;
}

// 4. Generate a unique filename and move the file
$extension = pathinfo($file[&#039;name'], PATHINFO_EXTENSION);
$newName = uniqid(&#039;avatar_', true) . '.' . $extension;
$destination = __DIR__ . &#039;/uploads/' . $newName;

if (move_uploaded_file($file[&#039;tmp_name'], $destination)) {
    // 5. Success! Return the URL
    $fileUrl = "https://api.example.com/uploads/" . $newName;
    http_response_code(201);
    echo json_encode([
        "message" => "File uploaded successfully",
        "url" => $fileUrl
    ]);
} else {
    http_response_code(500);
    echo json_encode(["error" => "Failed to save file."]);
}
?>

6. Request/Response Examples #

1. 1. Method: POST

1. 2. Body Tab -> Select form-data

1. 3. Key: avatar (Change type from Text to File)

1. 4. Value: Select an image from your computer.

Response:

{
  "message": "File uploaded successfully",
  "url": "https://api.example.com/uploads/avatar_60a8f9b9a1.jpg"
}

7. HTTP Examples #

POST /api/upload-avatar HTTP/1.1
Host: api.example.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="avatar"; filename="my_photo.jpg"
Content-Type: image/jpeg

[... RAW BINARY IMAGE DATA HERE ...]
------WebKitFormBoundary7MA4YWxkTrZu0gW--

8. JSON Examples #

1. 1. Send everything as multipart/form-data (PHP will put the text in $POST and the file in $FILES).

1. 2. Do it in two steps: Upload the file first (returns the URL), then send a standard JSON POST request containing the URL and the text caption. (This is the preferred modern approach).

9. Best Practices #

• Never trust the extension: A hacker can rename virus.php to virus.jpg and bypass extension checks. Always use PHP's finfofile() to read the actual binary signature (MIME type) of the file.

• uploadmaxfilesize in php.ini: PHP has a strict server-level limit on upload sizes (usually 2MB by default). If a user uploads a 5MB file, $FILES will be empty and PHP will throw a silent error unless you change your php.ini configuration.

11. Mini Exercises #

1. 1. If you are uploading a CSV file, what Content-Type header must your API client use?

12. Coding Challenges #

13. MCQs with Answers #

14. Interview Questions #

• Q: Describe the steps required to securely handle a file upload in a PHP API.

• Q: Explain the difference between application/json and multipart/form-data.

• Q: How do you securely validate that an uploaded file is truly an image and not a malicious script?

15. FAQs #

16. Summary #

17. Next Chapter Recommendation #