Download the PHP package oi-lab/oi-laravel-attachments without Composer

OI Laravel Attachments BETA

A Laravel package for polymorphic file attachments. Attach files to any Eloquent model, organize them into named collections with ordering, store rich file metadata (EXIF, IPTC, dimensions, color profile), and group files into nested folders.

Features

• Polymorphic Attachments: Attach files to any model via a single HasAttachments trait
• Named Collections: Group attachments per model (e.g. gallery, cover, documents)
• Ordering: First-class sort support with reorder, move, and swap helpers
• Rich File Metadata: File model captures mimetype, filesize, dimensions, MD5, EXIF, IPTC, and color info
• Folders: Optional self-nesting folder tree for organizing files
• Upload Actions: Single-call actions to store uploads and attach them to a model
• Audit Tracking: Automatic created_by / updated_by tracking on every record
• Configurable Models: Swap in your own File, Folder, or Attachment subclasses
• Storage Agnostic: Works with any Flysystem disk (local, S3, etc.)

How It Works

The package revolves around three models:

• File — a stored file and its metadata, optionally living inside a Folder.
• Folder — a self-nesting container (parent_id tree) for organizing files.
• Attachment — a polymorphic pivot linking a File to any attachable model, with a collection name and sort order.

Host models opt in with the HasAttachments trait, which exposes the full attach / detach / sync / reorder API. All package internals resolve model classes through the OiLaravelAttachments resolver, so you can override any model from config without touching package code.

Requirements

• PHP 8.2+
• Laravel 11.0+, 12.0+, or 13.0+

Installation

The package auto-discovers and registers its service provider — no manual registration required.

Local Development

For local development, add this to your main project's composer.json:

Then:

Publish & Migrate

Publish the migrations (and optionally the config) and run them:

This creates the folders, files, and attachments tables.

Configuration

The config file config/oi-laravel-attachments.php exposes the following options:

Usage

Make a Model Attachable

Add the HasAttachments trait to any model:

Attach & Detach Files

Sync a Collection

syncAttachments() replaces every attachment in a collection. syncAttachmentsIfChanged() does the same but skips the database work when the ids and their order already match:

Reorder

Uploading Files

Use the action classes instead of building File records manually. StoreUploadedFile persists the upload and captures its metadata; AttachUploadedFiles stores many uploads and attaches them in a single call:

Working with Files

The File model offers type helpers, storage access, and a search scope:

File metadata is exposed as a value object rather than raw JSON:

Folders

Files can optionally be organized into a nested folder tree:

Customizing Models

To extend a model, subclass the package model and point the config at your class. Always resolve model classes through the OiLaravelAttachments helper so your override is respected everywhere:

Events

Each action dispatches a Laravel event you can listen to. All events live in OiLab\OiLaravelAttachments\Events:

See the Events documentation for each event's payload and dispatch behaviour.

Database Schema

All three tables carry a unique uuid, created_by / updated_by audit columns, and timestamps.

Testing

This package ships 75 tests covering the attachment trait, models and relationships, sorting, upload actions, file metadata, audit tracking, and events.

AI Assistant Skills

This package ships a skill file that gives AI coding assistants (Claude Code, JetBrains Junie) context about how attachments work. Install it into your application with the Artisan command:

This writes .claude/skills/oilab-laravel-attachments/SKILL.md and .junie/skills/oilab-laravel-attachments/SKILL.md, and adds an oi-lab/oi-laravel-attachments rules section to your project's CLAUDE.md. See the documentation for details.

Contributing

Contributions are welcome! When contributing:

1. Write tests for new features
2. Ensure all tests pass: vendor/bin/pest
3. Run vendor/bin/pint to match the project code style
4. Update documentation as needed

License

This package is open-source software licensed under the MIT license.

Credits

Olivier Lacombe - Creator and maintainer

Olivier is a Product & Technology Director based in Montpellier, France, with over 20 years of experience innovating in UX/UI and emerging technologies. He specializes in guiding enterprises toward cutting-edge digital solutions, combining user-centered design with continuous optimization and artificial intelligence integration.

Projects & Resources:

• OI Dev Docs - Documentation for all Open Source OI Lab packages
• OnAI - Training courses and masterclasses on generative AI for businesses
• Promptr - Prompt engineering Management Platform

Support

For support, please open an issue on the GitHub repository.