Easy Api Core Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require citizen63000/easy-api-core
   php artisan vendor:publish --provider="Citizen63000\EasyApiCore\EasyApiCoreServiceProvider" --tag="config"
   

   Verify the config file exists in config/easy-api-core.php.

2. First Use Case: Authenticated Endpoint Create a controller extending Citizen63000\EasyApiCore\Http\Controllers\ApiController:

   use Citizen63000\EasyApiCore\Http\Controllers\ApiController;
   use Citizen63000\EasyApiCore\Traits\AuthorizesRequests;
   
   class ExampleController extends ApiController
   {
       use AuthorizesRequests;
   
       public function index()
       {
           return $this->successResponse(['data' => 'Hello, API!']);
       }
   }
   

   Register the route in routes/api.php with built-in auth middleware:

   Route::middleware('auth:easy-api')->get('/examples', [ExampleController::class, 'index']);
   

3. Validation Example: Use the validateRequest trait in your controller:

   use Citizen63000\EasyApiCore\Traits\ValidatesRequests;
   
   class CreateExampleController extends ApiController
   {
       use ValidatesRequests;
   
       protected $rules = [
           'name' => 'required|string|max:255',
           'description' => 'nullable|string',
       ];
   
       public function store()
       {
           $validated = $this->validateRequest();
           // Process $validated data
           return $this->successResponse($validated);
       }
   }
   

4. DTO Usage: Generate a DTO (e.g., php artisan make:dto ExampleDto) and use it in your controller:

   use App\DTOs\ExampleDto;
   
   public function show(ExampleDto $dto)
   {
       return $this->successResponse($dto->toArray());
   }
   

Implementation Patterns

Standardized Response Handling

1. Controller Base Class: Extend ApiController for consistent responses:

   class BaseApiController extends ApiController
   {
       protected function createResponse($data, $code = 200)
       {
           return $this->successResponse($data, $code);
       }
   }
   

2. Error Responses: Use built-in methods for standardized errors:

   return $this->errorResponse('Invalid data', 422, ['errors' => $validator->errors()]);
   

Authentication & Authorization

1. Middleware Integration: Attach the package’s middleware to routes:

   Route::middleware(['auth:easy-api', 'ability:view-examples'])->group(function () {
       // Protected routes
   });
   

2. Custom Guards: Extend the default guard configuration in config/easy-api-core.php:

   'guards' => [
       'api' => [
           'driver' => 'jwt',
           'provider' => 'users',
           'custom_claims' => ['role', 'permissions'],
       ],
   ],
   

Request Processing

1. DTO-Based Validation: Define DTOs for request/response contracts:

   namespace App\DTOs;
   
   use Citizen63000\EasyApiCore\DTO\BaseDto;
   
   class CreateExampleDto extends BaseDto
   {
       public string $name;
       public ?string $description;
   
       public function rules()
       {
           return [
               'name' => 'required|string|max:255',
               'description' => 'nullable|string',
           ];
       }
   }
   

2. Automatic Binding: Bind DTOs in your controller’s constructor:

   public function __construct(
       public CreateExampleDto $dto
   ) {}
   

API Resources

1. Resource Transformation: Extend BaseResource for consistent API responses:

   namespace App\Http\Resources;
   
   use Citizen63000\EasyApiCore\Http\Resources\BaseResource;
   
   class ExampleResource extends BaseResource
   {
       public function toArray($request)
       {
           return [
               'id' => $this->id,
               'name' => $this->name,
               'created_at' => $this->created_at->format('Y-m-d'),
           ];
       }
   
       public function withMeta()
       {
           return ['version' => '1.0.0'];
       }
   }
   

2. Collection Resources: Use BaseResourceCollection for paginated responses:

   namespace App\Http\Resources;
   
   use Citizen63000\EasyApiCore\Http\Resources\BaseResourceCollection;
   
   class ExampleCollection extends BaseResourceCollection
   {
       public function toArray($request)
       {
           return [
               'data' => $this->collection,
               'links' => $this->paginator->links(),
               'meta' => ['total' => $this->paginator->total()],
           ];
       }
   }
   

Workflow: CRUD API

1. Controller Setup:

   class ExampleController extends ApiController
   {
       public function index()
       {
           $examples = Example::paginate(15);
           return new ExampleCollection($examples);
       }
   
       public function store(CreateExampleDto $dto)
       {
           $example = Example::create($dto->toArray());
           return new ExampleResource($example)->response()->setStatusCode(201);
       }
   }
   

2. Route Definition:

   Route::apiResource('examples', ExampleController::class)
       ->middleware('auth:easy-api')
       ->parameters([
           'examples' => 'example',
       ]);
   

Integration with Laravel Features

1. Policy Integration: Use Laravel’s policies with the package’s auth system:

   class ExamplePolicy
   {
       public function viewAny(User $user)
       {
           return $user->hasPermission('view_examples');
       }
   }
   

2. Event Handling: Dispatch events after successful operations:

   use Citizen63000\EasyApiCore\Events\ApiOperationSucceeded;
   
   public function store(CreateExampleDto $dto)
   {
       $example = Example::create($dto->toArray());
       event(new ApiOperationSucceeded($example));
       return new ExampleResource($example)->response()->setStatusCode(201);
   }
   

Gotchas and Tips

Pitfalls

1. Middleware Order:

   • Issue: The package’s middleware must be registered before Laravel’s VerifyCsrfToken middleware to avoid CSRF token conflicts.
   • Fix: Ensure EasyApiCoreMiddleware is added to $middlewareGroups['web'] in App\Http\Kernel.php after auth:api but before VerifyCsrfToken.

2. DTO Validation Overhead:

   • Issue: DTO validation can add latency if rules are overly complex.
   • Tip: Use shouldValidate() to conditionally skip validation:

     public function shouldValidate()
     {
         return request()->isMethod('post');
     }
     

3. Caching Headers:

   • Issue: The package may not set proper Cache-Control headers by default, leading to performance issues.
   • Fix: Manually add headers in your controller:

     return $this->successResponse($data)
         ->header('Cache-Control', 'public, max-age=3600');
     

4. Route Caching:

   • Issue: Route caching (php artisan route:cache) may not work if the package dynamically modifies routes.
   • Tip: Exclude dynamic routes from caching by prefixing them with easy-api- and adding to config/cache.php:

     'routes' => [
         'except' => ['easy-api-*'],
     ],
     

5. JWT Expiration:

   • Issue: Default JWT expiration may be too short/long for your use case.
   • Fix: Configure in config/easy-api-core.php:

     'jwt' => [
         'expire' => 60 * 60 * 24, // 24 hours
         'refresh_expire' => 60 * 60 * 24 * 7, // 7 days
     ],
     

Debugging Tips

1. Enable Debug Mode: Set debug to true in config/easy-api-core.php to log detailed errors:

   'debug' => env('APP_DEBUG', false),
   

2. Middleware Debugging: Use dd() in middleware methods to inspect request/response cycles:

   public function handle($request, Closure $next)
   {
       \Log::debug('EasyApiCore middleware triggered', ['request' => $request->all()]);
       return $next($request);
   }
   

3. DTO Validation Errors: Check the easy-api-core.log file