Release Notes v1.1.0

🚀 New Features

Enhanced CRUD Controller

• Added pagination support with customizable items per page
• Implemented search functionality across multiple fields
• Added sorting capability with customizable sort direction
• Added relationship eager loading support
• Implemented built-in request validation
• Added consistent JSON response format

Configuration Options

• Added $validationRules for request validation
• Added $searchableFields for search functionality
• Added $relationships for eager loading
• Added $perPage for pagination customization

Response Format

• Standardized JSON response format across all endpoints
• Added metadata for paginated responses
• Improved error handling and response structure

🔧 Improvements

• Better integration with Laravel's resource controllers
• More flexible and configurable controller setup
• Enhanced documentation with examples and best practices

📝 Documentation

• Added comprehensive usage guide
• Added API endpoint documentation
• Added query parameters documentation
• Added response format examples
• Added best practices section

Generic CRUD Controller

The CrudController is a powerful abstract controller class that provides a complete set of CRUD (Create, Read, Update, and Delete) operations with additional features like pagination, searching, sorting, and relationship loading.

Features

• Complete CRUD Operations: Create, read, update, and delete records
• Pagination: Built-in pagination support with customizable items per page
• Searching: Search across multiple fields
• Sorting: Sort results by any field
• Relationship Loading: Automatically load related models
• Validation: Built-in request validation with customizable rules
• JSON Responses: Consistent JSON response format

Available Methods

1. getAllRecords: Gets paginated records with search, sort, and relationship loading
2. getRecordById: Gets a specific record with relationships
3. storeRecord: Creates a new record with validation
4. updateRecord: Updates an existing record with validation
5. deleteRecord: Deletes an existing record

Configuration Properties

The controller can be configured using these protected properties:

• $model: The Eloquent model instance
• $validationRules: Array of validation rules for create/update operations
• $searchableFields: Array of fields to search in
• $relationships: Array of relationships to eager load
• $perPage: Number of items per page (default: 15)

Usage

1. Create a New Controller: Extend the CrudController for your specific model:

   namespace App\Http\Controllers;
   
   use omarchouman\LaraUtilX\Http\Controllers\CrudController;
   use App\Models\User;
   
   class UserController extends CrudController
   {
      public function __construct(User $model)
      {
          parent::__construct($model);
   
          // Define validation rules
          $this->validationRules = [
              'name' => 'required|string|max:255',
              'email' => 'required|email|unique:users',
              'password' => 'required|min:6'
          ];
   
          // Define searchable fields
          $this->searchableFields = ['name', 'email'];
   
          // Define relationships to load
          $this->relationships = ['profile', 'roles'];
   
          // Customize items per page
          $this->perPage = 20;
      }
   
      // Map standard resource methods to CrudController methods
      public function index(Request $request)
      {
          return $this->getAllRecords($request);
      }
   
      public function store(Request $request)
      {
          return $this->storeRecord($request);
      }
   
      public function show($id)
      {
          return $this->getRecordById($id);
      }
   
      public function update(Request $request, $id)
      {
          return $this->updateRecord($request, $id);
      }
   
      public function destroy($id)
      {
          return $this->deleteRecord($id);
      }
   }

2. Routing: Define routes in your routes/web.php or routes/api.php file:

   use App\Http\Controllers\UserController;
   
   Route::apiResource('users', UserController::class);

3. API Endpoints: The controller provides these endpoints:

   GET    /users              - Get all users (with pagination)
   GET    /users/{id}         - Get a specific user
   POST   /users              - Create a new user
   PUT    /users/{id}         - Update a user
   DELETE /users/{id}         - Delete a user

4. Query Parameters: The getAllRecords method supports these query parameters:

   • search: Search term to filter records
   • sort_by: Field to sort by
   • sort_direction: Sort direction (asc/desc)
   • per_page: Number of items per page

   Example:

   GET /users?search=john&sort_by=name&sort_direction=desc&per_page=20

Response Format

Success Responses

1. Get All Records:

   {
      "data": [...],
      "meta": {
          "current_page": 1,
          "last_page": 5,
          "per_page": 15,
          "total": 75
      }
   }

2. Get Single Record:

   {
      "data": {
          "id": 1,
          "name": "John Doe",
          "email": "john@example.com",
          "profile": {...},
          "roles": [...]
      }
   }

3. Create/Update Record:

   {
      "message": "Record created/updated successfully",
      "data": {
          "id": 1,
          "name": "John Doe",
          "email": "john@example.com"
      }
   }

4. Delete Record:

   {
      "message": "Record deleted successfully"
   }

Error Responses

The controller returns appropriate error responses for:

• Validation errors
• Not found errors
• Server errors

Best Practices

1. Always define validation rules for your model
2. Specify searchable fields for better search functionality
3. Define relationships that should be loaded with the model
4. Use the standard resource method names (index, store, show, update, destroy) for better Laravel integration
5. Customize the per_page value based on your needs