Orbit Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ryangjchandler/orbit
   

2. Configure config/database.php:

   'connections' => [
       'orbit' => [
           'driver' => 'orbit',
           'path' => database_path('orbit'),
       ],
   ],
   

3. Run migrations:

   php artisan orbit:migrate
   

   (Creates the database/orbit directory with users.json and migrations.json.)

4. First query:

   use App\Models\User;
   
   $user = User::create(['name' => 'John', 'email' => 'john@example.com']);
   $users = User::all(); // Returns Collection from JSON files
   

First Use Case

Replace a legacy flat-file system (e.g., JSON/CSV) with Eloquent ORM:

// Before: Manual JSON file handling
$users = json_decode(file_get_contents('data/users.json'), true);

// After: Eloquent ORM
$users = User::all()->toArray();

Implementation Patterns

1. Model-Specific File Storage

Orbit auto-generates a JSON file per model (e.g., users.json, posts.json).

• Pros: Isolated data, no schema conflicts.
• Cons: File sprawl for many models.

Example:

// Posts will use `posts.json`
Post::create(['title' => 'Hello Orbit']);

2. Migrations for Schema

Use Laravel migrations to define structure:

Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('email')->unique();
    $table->timestamps();
});

• Tip: Run php artisan orbit:migrate after adding new migrations.

3. Seeding Data

Leverage Laravel’s seeder:

public function run()
{
    User::create(['name' => 'Admin', 'email' => 'admin@example.com']);
}

• Note: Seeders run on orbit:seed, not migrate.

4. Query Scoping

Use Eloquent query builders as usual:

// Soft deletes (if enabled in model)
User::withTrashed()->get();

// Relationships
$posts = User::find(1)->posts;

5. Custom File Paths

Override default paths per model:

class Product extends Model
{
    protected $connection = 'orbit';
    public $orbitPath = 'custom/products.json';
}

6. Caching Queries

Enable caching for performance:

// In config/orbit.php
'cache' => true,

• Cache key: orbit:model:query_hash.

7. Event Listeners

Hook into Orbit events (e.g., orbit.saving, orbit.deleted):

// app/Providers/OrbitEventServiceProvider.php
public function boot()
{
    Orbit::saving(function ($model) {
        logger()->info("Saving {$model->getTable()}: {$model->id}");
    });
}

8. Testing

Use Orbit facade to reset data:

public function tearDown(): void
{
    Orbit::reset();
}

Gotchas and Tips

Pitfalls

1. File Permissions:

   • Ensure storage/database/orbit is writable.
   • Fix: chmod -R 775 storage/database/orbit.

2. Soft Deletes:

   • Requires use SoftDeletes; in model and deleted_at in migration.
   • Gotcha: withTrashed() won’t work without proper setup.

3. Concurrent Writes:

   • Orbit locks files during writes. Avoid race conditions by:
     • Using transactions (DB::transaction()).
     • Disabling caching during writes ('cache' => false in config).

4. Large Files:

   • JSON files grow with data. For >10K records, consider:
     • Splitting by ID ranges (e.g., users_1.json, users_2.json).
     • Using orbit.path to point to a mounted network drive.

5. Timestamps:

   • Orbit uses created_at/updated_at by default. Override in migration:

     $table->timestamp('custom_created_at')->useCurrent();
     

6. Model Events:

   • saved()/deleted() events fire after file writes. Use saving()/deleting() for pre-actions.

Debugging Tips

1. Check File Contents:

   cat database/orbit/users.json
   

   • Verify data matches expectations.

2. Enable Logging:

   // config/orbit.php
   'debug' => true,
   

   • Logs file operations to storage/logs/orbit.log.

3. Validate Migrations:

   • Run php artisan orbit:schema:dump to regenerate files from migrations.

4. Clear Cache:

   php artisan cache:clear
   php artisan orbit:clear-cache
   

Extension Points

1. Custom Drivers: Override OrbitServiceProvider to add support for YAML/CSV:

   Orbit::extend('yaml', function () {
       return new YamlDriver();
   });
   

2. Encryption: Use Laravel’s encryption for sensitive fields:

   $user->password = Crypt::encrypt($request->password);
   $user->save();
   

3. Backup Strategy:

   • Schedule orbit:backup to compress files:

     zip -r orbit_backup.zip database/orbit
     

4. Performance:

   • For read-heavy apps, preload files into memory:

     Orbit::preload('users');
     

5. Multi-Tenant: Use orbit.path dynamically:

   public function getOrbitPath($table)
   {
       return "orbit/{$this->tenantId}/{$table}.json";
   }