README

Laradot is a library built on top of the Laravel framework, designed to optimize the structure and development flow of applications. Below are the key features and design patterns implemented in Laradot.

1. Application Structure and Lifecycle

Laradot defines a structured approach to building Laravel applications, with the following components:

• BaseModel: A foundation model that all application models inherit from.
• BaseController: A generic controller that handles CRUD operations and more.
• BaseService: A service layer that contains the business logic for the application.

Application Lifecycle

The lifecycle of an operation within Laradot follows a well-defined path:

• Middlewares: Process any incoming requests.
• FormRequest and Rules: Validate the incoming data.
• Controller: Handle the logic and direct the request to the appropriate service.
• Service: Execute the core operation (create, update, etc.) and handle business logic.
• Resource: Format the data to be returned.
• Response: Return the appropriate response or handle errors.

This lifecycle ensures a clean, structured flow for all operations, resulting in well-designed CRUD operations.

2. MakeFeatureCommand

Laradot introduces the MakeFeatureCommand, an advanced Artisan command that automates the creation of various components in the application lifecycle.

Features of MakeFeatureCommand:

• File Creation: Automatically generates controllers, services, form requests, resources, and other necessary files for a feature.
• Migrations: Creates migrations with pre-defined fields, constraints, and relationships.
• Validation Rules: Generates rules for creating and updating fields directly in the form request, ensuring consistency across operations.

3. Model Features

3.1 Image/File Handling

• Laradot provides an easy-to-use mechanism for declaring that a model stores images or files.
• Automatic discovery in the service layer to manage the storage of files.

3.2 Excel Export

• Convert any response into an Excel file with a simple mechanism.
• This feature integrates seamlessly with the resource layer, allowing for a quick export of data.

3.3 Validation Translation

• Automatically translate all validation messages and keys in form requests.
• Provide multi-language support for validation, enhancing user experience across different locales.

3.4 Deep Filtering

• Add deep filtering mechanisms to any model in seconds.
• This allows for complex query capabilities, enabling users to filter results based on various attributes easily.
• The deep filtering feature also provides an easy and fast way to perform filtering not only across the model itself but also across its related models and relationships.
• This enables powerful, multi-level filtering, giving users fine-grained control over the data they retrieve.

Spatie-style scopes & relations (with Laradot filters)

Laradot offers similar ergonomics to Spatie Query Builder filters: you can filter by model scopes and by related model fields using dot notation under the hood (Laradot uses whereHas automatically).

Model setup

use Wever\Laradot\App\Traits\Filterable;
use Wever\Laradot\App\FilterTypes\{
    BooleanFilter,
    LikeFilter,
    RangeFilter,
    ScopeFilter,
    WhereInFilter
};

class User extends Model
{
    use Filterable;

    protected $filterable = [
        'name' => LikeFilter::class,
        'is_active' => BooleanFilter::class,
        'role_id' => WhereInFilter::class,
        'created_at' => RangeFilter::class,
        'active' => ScopeFilter::class, // calls scopeActive(...)
        'company' => Company::class,    // enables company.* filters
    ];

    public function scopeActive($query, $value = true)
    {
        return $query->where('is_active', $value);
    }

    // Optional negation: ?active=false will call scopeNotActive(true) if it exists
    public function scopeNotActive($query, $value = true)
    {
        return $query->where('is_active', false);
    }
}

Examples

• Filter by scope: /users?active=true or /users?filter[active]=true
• Filter by relation field: /users?company[name]=Acme or /users?filter[company][name]=Acme
• Filter by range and list: /users?created_at_from=2024-01-01&created_at_to=2024-12-31&role_id=1,2 or /users?filter[created_at][from]=2024-01-01&filter[created_at][to]=2024-12-31&filter[role_id]=1,2

If you want a single relation field without exposing all of that model's filters, you can declare it directly:

protected $filterable = [
    'company.name' => LikeFilter::class,
];

For reference, see Spatie Query Builder filtering docs.

Multi-column sorting

Add a sortable list to your model, then sort using bracket params. Order in the query string is the priority order.

class User extends Model
{
    use Filterable;

    protected $sortable = [
        'name',
        'created_at',
        'email',
    ];
}

Examples

• /users?sort[name][desc]&sort[created_at][asc]
• /users?sort[created_at][desc]

3.5 Search Mechanism

• Implement an efficient search mechanism for any model in seconds.
• Supports keyword-based searching that can scan through various fields and relationships.

3.6 Automatic Loading of Required Relations

• Laradot solves the issue of forgetting to load necessary relations that the frontend might require.
• It introduces a mechanism where relations required by the frontend can be automatically detected and loaded.
• With Laradot, the frontend can request specific relations dynamically, giving more control over the data they need.
• You can also limit which relations the frontend is allowed to request, ensuring secure and controlled data access.
• This mechanism reduces back-and-forth communication between the frontend and backend, ensuring all necessary relations are included in the response while maintaining security and performance.

Laradot aims to streamline Laravel application development by providing a clear structure and advanced automation tools, reducing development time while maintaining code quality and flexibility.