Building The Image Controller

Welcome to the fourth lesson of our course on building an image generation service with PHP! So far, we've built several key components of our application: the PromptManager for formatting user inputs, the ImageManager for storing and processing images, and the ImageGeneratorService that connects to the Gemini API to generate images.

Now, we're ready to add another important layer to our application architecture: the controller. In web applications, controllers play a crucial role in the Model-View-Controller (MVC) pattern. They act as intermediaries between the service layer (which contains our business logic) and the presentation layer (which handles user interactions).

The controller's primary responsibilities include:

• Receiving and validating input from the user interface
• Calling the appropriate service methods with validated inputs
• Handling errors that might occur during processing
• Formatting responses in a consistent way before sending them back to the user

In our image generation application, the controller will receive text prompts from users, validate them, pass them to our ImageGeneratorService, and then format the responses (either successful image data or error messages) before sending them back to the client.

By adding this controller layer, we're further improving the separation of concerns in our application. The service layer can focus purely on business logic (generating images via the Gemini API), while the controller handles the specifics of HTTP requests and responses. This makes our code more maintainable, testable, and easier to extend in the future.

Let's start by creating our controller class. We'll create a new file called ImageGeneratorController.php in the app/controllers directory. This controller will depend on our ImageGeneratorService to perform the actual image generation.

Here's how we'll set up the basic structure of our controller:

<?php

require_once 'services/ImageGeneratorService.php';

class ImageGeneratorController {
    private $imageGeneratorService;

    public function __construct() {
        $this->imageGeneratorService = new ImageGeneratorService();
    }
}

In this code, we're requiring the ImageGeneratorService class that we created in the previous lesson.

The controller's __construct initializes an instance of the ImageGeneratorService. This establishes the dependency between our controller and service layers. By creating this dependency in the constructor, we're following the principle of dependency injection, which makes our code more modular and easier to test.

Our controller will be responsible for two main operations:

1. Generating a new image based on user input
2. Retrieving all previously generated images

For each of these operations, we'll create a dedicated method in our controller class. These methods will handle input validation, error handling, and response formatting, ensuring that our API provides a consistent interface to clients.

Now, let's implement the method for generating images. This method will receive user input, validate it, call the service to generate an image, and format the response:

public function generateImage($userInput, $aspectRatio)
{
    if (empty($userInput)) {
        return ['error' => 'Missing input', 'status_code' => 400];
    }
    
    try {
        $base64Image = $this->imageGeneratorService->generateImage($userInput, $aspectRatio);
        return ['image' => $base64Image];
    } catch (\Exception $e) {
        return ['error' => $e->getMessage(), 'status_code' => 500];
    }
}

Let's break down what's happening in this method:

First, we check if the $userInput is empty. If it is, we return an error response with a 400 status code (Bad Request), indicating that the client provided invalid input. The response is an associative array with an 'error' key containing a descriptive message.

If the input is valid, we enter a try-catch block. Within the try block, we call the generateImage method of our service, passing the user input and the aspect ratio. This method will format the prompt, call the Gemini API's generateContent endpoint using gemini-3.1-flash-image, and return the base64-encoded image data extracted from the response.

If the image generation is successful, we return an associative array with an 'image' key containing the base64 string and a status code of 200 (OK).

If an Exception occurs during image generation, we catch it in the catch block and return an error response with a 500 status code (Internal Server Error). The response includes the error message from the exception.

Notice how we're using HTTP status codes to indicate the nature of the response. This is a standard practice in RESTful APIs:

• 200: Success
• 400: Client error (invalid input)
• 500: Server error (something went wrong on our end)

By returning both a response body and a status_code, we provide clients with all the information they need to handle the response appropriately.

Next, let's implement the method for retrieving all previously generated images:

public function getImages()
{
    $images = $this->imageGeneratorService->getAllImages();
    return ['images' => $images];
}

This method is simpler than the previous one because it doesn't require input validation. We simply call the getAllImages method of our service, which returns a list of all stored images. Keep in mind that this approach loads all images into memory, which may become inefficient as the dataset grows. For production-grade systems, consider adding basic pagination (e.g., limit and offset parameters) to reduce payload size and memory usage.

We then use PHP's json_encode function to convert the list of images into a JSON response. The json_encode function converts PHP arrays and objects into JSON format.

The response is an associative array with an 'images' key containing the list of image objects. Each image object includes an id, the prompt used to generate it, and the base64-encoded image data.

Unlike the generateImage method, we don't need to handle exceptions here because the getAllImages method doesn't involve Gemini API calls or complex processing that might fail. However, in a more robust implementation, you might still want to add error handling for unexpected scenarios.

With these two methods, our controller provides a complete interface for clients to generate images and retrieve previously generated ones. The controller abstracts away the details of how images are generated and stored, presenting a clean, consistent API to clients.

