V3 Controller

V3 controllers in this project are designed to provide a standardized, RESTful API. They utilize an inheritance-based structure that encapsulates common functionalities in base classes, allowing you to implement only the logic specific to your module.

1. Core Structure

A V3 controller is automatically generated using the make:v3 {model} command and has the following structure:

• Inheritance: Every controller extends either BaseClientAPIController or BaseAdminAPIController. Both of these classes, in turn, extend BaseAPIController, where the core logic resides.
• Dependency Injection: In the __construct method, the repository and transformer corresponding to the model are automatically injected. This ensures a clean separation between the data, logic, and presentation layers.

<?php

namespace Modules\YourModule\Http\Controllers\API\V3\Admin;

use App\Http\Controllers\BaseAdminAPIController;
use Modules\YourModule\Repositories\YourModelRepository;
use Modules\YourModule\Http\Transformers\V3\Admin\YourModelTransformer;
use Modules\YourModule\Http\Requests\V3\Admin\YourModelStoreRequest;
use Modules\YourModule\Http\Requests\V3\Admin\YourModelUpdateRequest;
use Illuminate\Http\JsonResponse;

class YourModelController extends BaseAdminAPIController
{
    public function __construct()
    {
        // Repository and Transformer are injected automatically
        parent::__construct(
            resolve(YourModelRepository::class),
            resolve(YourModelTransformer::class)
        );
    }

    // ... Implemented methods ...
}

2. Implemented Methods in Your Controller

These methods are generated by default in your controller and handle the primary CRUD operations.

• store(YourModelStoreRequest $request): JsonResponse

  • Task: Creates a new record.
  • Process: It receives validated data from YourModelStoreRequest, creates a new model via the repository, and returns the result as a JSON response using the transformer.

• update(int $id, YourModelUpdateRequest $request): JsonResponse

  • Task: Updates an existing record.
  • Process: It receives validated data from YourModelUpdateRequest, updates the record with the specified id, and returns the result.

• delete(int $id): JsonResponse

  • Task: Deletes a record.
  • Process: It deletes the record with the specified id via the repository and returns a success response.

3. Inherited Methods from BaseAPIController

These methods are available in all V3 controllers and do not need to be re-implemented unless you want to override the default behavior.

• index(Request $request): JsonResponse

  • Task: Retrieves a paginated list of records.
  • Features: Automatically supports filtering, sorting, and loading relationships (includes) based on query string parameters using RequestCriteria.

• simpleIndex(Request $request): JsonResponse

  • Task: Similar to index, but uses simplePaginate for simpler pagination (next/previous links only).

• show(int|string $identifier, Request $request, ?string $field = 'id'): JsonResponse

  • Task: Retrieves a single record.
  • Features: Can find the record by id or any other unique field. Also supports loading relationships (includes).

• keyValList(string $field, Request $request, string $key = 'id'): JsonResponse

  • Task: Retrieves a list of records as key-value pairs, ideal for populating dropdown lists in a frontend application.
  • Example: api/v3/admin/users/key-val-list/name returns a list of users like [{ "id": 1, "name": "User A" }].

• signal(int|BaseModel $model, BaseSignalRequest $request): JsonResponse

  • Task: Used for signal-like operations, such as toggling a status (e.g., like/unlike).
  • Process: It receives a type and value from BaseSignalRequest and performs the corresponding operation on the model.

• countsBy(string $column, Request $request): JsonResponse

  • Task: Counts and groups records based on a specific column.
  • Example: api/v3/admin/posts/counts-by/status returns the number of posts grouped by their status (e.g., published, draft).

4. Specific BaseAdminAPIController Methods

• prepareForm(): JsonResponse
  • Task: Returns an empty model structure with default values, intended for use in "create" forms in the admin panel.