Export tools

To ensure type safety and consistency between your Laravel backend (Laraventus) and your AventusJs frontend, Laraventus provides a powerful export system. This system reads your PHP code and automatically generates AventusJs classes.

With this approach, your frontend developers can directly interact with backend routes and data models using strongly typed, auto-generated code.

Setting Up the Export

To export your PHP classes, follow these steps:

1. Install the AventusJs VS Code extension. This extension provides export commands and integrates Aventus tools directly in VS Code.

2. Create a configuration file named aventus.php.avt in your project root.

3. Define the export configuration in this file you need at minimum:

   • output: Path to the folder where the generated files will be saved.

4. Right-click the aventus.php.avt file and select Aventus: Export php

Configuration Example

// aventus.php.avt
{
    "output": "./Front/src/generated",
}

This example exports your Laraventus code to Front/src/generated

Configuration Reference

Below is the list of all supported configuration options.

output

• Type: string
• Required: ✅ Yes
• Description: Defines where the generated AventusJs code will be stored.
• Example: "./Front/src/generated"

---

exportAsTs

• Type: boolean
• Default: false
• Description: If true, the export will generate .ts files instead of .avt.

---

useNamespace

• Type: boolean
• Default: false if export as Ts; true if export as Aventus
• Description: Enables namespace-based code generation for better organization in large projects.

---

Export Toggles

These options control which parts of your Laravel app are exported by default. Each can be overridden at the class or property level using the [Export] or [NoExport] attributes.

Option	Default	Description
exportEnumByDefault	false	Export enums automatically
exportStorableByDefault	true	Export all storable models
exportHttpRouteByDefault	true	Export all HTTP routes
exportHttpRequestByDefault	true	Export request classes
exportHttpResourceByDefault	true	Export resource classes
exportErrorsByDefault	true	Export AventusError and related classes

---

replacer

The replacer system allows you to customize how certain PHP types are converted into AventusJs types.

You can apply replacements globally or specifically for:

• normalClass
• storable
• httpRouter
• httpRequest
• httpResource
• genericError
• withError
• all

Each replacer part supports two strategies:

type

Replace a PHP (backend) type directly during export.

{
    "replacer": {
        "all": {
            "type": {
                "Aventus\\Laraventus\\Controllers\\ModelController": {
                    "result": "Aventus.HttpRoute"
                }
            }
        }
    }
}

When Aventus\Laraventus\Controllers\ModelController is found in your PHP code, it will become Aventus.HttpRoute in AventusJs.

---

result

Replace an already exported AventusJs type before it’s written to disk.

{
    "replacer": {
        "all": {
            "result": {
                "Aventus.HttpRoute": {
                    "result": "Aventus.HttpRouter"
                }
            }
        }
    }
}

This is useful for fine-tuning or adapting the final exported type.

---

httpRouter

Configuration for HTTP route generation.

Field	Type	Default	Description
createRouter	boolean	false	Whether to generate a router for your routes
routerName	string	”GeneratedRouter”	Name of the generated router
uri	string	""	Base URI (e.g., /api)
host	string	”https://localhost:5000”	Base host used by the router
parent	string	”Aventus.HttpRouter”	Parent class to extend
parentFile	string	""	File path of the parent class if it needs import
namespace	string	”Routes”	Namespace for the router class

---

Export Attributes

ArrayOf

Defines the actual type of array elements in a property. Place it above the property you want to type. This attribute will be used inside a Request to create the right object

#[ArrayOf(User::class)]
public array $users = [];

However, it’s also recommended to use documentation comments for better IDE autocompletion:

/**
 * @property User[] $users
 */
class Todo {
    #[ArrayOf(User::class)]
    public array $users = [];
}

Both approaches tell the exporter that $users is an array of User objects.

---

DefaultValue

Defines a default value for a property during export. The value is wrapped in quotes (treated as a string literal).

/**
 * @extends AventusModelResource<User>
 */
class UserResource extends AventusModelResource {

    #[DefaultValue("John")]
    public string $name;
}

Resulting AventusJs output:

export class UserResource {
    public static get Fullname(): string { return "App.Http.Resources.UserResource"; }
    public name: string = "John";
}

---

DefaultValueRaw

