Route Management

Creating a Route

Let’s take a very simple example. In your web.php file, you can define a route as usual in Laravel:

Route::get('/hello_world', function () {
    return "Hello";
});

When this route is called, the response is automatically transformed by Laraventus into the standardized format:

{
  "result": "Hello",
  "errors": [],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}

This means that even a plain string returned from a route will be wrapped inside the AventusResult structure.

result contains the actual value or payload you returned.
errors lists any errors (empty in this case).
$type ensures that the frontend (AventusJs) can correctly interpret the object type.

With this approach, every response follows the same schema, making it predictable, type-safe, and easy to consume on the frontend side.

Returning an Error

Laraventus also makes it simple to standardize error handling. For example, in your web.php you can return an AventusError instead of a normal value:

Route::get('/hello_world', function () {
    return new AventusError(418, "I'm a teapot");
    return "Hello";
});

When calling this route, the response will look like this:

{
  "result": null,
  "errors": [
    {
      "code": 418,
      "message": "I'm a teapot",
      "details": [],
      "$type": "Aventus.Laraventus.Helpers.AventusError"
    }
  ],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}

Here’s what happens:

result is null because the call did not succeed.
errors contains a list of structured errors. Each error includes:
- a code (in this case HTTP 418)
- a message (“I’m a teapot”)
- optional details
and a $type marker so AventusJs can reconstruct the proper error object.

The top-level $type remains LaravelResult, ensuring the frontend always receives a predictable wrapper, whether the outcome is a success or an error.

Using a Controller

Instead of writing all the logic directly in web.php, Laraventus allows you to structure your code in a clean and type-safe way using controllers, requests, responses, and error wrappers.

Defining the Route

In routes/web.php, you can connect a route to a controller method:

Route::get('/hello_world', [\App\Http\Controllers\HelloWorld\Controller::class, "request"]);

We will create the following files under App\Http\Controllers\HelloWorld:

Controller

<?php

namespace App\Http\Controllers\HelloWorld;

class Controller
{
    public function request(Request $request): Error|Response
    {
        // Example error:
        // return new Error(ErrorEnum::TeaPot, "I'm a teapot");

        return new Response("Hello");
    }
}

The method receives a typed Request object.
The return type can be either an Error or a Response, making it explicit what outcomes are possible.

Error Wrapper

<?php

namespace App\Http\Controllers\HelloWorld;

use Aventus\Laraventus\Helpers\AventusError;

/**
 * @extends AventusError<ErrorEnum>
 */
class Error extends AventusError
{

}

Error extends AventusError but is scoped to your domain (HelloWorld).
It is linked to a specific ErrorEnum.

Error Enum

<?php

namespace App\Http\Controllers\HelloWorld;

enum ErrorEnum: int
{
    case TeaPot = 418;
}

All possible errors for this controller are declared here.
The example shows a 418 – I’m a teapot error.

Request Class

<?php

namespace App\Http\Controllers\HelloWorld;

use Aventus\Laraventus\Requests\AventusRequest;

/**
 * Custom request for HelloWorld route
 */
class Request extends AventusRequest
{

}

Extends AventusRequest, which integrates with Laraventus.
Any properties declared will have a required rule if not marked as optional with ? .
AventusRequest extends FormRequest from Laravel so that you can use normal rules

Response Class

<?php

namespace App\Http\Controllers\HelloWorld;

use Aventus\Laraventus\Resources\AventusResource;

/**
* @extends AventusResource
*/
class Response extends AventusResource
{
   public function __construct(
       public string $msg
   ) {}
}

Defines the shape of the response returned to the frontend.
Automatically enriched with the $type field by Laraventus.

Example Results

Success

{
  "result": {
    "$type": "App.Http.Controllers.HelloWorld.Response",
    "msg": "Hello"
  },
  "errors": [],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}

Error

{
    "result": null,
    "errors": [
        {
            "code": 418,
            "message": "I'm a teapot",
            "details": [],
            "$type": "App.Http.Controllers.HelloWorld.Error"
        }
    ],
    "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}

With this structure, every route:

Declares its expected request type.
Defines its possible responses (success or error).
Guarantees that the frontend (AventusJs) will always receive a predictable, type-safe format.

Using a POST Route with Request Validation

Laraventus seamlessly integrates request validation through its AventusRequest class. By simply defining typed public properties, validation rules are automatically inferred — no need to write manual validation logic.

In routes/web.php, define a POST route pointing to your controller:

Route::post('/hello_world', [\App\Http\Controllers\HelloWorld\Controller::class, "request"]);

Change the request:

<?php

namespace App\Http\Controllers\HelloWorld;

use Aventus\Laraventus\Requests\AventusRequest;

class Request extends AventusRequest
{
    public string $name;
}

The property public string $name; automatically makes the name field required and expects a string value.
Laraventus handles this validation under the hood and formats errors consistently.

Change the controller:

<?php

namespace App\Http\Controllers\HelloWorld;

class Controller
{
    public function request(Request $request): Error|Response
    {
        return new Response("Hello " . $request->name);
    }
}

If validation passes, Request is populated and type-safe.
The method returns a Response containing a greeting message.

If the route is called without a body, Laraventus automatically validates the request and returns a structured error response:

{
  "result": null,
  "errors": [
    {
      "code": 422,
      "message": "The name field is required.",
      "details": {
        "name": [
          "The name field is required."
        ]
      },
      "$type": "Aventus.Laraventus.Helpers.AventusError"
    }
  ],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}

422 corresponds to Laravel’s default validation error code.
details contains per-field validation messages.
$type fields ensure the frontend can reconstruct both the main result and error types correctly.

If the route is called with a valid body such as:

{ "name": "John" }

Then the response will be:

{
  "result": {
    "$type": "App.Http.Controllers.HelloWorld.Response",
    "msg": "Hello John"
  },
  "errors": [],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}

The request body is parsed, validated, and injected into the controller.
The response object is automatically serialized with its $type, making it ready for AventusJs to interpret on the frontend.

You can also add custom rules as in Laravel:

class Request extends AventusRequest
{
    public string $name;

    public function rules()
    {
        return [
            "name" => "min:8"
        ];
    }
}

With this rule, $name is required and must be at least 8 characters.

Using templates

To save time and maintain consistency when creating new Laraventus HTTP functions, you can use prebuilt templates available through the Aventus VS Code extension.

Installing a Template

Open the Aventus Shop
Search for "Laraventus.Http Function"
Click Download to add it to your template list.

This template automatically generates all the necessary files for a complete Laraventus HTTP function including the Controller, Request, Response, and Error classes - following the same structure as the examples above.

Adding the Template to Quick Actions

Once the template is installed, you can assign it to a Quick Action for faster access:

Press Ctrl + K, Ctrl + Shift + V to open the Aventus Quick Action Manager.
Check the box next to "Laraventus.Http Function".
Validate your choice. The template is now available as a quick command.

Using the Template as Quick Actions

When working in your Laravel project, you can now quickly generate a new HTTP function using the shortcut: Ctrl + K, Ctrl + V

This will:

Ask for the name of the function (for example, User/ChangeName).
Prompt you to select which files you want to generate (Error, Request, and/or Response).
Automatically create all selected files under app/Http/Controllers/… using the proper Laraventus structure.

Within seconds, you’ll have a fully functional controller setup ready to use, following the Laraventus conventions and compatible with AventusJs.