Download the PHP package edulazaro/laracrate without Composer

Laracrate

Polymorphic file storage for Laravel with direct upload to R2/S3, granular access control, sensitive content streaming, automatic image variants, video and PDF previews, per-variant watermarking, multipart uploads, text extraction, and vector embeddings.

Table of contents

1. Philosophy
2. Installation
3. Data model
4. Configuration
5. Using it from your model
6. Processing pipeline
7. Variants
8. Upload modes
9. HTTP endpoints
10. Sensitive content
11. Artisan commands
12. Optional Livewire component
13. Full API
14. Tests
15. Dependencies
16. License

Philosophy

1. Backend agnostic to the frontend. The core has zero dependency on Livewire or Alpine. It exposes endpoints, a trait, and a service.
2. Reuses Laravel's Storage::disk(). Disk credentials live in config/filesystems.php (single source of truth). The package does not duplicate configuration.
3. Pipeline of Actions. Every operation is an isolated class (edulazaro/laractions), testable and queueable.
4. Async processing. Variants, video and PDF previews, text extraction, embeddings, all run on the queue. The user upload is instant.
5. 3 access modes per collection: public (direct CDN), signed (temporary signed URL), stream (controller with audit and viewer bind).
6. path = full key convention. The path field on a File row stores the complete object key in the disk (directories, filename, extension). The name field is denormalization of basename($path).

Installation

migrate creates 3 tables, all with the laracrate_ prefix:

• laracrate_files, the main table for top-level files and variants.
• laracrate_file_contents, chunks of extracted text and embeddings (opt-in).
• laracrate_multipart_uploads, active multipart upload sessions.

The laracrate_ prefix avoids clashing with legacy files tables that exist in many Laravel apps.

Disks in config/filesystems.php

Add the disks you intend to use (R2/S3 for real storage, local for dev):

Data model

Table laracrate_files

47 core columns plus JSON:

The three *_indexed_at columns let a single deployment migrate between ChunkStore backends (mysql → meilisearch → custom) without re-running the whole pipeline: a re-index job only re-syncs files where the target backend's timestamp is null or older than updated_at.

Visibility values come from the FileVisibility enum; processing states from ProcessingStatus.

Auxiliary tables

