### Example Responses

Source: https://laraventus.com/route_http/crud_controller

Examples of JSON responses for GET /user and POST /user endpoints.

```APIDOC
## Example Responses

### GET /user

#### Response Example

```json
{
  "result": [
    {
      "$type": "App.Http.Resources.UserResource",
      "name": "Alice",
      "email": "alice@example.com"
    },
    {
      "$type": "App.Http.Resources.UserResource",
      "name": "Bob",
      "email": "bob@example.com"
    }
  ],
  "errors": [],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}
```

### POST /user

#### Response Example

```json
{
  "result": {
    "$type": "App.Http.Resources.UserResource",
    "name": "Charlie",
    "email": "charlie@example.com"
  },
  "errors": [],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}
```
```

--------------------------------

### Implementation Example

Source: https://laraventus.com/route_http/crud_controller

Example of how to extend the ModelController to create a custom controller for a User model.

```APIDOC
## Implementation Example

### Description
This example shows how to extend the `ModelController` to create a `UserController` for the `User` model, defining the model, request, and resource classes.

### Code

```php
<?php

namespace App\Http\Controllers;

use App\Http\Requests\UserRequest;
use App\Http\Resources\UserResource;
use App\Models\User;
use Aventus\Laraventus\Controllers\ModelController;

/**
 * @extends ModelController<User, UserRequest, UserResource>
 */
class UserController extends ModelController
{
    public function defineModel(): string
    {
        return User::class;
    }

    public function defineRequest(): string
    {
        return UserRequest::class;
    }

    public function defineResource(): string
    {
        return UserResource::class;
    }
}
```
```

--------------------------------

### Laraventus Configuration Example

Source: https://laraventus.com/laraventus

An example of the `config/laraventus.php` file, showing how to configure model timestamps and fillable attributes. This file allows customization of Laraventus behavior.

```php
<?php

return [
    "model" => [
        "timestamps" => true,
        "only_fillable" => false
    ]
];
```

--------------------------------

### GET /hello_world - Using a Controller

Source: https://laraventus.com/laraventus

Shows how to connect a route to a controller method and handle typed requests and responses using Laraventus.

```APIDOC
## GET /hello_world - Using a Controller

### Description
This endpoint demonstrates connecting a route to a controller method. It utilizes custom Request and Response classes, along with an Error wrapper, to provide a structured and type-safe API interaction.

### Method
GET

### Endpoint
/hello_world

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **msg** (string) - A message defined in the `Response` class.
- **$type** (string) - The type of the response wrapper ('Aventus.Laraventus.Helpers.LaravelResult').

#### Response Example (Success)
```json
{
  "result": {
    "msg": "Hello",
    "$type": "App\Http\Controllers\HelloWorld\Response"
  },
  "errors": [],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}
```

#### Response Example (Error)
```json
{
  "result": null,
  "errors": [
    {
      "code": 418,
      "message": "I'm a teapot",
      "details": [],
      "$type": "App\Http\Controllers\HelloWorld\Error"
    }
  ],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}
```
```

--------------------------------

### Example Laraventus Configuration File

Source: https://laraventus.com/getting_started/configuration

An example of the `config/laraventus.php` file, showing various configuration options for models, controllers, and error handling. These settings control aspects like model timestamps, fillable attributes, and error reporting.

```php
<?php


return [
    "model" => [
        "timestamps" => true,
        "only_fillable" => false
    ],
    "controller" => [
        "attributes" => true
    ],
    "error" => [
        "print_console" => true,
        "stack_limit" => 10
    ]
];
```

--------------------------------

### Install Laraventus Composer Package

Source: https://laraventus.com/getting_started/installation

Installs the Laraventus composer library into an existing Laravel project. This is the standard method for integrating Laraventus functionality into your application.

```bash
composer require aventus/laraventus
```

--------------------------------

### GET /hello_world - Basic Route

Source: https://laraventus.com/laraventus

Demonstrates how a simple string returned from a Laravel route is automatically wrapped into the standard Laraventus response format.

```APIDOC
## GET /hello_world - Basic Route

### Description
This endpoint demonstrates how a simple string returned from a Laravel route is automatically wrapped into the standard Laraventus response format.

### Method
GET

### Endpoint
/hello_world

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **result** (string) - The actual value returned from the route.
- **errors** (array) - An empty array indicating no errors.
- **$type** (string) - The type of the response wrapper ('Aventus.Laraventus.Helpers.LaravelResult').

#### Response Example
```json
{
  "result": "Hello",
  "errors": [],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}
```
```

