Larupload Laravel Package

Getting Started

• Check the constraint matrix first. Confirm the package version supports your PHP and Laravel versions in composer.json; the repo is small enough that a new Laravel major can land before an update does. Pin it in composer.json rather than floating.
• Install and publish config:

  composer require mostafaznv/larupload
  php artisan vendor:publish --tag=larupload-config
  

  Then read config/larupload.php end-to-end — it is the primary documentation for disks, paths, FFmpeg binaries, image driver, and naming.
• Satisfy the runtime dependencies. GD or Imagick for images; ffmpeg/ffprobe on the host (or in the container image) for video/audio. Verify the binary paths manually before blaming the package: which ffmpeg && ffmpeg -version.
• Public disk link (php artisan storage:link) if you use the public disk, otherwise every url() will 404.
• First model: add the package trait, then declare the upload definition:

  public array $larupload = [
      'main' => [
          'name'   => 'main',
          'styles' => [
              'thumb' => ['width' => 300, 'height' => 300, 'mode' => 'crop'],
          ],
      ],
  ];
  

• First migration: use the package's Blueprint macro ($table->larupload('main')) rather than hand-rolling columns — the meta layout is the package's business. If the macro isn't available, copy the stub from the package's migration files.
• First controller/view: assign the uploaded file to the attribute, save, then read it back:

  $post->main = $request->file('image');
  $post->save();
  
  $post->main->url();        // original
  $post->main->url('thumb'); // style
  $post->main->meta();       // size, mime, width/height, duration...
  

• Where to look next: the README and linked docs site for the public API; src/Attachment (or equivalent) for the full set of accessors (url, cover, meta, size/mime/dominant-color); the tests/ directory for real usage — with a package this size, tests are more current than blog posts.

Implementation Patterns

• Assignment-then-save is the core idiom. The attribute is a pending-upload object until save() persists the row and moves the file. Everything before save() is cheap; nothing exists on disk until then.
• Let the model own style definitions. Styles (crop/resize, format, quality) belong in $larupload, not scattered through controllers. Treat them as schema: changing them later requires regenerating derivatives, so decide early.
• Multiple uploads per model. Give each entry a distinct key matching its column/attribute, and name the file input identically in the form to avoid mapping code. A Post with main (image), video (video), and attachment (document) is a normal setup.
• Video/audio: enable FFmpeg, then lean on the generated cover() poster and duration metadata instead of pulling in a second package. Keep short uploads synchronous; push large transcodes into a queued job dispatched afterCommit.
• Documents: treat as opaque blobs, but always persist meta()'s original filename and MIME so a download endpoint can set Content-Disposition correctly. Serve through a signed route or temporaryUrl(), not a guessed disk path.
• Standalone mode for uploads that don't have a parent row yet (rich-text editors, wizard steps, temporary drafts). Save via the standalone API, return an identifier, then attach on final submit. This is also the natural place for async/chunked upload UX.
• Validation stays in Laravel. Use File::image(), mimes:, max: rules before assignment; the package handles storage and derivatives, not policy. Add authorization on the endpoint as usual.
• API resources: map to plain output once — ['url' => $post->main->url(), 'thumb' => $post->main->url('thumb')] — rather than letting presentation-layer code call meta() in loops or serializing the internal object.
• Tests: Storage::fake('public') plus assertExists on the expected path. Assert on metadata the package writes rather than exact bytes or exact FFmpeg output, which varies by build.

Gotchas and Tips

• Small ecosystem. Low star count means few Stack Overflow answers and fewer third-party examples. The README, config comments, and tests are the source of truth; pin versions and read the changelog before upgrading, especially around Intervention Image or Laravel majors.
• FFmpeg failures are late and deep. Missing binaries often surface as an exception inside the processing pipeline rather than a clear "ffmpeg not found." Reproduce the command by hand first; verify the container image actually ships FFmpeg.
• GD vs Imagick is not cosmetic. Format support, EXIF orientation, and animated GIF behavior differ. Pick one in config and test uploads from real phones (HEIC/EXIF-rotated JPEGs are the usual breakage).
• Don't bypass the package for deletes/replacements. Storage::delete() behind its back leaves styles and cover files orphaned. Always delete or replace through the attachment API so all derivatives are cleaned.
• Style changes need a regeneration plan. There's no magic backfill: changing dimensions or formats leaves old files as-is. Write a one-off command/job that re-processes existing rows if you must migrate styles.
• Attribute naming collisions. If your $larupload key collides with a real DB column (or vice versa), you get confusing nulls and "column not found" errors. The uploaded attribute is an object, not a string — don't dd() it expecting a path; log meta() instead.
• JSON meta and queries. Metadata lives in JSON. Sorting/filtering on size or duration works on MySQL 5.7+/Postgres JSON paths but is fragile in SQLite (common in tests). Keep heavy filtering in PHP or duplicate key fields into real columns.
• No transactionality across DB + disk. If you move uploads into jobs, handle both failure modes: row committed but file missing, and file written but row rolled back. Use afterCommit, make jobs idempotent, and add a cleanup sweep for orphaned directories.
• Disk quirks. Config is global but overridable per upload; S3 needs correct visibility and does not behave like the public disk (url() vs temporaryUrl()). Verify APP_URL, FILESYSTEM_DISK, and bucket policy before debugging the package.
• Extension points to prefer over patching internals: model-level $larupload definitions, config-level disk/FFmpeg/image settings, and custom style definitions. Subclassing Attachment is possible but couples you to internals on upgrade.
• Debugging order: (1) inspect the row's meta JSON, (2) inspect the disk path, (3) read storage/logs/laravel.log for the underlying FFmpeg/Intervention exception, (4) confirm APP_URL/storage:link for URL symptoms. That sequence resolves most "it uploaded but the URL is broken" reports.