Lumen.rest Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require nebo15/lumen.rest
   php artisan vendor:publish --provider="Nebo15\REST\RESTServiceProvider"
   

   • Publishes the package config and migrations (if any) to config/rest.php and database/migrations/.

2. Generate a CRUD Endpoint:

   php artisan rest:create Post
   

   • Creates:
     • A PostController with basic CRUD methods (index, store, show, update, destroy).
     • A Post model (if not exists).
     • A PostRepository (interface + implementation).
     • A PostRequest (form request for validation).

3. Register the API Route: In bootstrap/app.php or routes/web.php:

   $api = $app->make('Nebo15\REST\Router');
   $api->api('api/v1', 'PostController', ['auth']);
   

   • Maps routes like:
     • GET /api/v1/posts → index
     • POST /api/v1/posts → store
     • GET /api/v1/posts/{id} → show
     • PUT/PATCH /api/v1/posts/{id} → update
     • DELETE /api/v1/posts/{id} → destroy

4. Test the Endpoint: Use tools like Postman or cURL to hit the generated routes. Example:

   curl -X GET http://your-lumen-app/api/v1/posts
   

First Use Case: Rapid API Prototyping

• Scenario: Quickly scaffold a RESTful API for a blog with Post, User, and Comment resources.
• Workflow:
  1. Generate controllers/repositories for each model:

     php artisan rest:create Post
     php artisan rest:create User
     php artisan rest:create Comment
     

  2. Register routes in routes/web.php:

     $api->api('api/v1', 'PostController', ['auth']);
     $api->api('api/v1', 'UserController', ['auth']);
     $api->api('api/v1', 'CommentController', ['auth']);
     

  3. Extend the generated Request classes (e.g., PostRequest) to add custom validation rules.
  4. Deploy and test.

Implementation Patterns

Core Workflows

1. Controller Layer:

   • Generated controllers extend Nebo15\REST\Controller and delegate logic to repositories.
   • Override methods like store(), update(), or customAction() for business logic.
   • Example:

     public function store(PostRequest $request)
     {
         $data = $request->all();
         $data['author_id'] = auth()->id(); // Custom logic
         return $this->repository->create($data);
     }
     

2. Repository Pattern:

   • Use the generated PostRepository to abstract data access.
   • Extend Nebo15\REST\Repository\Eloquent for Eloquent-based implementations.
   • Example:

     public function findWithAuthor($id)
     {
         return $this->model->with('author')->find($id);
     }
     

3. Request Validation:

   • Generated PostRequest extends Nebo15\REST\Request and uses Laravel's form requests.
   • Add rules in the rules() method:

     public function rules()
     {
         return [
             'title' => 'required|string|max:255',
             'content' => 'required|string',
             'author_id' => 'exists:users,id',
         ];
     }
     

4. Middleware Integration:

   • Pass middleware as an array to the api() method:

     $api->api('api/v1', 'PostController', ['auth', 'throttle:60,1']);
     

   • Supports global middleware (e.g., auth) and custom middleware.

5. Resource Transformation:

   • Use Laravel's Resource classes (v5) or manually transform data in controllers/repositories.
   • Example with JsonResource:

     public function show($id)
     {
         $post = $this->repository->find($id);
         return new PostResource($post);
     }
     

Integration Tips

1. Versioning:

   • Use route prefixes for versioning:

     $api->api('api/v1/posts', 'PostController', ['auth']);
     $api->api('api/v2/posts', 'PostController', ['auth']);
     

2. API Documentation:

   • Pair with tools like Swagger or Postman to document endpoints.
   • Example Swagger annotation in a controller:

     /**
      * @GET /api/v1/posts
      * @return array
      */
     public function index()
     

3. Testing:

   • Use Laravel's Http tests to test controllers:

     public function testCreatePost()
     {
         $response = $this->post('/api/v1/posts', [
             'title' => 'Test Post',
             'content' => 'Hello World',
         ]);
         $response->assertStatus(201);
     }
     

4. Custom Actions:

   • Add non-CRUD methods to controllers:

     public function publish($id)
     {
         $post = $this->repository->find($id);
         $post->update(['published_at' => now()]);
         return response()->json(['message' => 'Published!']);
     }
     

   • Register the route manually in routes/web.php:

     $api->get('api/v1/posts/{id}/publish', 'PostController@publish');
     

5. Pagination:

   • Use Laravel's built-in pagination in the index() method:

     public function index()
     {
         return $this->repository->paginate(10);
     }
     

Gotchas and Tips

Pitfalls

1. Outdated Package:

   • Last release in 2016; may not support modern Laravel/Lumen versions (e.g., Lumen 8+).
   • Workaround: Fork the repo and update dependencies (e.g., laravel/framework, illuminate/database).

2. No Built-in DTOs/Resources:

   • The package doesn’t include Laravel's Resource classes (introduced in Laravel 5.1).
   • Tip: Manually create JsonResource classes or use a package like spatie/laravel-data.

3. Limited Customization:

   • Generated controllers/repositories are rigid. Heavy customization may require rewriting.
   • Tip: Extend the base classes and override methods as needed.

4. Middleware Conflicts:

   • Middleware passed to api() may conflict with global middleware.
   • Tip: Test middleware order and use ->except() or ->only() in HandleThrottleRequests if needed.

5. No API Rate Limiting:

   • The package doesn’t include built-in rate limiting.
   • Tip: Use Laravel's throttle middleware or a package like fruitcake/laravel-throttle.

6. Database Migrations:

   • The package doesn’t generate migrations. Create them manually or use a scaffold tool like laravel/model:make.

Debugging Tips

1. Route Debugging:

   • Dump registered routes to verify API endpoints:

     Route::get('/debug/routes', function() {
         return response()->json(Route::getRoutes()->getRoutes());
     });
     

2. Repository Debugging:

   • Add logging to repository methods:

     public function find($id)
     {
         \Log::debug("Finding model ID: {$id}");
         return parent::find($id);
     }
     

3. Request Validation:

   • Check validation errors in responses:

     public function store(PostRequest $request)
     {
         if ($request->fails()) {
             return response()->json($request->errors(), 422);
         }
         // ...
     }
     

4. Middleware Debugging:

   • Temporarily disable middleware to isolate issues:

     $api->api('api/v1', 'PostController', []); // Disable middleware
     

Extension Points

1. Custom Repository Methods:

   • Add methods to the repository interface and implementation:

     // PostRepositoryInterface.php
     public function findPublished();
     

     // PostRepository.php
     public function findPublished()
     {
         return $this->model->where('published_at', '<=', now())->get();
     }
     

2. Custom Controller Actions:

   • Extend the controller to add actions:

     public function archive($id)
     {
         $this->repository->archive($id);
         return response()->json(['message' => 'Archived']);
     }
     

3. Override Base Classes:

   • Replace the default Controller or Repository classes