--------------------------------

### GET /hello_world - Returning an Error

Source: https://laraventus.com/laraventus

Illustrates how to return a standardized error response using `AventusError` from a Laravel route.

```APIDOC
## GET /hello_world - Returning an Error

### Description
This endpoint demonstrates how to return a standardized error response using `AventusError` from a Laravel route. The response structure includes a null `result` and a populated `errors` array.

### Method
GET

### Endpoint
/hello_world

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **result** (null) - Null because the operation did not succeed.
- **errors** (array) - A list of structured errors, each containing `code`, `message`, and optional `details`.
- **$type** (string) - The type of the response wrapper ('Aventus.Laraventus.Helpers.LaravelResult').

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

--------------------------------

### Configure Laraventus Export

Source: https://laraventus.com/tools/export

Configuration example for the `aventus.php.avt` file. This JSON object specifies the output directory for generated AventusJs files.

```json
{
    "output": "./Front/src/generated"
}
```

--------------------------------

### Define Simple GET Route in Laravel

Source: https://laraventus.com/route_http/route_management

Defines a basic GET route in Laravel's web.php file. When accessed, it returns a simple string 'Hello'. Laraventus automatically wraps this string into a standardized JSON response format.

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

--------------------------------

### Valid Request Body Example (JSON)

Source: https://laraventus.com/route_http/route_management

An example of a valid JSON request body that Laraventus can parse and validate. This structure is used to send data to the backend controller.

```json
{ "name": "John" }
```

--------------------------------

### Laravel JSON Response Examples (Success and Error)

Source: https://laraventus.com/route_http/route_management

Demonstrates the JSON structure for successful and error responses in Laraventus. These structures ensure type-safe data transfer between the backend and AventusJs frontend.

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

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

--------------------------------

### Define Detailed Resource for Richer Data in PHP

Source: https://laraventus.com/route_http/crud_controller

This example demonstrates how to define a detailed resource (`UserResourceDetails`) in addition to the standard resource (`UserResource`). When specified in the `ModelController`'s type hint, the detailed resource is automatically used for `show`, `update`, and `store` methods, providing richer data for single record operations while `index` continues to use the standard resource for performance.

```php
<?php


namespace App\Http\Controllers;


use App\Http\Requests\UserRequest;
use App\Http\Resources\UserResource;
use App\Http\Resources\UserResourceDetails;
use App\Models\User;
use Aventus\Laraventus\Controllers\ModelController;


/**
 * @extends ModelController<User, UserRequest, UserResource, UserResourceDetails>
 */
class UserController extends ModelController
{
    public function defineModel(): string
    {
        return User::class;
    }


    public function defineRequest(): string
    {
        return UserRequest::class;
    }


    public function defineResource(): string
    {
        return UserResource::class;
    }


    public function defineResourceDetails(): string
    {
        return UserResourceDetails::class;
    }
}


```

--------------------------------

### Create Custom AventusFile for User Pictures

Source: https://laraventus.com/laraventus

Define a custom file handler by extending the `AventusFile` abstract class. This example shows how to create a `UserPicture` class that specifies a dedicated directory for storing uploaded user pictures using the `get_save_directory` method.

```php
<?php

namespace App\Models;

use Aventus\Laraventus\Models\AventusFile;

class UserPicture extends AventusFile
{
    protected function get_save_directory($model): string
    {
        // All uploaded pictures will be stored in the "users" directory
        return "users";
    }
}
```

--------------------------------

### User Model Example Extending AventusModel

Source: https://laraventus.com/model/aventus_model

This PHP code demonstrates how to create a `User` model that extends `AventusModel`. It defines fillable properties and includes type hints for model attributes.

```php
<?php


namespace App\Models;


use Aventus\Laraventus\Models\AventusModel;


/**
 * @property string $name
 * @property string $email
 * @property string $password
 */
class User extends AventusModel
{
    protected $fillable = [
        'name',
        'email',
        'password'
    ];
}
```

--------------------------------

### Generic Class Typing for Resources

Source: https://laraventus.com/tools/export

Illustrates how to use DocBlock comments with the @extends annotation to type generic extensions like resources. This example shows how UserResource extends AventusModelResource<User>, ensuring type safety between the resource and the User model in generated AventusJs code.

```php
<?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;
    }
}

