Data Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require greenter/data
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Greenter\Data\DataServiceProvider"
   

2. First Use Case: Storing a Document Import the Greenter\Data\Document class and create a new document:

   use Greenter\Data\Document;
   
   $document = new Document();
   $document->setData([
       'invoice_number' => 'INV-12345',
       'amount' => 100.00,
       'customer' => 'John Doe'
   ]);
   $document->save(); // Assumes a default storage adapter (e.g., filesystem/database)
   

3. Where to Look First

   • Config File: config/greenter-data.php (if published) for storage adapters and settings.
   • Document Class: vendor/greenter/data/src/Document.php for core functionality.
   • Service Provider: vendor/greenter/data/src/DataServiceProvider.php for binding interfaces.

Implementation Patterns

Core Workflows

1. Document Creation and Storage Use the Document class to encapsulate data with metadata (e.g., created_at, updated_at):

   $document = new Document();
   $document->setMetadata(['user_id' => auth()->id()]);
   $document->setData($invoiceArray);
   $document->save(); // Uses the configured storage adapter
   

2. Retrieving Documents Fetch documents by ID or query:

   // By ID
   $document = Document::find($id);
   
   // Query builder (if adapter supports it)
   $documents = Document::where('invoice_number', 'LIKE', 'INV-%')->get();
   

3. Custom Storage Adapters Implement Greenter\Data\Contracts\StorageAdapter for custom backends (e.g., S3, database):

   class S3Adapter implements StorageAdapter {
       public function save(Document $document) { /* ... */ }
       public function find($id) { /* ... */ }
   }
   

   Bind the adapter in the service provider:

   $this->app->bind(
       StorageAdapter::class,
       function () { return new S3Adapter(); }
   );
   

4. Event Handling Listen for document events (e.g., document.saved):

   Document::saved(function ($document) {
       // Send notification, log, etc.
   });
   

Integration Tips

• Laravel Eloquent: Treat Document as a lightweight alternative to Eloquent models for non-relational data.
• API Responses: Serialize documents to JSON:

  return response()->json($document->toArray());
  

• Validation: Validate document data before saving:

  $validator = Validator::make($document->getData(), [
      'invoice_number' => 'required|string',
      'amount' => 'required|numeric'
  ]);
  

Gotchas and Tips

Pitfalls

1. Deprecated Package

   • Last release in 2019; verify compatibility with Laravel 8/9/10 (may require patches).
   • No active maintenance; consider forking if critical bugs arise.

2. Storage Adapter Assumptions

   • Default adapter may not be configured. Explicitly set one in config/greenter-data.php:

     'default' => env('DATA_DRIVER', 'file'),
     'drivers' => [
         'file' => Greenter\Data\Adapters\FileAdapter::class,
     ],
     

3. No Built-in Querying

   • Adapters like FileAdapter may not support querying. Use a database adapter (e.g., DatabaseAdapter) for complex queries.

4. Metadata Overrides

   • Avoid overriding created_at/updated_at manually; use setMetadata() for custom fields.

Debugging

• Adapter Issues: Check if the bound adapter implements StorageAdapter. Use:

  $this->app->bind(StorageAdapter::class, function () {
      return new CustomAdapter(); // Ensure this class exists
  });
  

• Serialization Errors: Ensure setData() accepts arrays or JSON-serializable objects.

Extension Points

1. Custom Document Types Extend Document for domain-specific logic:

   class InvoiceDocument extends Document {
       public function calculateTax() { /* ... */ }
   }
   

2. Add Fields to Metadata Override getMetadata() to include additional fields:

   public function getMetadata() {
       return array_merge(parent::getMetadata(), ['tax_rate' => $this->taxRate]);
   }
   

3. Hooks for Pre/Post Save Use events or traits to inject logic:

   Document::creating(function ($document) {
       $document->setMetadata(['ip' => request()->ip()]);
   });
   

Performance Tips

• Batch Operations: If using a database adapter, leverage bulk inserts:

  Document::insert($documentsArray);
  

• Caching: Cache frequently accessed documents:

  $document = Cache::remember("document_{$id}", now()->addHours(1), function () use ($id) {
      return Document::find($id);
  });
  

```markdown
### Config Quirks
- **Environment Variables**: The package may rely on `.env` for adapter settings (e.g., `DATA_DRIVER`). Define these explicitly:
  ```env
  DATA_DRIVER=database
  DB_DOCUMENTS_CONNECTION=mysql

• Default Values: If no config is published, defaults may not match expectations. Publish and customize:

  php artisan vendor:publish --tag=greenter-data-config