Easy Api Core Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require citizen63000/easy-api-core
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Citizen63000\EasyApiCore\EasyApiCoreServiceProvider" --tag="config"
   

2. First Use Case: Define a basic API resource in app/Http/Resources/ExampleResource.php:

   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,
           ];
       }
   }
   

3. Register in routes/api.php:

   use App\Http\Resources\ExampleResource;
   use Citizen63000\EasyApiCore\Facades\EasyApi;
   
   Route::get('/examples', function () {
       return EasyApi::resource(ExampleResource::class, Example::all());
   });
   

Implementation Patterns

Core Workflows

1. Resource Transformation: Use BaseResource to standardize API responses with built-in methods like:

   $this->withMeta(['count' => $this->count]);
   $this->withLinks(['next' => url('/examples?page=2')]);
   

2. API Versioning: Leverage the version() helper in routes:

   Route::prefix('v1')->group(function () {
       Route::get('/examples', function () {
           return EasyApi::resource(ExampleResource::class, Example::all());
       });
   });
   

3. Request Validation: Extend BaseRequest for consistent validation:

   namespace App\Http\Requests;
   
   use Citizen63000\EasyApiCore\Http\Requests\BaseRequest;
   
   class StoreExampleRequest extends BaseRequest
   {
       public function rules()
       {
           return [
               'name' => 'required|string|max:255',
           ];
       }
   }
   

4. Pagination: Use EasyApi::paginate() for standardized pagination:

   return EasyApi::paginate(ExampleResource::class, Example::paginate(10));
   

Integration Tips

• Middleware: Attach EasyApiCore\Middleware\ApiAuthenticate to API routes for unified auth handling.
• Error Handling: Override BaseExceptionHandler to customize API error responses.
• Testing: Use EasyApi::mockResource() for unit testing:

  $mock = EasyApi::mockResource(ExampleResource::class, ['id' => 1, 'name' => 'Test']);
  $response = $this->getJson('/examples/1')->assertOk();
  

Gotchas and Tips

Pitfalls

1. Resource Caching:

   • Avoid caching BaseResource instances directly; use Laravel’s built-in caching or EasyApi::cacheResource() for granular control.
   • Symptom: Stale data in responses due to cached resources.

2. Versioning Conflicts:

   • Ensure route prefixes (v1, v2) are consistent across all API endpoints to avoid versioning mismatches.
   • Fix: Use EasyApi::setVersion('v1') in a middleware for dynamic versioning.

3. Request Validation:

   • Custom BaseRequest classes must extend Citizen63000\EasyApiCore\Http\Requests\BaseRequest to inherit core validation logic.
   • Symptom: Validation rules silently failing.

4. Pagination Edge Cases:

   • EasyApi::paginate() assumes Eloquent paginators by default. For custom collections, pass ['paginator' => true]:

     EasyApi::paginate(ExampleResource::class, $customCollection, ['paginator' => true]);
     

Debugging Tips

• Enable API Logging: Set api.log_enabled = true in config/easy-api-core.php to log resource transformations and requests.
• Resource Dumping: Use EasyApi::dumpResource() in Tinker to inspect resource output:

  php artisan tinker
  >>> EasyApi::dumpResource(new ExampleResource(Example::first()));
  

Extension Points

1. Custom Directives: Extend BaseResource to add reusable directives:

   class ExampleResource extends BaseResource
   {
       public function toArray($request)
       {
           return $this->mergeWhen(
               $this->whenLoaded('user'),
               ['user' => new UserResource($this->user)]
           );
       }
   }
   

2. API Middleware: Override EasyApiCore\Middleware\ApiTransformResponse to modify all API responses globally.

3. Dynamic Fields: Use EasyApi::fields() to support dynamic field inclusion:

   Route::get('/examples', function () {
       return EasyApi::fields(ExampleResource::class, ['name', 'id'])
                   ->resource(ExampleResource::class, Example::all());
   });