```

--------------------------------

### Define Route to Controller Method in Laravel

Source: https://laraventus.com/route_http/route_management

Connects a GET route '/hello_world' to a specific controller method 'request' within the `HelloWorldController` class in Laravel's routing file.

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

--------------------------------

### Define POST Route in Laravel

Source: https://laraventus.com/route_http/route_management

Example of defining a POST route in Laravel's `routes/web.php` file that points to a controller action. This is a standard Laravel routing definition.

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

--------------------------------

### Create Custom File Type with AventusFile

Source: https://laraventus.com/model/file

Defines a custom file handler by extending the abstract AventusFile class. This example creates a 'UserPicture' handler that specifies a 'users' directory for storing uploaded files.

```php
<?php


namespace App\Models;


use Aventus\Laraventus\Models\AventusFile;


class UserPicture extends AventusFile
{
    protected function get_save_directory($model): string
    {
        // All uploaded pictures will be stored in the "users" directory
        return "users";
    }
}

```

--------------------------------

### Laravel Controller with Typed Request and Response/Error Handling

Source: https://laraventus.com/laraventus

An example of a Laravel controller method using Laraventus. The method accepts a typed `Request` and is designed to return either a `Response` object or an `Error` object, ensuring type safety and predictable outcomes.

```php
<?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");
    }
}
```

--------------------------------

### Define AventusModel in PHP

Source: https://laraventus.com/laraventus

Example of defining a User model that extends Laraventus's `AventusModel`. This model is intended for exposure to the frontend via Aventus.js or for use within Laraventus resources. It includes property type hints and specifies fillable attributes.

```php
<?php

namespace App\Models;

use Aventus\Laraventus\Models\AventusModel;

/**
 * @property string $name 
 * @property string $email 
 * @property string $password 
 */
class User extends AventusModel
{
    protected $fillable = [
        'name',
        'email',
        'password'
    ];
}
```

--------------------------------

### Connect Route to Controller Method in Laravel

Source: https://laraventus.com/laraventus

This snippet defines a GET route in Laravel's web.php that is mapped to a specific method within a controller. This approach promotes better code organization by separating route definitions from business logic.

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

--------------------------------

### Restrict Endpoint Access with Deny Attribute in PHP

Source: https://laraventus.com/route_http/crud_controller

This example shows how to restrict access to a controller's index method using the custom `#[Deny]` attribute. The `AventusAttributesMiddleware` automatically detects this attribute and executes its `handle()` method before the controller logic, allowing for permission checks. The `#[NoExport]` attribute is also used to prevent re-exporting functionality defined in the parent class.

```php
<?php


namespace App\Http\Controllers;


use App\Http\Middlewares\Deny;
use App\Http\Requests\UserRequest;
use App\Http\Resources\UserResource;
use App\Models\User;
use Aventus\Laraventus\Controllers\ModelController;
use Aventus\Laraventus\Attributes\NoExport;


/**
 * @extends ModelController<User, UserRequest, UserResource>
 */
class UserController extends ModelController
{
    /**
     * @return class-string<User>
     */
    public function defineModel(): string
    {
        return User::class;
    }


    /**
     * @return class-string<UserRequest>
     */
    public function defineRequest(): string
    {
        return UserRequest::class;
    }


    /**
     * @return class-string<UserResource>
     */
    public function defineResource(): string
    {
        return UserResource::class;
    }


    #[Deny] // use a custom attribute to implement your permission logic
    #[NoExport] // use no export because already define inside the parent class
    public function index(): array
    {
        return parent::index();
    }
}

```

--------------------------------

### Database Transaction Rollback Example in Laravel

Source: https://laraventus.com/route_http/crud_controller

This PHP code illustrates Laraventus's safe-by-design feature where public CRUD methods are wrapped in database transactions. If an exception occurs within an overridden `*Action` method, such as `updateAction`, the entire operation is automatically rolled back, ensuring database consistency. This example shows a custom `updateAction` that intentionally throws an exception to demonstrate the rollback mechanism.

```php
protected function updateAction($item): void
{
    // Your custom logic
    $item->save();


    // If something goes wrong here...
    throw new \Exception('Unexpected error');


    // The transaction will be rolled back automatically
}

```

--------------------------------

### POST /hello_world - Hello World Endpoint

Source: https://laraventus.com/laraventus

This endpoint demonstrates a POST request with automatic validation using AventusRequest. It expects a 'name' field in the request body and returns a personalized greeting.

```APIDOC
## POST /hello_world

### Description
This endpoint accepts a POST request with a JSON body. It validates the presence and type of the 'name' field. If validation succeeds, it returns a greeting message. If validation fails, it returns a structured error response.

### Method
POST

### Endpoint
/hello_world

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name to be greeted.

### Request Example
```json
{
  "name": "John"
}
```

### Response
#### Success Response (200)
- **result** (object) - Contains the greeting message.
  - **msg** (string) - The greeting message.
- **errors** (array) - An empty array indicating no errors.

#### Response Example (Success)
```json
{
  "result": {
    "$type": "App.Http.Controllers.HelloWorld.Response",
    "msg": "Hello John"
  },
  "errors": [],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}
