Download the PHP package codebyray/livewire-media-uploader without Composer

On this page you can find all versions of the php package codebyray/livewire-media-uploader. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of codebyray/livewire-media-uploader

Informations about the package livewire-media-uploader

media_uploader_screenshot

Livewire Media Uploader

tests

Livewire Media Uploader is a reusable Livewire v3/v4 component that integrates seamlessly with Spatie Laravel Media Library. It ships a clean Tailwind Blade view by default (fully publishable), Bootstrap theme as an option, Alpine overlays for previews/confirmations, drag-and-drop uploads, per-file metadata (caption/description/order), configurable presets, image watermarking, name-conflict strategies, and optional SHA-256 duplicate detection. Drop it in, point it at a model, and you’re shipping in minutes.

Upgrading from v0.7.x? Read Upgrading to v0.8.0 before deploying, especially if you use deferred uploads on create forms.

Table of Contents

Features

Requirements

Note on Laravel 10/11: Earlier releases of this package listed Laravel 10 and 11 as supported. Both are now past their security-support window (Laravel 10 is EOL; Laravel 11 security support ended March 2026), and current releases of laravel/framework in those lines carry known, unpatched advisories — meaning a fresh composer install targeting either will be blocked by Composer's own audit for most consumers. Support for both has been dropped as of v0.5.0. If you're still running Laravel 10/11, pin this package to v0.4.x, but prioritize upgrading Laravel first — that's the more urgent fix.

Every supported PHP/Laravel/Livewire combination is verified on pull requests and pushes to the configured release branches via GitHub Actions.

Installation

Auto-discovery will register the service provider. If you disable discovery, add:

The component is registered under both aliases:

Upgrading to v0.8.0

v0.8.0 fixes attachment security, replacement failures, morph-map ownership checks, queue ordering, and uploaded media names. The dependency requirements are unchanged from v0.7.0; the attachment rules below are intentional behavior changes.

Update your Composer constraint when the release is available:

Deferred uploads require a policy

If an uploader uses model without an id, add authorizeAbility and ensure its Gate/Policy permits the current user to manage media on the newly saved record:

For posts owned by a user, an example App\Policies\PostPolicy is:

Use your application's actual ownership or permission rules. Register the policy if your app does not discover it automatically. Without an ability, or if its policy denies access, deferred attachment returns 403. A create-page authorization check alone does not authorize the record ID supplied to an attach event.

After saving the post, dispatch the matching event:

Configure attachment settings on the uploader

Move any collection or disk overrides from attach events to the uploader's props. These event arguments can only confirm the configured settings: a different collection is ignored, and a different disk returns 403. Omit disk from the event to use the uploader's configured/default disk.

The initial attachment must use the configured deferred model class, and an already-bound uploader cannot switch records. Use distinct channels for multiple uploader instances. To edit another record, mount a new uploader for that record.

Uploaders already bound to a saved record through :for or model plus id do not require a new prop, provided your application already authorizes access to that fixed record. The optional authorization hook still enforces a policy on their mutations.

No package database migration or new config key is required. Existing media names are not rewritten; preserving the original display name applies to new uploads. See the changelog for the complete release notes.

Publishing Assets

Config:

Views:

After publishing, customize the Blade at:

Theme System (Tailwind + Bootstrap + custom)

Select the theme in config/media-uploader.php:

Dark mode (Tailwind theme)

This package’s Tailwind theme is dark-ready. Add this tiny snippet in your main layout <head> to apply the user’s saved choice / system default:

Custom themes

Notes

Quick Start

1) Ensure your target Eloquent model implements Spatie\MediaLibrary\HasMedia and is saved.

Model Setup (Spatie Media Library)

Your model must implement HasMedia and be saved before attaching media.

Multiple uploads and singleFile()

The uploader's multiple prop controls whether the file input allows selecting multiple files. It does not override Spatie Media Library's collection configuration.

If a collection is configured with ->singleFile(), Spatie will remove the existing media item each time another file is added. Selecting multiple files can therefore process every selected file while leaving only the last file in the collection.

For galleries and other multi-file collections, do not use ->singleFile():

Use ->singleFile() only when the collection should contain one item, such as an avatar or logo:

