Nimbus Laravel Package

Getting Started

First Steps

1. Installation

   composer require sunchayn/nimbus
   php artisan nimbus:install
   

   This publishes the config file (config/nimbus.php) and creates a migration for the schema cache table.

2. Basic Configuration

   • Ensure your routes/api.php (or relevant route file) contains properly defined API routes with validation rules.
   • Run migrations:

     php artisan migrate
     

3. First Use Case

   • Visit /nimbus in your browser (or the configured route in nimbus.php).
   • Nimbus will auto-discover your API routes and display an interactive schema with request/response examples, validation rules, and a live testing interface.

Implementation Patterns

Core Workflows

1. Schema Generation

   • Nimbus scans your route definitions and validation rules (e.g., Request classes, Validator rules, or inline Route::post()->validate()).
   • Example: Use FormRequest classes for complex validation:

     namespace App\Http\Requests;
     use Illuminate\Foundation\Http\FormRequest;
     class StorePostRequest extends FormRequest {
         public function rules() {
             return ['title' => 'required|string', 'body' => 'required|string|max:1000'];
         }
     }
     

   • Nimbus will auto-generate a schema with these rules in the UI.

2. Testing API Endpoints

   • The UI provides a live request builder with:
     • Pre-filled headers (e.g., Accept: application/json, Authorization if middleware is configured).
     • Dynamic validation feedback (e.g., real-time error messages for invalid inputs).
   • Example Workflow:
     1. Select an endpoint (e.g., POST /api/posts).
     2. Fill in the request body (auto-completed with validation rules).
     3. Click "Send" to test the endpoint and view the response.

3. Integration with Laravel Features

   • Middleware: Nimbus respects middleware (e.g., auth:sanctum). Test authenticated routes by logging in via the UI.
   • Rate Limiting: Visualize rate limit headers (e.g., X-RateLimit-Remaining) in responses.
   • API Resources: If using Illuminate\Http\Resources\Json\JsonResource, Nimbus will display the structured response format.

4. Customizing the UI

   • Override the default Blade views by publishing and modifying:

     php artisan vendor:publish --tag=nimbus-views
     

   • Extend the schema with custom metadata (e.g., descriptions, examples) via annotations in your FormRequest:

     /**
      * @property string $title - The post title (max 100 chars)
      */
     

5. Programmatic Access

   • Use the Nimbus facade to generate schemas programmatically:

     use Sunchayn\Nimbus\Facades\Nimbus;
     $schema = Nimbus::schemaForRoute('api.posts.store');
     

Gotchas and Tips

Common Pitfalls

1. Route Caching Conflicts

   • If routes are cached (php artisan route:cache), Nimbus may not detect changes. Clear the cache after modifying routes:

     php artisan route:clear
     

   • Tip: Exclude cached routes from Nimbus by adding a comment:

     // nimbus:ignore
     Route::post('/admin/secret', ...);
     

2. Validation Rule Mismatches

   • Nimbus may not pick up dynamic validation rules (e.g., rules set in boot() or middleware). Ensure rules are defined in FormRequest or inline route validation.
   • Debugging: Check the schema cache table (nimbus_schemas) for discrepancies. Clear the cache with:

     php artisan nimbus:clear
     

3. Authentication Issues

   • If testing authenticated routes, ensure the Nimbus UI session is properly authenticated. Use middleware like auth:sanctum in your routes and log in via the UI.
   • Tip: Add a "Login" button to the Nimbus dashboard for quick authentication.

4. Performance with Large APIs

   • Nimbus generates schemas on-demand. For APIs with >500 routes, consider:
     • Excluding unused routes via nimbus.php:

       'exclude' => [
           'admin/*',
           'web/*',
       ],
       

     • Disabling schema caching (not recommended for production):

       'cache' => false,
       

5. Custom Validation Rules

   • Nimbus may not recognize custom validation rules (e.g., rule:custom). Extend the schema builder by publishing the config and adding custom rule mappings:

     'custom_rules' => [
         'custom' => ['type' => 'string', 'description' => 'Custom validation logic'],
     ],
     

Debugging Tips

• Schema Inspection: Use Tinker to inspect generated schemas:

  php artisan tinker
  >>> \Sunchayn\Nimbus\Facades\Nimbus::schemaForRoute('api.posts.store')->toArray();
  

• Log Level: Increase Nimbus logging in nimbus.php for verbose output:

  'log_level' => \Illuminate\Log::DEBUG,
  

• Browser DevTools: Use the "Network" tab to inspect API requests/responses made via Nimbus.

Extension Points

1. Custom UI Components

   • Extend the Vue.js frontend by publishing assets:

     php artisan vendor:publish --tag=nimbus-assets
     

   • Override components in resources/js/nimbus/.

2. Webhook Support

   • Nimbus doesn’t natively support webhooks, but you can:
     • Add a custom route to /nimbus/webhooks and use the schema UI to test.
     • Extend the SchemaBuilder to include webhook-specific metadata.

3. Dark Mode

   • Enable via config:

     'dark_mode' => env('NIMBUS_DARK_MODE', false),
     

   • Or override the CSS in the published assets.

4. Localization

   • Publish translations:

     php artisan vendor:publish --tag=nimbus-translations
     

   • Add custom language files to resources/lang/vendor/nimbus/.