Eloquent Filemaker Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require gearbox-solutions/eloquent-filemaker
   

   Publish the config file:

   php artisan vendor:publish --provider="GearboxSolutions\EloquentFileMaker\FileMakerServiceProvider"
   

2. Configure .env Add FileMaker credentials to your .env:

   FILEMAKER_API_KEY=your_api_key
   FILEMAKER_HOST=https://your-filemaker-server.fm
   FILEMAKER_DATABASE=your_database
   

3. Define a Model Extend GearboxSolutions\EloquentFileMaker\EloquentFileMakerModel:

   use GearboxSolutions\EloquentFileMaker\EloquentFileMakerModel;
   
   class Client extends EloquentFileMakerModel
   {
       protected $table = 'clients'; // FileMaker layout name
       protected $primaryKey = 'client_id';
   }
   

4. First Query

   $client = Client::find(123);
   // or
   $clients = Client::where('status', 'active')->get();
   

Key First Use Cases

• CRUD Operations: Use create(), update(), delete() as with Eloquent.
• Relationships: Define belongsTo, hasMany, etc., via FileMaker layouts.
• API Integration: Fetch FileMaker data directly into Laravel controllers.

Implementation Patterns

Core Workflows

1. Model Definition

   • Map FileMaker layouts to Eloquent models.
   • Use $table to specify the FileMaker layout name.
   • Override $fillable for mass assignment:

     protected $fillable = ['name', 'email', 'status'];
     

2. Querying Data

   • Basic Queries:

     $activeClients = Client::where('status', 'active')->get();
     

   • Eager Loading:

     $client = Client::with('orders')->find(1);
     

   • Pagination:

     $clients = Client::paginate(10);
     

3. Relationships

   • Define relationships in models:

     public function orders()
     {
         return $this->hasMany(Order::class, 'client_id', 'client_id');
     }
     

   • Use belongsTo, hasOne, morphTo, etc., as in Eloquent.

4. Custom API Calls

   • Use FileMaker::layout('layout_name')->find() for raw API calls:

     $data = FileMaker::layout('custom_layout')->find(1, ['field1', 'field2']);
     

5. Events and Observers

   • Use Laravel’s built-in observers for model events:

     class ClientObserver
     {
         public function saved(Client $client)
         {
             // Post-save logic
         }
     }
     

   • Register in AppServiceProvider:

     Client::observe(ClientObserver::class);
     

Integration Tips

• Caching: Cache frequent queries using Laravel’s cache:

  $clients = Cache::remember('active_clients', now()->addHours(1), function () {
      return Client::where('status', 'active')->get();
  });
  

• Error Handling: Wrap API calls in try-catch:

  try {
      $client = Client::find(1);
  } catch (\Exception $e) {
      Log::error("FileMaker API Error: " . $e->getMessage());
  }
  

• Testing: Use FileMakerFake for unit tests:

  use GearboxSolutions\EloquentFileMaker\Testing\FileMakerFake;
  
  public function test_client_retrieval()
  {
      FileMakerFake::fake();
      $client = Client::find(1);
      $this->assertEquals('Test Client', $client->name);
  }
  

Gotchas and Tips

Common Pitfalls

1. Layout Mismatches

   • Ensure $table in the model matches the FileMaker layout name, not the table name.
   • Debug with:

     FileMaker::layout('layout_name')->getLayoutSchema();
     

2. Field Name Conflicts

   • FileMaker fields with special characters (e.g., field-name) may cause issues. Use $casts to normalize:

     protected $casts = [
         'field-name' => 'string',
     ];
     

3. API Rate Limits

   • FileMaker Data API has rate limits. Implement exponential backoff for retries:

     use GearboxSolutions\EloquentFileMaker\Exceptions\FileMakerException;
     
     try {
         $client = Client::find(1);
     } catch (FileMakerException $e) {
         if ($e->isRateLimited()) {
             sleep(2);
             retry();
         }
     }
     

4. Primary Key Issues

   • FileMaker layouts may not have auto-incrementing IDs. Use UUIDs or custom logic:

     protected $primaryKey = 'uuid';
     public $incrementing = false;
     

5. Relationship Caching

   • Eager loading (with()) may not work as expected if FileMaker layouts aren’t properly linked. Verify relationships with:

     $client = Client::with('orders')->find(1);
     dd($client->orders->toArray());
     

Debugging Tips

• Enable API Logging Add to config/filemaker.php:

  'log' => [
      'enabled' => true,
      'channel' => 'single',
  ],
  

  Check logs in storage/logs/laravel.log.

• Inspect Raw API Calls Use FileMaker::layout()->toDebugString() to see the last API request/response.

• Validate Layout Schema Dump the layout schema to ensure fields match:

  dd(FileMaker::layout('clients')->getLayoutSchema());
  

Extension Points

1. Custom API Endpoints Extend the FileMaker facade to support custom endpoints:

   FileMaker::extend('custom', function ($app) {
       return new CustomFileMakerApi($app);
   });
   

2. Query Scopes Add reusable scopes:

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

   Usage:

   $clients = Client::active()->get();
   

3. Model Events Override boot() for custom logic:

   protected static function boot()
   {
       parent::boot();
       static::creating(function ($model) {
           $model->slug = Str::slug($model->name);
       });
   }
   

4. Custom Casts Handle FileMaker-specific data types (e.g., timestamps, containers):

   protected $casts = [
       'created_at' => 'datetime:Y-m-d H:i:s',
       'file_container' => 'array',
   ];
   

5. Batch Operations Use chunking for large datasets:

   Client::chunk(100, function ($clients) {
       foreach ($clients as $client) {
           // Process batch
       }
   });