Ti Ext Api Laravel Package

Getting Started

Minimal Setup Steps

1. Installation:

   composer require tastyigniter/ti-ext-api
   php artisan ti-ext-api:install
   

   • Publishes config (config/igniter-api.php) and migrations.

2. Configuration:

   • Update config/igniter-api.php to define:
     • Auth fallback (e.g., 'all' or 'admin').
     • Custom token groups/abilities.
   • Example:

     'auth' => [
         'fallback' => 'all',
     ],
     

3. First Use Case:

   • Expose a Model API:

     php artisan ti-ext-api:resource User
     

     • Generates API routes (e.g., /api/users) and resource class (app/Http/Resources/UserResource.php).
   • Test Endpoint:

     php artisan ti-ext-api:token --email=user@example.com
     

     • Returns a Sanctum token for authentication.

4. Quick Validation:

   • Send a request to /api/users with the token:

     curl -X GET http://your-app.test/api/users -H "Authorization: Bearer {token}"
     

Where to Look First

• Documentation: TastyIgniter API Docs (focus on "Getting Started" and "Custom Resources").
• Config File: config/igniter-api.php (customize auth, token groups, and resource defaults).
• Artisan Commands:
  • ti-ext-api:resource (generate API for a model).
  • ti-ext-api:token (create test tokens).
  • ti-ext-api:abilities (manage token permissions).

Implementation Patterns

Core Workflows

1. Auto-Generating API Endpoints

• Pattern: Use ti-ext-api:resource to scaffold CRUD APIs for Eloquent models.

  php artisan ti-ext-api:resource Product --with-relations
  

  • Output:
    • Routes (routes/api.php).
    • Resource class (app/Http/Resources/ProductResource.php).
    • Controller (app/Http/Controllers/Api/ProductController.php).
  • Relations: Automatically includes defined model relationships (e.g., Product::hasMany(Inventory::class)).

• When to Use:

  • Rapid prototyping of standard CRUD APIs.
  • Exposing TastyIgniter core models (e.g., User, Order, Menu).

2. Customizing API Resources

• Pattern: Extend auto-generated resources or override methods.

  • Example: Hide sensitive fields in UserResource:

    namespace App\Http\Resources;
    
    use TastyIgniter\Api\Resources\ApiResource;
    
    class UserResource extends ApiResource
    {
        public function toArray($request)
        {
            return array_merge(parent::toArray($request), [
                'custom_field' => $this->whenLoaded('customField'),
            ]);
        }
    }
    

  • Override Actions: Modify controller methods (e.g., store()):

    public function store(Request $request)
    {
        $validated = $request->validate([
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users',
            // Custom validation
        ]);
        return parent::store($request);
    }
    

• When to Use:

  • Tailoring responses (e.g., omitting passwords, adding computed fields).
  • Enforcing business logic (e.g., validation, pre-processing).

3. Token-Based Authentication

• Pattern: Use Sanctum tokens with custom abilities.

  • Generate Token:

    php artisan ti-ext-api:token --email=admin@example.com --group=admin
    

  • Define Abilities (in config/igniter-api.php):

    'abilities' => [
        'admin' => ['users.create', 'orders.update'],
        'editor' => ['menus.read'],
    ],
    

  • Authorize in Code:

    public function update(Request $request, $id)
    {
        $this->authorize('orders.update'); // Uses Sanctum's ability system
        return parent::update($request, $id);
    }
    

• When to Use:

  • Securing endpoints for mobile apps/SPAs.
  • Role-based access control (RBAC).

4. Custom API Resources

• Pattern: Create standalone API resources for non-model data.

  • Generate Resource:

    php artisan ti-ext-api:resource CustomReport --type=custom
    

  • Define Logic (e.g., app/Http/Controllers/Api/CustomReportController.php):

    public function index()
    {
        return response()->json([
            'data' => $this->fetchReportData(),
        ]);
    }
    
    private function fetchReportData()
    {
        // Custom logic (e.g., query database, call external API)
        return Report::query()->where('active', true)->get();
    }
    

  • Route Manually: Add to routes/api.php:

    Route::apiResource('reports', \App\Http\Controllers\Api\CustomReportController::class);
    

• When to Use:

  • APIs for non-Eloquent data (e.g., analytics, third-party integrations).
  • Complex logic not tied to a single model.

5. Pagination and Filtering

• Pattern: Leverage Laravel’s built-in pagination and query scopes.

  • Auto-Pagination: Enabled by default for index() endpoints.
  • Custom Scopes: Add to your model:

    public function scopeActive($query)
    {
        return $query->where('is_active', true);
    }
    

    • Access via URL: /api/users?active=true.
  • Manual Pagination:

    public function index(Request $request)
    {
        return User::paginate($request->input('per_page', 15));
    }
    

• When to Use:

  • Large datasets (e.g., user lists, product catalogs).
  • Client-side filtering (e.g., mobile apps).

Integration Tips

Laravel Ecosystem

• Sanctum: Use ti-ext-api:token to generate tokens for testing:

  php artisan ti-ext-api:token --email=user@example.com --group=customer
  

• Testing: Write PEST/PHPUnit tests for custom controllers:

  public function test_custom_validation()
  {
      $response = $this->post('/api/users', [
          'email' => 'invalid-email',
      ]);
      $response->assertStatus(422);
  }
  

• Caching: Cache frequent API responses (e.g., product lists):

  public function index()
  {
      return Cache::remember('api_products', now()->addHours(1), function () {
          return Product::all();
      });
  }
  

TastyIgniter-Specific

• Model Extensions: Ensure your TastyIgniter models extend TastyIgniter\Api\Concerns\Apiable for full support:

  use TastyIgniter\Api\Concerns\Apiable;
  
  class Order extends Model
  {
      use Apiable;
  }
  

• Reservations/Orders: Use status-only endpoints for performance:

  Route::put('/api/orders/{id}/status', [OrderController::class, 'updateStatus']);
  

Performance

• Eager Loading: Optimize relations in resources:

  public function toArray($request)
  {
      return [
          'id' => $this->id,
          'name' => $this->name,
          'user' => UserResource::make($this->whenLoaded('user')),
      ];
  }
  

• Rate Limiting: Add middleware to app/Http/Kernel.php:

  \Illuminate\Cache\RateLimiting\Limit::perMinute(60)->by($this->resolveRequest()->ip());
  

Gotchas and Tips

Pitfalls

1. Model Compatibility Issues

• Gotcha: Auto-generated APIs fail if models lack proper fillable or guarded attributes.
  • Fix: Define these in your model:

    protected $fillable = ['name', 'email'];
    protected $guarded = ['deleted_at'];
    

• Gotcha: TastyIgniter-specific traits (e.g., SoftDeletes) may conflict with API generation.
  • Fix: Explicitly include traits in your model:

    use Illuminate\Database\Eloquent\SoftDeletes;
    use TastyIgniter\Api\Concerns\Apiable;
    
    class User extends Authenticatable
    {
        use SoftDeletes, Apiable;
    }
    

2. Authentication Quirks

• Gotcha: Default auth fallback is 'all' (not 'admin'), which may expose endpoints unintentionally.