```

#### Error Response (422)
- **result** (null) - Null when errors occur.
- **errors** (array) - Contains error details.
  - **code** (integer) - The error code (e.g., 422 for validation).
  - **message** (string) - A description of the error.
  - **details** (object) - Specific field validation errors.

#### Response Example (Error - Missing Field)
```json
{
  "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"
}
```

#### Response Example (Error - Custom Rule)
```json
{
  "result": null,
  "errors": [
    {
      "code": 422,
      "message": "The name must be at least 8 characters.",
      "details": {
        "name": [
          "The name must be at least 8 characters."
        ]
      },
      "$type": "Aventus.Laraventus.Helpers.AventusError"
    }
  ],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}
```
```

--------------------------------

### POST /hello_world

Source: https://laraventus.com/route_http/route_management

This endpoint handles 'hello_world' requests. It expects a JSON request body with a 'name' field. Validation is performed automatically based on the Request class definition. It returns a structured response indicating success or failure.

```APIDOC
## POST /hello_world

### Description
Handles 'hello_world' requests with automatic request validation and structured responses.

### Method
POST

### Endpoint
/hello_world

### Parameters
#### Request Body
- **name** (string) - Required - The name to be greeted.

### Request Example
```json
{
  "name": "John"
}
```

### Response
#### Success Response (200)
- **result** (object) - Contains the greeting message.
  - **msg** (string) - The greeting message.
- **errors** (array) - An empty array indicating no errors.

#### Response Example (Success)
```json
{
  "result": {
    "$type": "App.Http.Controllers.HelloWorld.Response",
    "msg": "Hello John"
  },
  "errors": [],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}
