Orbit Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: Ideal for lightweight, read-heavy applications where SQL databases are overkill (e.g., prototyping, static data storage, or low-traffic internal tools). Misaligned for high-write, transactional, or relational-heavy workloads.
• Eloquent Compatibility: Seamlessly integrates with Laravel’s Eloquent ORM, enabling familiar query syntax (where, orderBy, relations) while abstracting flat-file storage. Reduces boilerplate for simple data persistence.
• Trade-offs:
  • Pros: Zero database setup, portable storage (single file), no server dependencies, and instant cold-start performance.
  • Cons: No ACID compliance, limited to ~100MB–1GB file sizes (depends on filesystem), and no advanced features (indexing, joins, migrations).

Integration Feasibility

• Laravel Ecosystem Fit: Designed for Laravel 10+ (PHP 8.1+), with minimal configuration (add driver to config/database.php). Leverages Eloquent’s existing query builder, reducing learning curve.
• Dependencies: Only requires PHP’s built-in filesystem and json extensions. No external services or heavy libraries.
• Customization: Supports custom file paths, encryption (via OrbitEncryptor), and chunked file handling for larger datasets.

Technical Risk

• Data Corruption: Flat files are vulnerable to partial writes or filesystem failures. Mitigate with:
  • Atomic writes (e.g., temporary files + rename).
  • Backup strategies (e.g., cron jobs to duplicate files).
• Performance: File I/O becomes a bottleneck at scale (>10K records). Benchmark with dd() or telescope before production.
• Concurrency: Not thread-safe. Use Laravel’s queue system or external locks (e.g., flock) for multi-process writes.
• Schema Evolution: Manual migrations required (e.g., php artisan orbit:migrate). No built-in schema management.

Key Questions

1. Data Volume: Will the dataset exceed 1GB? If so, consider hybrid storage (e.g., SQLite for meta + Orbit for blobs).
2. Concurrency Needs: How many concurrent writes are expected? If >1, implement locking.
3. Backup Strategy: How will you handle file corruption or accidental deletions?
4. Query Complexity: Are you using advanced Eloquent features (e.g., hasManyThrough)? Orbit may simplify these to linear scans.
5. Deployment: Is the storage location (e.g., /storage/orbit) writable and persistent across deployments?

Integration Approach

Stack Fit

• Best For:
  • Laravel applications with simple data models (e.g., CMS pages, configuration, or user-generated content).
  • Serverless/edge deployments (e.g., Laravel Vapor) where database provisioning is costly.
  • Development environments (e.g., local testing, seed data).
• Avoid For:
  • High-traffic APIs or applications requiring complex queries/transactions.
  • Multi-tenant systems needing isolation.

Migration Path

1. Pilot Phase:
   • Start with non-critical models (e.g., Settings, StaticPages).
   • Use OrbitServiceProvider to register the driver alongside existing DB connections.

   // config/database.php
   'connections' => [
       'orbit' => [
           'driver' => 'orbit',
           'path' => storage_path('app/orbit'),
       ],
   ];
   

2. Hybrid Approach:
   • Migrate read-heavy tables to Orbit while keeping write-heavy tables in MySQL/PostgreSQL.
   • Use Eloquent’s connection() method to route models dynamically:

     class Product extends Model {
         protected $connection = 'orbit'; // or 'mysql'
     }
     

3. Full Migration:
   • Export data from the old DB to JSON/CSV, then import into Orbit files using the package’s OrbitSeeder.
   • Update all model configurations to use the orbit connection.

Compatibility

• Eloquent Features Supported:
  • Basic CRUD, where, orderBy, limit, relations (via JSON nesting).
  • Soft deletes (if manually implemented in the model).
• Limitations:
  • No join clauses (use denormalized data or pre-computed relations).
  • No increment/decrement (implement manually with file reads/writes).
  • No full-text search (use Laravel Scout or Algolia for search-heavy apps).

Sequencing

1. Setup:
   • Install via Composer: composer require ryangjchandler/orbit.
   • Configure the connection in config/database.php.
2. Testing:
   • Validate with a single model (e.g., php artisan tinker):

     $user = new User(); $user->name = 'Test'; $user->save();
     

   • Test edge cases: concurrent writes, large payloads, and file permissions.
3. Monitoring:
   • Log file operations (e.g., Orbit::logQueries(true)) to detect performance issues.
   • Set up alerts for file size growth (e.g., storage_path('app/orbit') disk usage).

Operational Impact

Maintenance

• Pros:
  • No database backups or migrations (files are self-contained).
  • Easy to debug (open the JSON file directly).
• Cons:
  • Manual file management (e.g., archiving old data, rotating files).
  • No built-in monitoring (track file sizes and access times via fs events).
• Tooling:
  • Use Laravel’s filesystem events to trigger cleanup:

    // app/Providers/EventServiceProvider.php
    Event::listen(FileWritten::class, function ($event) {
        if (str_contains($event->path(), 'orbit')) {
            // Log or alert on large files
        }
    });
    

Support

• Debugging:
  • Validate data integrity by comparing file contents with query results.
  • Use Orbit::getRawData() to inspect the underlying JSON structure.
• Common Issues:
  • Permission Denied: Ensure the Laravel storage directory is writable (chmod -R 755 storage).
  • File Locking: Implement flock in custom queries for high-concurrency apps.
  • Serialization Errors: Avoid circular references in Eloquent relations.

Scaling

• Horizontal Scaling:
  • Not recommended for distributed setups (files must be shared via NFS/S3, adding latency).
  • For multi-server deployments, use a shared filesystem (e.g., S3 with flysystem adapter).
• Vertical Scaling:
  • Limit file size by partitioning data (e.g., users_1.json, users_2.json).
  • Use Orbit’s chunk option to split files by record count:

    'path' => storage_path('app/orbit'),
    'chunk' => 1000, // Split into files of ~1000 records
    

• Performance:
  • Cache frequent queries (e.g., Cache::remember()).
  • Avoid eager-loading deep relations (Orbit uses linear scans).

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Document the hybrid DB strategy (which models use Orbit vs. SQL).
  • Provide a cheat sheet for Orbit-specific Eloquent quirks (e.g., no join).
• Training:
  • Demo file-based debugging (e.g., "To fix this, open storage/app/orbit/users.json").
  • Train ops on backup procedures (e.g., zip -r orbit_backup.zip storage/app/orbit).
• Documentation:
  • Add a README.md section in your repo outlining Orbit’s role in the stack.
  • Example:

    ## Data Storage
    - **Orbit**: Used for static data (e.g., `/config`, `/pages`).
    - **MySQL**: Used for dynamic data (e.g., `/users`, `/orders`).