Building Image Manager

Welcome to the second lesson of our course on building an image generation service with PHP. In our previous lesson, we created the PromptManager class to handle the formatting of prompts for our image generation process. Now, we'll build upon that foundation by creating the ImageManager class, which will be responsible for handling the images once they're generated.

The ImageManager serves as a crucial component in our application architecture. While the PromptManager prepares the instructions for image generation, the ImageManager takes care of what happens after an image is created. Its primary responsibilities include:

1. Storing generated images along with their associated prompts
2. Converting images to a web-friendly format (base64)
3. Providing access to the collection of stored images

This component is essential because web applications cannot directly work with raw image data. By converting images to base64 strings, we can easily embed them in HTML or send them as JSON responses in our API. Additionally, keeping track of which prompt generated which image allows us to maintain a history of generations and potentially reuse successful prompts.

In the next lesson, we'll call the Gemini API using the generateContent flow with gemini-3.1-flash-image to actually produce images, and the ImageManager will take care of everything that happens after that.

Let's dive into building this important piece of our image generation service.

To begin, we'll create a new file called ImageManager.php in our app/models directory. This file will contain our ImageManager class. First, let's set up the basic structure and understand the imports we'll need:

<?php

class ImageManager {
    private $images = [];

    public function __construct() {
        $this->images = [];
    }
}

Our ImageManager class starts with a simple constructor that initializes an empty array called $images. This array will store associative arrays containing information about each image, including:

• A unique identifier
• The prompt that generated the image
• The base64-encoded image data

This simple data structure allows us to keep track of all generated images and their associated metadata in memory. In a production application, you might want to use a database instead, but for our learning purposes, this in-memory storage works well.

One of the key functions of our ImageManager class is to convert image data into a format that can be easily used in web applications. Base64 encoding is perfect for this purpose as it transforms binary data into a string of ASCII characters that can be included directly in HTML or JSON.

For example, you can embed a base64-encoded image directly into an HTML <img> tag using the src="data:image/jpeg;base64,..." format. This avoids having to serve the image as a separate static file, which simplifies delivery for small-scale applications or APIs that return dynamic image content. However, note that this technique is inefficient for large images or high-volume applications due to increased payload size and rendering time.

Let's implement the imageToBase64 method:

public function imageToBase64($imageData) {
    try {
        $image = imagecreatefromstring($imageData);
        ob_start();
        imagejpeg($image);
        $imageContents = ob_get_clean();
        return base64_encode($imageContents);
    } catch (Exception $e) {
        throw new RuntimeException("Error processing image: " . $e->getMessage());
    }
}

This method takes $imageData as input, which will be the raw image bytes extracted from the Gemini API response — not the full response object itself. The Gemini API returns structured content, and the next lesson will handle parsing that response and pulling out the binary image data before passing it here. Let's walk through what's happening inside the method:

1. We use imagecreatefromstring() to create an image resource from the raw image bytes.
2. We start output buffering with ob_start() to capture the image output.
3. We save the image as a JPEG to the output buffer.
4. We get the contents of the buffer and clean it with ob_get_clean().
5. We encode the buffer's contents as base64.
6. If any errors occur during this process, we catch them and raise a more informative RuntimeException.

The error handling is particularly important here because image processing can fail for various reasons, such as corrupted image data or memory issues. By catching exceptions and providing clear error messages, we make debugging much easier.

While base64 encoding is convenient for embedding images in small-scale applications, it is worth noting that it increases file size by approximately 33%. In large-scale or high-performance applications, serving images from a CDN or file server is more efficient.

Now that we can convert images to base64, let's implement the methods for adding images to our collection and retrieving the stored images.

public function addImage($prompt, $imageData) {
    $imageBase64 = $this->imageToBase64($imageData);
    $imageEntry = [
        "id" => count($this->images),
        "prompt" => $prompt,
        "image_base64" => $imageBase64
    ];
    $this->images[] = $imageEntry;
    return $imageBase64;
}

This method performs several important tasks:

1. It calls our imageToBase64 method to convert the image data to a base64 string.
2. It creates an associative array (called $imageEntry) containing:
   • An id based on the current length of the $images array (ensuring each image gets a unique identifier)
   • The prompt that was used to generate the image
   • The base64-encoded image data
3. It appends this array to our $images array.
4. It returns the base64 string, which can be immediately used by the caller if needed.

Here, $imageData is the binary image content obtained after parsing the Gemini generateContent response. The Gemini API returns a structured response object; the caller (which we'll build in the next lesson) is responsible for extracting the raw image bytes from that response before passing them into addImage.

public function getImages() {
    return $this->images;
}

This method simply returns the entire array of image entries, allowing other parts of our application to access all stored images and their associated metadata.

Now that we've implemented our ImageManager class, let's create a simple test script to verify that it works correctly. We'll create this in our app/main.php file:

<?php

require_once 'models/ImageManager.php';

$imageManager = new ImageManager();
$fakeImageData = "fake image data";  // Placeholder — real data will be binary image bytes extracted from the Gemini API response
$prompt = "Test prompt for ImageManager";

try {
    $result = $imageManager->addImage($prompt, $fakeImageData);
    echo "Image Added Successfully:\n";
    echo $result . "\n\n";
    echo "All Stored Images:\n";
    print_r($imageManager->getImages());
} catch (Exception $e) {
    echo "An error occurred: " . $e->getMessage();
}

In this test script, we:

1. Include our ImageManager.php class.
2. Create an instance of the ImageManager.
3. Define a placeholder for image data and a test prompt. In real usage, this variable will hold the binary image bytes decoded from the Gemini API's generateContent response — the next lesson will cover exactly how to extract that data.
4. Call the addImage method with our test data.
5. Print the $result and then retrieve and print all stored images.

When running this script with real image data, you would see output similar to:

Image Added Successfully:
/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a...

All Stored Images:
Array
(
    [0] => Array
        (
            [id] => 0
            [prompt] => Test prompt for ImageManager
            [image_base64] => /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a...
        )
)

The base64 string would be much longer in a real application, but I've truncated it here for readability.

In this lesson, we've built the ImageManager class, a crucial component of our image generation service. This class handles the storage and processing of generated images, converting them to a web-friendly format and maintaining a collection of all images along with their associated prompts.

Let's review what we've learned:

1. We created a class structure with a simple in-memory storage mechanism.
2. We implemented a method to convert image data to base64 format, making it suitable for web applications.
3. We built methods to add images to our collection and retrieve all stored images.
4. We created a simple test script to verify the functionality of our ImageManager.

The ImageManager complements the PromptManager we built in the previous lesson. While the PromptManager prepares the instructions for image generation, the ImageManager handles the results of that generation process. Together, these components form the foundation of our image generation service.

In the upcoming practice exercises, you'll have the opportunity to work with the ImageManager class, testing its functionality with different types of image data and exploring how it integrates with the rest of our application. You'll also get to experiment with error handling and see how the class behaves in various scenarios.

In our next lesson, we'll build upon this foundation by implementing the ImageGeneratorService, which will call the Gemini generateContent API using gemini-3.1-flash-image to generate images based on our prompts, then extract the binary image bytes from the response and pass them into the ImageManager. This service will bring together both the PromptManager and ImageManager classes we've created so far.