• laracrate_file_chunks — one row per chunk produced by the embeddings pipeline. Each row carries text, embedding (vector), context (optional discriminator when a single extraction yields multiple sections, e.g. OCR text + visual description), and summary/description if the extractor produced them. Indexed by FULLTEXT for keyword search; cosine similarity is computed in PHP by MysqlChunkStore, or pushed to Meilisearch by MeilisearchChunkStore (see ### chunks below).
• laracrate_multipart_uploads — active multipart upload sessions for S3/R2. Typical lifetime minutes to hours. The laracrate:abort-stale-multipart cron aborts those past expires_at. Status enum: MultipartUploadStatus.
• laracrate_file_slots — optional structured "slots" with validation rules (max files, accepted mime types, required) for workflows like "upload your DNI: PDF only, 1 file max". The FileSlot model wraps the row; the HasFiles trait exposes helpers to fill, validate, and check slot completion.
• laracrate_tenant_buckets — per-tenant bucket/disk overrides for multi-tenant or BYOA (bring-your-own-account) setups. A row maps (tenant_type, tenant_id, base_disk) to a concrete bucket + credentials. Resolved by StorageManager::diskFor() via the tenant relation on the File. Useful when each customer's data must live in their own S3 account for compliance or cost attribution.

Each table has a matching Eloquent model under EduLazaro\Laracrate\Models\ — FileChunk, MultipartUpload, FileSlot, TenantBucket — that you can query directly when you need fine-grained access (e.g. listing chunks for debugging, aborting a specific multipart session by id, attaching slot rules to a workflow).

Key concepts

• path is the full object key in the disk. It is not concatenated with name. Recommended access: $file->key (an accessor that does ltrim($file->path, '/')).
• name is denormalization of the basename (with extension). Useful for queries and display, never concatenated.
• parent_id and variant: any child File (thumbnail, preview, transcoded) has parent_id pointing to its parent and variant carrying the role (thumbnail, medium, preview, display...). Recursive: a video preview has its own child variants.
• 3 orthogonal polymorphic relations: fileable (what it belongs to), creator (who created it), tenant (multi-tenant scope).
• access: public produces a direct CDN URL, signed produces a signed URL with TTL, stream produces a package route with per-request re-validation.
• processing_status: pending, processing, completed, failed. Enum EduLazaro\Laracrate\Enums\ProcessingStatus.

Configuration

Everything lives in config/laracrate.php (published with vendor:publish).

default_collection and default_context

Schema defaults applied when a File row is inserted without specifying them.

defaults, defaults per file type

These apply to every collection unless overridden. Each type defines accepted mime types, max size, quality, max dimensions, and default variants.

collections, definition of each collection

Each collection sets disk, access mode, accepted types with their config, and optionally single, sensitive, encrypt, ttl_hours, quota_bytes, component, placeholder.

Rules for types:

• An allowlist of which types the collection accepts, plus the config of what to do with each.
• Each entry can be a bare string ('image', inherits global defaults) or an array ('image' => [overrides]).
• variants always live inside a type (types.image.variants).
• preview for document and video produces a special variant; its own child variants go in preview.variants.
• The global type defaults are recursively merged with the collection override. You only declare what you want to change.

Granular per-model config (optional)

The same collection name can serve several models with different config per model, using an optional models block. The block is keyed by morph alias (or FQCN if you don't use a morph map). Each entry is merged on top of the base.

Semantics:

• Without models → flat config, any model that uses the collection gets the same behavior (legacy / default).
• With models → the collection is restricted to those aliases; any other model throws EduLazaro\Laracrate\Exceptions\CollectionNotAllowedForModel.
• Override is array_replace_recursive on top of the base. Scalars get replaced; nested arrays merge key by key (declare the full array on a key when you want a wholesale swap).
• The models key itself is stripped from the resolved output — callers see a normal flat array.
• Tooling that iterates collections without a model context (e.g. laracrate:purge-expired) gets the base config without the models block.

placeholders, fallback when there is no file

Resolution order (most specific to most general):

1. config('laracrate.collections.{name}.placeholder')
2. config('laracrate.placeholders.{type}')
3. config('laracrate.placeholders.default')

Each slot accepts a fixed string or a dynamic closure:

urls, URL strategy

policies, bridge to Laravel's Gate

When register_gate is on you can use the native ergonomics:

Mapping: view/update/delete go to the registry's canView/canEdit/canDelete.

stream, streaming endpoints

status, polling endpoints

Endpoints:

• GET /laracrate/files/{slug}/status, status of a single file.
• POST /laracrate/files/status, batch (multiple slugs).

multipart, large uploads

image, image processing

video, transcoding

Requires ffmpeg and ffprobe on the server's PATH.

encryption, encryption of sensitive binaries

If a collection sets 'encrypt' => true, the binary is encrypted with EncryptFileAction before being uploaded to the backend, and decrypted on the fly when served by StreamFileController.

embeddings, text extraction and vectors

Per-collection activation:

Custom provider:

Custom text extractor:

Bundled implementations:

• OpenAiEmbeddingProvider (default).
• NullEmbeddingProvider (no-op for testing).
• PdfTextExtractor — PDFs via smalot/pdfparser, native text only.
• PlainTextExtractor — text/* files.
• OcrPdfTextExtractor — OCR fallback for scanned PDFs (Vision LLM), configured below.
• OcrImageTextExtractor — OCR for image files (JPG, PNG, HEIC) via Anthropic Claude or OpenAI Vision.
• AudioTranscribeExtractor — transcribes audio (mp3, wav, ogg, m4a, etc.) via OpenAI Whisper.
• VideoTranscribeExtractor — extracts audio with ffmpeg, transcribes via Whisper, optionally adds visual frame descriptions via Vision LLM.

Audio/video/image extractors call paid APIs — wire them in the extractors chain explicitly when you need them and check pricing for your workload.

chunks, persistence and search backend

Chunks produced by the embeddings pipeline (text split + vector) need a place to live. Laracrate ships two ChunkStore implementations and lets you wire a third one yourself.

Drivers:

• mysql — MysqlChunkStore. Persists to laracrate_file_chunks with a FULLTEXT index for keyword search and cosine similarity computed in PHP over the candidate pool. Zero external dependencies. Scales fine up to roughly 5K chunks per scope.

• meilisearch — MeilisearchChunkStore. Syncs chunks to a Meilisearch index with user-provided embeddings, enabling native hybrid search (BM25 + vector) via the semanticRatio parameter — all server-side, no pool ceiling. Requires meilisearch/meilisearch-php and a bound Meilisearch\Client in the app container.

Custom store (Qdrant, pgvector, Pinecone, etc.):

The ChunkStore contract has four methods: upsert, delete, search and countForFile. Pick whichever vector store fits your infra.

ocr, PDF scanning fallback

For PDFs that don't have extractable native text (scanned documents), the package ships OcrPdfTextExtractor. It sends the PDF base64 to an API and gets back the extracted text. No Imagick, no Ghostscript, no shell_exec, no pdftoppm. Just PHP and HTTP.

API key resolution, in order:

1. Explicit constructor argument (advanced).
2. Provider-specific LARACRATE_*_API_KEY (so the package has its own key, distinct from other usages in the app).
3. Fallback to the generic provider env (ANTHROPIC_API_KEY, OPENAI_API_KEY).

Model resolution, in order:

1. Provider-specific LARACRATE_OCR_{PROVIDER}_MODEL (e.g. LARACRATE_OCR_ANTHROPIC_MODEL).
2. Generic LARACRATE_OCR_MODEL (applies to whichever provider is active).
3. Hardcoded default (claude-haiku-4-5 / gpt-4o-mini).

Recommended chain for legal / scanned documents:

Cost reference per 10-page PDF (rough estimates, may change):

watermark, per-variant watermark

The watermark is baked into the binary of specific variants. The original (master) NEVER carries a watermark. Only variants that explicitly opt in.

Per-variant activation:

If you change the PNG or tweak sizes, regenerate the variants and the master stays untouched.

ui, default theme for the optional Livewire component

Only relevant if you use the optional Livewire component. Details in its section.

queue

Useful for isolating file processing from other queues.

Using it from your model

HasFiles trait

Server-side upload (regular request)

Direct upload to R2 (presigned, recommended)

JS client:

Backend confirm:

Multipart (large files, larger than 100 MB)

The JS helper detects the size and switches to multipart automatically when it crosses the threshold. The backend is already covered by the package routes.

Show in blade

$file->variant('preview.thumbnail') walks with dot notation and falls back to the closest real ancestor if the chain breaks (it never returns null). If you need to fail loudly, use variantOrFail().

Helpers fileLink() and fileRender()

They remove the null-check boilerplate:

fileLink() returns string|null. fileRender() returns HtmlString.

Default blade component per collection

Component in your app:

Delete, reorder, publish

Policies (authorization)

Defaults when no policy is registered:

• The human creator of the File can always view, edit, and delete.
• Files with access='public' can always be viewed.
• Everything else: deny.

Processing pipeline

When a top-level File is created (no parent_id), FileObserver::created dispatches ProcessFileJob (queue). The job orchestrates ProcessFileAction, which iterates the Steps of the ProcessingPipelineRegistry in ascending priority order.

Default steps shipped by the package:

Priority convention:

• 0 to 19: metadata (dimensions, duration).
• 20 to 39: original transformation (optimize, transcode, encrypt).
• 40 to 59: derivatives (variants, previews, thumbnails).
• 60 to 79: semantic extraction (text, OCR, transcription).
• 80 to 99: AI (chunking, embeddings, classification).

Events:

• FileProcessingStarted, before the first step.
• FileProcessed, all steps completed OK.
• FileProcessingFailed, a step threw.
• VariantGenerated, when a variant is created.
• EmbeddingsReady, when embeddings are generated.

Fail-fast policy: if a step throws, the File is left at processing_status = FAILED and ProcessFileJob retries with backoff (3 tries: 10s, 30s, 60s). Subsequent steps do not run on that attempt.

If the File is deleted before the worker reaches the job (typical when setFile() replaces an avatar), Laravel discards the job silently thanks to $deleteWhenMissingModels = true. No zombie entries in failed_jobs.

Extending the pipeline from your app

There are two extension points, depending on whether your step should run for every file in the system or only for a specific collection.

Global step (runs for every file)

Register at boot in the FileActionRegistry. The step's own supports() decides which files it actually touches.

Per-collection step (runs only for files in that collection)

Declare it under actions in the collection config — no service-provider wiring needed. Useful for domain-specific work (deadlines detection, document classification) that only makes sense for one collection.

Writing a step

Both registries expect classes implementing FileActionInterface (from edulazaro/laractions). supports() is optional; if absent, handle() runs for every file in scope.

The global registry and the collection's actions array are merged, deduplicated (by class), and sorted by priority() ascending before each pipeline run. Use the priority bands documented above (0-19 metadata, 20-39 transforms, 40-59 derivatives, 60-79 semantic, 80-99 AI) to slot your step where it makes sense.

Variants

Variants are child rows of laracrate_files with parent_id and variant. The cascade FK deletes them when you delete the parent. The FileObserver deletes the binary in R2 when the row is force-deleted.

Path convention

• path of the original: {fileable_type}/{fileable_id}/{collection}/{ulid_filename.ext}.
• path of a variant: {parentDir}/variants/{baseName}_{variantName}.{ext}.
• path of a sibling (for example, a transcoded mp4 replacing the mov): {parentDir}/{newName}.{ext}.

Helpers on the File model:

Per-variant watermark

The watermark is baked into the variant's binary at generation time. The original always stays clean. If you change the PNG or text tomorrow, regenerate the variants and you are done.

See the watermark config block.

Upload modes

The presign accepts fileable_type, fileable_id, and collection to generate the canonical key directly. If the model is unknown at upload time, the binary lands in temp/ and CreateFileAction moves it with S3 server-side copyObject (zero download to PHP).

HTTP endpoints

Sensitive content

For collections with access=stream, the per-request flow is:

1. Package URL signed by Laravel (TTL route_signed_ttl).
2. The controller validates the signature.
3. If sensitive=true, validates Auth::id() === query('u') (URL bind).
4. Policy chain, FilePolicy::view($file, $user) reads PolicyRegistry.
5. If is_encrypted=true, DecryptFileAction decrypts before serving.
6. Audit, increments last_downloaded_at, optionally logs IP and user_id.

The watermark is not applied here, it is baked into the variant.

Artisan commands

Recommended schedule in app/Console/Kernel.php:

Optional Livewire components

The package ships six Livewire components that cover the common upload UIs. All are fully optional: the core works without Livewire, and your app can build its own uploader or call addFile()/setFile() directly from your forms.

Deferred variants are useful inside modals or tabs where you don't want JS/CSS to load until the user opens the panel.

All components support 8 themes (default, brutalist, material, ios, glassmorphism, neon, minimal, neumorphism) and 2 layouts for the card uploader (row, portrait). The global theme is configured at config('laracrate.ui.default_theme').

Publish the views to customize:

If you do not use Livewire, ignore this section. Themes and the components are not loaded unless rendered.

Full API

HasFiles trait

File model

StorageManager service

UsageReporter service

Aggregates storage consumption across tenants, creators, or collections. Useful for billing, quotas, or dashboard widgets without writing custom SUM queries.

Each call returns a UsageStats value object:

forTenant honors the polymorphic tenant_* columns and includes variants of those files. forCollection is global across tenants.

Tests

Storage::fake() and SQLite in-memory, no Docker, no external services:

Tests cover the model, trait, observer, manager, policies, presigned controller, stream controller, multipart, and embeddings.

Dependencies

• Laravel 11+ and PHP 8.2+
• intervention/image (image processing, watermark)
• aws/aws-sdk-php (S3/R2 presign and multipart)
• edulazaro/laractions (base Action class)
• smalot/pdfparser (optional, for PdfTextExtractor)
• imagick PHP extension (recommended) or gd
• ffmpeg, ffprobe on PATH (only if you use video)

License

MIT