Request Lifecycle

Relevant source files

The following files were used as context for generating this wiki page:

• public/index.php
• app/Providers/Filament/AdminPanelProvider.php
• tests/Feature/Api/ProductApiTest.php
• tests/Feature/Api/TagApiTest.php
• app/Filament/Resources/TagResource/Api/Requests/CreateTagRequest.php
• composer.json
• app/Filament/Resources/ProductResource.php
• app/Filament/Resources/TagResource.php

The request lifecycle in PriceBuddy follows the standard Laravel framework pattern, processing incoming HTTP requests and returning responses. The application serves both a web-based administrative interface built with Filament and a RESTful API for managing resources like Products and Tags. The API functionality is largely provided by the rupadana/filament-api-service package, which automates the creation of API endpoints for Filament resources.

This document outlines the journey of a request from the initial entry point to the final response, covering bootstrapping, routing, validation, controller logic, and response generation for both web and API requests.

High-Level Overview

The following diagram illustrates the major stages of a typical request within the PriceBuddy application.

1. Entry Point & Bootstrapping

All HTTP requests to the application are directed to a single entry point: public/index.php.

This script performs three key actions:

1. Defines LARAVEL_START: Records the start time for performance monitoring.
2. Loads Composer Autoloader: Includes vendor/autoload.php to make all project dependencies available.
3. Bootstraps Laravel: Includes bootstrap/app.php, which creates the application instance and prepares it to handle the request.
4. Handles Request: The application instance's handleRequest method is called, passing a Request object that captures the incoming HTTP request details.

// public/index.php:1-15
<?php

use Illuminate\Http\Request;

define('LARAVEL_START', microtime(true));

// ... maintenance mode check ...

// Register the Composer autoloader...
require __DIR__.'/../vendor/autoload.php';

// Bootstrap Laravel and handle the request...
(require_once __DIR__.'/../bootstrap/app.php')
    ->handleRequest(Request::capture());

Sources: public/index.php:1-15

During bootstrapping, service providers are registered. A key provider for the application's user interface is AdminPanelProvider, which configures the Filament admin panel.

Sources: app/Providers/Filament/AdminPanelProvider.php

2. Routing

After the application is bootstrapped, the incoming request is passed to the router to be matched with a defined route. The application uses routes for both its web interface (Filament) and its REST API.

API Routing

The application exposes RESTful API endpoints for resources like Product and Tag. These are managed by the rupadana/filament-api-service package, which automatically generates API routes for Filament resources. The API tests confirm the existence and structure of these routes.

Sources: composer.json:20, tests/Feature/Api/ProductApiTest.php, tests/Feature/Api/TagApiTest.php

The following table shows examples of API endpoints derived from the test suite.

Method	URI	Action	Test File
GET	/api/products	List all products	ProductApiTest.php:32
POST	/api/products	Create a new product	ProductApiTest.php:111
GET	/api/products/{id}	Show a single product	ProductApiTest.php:61
PUT	/api/products/{id}	Update a product	ProductApiTest.php:172
DELETE	/api/products/{id}	Delete a product	ProductApiTest.php:214
GET	/api/tags	List all tags	TagApiTest.php:28
POST	/api/tags	Create a new tag	TagApiTest.php:83

Web Routing

The primary web interface is the Filament admin panel. The routes for this panel, including pages for resources like Users, Tags, and Products, are configured within the AdminPanelProvider.

// app/Providers/Filament/AdminPanelProvider.php:32-34
->pages([
    Pages\Dashboard::class,
])

The provider also registers resource pages, which create the necessary routes for listing, creating, and editing resources.

Sources: app/Filament/Resources/TagResource.php:98-102, app/Providers/Filament/AdminPanelProvider.php:32-34

3. Request Validation

For API POST and PUT requests, data is validated before it reaches the controller logic. This is handled by Form Request classes.

For example, when creating a new Tag via the API, the CreateTagRequest class is used. It defines authorization logic and validation rules.

Validation Rules

The rules() method in CreateTagRequest specifies that the name must be a unique string for the authenticated user and that the user_id, if provided, must match the authenticated user's ID to prevent spoofing.

// app/Filament/Resources/TagResource/Api/Requests/CreateTagRequest.php:23-29
public function rules(): array
{
    return [
        'name' => 'required|string|max:255|unique:tags,name,NULL,id,user_id,'.auth()->id(),
        'user_id' => 'nullable|exists:users,id|in:'.auth()->id(),
    ];
}

Sources: app/Filament/Resources/TagResource/Api/Requests/CreateTagRequest.php:23-29, tests/Feature/Api/TagApiTest.php:121-129

Validation Flow

The sequence diagram below shows the validation process for a POST /api/tags request.

If validation fails, Laravel automatically returns a 422 Unprocessable Entity response with a JSON object containing the validation errors, and the controller method is never executed.

Sources: app/Filament/Resources/TagResource/Api/Requests/CreateTagRequest.php, tests/Feature/Api/TagApiTest.php:112-119

4. Controller Logic & Response

Once a request is routed and validated, it is handled by a controller method.

API Controllers

For the API, the rupadana/filament-api-service package likely provides the base controller logic that handles CRUD operations. These controllers interact with the Eloquent models (Product, Tag) to perform database operations.

The API tests demonstrate that the API supports advanced features like:

• Filtering: ?filter[status]=published
• Sorting: ?sort=title or ?sort=-created_at
• Pagination: ?per_page=10
• Relationship Inclusion: ?include=tags,user

Sources: tests/Feature/Api/ProductApiTest.php:230-293, tests/Feature/Api/TagApiTest.php:213-288

Web Controllers (Filament Pages)

For the web interface, requests are handled by Filament's Livewire components, which act as controllers. For example, AppSettingsPage.php handles the logic for the application settings page. The form() method defines the structure of the settings form, and the save() method persists the data.

Sources: app/Filament/Pages/AppSettingsPage.php:36-102

Response Generation

• API Responses: The API returns JSON responses. A successful creation request returns a 201 Created status with the created resource data. A successful list request returns a 200 OK status with a paginated data structure containing data, links, and meta objects. An unauthorized request returns a 401 Unauthorized status.

  Sources: tests/Feature/Api/ProductApiTest.php:32-59, 111-133, 303-309

• Web Responses: The web routes render HTML views. The main application interface is built with Filament and Livewire, which dynamically render and update HTML components. The base layout for the welcome page can be seen in resources/views/welcome.blade.php.

  Sources: resources/views/welcome.blade.php

Conclusion

The request lifecycle in PriceBuddy is a robust process built on the Laravel framework. It efficiently handles both web and API requests by leveraging a single entry point, a powerful routing system, and dedicated validation layers. The integration with Filament and the filament-api-service package provides a highly structured and automated way to manage the application's data through both a graphical user interface and a RESTful API, ensuring a consistent and predictable flow from request to response.