Laravel Easy Request Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require shureban/laravel-easy-request
   

   Register the service provider in config/app.php:

   Shureban\LaravelEasyRequest\EasyRequestServiceProvider::class,
   

2. Publish Config (Optional):

   php artisan vendor:publish --provider="Shureban\LaravelEasyRequest\EasyRequestServiceProvider"
   

3. First Use Case: Create a FormRequest class with PhpDoc annotations for type-safe access to request data:

   /**
    * @method string getName()
    * @method int getAge()
    */
   class UserProfileRequest extends FormRequest {}
   

   Use it in a controller:

   public function update(UserProfileRequest $request) {
       $name = $request->getName(); // Returns string (type-safe)
       $age = $request->getAge();   // Returns int (type-safe)
   }
   

Implementation Patterns

Core Workflows

1. Type-Safe Request Handling:

   • Define methods in PhpDoc for automatic type casting (e.g., int, bool, DateTime).
   • Supports snake_case/camelCase field mapping (e.g., userId() fetches user_id from input).

2. Model Instantiation:

   • Annotate methods with model types (e.g., @method User user()) to auto-fetch Eloquent models by ID:

     /**
      * @method User user()
      */
     class UserRequest extends FormRequest {
         public function rules() { return ['user_id' => 'required|int']; }
     }
     

3. Integration with Laravel Ecosystem:

   • Validation: Combine with FormRequest::rules() for validation.
   • Authorization: Use FormRequest::authorize() for policy checks.
   • API Responses: Pair with JsonResponse for consistent JSON output.

4. Dynamic Requests:

   • Use the facade (EasyRequest) for non-form requests:

     $response = EasyRequest::get('https://api.example.com/data')
         ->withHeaders(['Authorization' => 'Bearer token'])
         ->send();
     

5. Testing:

   • Mock FormRequest methods in tests:

     $request = Mockery::mock(UserRequest::class);
     $request->shouldReceive('getName')->andReturn('John');
     

Gotchas and Tips

Pitfalls

1. Type Casting Edge Cases:

   • Null values may not cast as expected (e.g., null → int fails). Handle with @method mixed|null or default values:

     /**
      * @method int|null age()
      */
     

2. Model Fetching Quirks:

   • Requires _id suffix or Id in camelCase (e.g., user_id → user() or userId()).
   • Fails silently if the model isn’t found (add ->firstOrFail() or validation).

3. Facade vs. FormRequest:

   • The EasyRequest facade is for dynamic HTTP calls; FormRequest is for typed form data. Mixing them may cause confusion.

4. Performance:

   • Model instantiation in PhpDoc methods triggers eager loading. Use sparingly in high-traffic endpoints.

Debugging Tips

• Check Annotations: Use php artisan ide-helper:generate (if using Barryvdh/laravel-ide-helper) to validate PhpDoc syntax.
• Log Raw Input: Temporarily dump $request->all() to verify field names.
• Facade Debugging: Enable Guzzle logging via config:

  'guzzle' => [
      'debug' => env('APP_DEBUG', false),
  ],
  

Extension Points

1. Custom Type Casting: Override the default caster by publishing the config and extending Shureban\LaravelEasyRequest\Caster\CasterInterface.

2. Model Resolution: Extend Shureban\LaravelEasyRequest\ModelResolver to support custom ID fields or relationships.

3. Request Macros: Add reusable methods to the facade:

   EasyRequest::macro('withAuth', function ($token) {
       return $this->withHeaders(['Authorization' => "Bearer $token"]);
   });
   

4. Testing Utilities: Create a trait for testable requests:

   trait TestableRequest {
       protected function mockRequest(array $data) {
           return Mockery::mock(UserRequest::class)->makePartial()
               ->shouldReceive('all')->andReturn($data);
       }
   }