Chill Doc Store Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require chill-project/chill-doc-store
   php artisan vendor:publish --provider="Chill\DocStore\DocStoreServiceProvider" --tag="config"
   php artisan migrate
   

   • Verify the doc_store table exists in your database.

2. First Use Case: Uploading a Document

   use Chill\DocStore\Models\Document;
   
   $document = Document::create([
       'title' => 'Project Proposal',
       'description' => 'Q3 2024 Proposal',
       'file_path' => 'documents/project-proposal.pdf', // Relative to storage/app/public
       'mime_type' => 'application/pdf',
       'size' => 2048, // in KB
   ]);
   

   • Ensure storage/app/public/documents is symlinked to public/documents:

     php artisan storage:link
     

3. Retrieving a Document

   $document = Document::find(1);
   $filePath = $document->getFullPath(); // Returns full public URL
   

Implementation Patterns

Core Workflows

1. File Upload Handling

   • Use the Chill\DocStore\Services\DocumentUploader service for automated uploads:

     use Chill\DocStore\Services\DocumentUploader;
     
     $uploader = app(DocumentUploader::class);
     $result = $uploader->upload(
         file: $request->file('document'),
         metadata: ['title' => 'Contract', 'client_id' => 123]
     );
     // Returns Document model or throws exception
     

2. Versioning Documents

   • Enable versioning in config/doc-store.php:

     'versioning' => true,
     

   • Access versions via:

     $document->versions()->latest()->first();
     

3. Access Control

   • Attach policies to the Document model (e.g., DocumentPolicy):

     use Chill\DocStore\Models\Document;
     
     class DocumentPolicy
     {
         public function download(User $user, Document $document)
         {
             return $user->hasRole('admin') || $document->user_id === $user->id;
         }
     }
     

4. Events and Observers

   • Listen for document events (e.g., DocumentCreated):

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

Integration Tips

1. Laravel Filesystem

   • Customize storage disk in config/doc-store.php:

     'disk' => 's3', // Use 's3', 'local', or custom disk
     's3' => [
         'bucket' => 'my-documents-bucket',
     ],
     

2. API Responses

   • Serialize documents with API resources:

     namespace App\Http\Resources;
     
     use Chill\DocStore\Models\Document;
     use Illuminate\Http\Resources\Json\JsonResource;
     
     class DocumentResource extends JsonResource
     {
         public function toArray($request)
         {
             return [
                 'id' => $this->id,
                 'title' => $this->title,
                 'url' => $this->getFullPath(),
                 'size' => $this->size,
                 'created_at' => $this->created_at->toIso8601String(),
             ];
         }
     }
     

3. Frontend Integration

   • Use the document-url helper in Blade:

     <a href="{{ document_url($document) }}" download>Download</a>
     

Gotchas and Tips

Pitfalls

1. File Paths

   • Issue: Hardcoding storage_path() instead of using Document::getFullPath().
   • Fix: Always use getFullPath() for public URLs to handle symlinks/config changes.

2. Mime Type Detection

   • Issue: Incorrect mime_type can break downloads or security checks.
   • Fix: Use Laravel’s mime-type package or validate manually:

     $mime = mime_content_type($file->getPathname());
     

3. Versioning Overhead

   • Issue: Enabling versioning without cleanup can bloat storage.
   • Fix: Implement a cron job to purge old versions:

     // app/Console/Commands/CleanupDocVersions.php
     Document::where('created_at', '<', now()->subMonths(6))
         ->each(function ($doc) {
             $doc->versions()->where('created_at', '<', now()->subMonths(3))->delete();
         });
     

4. Concurrent Uploads

   • Issue: Race conditions when uploading files with the same name.
   • Fix: Use UUIDs or timestamps in filenames:

     $path = "documents/{$document->id}_{$document->title}_{time()}.{$extension}";
     

Debugging

1. Missing Files

   • Check:
     • storage/app/public/documents symlink exists.
     • File permissions (chmod -R 755 storage/app/public).
     • config/doc-store.php disk settings.

2. Slow Queries

   • Add indexes to doc_store table:

     Schema::table('doc_store', function (Blueprint $table) {
         $table->index('user_id');
         $table->index('mime_type');
     });
     

Extension Points

1. Custom Storage Logic

   • Override the Chill\DocStore\Services\DocumentUploader class to add pre/post-upload logic:

     class CustomDocumentUploader extends DocumentUploader
     {
         protected function beforeUpload(Document $document, $file)
         {
             // Add watermark, validate size, etc.
         }
     }
     

   • Bind it in a service provider:

     $this->app->bind(DocumentUploader::class, CustomDocumentUploader::class);
     

2. Metadata Fields

   • Extend the Document model to add custom fields:

     class Document extends \Chill\DocStore\Models\Document
     {
         protected $casts = [
             'tags' => 'array',
             'expiry_date' => 'datetime',
         ];
     }
     

3. Webhooks

   • Trigger external actions on document events:

     Document::created(function ($document) {
         Http::post('https://webhook.example.com/documents', [
             'document_id' => $document->id,
             'title' => $document->title,
         ]);
     });