Defines a raw default value for a property, inserted without quotes. Useful for initializing objects or expressions.

/**
 * @extends AventusModelResource<User>
 */
class UserResource extends AventusModelResource {

    #[DefaultValueRaw("new User()")]
    public User $user;
}

Resulting AventusJs output:

export class UserResource {
    public static get Fullname(): string { return "App.Http.Resources.UserResource"; }
    public user: User = new User();
}

---

Export

Marks a class, property, or enum for export, even if it’s not exported by default.

use Aventus\Laraventus\Attributes\Export;

#[Export]
class MyDTO {
    public int $version;
    public string $name = "";
}

---

NoExport

Prevents a class, property, or method from being exported.

#[NoExport]
class User extends AventusModel {
    public string $username;
}

Or

class User extends AventusModel {
    public string $username;
    #[NoExport]
    public string $internalNotes;
}

---

Override

Marks a method as overridden in the exported TypeScript code. This is particularly helpful for controller inheritance, ensuring that the generated code clearly reflects overridden methods.

---

Rename

You can rename a controller or class for the exported AventusJs code using the #[Rename] attribute.

<?php

namespace App\Http\Controllers\Test;

use Aventus\Laraventus\Attributes\Rename;
use Aventus\Laraventus\Http\Response;
use Aventus\Laraventus\Http\Request;
use Aventus\Laraventus\Http\Error;

#[Rename("TestController")]
class Controller
{
    public function request(Request $request): Error|Response
    {
        return new Response();
    }
}

In this example:

• The PHP class Controller is renamed to TestController in the generated AventusJs code.
• This is especially useful when your file or folder structure causes naming conflicts or when you want more descriptive frontend class names.

You can also rename a function for the exported code. Useful for controllers.

use Aventus\Laraventus\Attributes\Rename;
use Aventus\Laraventus\Controllers\ModelController;

class UserController extends ModelController
{
    #[Rename("myCustomFetch")]
    public function index()
    {
        // Will be accessible in AventusJs as userController.myCustomFetch()
    }
}

Controller Export

Only controllers registered in your Laravel routing system will be treated as true controllers and exported to AventusJs.

This means that during export, Laraventus checks the output of the command:

php artisan route:list

Only the controllers appearing in this list are recognized as HTTP controllers and will be exported automatically. Any other PHP class will be considered a regular class and exported as-is (if applicable).

You can also use #[IsController] but this is strongly discouraged.

Typing Your PHP Classes

For a successful and accurate export, strong typing is essential in PHP. Since PHP’s type system is looser than C# or TypeScript, you must provide additional type information using DocBlock comments (@property, @extends, etc.).

These comments help Laraventus understand your data model structure and generate the correct AventusJs types.

Model Typing Example

<?php

use Aventus\Laraventus\Attributes\Export;
use Aventus\Laraventus\Models\AventusModel;

/**
 * @property string $name
 * @property string $email
 */
#[Export]
class User extends AventusModel
{}

Here:

• The @property annotations declare typed properties even if they’re not explicitly defined in the class.
• This helps the exporter generate a strongly typed AventusJs model with name: string and email: string.

Generic Class Typing

DocBlock comments can also be used to correctly type generic extensions such as resources.

<?php

/**
 * @extends AventusModelResource<User>
 */
class UserResource extends AventusModelResource {

    public string $name;
    public string $email;

    protected function bind($item): void {
        $this->name = $item->name;
        $this->email = $item->email;
    }
}

In this example:

• The @extends annotation defines that UserResource extends AventusModelResource<User>.
• This ensures the generated AventusJs code correctly links the resource to the User model, maintaining type safety.

Controlling Exported Properties

Sometimes, the value you want to export differs from the actual property or method used in PHP. To handle these cases cleanly without cluttering your PHP code, Laraventus supports the use of @export... and @noExport... annotations. For example @exportProperty and @noExportProperty.

These annotations let you control exactly which elements are exported and how they appear in AventusJs.

<?php

use Aventus\Laraventus\Attributes\Export;
use Aventus\Laraventus\Models\AventusModel;

/**
 * @property string $id
 * @property string $name
 * @property string $email
 * @property string $password
 *
 * @exportProperty int $id
 * @noExportProperty $password
 */
#[Export]
class User extends AventusModel
{}