Smart Response Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require quonain/smart-response
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Quonain\SmartResponse\SmartResponseServiceProvider"
   

2. First Use Case: Replace a standard controller method with a unified response:

   use Quonain\SmartResponse\Facades\SmartResponse;
   
   public function index()
   {
       $data = ['users' => User::all()];
       return SmartResponse::make($data);
   }
   

   • API Request: Returns JSON ({"users": [...]})
   • Web Request: Returns Blade/Inertia view with $data passed to the view.

Where to Look First

• Config File: config/smart-response.php (customize detection logic, default view, etc.)
• Facade: SmartResponse::make() for unified responses.
• Middleware: Built-in SmartResponseMiddleware for automatic detection.

Implementation Patterns

Unified Response Workflow

1. Single Controller Method:

   public function show($id)
   {
       $user = User::findOrFail($id);
       return SmartResponse::make([
           'user' => $user,
           'meta' => ['status' => 'active']
       ]);
   }
   

   • API: Returns JSON with meta field.
   • Web: Passes $user and $meta to the default view (e.g., users.show).

2. View Overrides: Specify a custom view for web responses:

   return SmartResponse::make($data)->view('custom.users.show');
   

Integration Tips

• API Routes: Prefix with /api/ for automatic JSON detection.
• Inertia.js: Works seamlessly with SmartResponse::make() for SPA responses.
• Pagination: Use SmartResponse::paginate() for API pagination:

  return SmartResponse::paginate(User::paginate(10));
  

• Middleware: Add SmartResponseMiddleware to your web/api routes:

  Route::middleware(['web', 'smart.response'])->group(function () {
      // Routes here
  });
  

Facade vs. Helpers

• Facade: SmartResponse::make(), SmartResponse::paginate().
• Global Helpers: smartResponse(), smartPaginate() (if enabled in config).

Response Macros

Extend responses dynamically:

\Quonain\SmartResponse\Facades\SmartResponse::macro('success', function ($data) {
    return $this->make($data)->withStatus(200)->withMeta(['success' => true]);
});

Usage:

return SmartResponse::success(['message' => 'Done']);

Gotchas and Tips

Pitfalls

1. Detection Logic Conflicts:

   • If Accept: application/json is sent but the route is /web/..., the package may misdetect. Override detection in config:

     'detection' => [
         'headers' => ['Accept' => 'application/json'],
         'routes' => ['prefix' => 'api'],
         'custom' => function ($request) {
             return $request->expectsJson() || $request->bearerToken();
         }
     ],
     

2. View Not Found:

   • Ensure the default view (config('smart-response.default_view')) exists. For Inertia, set:

     'default_view' => 'layouts.app', // Inertia's default layout
     

3. Caching API Responses:

   • Use SmartResponse::cache() for API responses:

     return SmartResponse::make($data)->cache(60); // Cache for 60 mins
     

   • Gotcha: Caching applies only to API responses (JSON). Web views are cached separately.

Debugging

• Log Detection: Enable debug mode in config:

  'debug' => env('SMART_RESPONSE_DEBUG', false),
  

  Check Laravel logs for detection details.

• Override Detection: Temporarily force a response type:

  return SmartResponse::make($data)->forceJson(); // Force JSON
  // or
  return SmartResponse::make($data)->forceView(); // Force Blade/Inertia
  

Extension Points

1. Custom Response Classes: Extend Quonain\SmartResponse\SmartResponse to add methods:

   namespace App\Extensions;
   use Quonain\SmartResponse\SmartResponse as BaseResponse;
   
   class CustomResponse extends BaseResponse {
       public function customMethod() {
           return $this->withMeta(['custom' => true]);
       }
   }
   

   Use via facade:

   SmartResponse::setCustomClass(CustomResponse::class);
   

2. Event Listeners: Listen for smart.response.sent events to log or modify responses:

   \Event::listen('smart.response.sent', function ($response) {
       \Log::info('Response sent:', ['type' => $response->isJson() ? 'API' : 'Web']);
   });
   

Performance Tips

• Disable Detection for Known Routes: Use middleware to skip detection for specific routes:

  Route::middleware(['smart.response:skip'])->group(function () {
      // Routes where detection is disabled
  });
  

• Lazy-Load Views: For heavy views, defer loading until needed:

  return SmartResponse::make($data)->lazyView(function () {
      return view('heavy.view')->with('data', $data);
  });
  

Rate Limiting

• API-Specific Limits: Use SmartResponse::throttle() to apply rate limits:

  return SmartResponse::make($data)->throttle('api', 60); // 60 requests/min
  

  Configure keys in config/smart-response.php:

  'rate_limits' => [
      'api' => 'api|60',
  ],