2) Include Livewire & Alpine (usually in your app layout):

3) Drop the component into your Blade:

Usage Examples

1) Pass a saved model instance

2) Short string model + id

3) Morph map alias**

4) FQCN

5) Dotted path + custom namespaces

6) Local aliases (per-instance)

7) Single-file mode + hide list

8) Name conflict strategies

9) Duplicate detection by SHA-256

10) Restrict types/mimes/max size manually

11) Watermark image uploads

See [Watermarking](#watermarking) for setup, every available option, and processing behavior.

Create flow (deferred uploads)

You can let users pick files before the model exists, and attach them after save.

Blade (create page)

Deferred attachment requires authorizeAbility. Define a Gate or Policy that permits the current user to update the newly saved record (for example, only its owner). A create-page authorization check alone does not authorize the record ID supplied to an attach event.

Livewire component (simplified)

How it works

Configuration

Publish the package configuration before customizing global behavior:

The published file is config/media-uploader.php. Laravel automatically merges the package defaults when the file has not been published.

Configuration reference

Key Default Purpose
model_namespaces ['App\\Models'] Namespaces searched when resolving short or dotted model names. They are checked in array order.
theme tailwind Default theme key. It must exist in the themes map. Set it with MEDIA_UPLOADER_THEME or override it using the component's theme prop.
themes Tailwind and Bootstrap views Maps theme keys to fully qualified Blade view names. Add published custom themes here.
accept_from_config true Builds the file input's accept attribute from the active preset's MIME types and extensions. This is a browser hint; server validation still runs independently.
watermark Disabled Controls image watermark processing. See Watermarking.
collections Common collection mappings Maps a Media Library collection name to a validation preset.
presets images, docs, videos, default Defines reusable upload validation and file-picker rules.

Collection and preset resolution

Collections and presets are separate concepts. collection="avatars" selects the Spatie Media Library collection, while the collection map selects which validation preset applies:

For collection="avatars", the component uses the images preset unless the component receives an explicit preset prop.

The active preset is resolved in this order:

  1. The component's explicit preset prop.
  2. The preset mapped from the active collection in collections.
  3. The default preset.

Each preset supports:

Key Meaning
types Comma-separated filename extensions. These are used for validation and, when enabled, the input's accept attribute.
mimes Comma-separated MIME types used for server-side validation and the generated accept attribute.
max_kb Maximum size of each uploaded file in kilobytes. PHP, the web server, and Livewire upload limits must also allow this size.

You can add your own preset and map any collection to it:

The built-in preset values can be overridden through the environment variables listed in Environment variables. After changing configuration in a cached production application, run php artisan config:clear or rebuild the configuration cache.

Showing every collection

Set :list-all="true" to render a grouped list of every collection on the target model. Items remain editable, and ordering stays scoped to each collection.

Watermarking

Watermarking is disabled by default. When enabled, the uploader composites a server-side image over each uploaded image before passing the file to Spatie Media Library. The stored original and any Media Library conversions generated from it therefore contain the watermark. Documents, videos, and other non-image uploads are not changed.

Configure the watermark

Publish config/media-uploader.php, place a watermark image somewhere readable by PHP, and configure the complete watermark section:

A transparent PNG is usually the best watermark source. path must resolve to a readable local file; it is not a URL or a filesystem-disk key.

Watermark options

Key Accepted values Description
enabled true or false Global default. An uploader's watermark prop can override it.
path Readable local path Source watermark image. An enabled image upload fails with a clear exception when this is missing or unreadable.
position top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right Alignment of the watermark within the uploaded image.
padding_x Integer Horizontal distance from the aligned edge.
padding_y Integer Vertical distance from the aligned edge.
padding_unit pixel or percent Unit shared by padding_x and padding_y. Percentage padding is relative to the uploaded image dimensions.
width Integer Desired watermark width. Set to 0 to derive it from height.
width_unit pixel or percent Unit for width. The default 20 percent makes the watermark responsive to source-image width.
height Integer Desired watermark height. Set to 0 to preserve the watermark's aspect ratio from its configured width.
height_unit pixel or percent Unit for height.
fit contain, max, fill, fill-max, stretch, or crop Resize behavior when both width and height are set. With the default height of 0, the original aspect ratio is preserved.
opacity Integer from 0 to 100 Watermark opacity, where 0 is invisible and 100 is fully opaque.

Enable it globally or per uploader

To watermark every image handled by the package, set the global configuration:

To enable it only for selected uploaders, leave the global setting disabled and pass :watermark="true":

To disable it for one uploader when the global setting is enabled, pass :watermark="false":

The prop is optional. When omitted, the uploader uses watermark.enabled from configuration. The prop only controls whether processing runs; the path and rendering options remain server-controlled in the configuration file.

Processing behavior and requirements

Props

Prop Type Default Description
for Model — Saved Eloquent model instance implementing HasMedia.
model string — Model resolver: alias, FQCN, morph alias, or dotted path.
id int|string — Target model id (used with model).
collection string images Media collection name.
disk ?string null Storage disk (e.g. s3).
multiple bool true Allow selecting multiple files. The target Spatie collection must not use singleFile() if multiple files should be retained.
accept ?string null <input accept> override (otherwise may be auto from config).
showList bool true Show the attached media list.
theme ?string Configured theme Override the globally configured theme for this uploader.
maxSizeKb ?int Active preset's max_kb Max file size (KB). An explicit value overrides the preset.
preset ?string null Choose a preset (images, docs, videos, default, etc.).
allowedTypes array [] Extensions filter (e.g. ['jpg','png']).
allowedMimes array [] MIME filter (e.g. ['image/jpeg']).
onNameConflict string rename Strategy: rename | replace | skip | allow.
skipExactDuplicates bool false Uses SHA-256 stored in custom_properties->sha256.
watermark ?bool Config value Enable or disable watermarking for this uploader instance.
namespaces array ['App\\Models'] Namespaces for dotted-path resolution.
aliases array [] Local alias map, e.g. ['profile' => \App\Models\User::class].
attachedFilesTitle string "Attached media" Heading text in the list card.
channel ?string null Route deferred media:attach events to a specific uploader. When set, the incoming event must contain the same channel.
listAll bool false When true, the attached media list shows all collections, grouped by collection name (still editable).
authorizeAbility ?string null Gate/Policy ability checked against the target model before upload/delete/edit/reorder/attach. Required for deferred attachment. See Authorization.

Events

The component dispatches browser events you can listen for:

Example:

Authorization

For an uploader bound to a saved record at mount, authorizeAbility is optional. Without it, the component verifies that media belongs to that fixed record, but your app must authorize the user's access before rendering the component. The uploader cannot be retargeted to another record by an attach event.

For deferred uploads (model without an id), authorizeAbility is required before attachment. The model and ID passed to media:attach are client-controlled input, even when the event is dispatched by a parent Livewire component. A route or create-page policy check cannot authorize those arguments. The uploader checks the configured ability against the selected saved record and returns 403 if no ability is configured or the policy denies access.

Set authorizeAbility to a Gate/Policy ability name to enforce authorization before every persistent mutation (uploadFiles, remove, saveEdit, reorderItems, and media:attach). It uses Laravel's Gate::authorize() and works with existing Policies, Gate closures, or permission systems integrated with Gate.

With the example above, before any upload/delete/edit/reorder/attach action runs, the component calls the equivalent of Gate::authorize('update', $post). If your PostPolicy::update() returns false, the action aborts with a 403 instead of proceeding.

Notes:

The list view tries getUrl('thumb') and falls back to getUrl() if no conversion is available.

Overlays & UX Notes

Troubleshooting

Roadmap

Possible future additions:

PRs welcome!

License

MIT © CodebyRay (Ray Cuzzart II)

Component aliases: media-uploader and media.media-uploader
View namespace: media-uploader::livewire.media-uploader

All versions of livewire-media-uploader with dependencies

PHP Build Version
Package Version
Requires php Version ^8.2
livewire/livewire Version ^3.8.3 || ^4.3.4
laravel/framework Version ^12.0 || ^13.0
spatie/image Version ^3.3.2
spatie/laravel-medialibrary Version ^11.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package codebyray/livewire-media-uploader contains the following files

Loading the files please wait ...