```

#### Error Response (422 - Validation Error)
- **result** (null) - Null when there are errors.
- **errors** (array) - Contains validation error details.
  - **code** (integer) - The HTTP status code (e.g., 422).
  - **message** (string) - A general error message.
  - **details** (object) - Field-specific validation messages.

#### Response Example (Validation Error)
```json
{
  "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"
}
```

#### Error Response (418 - Custom Error Example)
- **result** (null) - Null when there are errors.
- **errors** (array) - Contains custom error details.
  - **code** (integer) - The custom error code (e.g., 418).
  - **message** (string) - The custom error message.
  - **details** (array) - Additional error details.

#### Response Example (Custom Error)
```json
{
    "result": null,
    "errors": [
        {
            "code": 418,
            "message": "I'm a teapot",
            "details": [],
            "$type": "App.Http.Controllers.HelloWorld.Error"
        }
    ],
    "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}
```
```

--------------------------------

### Returning Resource Collections

Source: https://laraventus.com/laraventus

Explains how to transform collections of models into typed resources using the static `collection()` method, ensuring frontend compatibility with AventusJs.

```APIDOC
## Returning Resource Collections

### Description
Both `AventusModelResource` and `AventusAutoBindResource` can be used to transform collections of models. You can use the static `collection()` method to convert an array or Eloquent collection into a list of typed resources.

### Method
N/A (This is a class method usage)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **result** (array) - An array of transformed resources, each with a `$type` field.
- **errors** (array) - An array of errors, if any.
- **$type** (string) - The type of the result, e.g., `Aventus.Laraventus.Helpers.LaravelResult`.

#### Response Example
```json
{
  "result": [
    {
      "$type": "App.Http.Resources.UserResource",
      "name": "Alice",
      "email": "alice@example.com"
    },
    {
      "$type": "App.Http.Resources.UserResource",
      "name": "Bob",
      "email": "bob@example.com"
    }
  ],
  "errors": [],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}
```
```

--------------------------------

### Create Model-Based Resource (PHP)

Source: https://laraventus.com/route_http/response_resource

Creates a resource representing a Laravel Eloquent model by extending AventusModelResource. The bind() method maps model data to resource properties, allowing selective exposure of fields. Requires AventusModelResource and the specific Eloquent model.

```PHP
<?php


namespace App\Http\Resources;


use App\Models\User;
use Aventus\Laraventus\Resources\AventusModelResource;


/**
 * @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;
    }
}

```

--------------------------------

### Customize Exported Type Names in Laraventus

Source: https://laraventus.com/tools/export

Example of using the `replacer` system to modify AventusJs types after they have been initially exported but before they are written to disk. This JSON shows how to rename an exported type.

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

--------------------------------

### Implementing CRUD Endpoints with Laraventus ModelController

Source: https://laraventus.com/laraventus

Illustrates the implementation of a basic CRUD controller using Laraventus's `ModelController`. This abstract controller provides pre-built methods for indexing, showing, storing, updating, and deleting resources, including batch operations. It automatically handles typed resource responses compatible with AventusJs.

```php
<?php

namespace App\Http\Controllers;

use App\Http\Requests\UserRequest;
use App\Http\Resources\UserResource;
use App\Models\User;
use Aventus\Laraventus\Controllers\ModelController;

/**
 * @extends ModelController<User, UserRequest, UserResource>
 */
class UserController extends ModelController
{
    public function defineModel(): string
    {
        return User::class;
    }

    public function defineRequest(): string
    {
        return UserRequest::class;
    }

    public function defineResource(): string
    {
        return UserResource::class;
    }
}
```

--------------------------------

### Error Enum for Domain-Specific Errors

Source: https://laraventus.com/laraventus

An example of an enum used to define specific error codes and messages for a particular domain or controller. This enum, `ErrorEnum`, declares a `TeaPot` error with an integer code of 418.

```php
<?php

namespace App\Http\Controllers\HelloWorld;

enum ErrorEnum: int
{
    case TeaPot = 418;
}
```

--------------------------------

### Create Basic Response Resource (PHP)

Source: https://laraventus.com/route_http/response_resource

Defines a basic response resource by extending AventusResource. All public properties are included in the JSON response with a $type field. Requires the AventusResource class.

```PHP
<?php


namespace App\Http\Controllers\HelloWorld;


use Aventus\Laraventus\Resources\AventusResource;


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

```

--------------------------------

### Laravel Controller Handling Validated Request (PHP)

Source: https://laraventus.com/route_http/route_management

An example of a Laravel controller method that accepts a validated `Request` object. It demonstrates returning either a success `Response` or an error based on validation.

```php
<?php

namespace App\Http\Controllers\HelloWorld;

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

--------------------------------

### Customize Type Replacements in Laraventus Export

Source: https://laraventus.com/tools/export

Example of using the `replacer` system to customize type conversions during the Laraventus export process. This JSON demonstrates how to replace a specific PHP class with an AventusJs type globally.

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

--------------------------------

### Create Auto-Binding Resource (PHP)

Source: https://laraventus.com/route_http/response_resource

Enables automatic binding of resource properties to matching model attributes by extending AventusAutoBindResource. Custom computed properties can be added in the bind() method. Requires AventusAutoBindResource and the specific Eloquent model.

```PHP
<?php


namespace App\Http\Resources;


use App\Models\User;
use Aventus\Laraventus\Resources\AventusAutoBindResource;


/**
 * @extends AventusAutoBindResource<User>
 */
class UserResource2 extends AventusAutoBindResource {


    // These will be automatically bound
    public string $name;
    public string $email;


    // Custom properties can still be added
    public string $token;


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

```

--------------------------------

### Logging to Console with Aventus Tools in PHP

Source: https://laraventus.com/laraventus

This PHP code demonstrates how to use the `Aventus\Laraventus\Tools\Console` utility class to log messages and dump variables directly to the console during a web request. This is useful for debugging without corrupting the HTTP response.

```php
use Aventus\Laraventus\Tools\Console;

// Log a simple text message
Console::log('User data processed.');

// Dump a variable's content
$userData = ['name' => 'John Doe', 'email' => 'john@example.com'];
Console::dump($userData);

// Display a stack trace
Console::trace();

```

--------------------------------

### Auto-Binding Resource with Laraventus

Source: https://laraventus.com/laraventus

Demonstrates how to automatically bind resource properties to model attributes using `AventusAutoBindResource`. Properties matching model attributes are bound automatically, while custom properties can be defined and populated in the `bind()` method. This simplifies resource creation when model and resource structures align.

```php
<?php

namespace App\Http\Resources;

use App\Models\User;
use Aventus\Laraventus\Resources\AventusAutoBindResource;

/**
 * @extends AventusAutoBindResource<User>
 */
class UserResource2 extends AventusAutoBindResource {

    // These will be automatically bound
    public string $name;
    public string $email;

    // Custom properties can still be added
    public string $token;

    protected function bind($item): void {
        $this->token = md5($item->name . ' ' . $item->email);
    }
}
```

--------------------------------

### Auto-Binding Resource

Source: https://laraventus.com/laraventus

Demonstrates how to use AventusAutoBindResource to automatically bind resource properties to model attributes. Custom properties can also be added and computed.

```APIDOC
## Auto-Binding Resource

### Description
If your resource properties match your model's attributes, Laraventus can automatically bind them for you. To do this, extend `AventusAutoBindResource`.

### Method
N/A (This is a class definition)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **result** (object) - The transformed resource data, including a `$type` field.
- **errors** (array) - An array of errors, if any.
- **$type** (string) - The type of the result, e.g., `Aventus.Laraventus.Helpers.LaravelResult`.

#### Response Example
```json
{
  "result": {
    "$type": "App.Http.Resources.UserResource2",
    "name": "John Doe",
    "email": "john@example.com",
    "token": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3"
  },
  "errors": [],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}
```
```

--------------------------------

### AventusJs RAM Integration

Source: https://laraventus.com/route_http/crud_controller

Connect backend controllers directly to the frontend using AventusJs RAM for type-safe data access.

```APIDOC
## AventusJs RAM Integration

### Description
Laraventus enables seamless integration with AventusJs, allowing automatic generation of type-safe frontend classes (`.lib.avt`) from backend controllers. This provides reactive access to Laravel data directly from the frontend without manual HTTP requests.

### Frontend Code Example

```javascript
import { UserController } from "../generated/app/Http/Controllers/UserController.lib.avt";
import { UserResource } from "../generated/app/Http/Resources/UserResource.lib.avt";

export class UserRAM extends AventusPhp.RamHttp<UserResource> implements Aventus.IRam {
    /**
     * @inheritdoc
     */
    public override defineRoutes(): AventusPhp.RamQuery<UserResource> {
        return new UserController();
    }
}
```

This code connects the `UserRAM` to the backend `UserController`, enabling direct data interaction.
```

--------------------------------

### Save User with Uploaded Picture in Laraventus

Source: https://laraventus.com/laraventus

This example demonstrates how to save a `User` model with an uploaded picture. The file is assigned to the `picture` attribute, and the `save()` method handles the file upload and database entry creation, storing the file's public URL.

```php
$user = new User();
$user->picture = [
    'upload' => $request->file('picture')
];
$user->save();
```

--------------------------------

### CRUD Controller Implementation

Source: https://laraventus.com/laraventus

Details the implementation of the generic `ModelController` for creating full CRUD API endpoints with minimal code, supporting typed resources and batch operations.

```APIDOC
## CRUD Controller

### Description
Laraventus includes a ready-to-use generic controller called `ModelController` that allows you to quickly create full CRUD endpoints for any Eloquent model with minimal code. This controller automatically handles listing, creation, updating, and deletion of records, all fully compatible with the Aventus `$type` response system and AventusJs integration.

### Method
N/A (This is a class definition)

### Endpoint
N/A (Endpoints are defined by the methods within the controller, e.g., GET /users, POST /users)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
Responses vary based on the method called (index, show, store, update, destroy). All responses will contain typed resources with the `$type` metadata expected by AventusJs.

#### Response Example
(Example for `index` method, returning a collection)
```json
{
  "result": [
    {
      "$type": "App.Http.Resources.UserResource",
      "name": "Alice",
      "email": "alice@example.com"
    },
    {
      "$type": "App.Http.Resources.UserResource",
      "name": "Bob",
      "email": "bob@example.com"
    }
  ],
  "errors": [],
  "$type": "Aventus.Laraventus.Helpers.LaravelResult"
}
```
```

--------------------------------

### Use Custom File Type in Laraventus Model

Source: https://laraventus.com/laraventus

Integrate a custom file handler, like `UserPicture`, into your Laraventus model by defining it in the `casts` array. This example demonstrates how to cast the `picture` attribute of a `User` model to use the `UserPicture` class, enabling automatic file handling.

```php
<?php

namespace App\Models;

use Aventus\Laraventus\Models\AventusModel;

/**
 * @property UserPicture $picture
 */
class User extends AventusModel
{
    protected $fillable = [
        'picture'
    ];

    protected function casts(): array
    {
        return [
            'picture' => UserPicture::class
        ];
    }
}
```

--------------------------------

### Define Custom Image Resizing and Conversion (PHP)

Source: https://laraventus.com/model/file

This PHP code defines a UserPicture class that extends AventusImage. It customizes image saving by setting a specific directory ('users'), enforcing a maximum size of 800x800 pixels, and converting all images to the WebP format. This class ensures consistent image handling for user-uploaded pictures.

```php
<?php


namespace App\Models;


use Aventus\Laraventus\Models\AventusImage;


class UserPicture extends AventusImage
{
    protected function get_save_directory($model): string
    {
        // Store all user pictures under "users"
        return "users";
    }


    protected function max_size()
    {
        // Resize down to a maximum of 800x800 pixels
        return ["width" => 800, "height" => 800];
    }


    protected function force_extension(): bool|string
    {
        // Convert all images to webp format
        return "webp";
    }
}

```

--------------------------------

### Create Model-Based Response Resource in PHP

Source: https://laraventus.com/laraventus

Illustrates creating a model-based response resource in PHP using `AventusModelResource`. This allows binding data from a Laravel Eloquent model to resource properties, enabling selective exposure of model fields and privacy of sensitive data.

```php
<?php

namespace App\Http\Resources;

use App\Models\User;
use Aventus\Laraventus\Resources\AventusModelResource;

/**
 * @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;
    }
}

```

--------------------------------

### Defining Routes

Source: https://laraventus.com/route_http/crud_controller

Laraventus provides a helper method to generate all CRUD endpoints for a controller at once.

```APIDOC
## Defining Routes

### Description
Laraventus offers a helper method `Route::resourceWithMany()` to automatically generate all CRUD endpoints for a controller, including batch operations, simplifying route registration.

### Code

```php
<?php

use App\Http\Controllers\UserController;
use Aventus\Laraventus\Routes\Route;

Route::resourceWithMany('user', UserController::class);
```

### Generated Endpoints

| HTTP Verb | URI         | Controller Method |
|-----------|-------------|-------------------|
| `GET`     | `/user`     | `index`           |
| `GET`     | `/user/{id}`| `show`            |
| `POST`    | `/user`     | `store`           |
| `POST`    | `/user/many`| `storeMany`       |
| `PUT`     | `/user/{id}`| `update`          |
| `PUT`     | `/user/many`| `updateMany`      |
| `DELETE`  | `/user/{id}`| `destroy`         |
| `DELETE`  | `/user/many`| `destroyMany`     |

Each route returns a Laraventus-formatted JSON response containing `$type`, `errors`, and `result`.
```

--------------------------------

### Log and Dump User Data in Laravel Controller

Source: https://laraventus.com/laraventus

This PHP snippet demonstrates how to use the Console class to log and dump user data within a Laravel controller. It requires the Aventus\Laraventus\Tools\Console namespace and the Illuminate\Routing\Controller base class. The input is a user ID, and the output is a UserResource.

```php
use Aventus\Laraventus\Tools\Console;

class UserController extends Controller
{
    public function show(int $id)
    {
        $user = User::find($id);

        Console::log("Fetching user with ID: $id");
        Console::dump($user);
        
        return new UserResource($user);
    }
}
```

--------------------------------

### Define Custom User Picture Handling with AventusImage

Source: https://laraventus.com/laraventus

This PHP snippet demonstrates how to create a custom image class 'UserPicture' that extends AventusImage. It configures automatic resizing to 800x800 pixels and forces conversion to WebP format, ensuring optimized image storage.

```php
<?php

namespace App\Models;

use Aventus\Laraventus\Models\AventusImage;

class UserPicture extends AventusImage
{
    protected function get_save_directory($model): string
    {
        // Store all user pictures under "users"
        return "users";
    }

    protected function max_size()
    {
        // Resize down to a maximum of 800x800 pixels
        return ["width" => 800, "height" => 800];
    }

    protected function force_extension(): bool|string
    {
        // Convert all images to webp format
        return "webp";
    }
}

```

--------------------------------

### Transforming Model Collections with Laraventus Resources

Source: https://laraventus.com/laraventus

Shows how to transform collections of models into typed resources using the static `collection()` method available in `AventusModelResource` and `AventusAutoBindResource`. This method converts arrays or Eloquent collections into a list of typed resources, ensuring each item is wrapped with the correct `$type` field for AventusJs.

```php
$users = User::all();
return UserResource::collection($users);
```

--------------------------------

### Typing Generic PHP Classes (Resources) for AventusJs

Source: https://laraventus.com/laraventus

DocBlock comments, specifically `@extends`, are used to type generic PHP class extensions like resources. This annotation helps Laraventus correctly link resources to their associated models in the generated AventusJs code, maintaining type safety.

```php
<?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;
    }
}

```

--------------------------------

### Return Resource Collections (PHP)

Source: https://laraventus.com/route_http/response_resource

Transforms collections of models into typed resources using the static collection() method available on AventusModelResource and AventusAutoBindResource. This ensures each item in the response array is properly typed for AventusJs.

```PHP
$users = User::all();
return UserResource::collection($users);

```

--------------------------------

### Connect Backend Controller to Frontend with AventusJs RAM

Source: https://laraventus.com/route_http/crud_controller

Defines a RAM (Remote Access Module) in AventusJs to connect to the backend UserController, enabling type-safe data access from the frontend.

```typescript
import { UserController } from "../generated/app/Http/Controllers/UserController.lib.avt";
import { UserResource } from "../generated/app/Http/Resources/UserResource.lib.avt";


export class UserRAM extends AventusPhp.RamHttp<UserResource> implements Aventus.IRam {
    /**
     * @inheritdoc
     */
    public override defineRoutes(): AventusPhp.RamQuery<UserResource> {
        return new UserController();
    }
}

```

--------------------------------

### Upload File Structure for Laraventus

Source: https://laraventus.com/model/file

Illustrates the JSON structure required when sending file upload data to the backend. It includes a 'uri' and the binary 'upload' file, which Laraventus processes automatically.

```json
{
  "picture": {
    "uri": "",
    "upload": <binary file>
  }
}

```

--------------------------------

### Generate CRUD Routes with Laraventus

Source: https://laraventus.com/laraventus

This snippet demonstrates how to use Laraventus's `Route::resourceWithMany` helper to automatically generate all CRUD endpoints, including 'Many' operations, for a given resource. It simplifies route registration by creating multiple endpoints with a single line of code.

```php
<?php

use App\Http\Controllers\UserController;
use Aventus\Laraventus\Routes\Route;

Route::resourceWithMany('user', UserController::class);
```

--------------------------------

### Log User Data to Console in Laravel

Source: https://laraventus.com/tools/console

Demonstrates how to use the Aventus Console utility to log messages and dump user data within a Laravel controller. This helps in debugging API logic and request data in real-time without corrupting the HTTP response.

```php
use Aventus\Laraventus\Tools\Console;


class UserController extends Controller
{
    public function show(int $id)
    {
        $user = User::find($id);


        Console::log("Fetching user with ID: $id");
        Console::dump($user);


        return new UserResource($user);
    }
}
```

--------------------------------

### Connect Backend Controllers to Frontend with AventusJs RAM

Source: https://laraventus.com/laraventus

This TypeScript code defines a `UserRAM` class that extends `AventusPhp.RamHttp`. It connects backend Laravel controllers to the frontend using AventusJs, enabling type-safe and reactive data access without manual HTTP requests. The `defineRoutes` method returns an instance of `UserController`, establishing the connection.

```ts
import { UserController } from "../generated/app/Http/Controllers/UserController.lib.avt";
import { UserResource } from "../generated/app/Http/Resources/UserResource.lib.avt";

export class UserRAM extends AventusPhp.RamHttp<UserResource> implements Aventus.IRam {
    /**
     * @inheritdoc
     */
    public override defineRoutes(): AventusPhp.RamQuery<UserResource> {
        return new UserController();
    }
}
```

--------------------------------

### Custom User Creation Logic in Laravel

Source: https://laraventus.com/route_http/crud_controller

This PHP code snippet demonstrates how to override the default `storeAction` method in a `UserController` to implement custom logic for creating a new user. It shows how to hash the password and set a default role before saving the user, while still leveraging automatic request validation, database transaction handling, and standardized response wrapping provided by the `ModelController`.

```php
<?php


namespace App\Http\Controllers;


use App\Http\Requests\UserRequest;
use App\Http\Resources\UserResource;
use App\Models\User;
use Aventus\Laraventus\Controllers\ModelController;


/**
 * @extends ModelController<User, UserRequest, UserResource>
 */
class UserController extends ModelController
{
    public function defineModel(): string
    {
        return User::class;
    }


    public function defineRequest(): string
    {
        return UserRequest::class;
    }


    public function defineResource(): string
    {
        return UserResource::class;
    }


    /**
     * Customize how a new user is stored
     *
     * @param User $item
     */
    protected function storeAction($item): void
    {
        // Example: hash password before saving
        $item->password = bcrypt($item->password);


        // Example: set default role
        $item->role = 'user';


        $item->save();
    }
}

```

--------------------------------

### Publish Laraventus Configuration

Source: https://laraventus.com/getting_started/configuration

This command publishes the Laraventus configuration file to your project. After running this, you can edit the `config/laraventus.php` file to customize settings.

```php
php artisan vendor:publish
```