Php Rest Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require dbstudios/php-rest
   

   Publish the default configuration (if needed):

   php artisan vendor:publish --provider="Dbstudios\Rest\RestServiceProvider" --tag="config"
   

2. Basic REST Controller Extend Dbstudios\Rest\RestController to leverage built-in CRUD methods:

   use Dbstudios\Rest\RestController;
   
   class UserController extends RestController
   {
       protected $model = \App\Models\User::class; // Auto-injects Eloquent model
   }
   

   Define routes in routes/api.php:

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

3. First API Call Test with GET /api/users (returns paginated list) or POST /api/users (create record).

Where to Look First

• Core Classes:
  • RestController (base controller with CRUD methods)
  • RestServiceProvider (bootstraps middleware, formatters)
• Configuration:
  • config/rest.php (API versioning, default responses, pagination)
• Middleware:
  • ApiVersionMiddleware (handles versioning)
  • ApiResponseFormatter (standardizes JSON responses)

First Use Case: Custom Endpoint

Override a single method (e.g., show()) while keeping default behavior for others:

public function show($id)
{
    $user = $this->model->findOrFail($id);
    return $this->respondWithItem($user, 'User retrieved');
}

Implementation Patterns

1. Model-Driven Workflows

• Auto-Inject Models: Declare $model in your controller to auto-generate CRUD endpoints.
• Custom Queries: Override getModel() to modify the query builder:

  protected function getModel()
  {
      return $this->model->with('roles')->where('active', 1);
  }
  

2. API Versioning

• Route-Based: Use Route::apiResource('v1/users', ...) and rely on ApiVersionMiddleware.
• Header-Based: Set Accept: application/vnd.api.v1+json in requests.
• Configurable: Adjust api_versions in config/rest.php.

3. Response Standardization

• Success Responses:

  return $this->respondWithSuccess('Data fetched', ['key' => 'value']);
  

  Output:

  {
    "success": true,
    "message": "Data fetched",
    "data": { "key": "value" }
  }
  

• Error Responses:

  return $this->respondWithError('Not found', 404);
  

4. Pagination

• Default: Uses Laravel’s paginate() (configurable in config/rest.php).
• Customize:

  protected $paginate = 20; // Override per controller
  

5. Request Validation

• Built-in: Uses Laravel’s FormRequest. Extend Dbstudios\Rest\Requests\RestRequest:

  use Dbstudios\Rest\Requests\RestRequest;
  
  class StoreUserRequest extends RestRequest
  {
      public function rules()
      {
          return ['email' => 'required|email'];
      }
  }
  

• Auto-Validation: Annotate controllers:

  public function store(StoreUserRequest $request)
  {
      // Validated automatically
  }
  

6. Middleware Integration

• Global Middleware: Add to RestServiceProvider:

  protected $middleware = [
      \App\Http\Middleware\CheckApiKey::class,
  ];
  

• Per-Controller: Use middleware() in controllers:

  public function __construct()
  {
      $this->middleware('auth:api')->except(['index', 'show']);
  }
  

Gotchas and Tips

Pitfalls

1. Model Not Found

   • Issue: Forgetting to declare $model or using a non-Eloquent class.
   • Fix: Ensure $model points to a valid Eloquent model.

2. Versioning Conflicts

   • Issue: Routes not respecting versioning due to misconfigured middleware.
   • Fix: Verify ApiVersionMiddleware is registered in RestServiceProvider and routes use apiResource.

3. Pagination Overrides

   • Issue: $paginate not being respected.
   • Fix: Check for typos in config/rest.php or controller overrides.

4. Validation Errors

   • Issue: Custom requests not triggering validation.
   • Fix: Ensure requests extend RestRequest and are properly annotated in controller methods.

5. CORS Headers

   • Issue: Missing CORS headers in responses.
   • Fix: Install fruitcake/laravel-cors or manually add headers in middleware.

Debugging Tips

1. Log Responses Temporarily modify ApiResponseFormatter to log payloads:

   Log::debug('Response:', $responseData);
   

2. Check Middleware Order Use php artisan route:list to verify middleware is applied correctly.

3. Validate Config Dump the merged config:

   dd(config('rest'));
   

4. Override Defaults Extend core classes (e.g., RestController) to debug behavior:

   class CustomRestController extends RestController
   {
       public function __construct()
       {
           parent::__construct();
           Log::info('Controller initialized');
       }
   }
   

Extension Points

1. Custom Formatters Extend Dbstudios\Rest\Formatters\ApiResponseFormatter to modify response structure:

   class CustomFormatter extends ApiResponseFormatter
   {
       protected function customizeResponse(array $data, string $message, int $status)
       {
           $data['custom_field'] = 'value';
           return parent::customizeResponse($data, $message, $status);
       }
   }
   

   Register in RestServiceProvider:

   $this->app->bind(
       ApiResponseFormatter::class,
       CustomFormatter::class
   );
   

2. Add Custom Methods Extend RestController to add domain-specific actions:

   public function softDelete($id)
   {
       $item = $this->model->findOrFail($id);
       $item->delete();
       return $this->respondWithSuccess('Item soft-deleted');
   }
   

3. Hooks for Pre/Post Actions Override beforeAction() or afterAction() in controllers:

   protected function beforeAction()
   {
       Log::info('Before action hook');
   }
   

4. Event Listeners Listen to rest.before or rest.after events in EventServiceProvider:

   protected $listen = [
       'rest.before' => [
           \App\Listeners\LogRequest::class,
       ],
   ];
   

Config Quirks

1. Default API Version Set in config/rest.php:

   'default_version' => 'v1',
   

   Override per route with Route::apiResource('v2/users', ...).

2. Response Wrapping Disable with:

   'wrap_responses' => false,
   

3. Pagination Links Disable in config:

   'paginate_links' => false,
   

Performance Tips

1. Eager Loading Use with() in getModel() to avoid N+1 queries:

   protected function getModel()
   {
       return $this->model->with('posts');
   }
   

2. Caching Responses Cache frequent queries in beforeAction():

   $data = Cache::remember("users_{$id}", now()->addHours(1), function() use ($id) {
       return $this->model->find($id);
   });
   

3. Batch Processing Use chunking for large datasets:

   $this->model->chunk(100, function ($items) {
       // Process batch
   });