To ensure that our images are not lost when the application restarts, we need to store them in a database. This involves creating a database table and an Eloquent model, and updating our ImageManager to interact with the database.

First, we'll create a migration for the images table. This table will have fields for id, prompt, and image_base64:

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreateImagesTable extends Migration
{
    public function up()
    {
        Schema::create('images', function (Blueprint $table) {
            $table->id();
            $table->text('prompt');
            $table->longText('image_base64');
            $table->timestamps();
        });
    }

    public function down()
    {
        Schema::dropIfExists('images');
    }
}

Next, we'll create an Eloquent model for the Image entity. This model will represent the images table in our application:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Image extends Model
{
    use HasFactory;

    protected $fillable = ['prompt', 'image_base64'];
}

Finally, we'll update the ImageManager class to store and retrieve images from the database:

<?php

namespace App\Models;

class ImageManager
{
    public function addImage(string $prompt, $imageBase64): string
    {
        Image::create([
            'prompt' => $prompt,
            'image_base64' => $imageBase64
        ]);

        return $imageBase64;
    }
    
    public function getImages(): array
    {
        return Image::all()->toArray();
    }
}

In this updated ImageManager, the addImage method creates a new record in the images table, and the getImages method retrieves all records from the table.

Now that we've implemented our controller, let's validate it to make sure it works correctly. We'll create a simple PHP script to use the new controller:

require_once 'controllers/ImageGeneratorController.php';

$controller = new ImageGeneratorController();

// Simulate image generation
try {
    $response = $controller->generateImage("Luxury Tech Conference 2025", "16:9");
    if (isset($response['error'])) {
        echo "Error: " . $response['error'] . "\n";
    } else {
        echo "Generated Image:\n";
        echo $response['image'] . "\n";
    }
} catch (Exception $e) {
    echo "Error generating image: " . $e->getMessage() . "\n";
}

// Retrieve all images through the controller
$allImagesResponse = $controller->getImages();
echo "\nAll Images via Controller:\n";
echo json_encode($allImagesResponse) . "\n";

In this test script, we're creating an instance of our ImageGeneratorController and using it to perform two operations:

First, we call the generateImage method with a sample prompt and aspect ratio. The controller validates the input and delegates to the ImageGeneratorService, which triggers the Gemini image generation flow by calling the generateContent endpoint with gemini-3.1-flash-image. We check if the response contains an 'error' key, which would indicate that something went wrong. If there's no error, we print the base64-encoded image data extracted from the Gemini response.

Then, we call the getImages method to retrieve all stored images. We print the JSON representation of the $allImagesResponse, which includes all previously generated images.

When running this script, you would see output similar to:

Generated Image:
/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a...

All Images via Controller:
{"images":[{"id":1,"prompt":"Luxury Tech Conference 2025","image_base64":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a..."}]}

The base64 string would be much longer in a real application, but it's truncated here for readability. This string represents the encoded image data returned by the Gemini API, which can be used directly in an HTML <img> tag.

Let's also test the error handling by trying to generate an image with an empty prompt:

// Test error handling with empty input
$emptyResponse = $controller->generateImage("", "1:1");
echo "\nEmpty Input Test:\n";
echo "Status Code: " . $emptyResponse['status_code'] . "\n";
echo "Response: " . json_encode($emptyResponse) . "\n";

This would produce output like:

Empty Input Test:
Status Code: 400
Response: {"error":"Missing input","status_code":400}

This confirms that our controller correctly validates input and returns appropriate error responses with status_code values.

In this lesson, we've built the ImageGeneratorController, which serves as an intermediary between our service layer and the future PHP routes. This controller handles input validation, error management, and response formatting, providing a clean, consistent interface for clients to interact with our Gemini-powered image generation service.

Let's review what we've learned:

1. We understood the role of controllers in the MVC architecture and how they fit into our application.
2. We created a controller class that depends on our ImageGeneratorService.
3. We implemented methods for generating images and retrieving previously generated ones.
4. We added input validation and error handling to ensure robust operation.
5. We integrated database storage for images, ensuring they persist across application restarts.
6. We tested our controller to verify that it correctly triggers the Gemini image generation flow and handles responses.

The ImageGeneratorController is a crucial component of our application architecture. It abstracts away the details of how images are generated via the Gemini API and stored, presenting a clean, consistent API to clients. This separation of concerns makes our code more maintainable, testable, and easier to extend.

In the next lesson, we'll integrate our controller with PHP routes to create a complete web API for image generation. We'll define endpoints that clients can call to generate images and retrieve previously generated ones.

In the upcoming practice exercises, you'll have the opportunity to work with the ImageGeneratorController, testing its functionality with different inputs and exploring how it handles various scenarios. You'll also get to experiment with error handling and see how the controller formats responses for different types of requests.

With the ImageGeneratorController in place, we're one step closer to having a complete Gemini-powered image generation web application. In the next lesson, we'll see how to expose our controller's functionality through HTTP endpoints using PHP.