Rest Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require creonit/rest-bundle
   

   Register the bundle in config/app.php under the extra.bundles key:

   Creonit\RestBundle\CreonitRestBundle::class => ['all' => true],
   

2. Basic Configuration Publish the default config:

   php artisan vendor:publish --provider="Creonit\RestBundle\CreonitRestServiceProvider" --tag="config"
   

   Edit config/rest.php to define your API endpoints and routes.

3. First Use Case: REST Endpoint Define a simple controller to handle REST requests:

   namespace App\Http\Controllers;
   
   use Creonit\RestBundle\Annotations\Rest;
   use Creonit\RestBundle\Annotations\Route;
   
   class UserController extends Controller
   {
       /**
        * @Rest()
        * @Route("/users", name="users_list", methods={"GET"})
        */
       public function listUsers()
       {
           return response()->json(['users' => User::all()]);
       }
   }
   

   Ensure your routes are auto-discovered by the bundle (check config/rest.php for auto_discovery).

Implementation Patterns

Annotations-Based Routing

• Decorate controllers with @Rest() and @Route() annotations to define RESTful endpoints.
• Example:

  /**
   * @Rest()
   * @Route("/users/{id}", name="users_show", methods={"GET"})
   */
  public function showUser($id)
  {
      return response()->json(User::findOrFail($id));
  }
  

• Best Practice: Group related endpoints in a single controller for clarity.

Request/Response Handling

• Custom Request Validation: Use Laravel’s built-in validation or extend Creonit\RestBundle\Request\RestRequest for custom logic.

  public function storeUser(RestRequest $request)
  {
      $validated = $request->validate([
          'name' => 'required|string|max:255',
          'email' => 'required|email',
      ]);
      // Process validated data
  }
  

• Response Formatting: Leverage the bundle’s response helpers for consistency:

  return $this->restResponse()->success(['data' => $user]);
  

Integration with Laravel Features

• Middleware: Apply middleware to REST controllers via annotations:

  /**
   * @Rest(middleware={"auth:api"})
   */
  class AdminController extends Controller { ... }
  

• API Resources: Combine with Laravel’s ApiResource for structured JSON responses:

  class UserResource extends ApiResource
  {
      public function toArray($request)
      {
          return [
              'id' => $this->id,
              'name' => $this->name,
          ];
      }
  }
  

• Event Listeners: Dispatch events for pre/post-request handling:

  use Creonit\RestBundle\Events\RestRequestEvent;
  
  public function handle(RestRequestEvent $event)
  {
      // Modify request/response logic here
  }
  

Gotchas and Tips

Pitfalls

1. Annotation Caching:

   • Clear Laravel’s route cache (php artisan route:clear) after adding/removing annotations.
   • Ensure auto_discovery is enabled in config/rest.php:

     'auto_discovery' => true,
     

2. Middleware Conflicts:

   • Avoid mixing @Rest(middleware={...}) with Laravel’s global middleware. Test middleware order explicitly.

3. Validation Overrides:

   • Custom RestRequest validation may conflict with Laravel’s default validation. Use $request->merge() to preprocess data before validation.

Debugging

• Route Debugging: Use php artisan route:list to verify REST routes are registered. Filter by rest namespace if needed.

• Annotation Errors: Enable Laravel’s annotation parser logging:

  'annotations' => [
      'enabled' => true,
      'log_errors' => true,
  ],
  

  in config/rest.php.

Extension Points

1. Custom Response Formats: Extend Creonit\RestBundle\Response\RestResponse to add domain-specific response wrappers:

   class CustomRestResponse extends RestResponse
   {
       public function success($data, $code = 200)
       {
           return response()->json([
               'status' => 'success',
               'data' => $data,
               'custom_field' => 'value',
           ], $code);
       }
   }
   

2. Dynamic Route Parameters: Use Route annotation with regex for flexible parameters:

   /**
    * @Route("/users/{id:\d+}", name="users_show")
    */
   

3. Rate Limiting: Integrate with Laravel’s throttle middleware in annotations:

   /**
    * @Rest(middleware={"throttle:60,1"})
    */
   

Configuration Quirks

• CORS Settings: Configure CORS in config/rest.php if needed:

  'cors' => [
      'paths' => ['api/*'],
      'allowed_methods' => ['GET', 'POST', 'PUT', 'DELETE'],
  ],
  

• Error Handling: Override default error responses by binding to Creonit\RestBundle\Events\RestExceptionEvent.