Download the PHP package tekkenking/documan without Composer
On this page you can find all versions of the php package tekkenking/documan. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package documan
Documan — Laravel File Upload & Display Manager
Documan is a Laravel file upload manager package that provides a convenient way to upload files and, for images, automatically creates multiple resized variants that can be retrieved by name — similar to Cloudinary but fully self-hosted. It works with any Laravel filesystem disk (local, S3, etc.).
Requirements
- PHP ^8.1
- Laravel ^10.0 | ^11.0 | ^12.0 | ^13.0
Installation
The package is auto-discovered by Laravel (5.5+). No manual provider registration is needed.
Configuration
Publish the config file:
This creates config/documan.php. See the Full Configuration Reference section for every available key.
Basic Usage
Uploading a File
The original file is always stored automatically — it is saved as the plain base_name on disk (no prefix). Resized variants are stored alongside it with their size prefix (e.g. medium_AbCdEfGhIj.jpg).
Backward compatibility — Images uploaded with an earlier version of Documan may have their original stored as
original_AbCdEfGhIj.jpg(with theoriginal_prefix). Documan handles both formats transparently when displaying and deleting files.
Uploading Without a Request Object
If you already have a file object (e.g. from a test or a queued job), use upload_without_request():
Moving a File Between Disks
move() copies a file from a source disk to the currently configured disk and creates the requested size variants:
The source is copied through a temporary file using streams, and upload size limits are applied during the copy. Pass a plain storage filename, not a path: file names containing /, \, control characters, . or .. are rejected. The same filename rule applies to delete() and custom size names. move() also recognizes legacy originals stored with an original_ prefix.
Uploading with Custom Sizes
Pass an associative array of name => ['width' => x, 'height' => y] to register arbitrary sizes at upload time:
You can also reference an existing default size by its string name in the array:
Upload and image limits
The defaults limit each file to 20 MiB, the total upload to 40 MiB, and each upload call to 20 files. Image size requests are limited by maxVariantsPerUpload (20 by default). Set any of these limits to 0 to disable it. Configure these values in the published config/documan.php.
maxImagePixels defaults to 40 million pixels and is checked when image resizing runs, including source and output dimensions. An original-only image upload does not invoke resizing. To generate a WebP companion for each resized image where the active image driver supports WebP, enable outputWebp.
Adding Extra Allowed Extensions
Displaying / Showing a File
Use show($baseName) to set the file, then chain a size method to get the URL:
Show Helper Methods
After calling show(), the following helper methods are also available:
| Method | Returns | Description |
|---|---|---|
getExtension() |
string |
File extension derived from the stored base_name |
getType() |
string |
Group name (image, pdf, document, excel, powerpoint, other) |
mimeType() |
string |
MIME type string (e.g. image/jpeg) |
localPath(string $size) |
string |
Absolute local filesystem path to the given size variant |
showFileName() |
?string |
The raw base_name that was passed to show() |
Deleting a File
delete() removes the original and all resized variants. It respects the delete.mode setting in config/documan.php:
hard(default) — files are permanently removed from disk.soft— files are moved to a configurable trash folder on the same disk, allowing recovery before a final hard purge.
Both the current (un-prefixed) and the legacy (original_-prefixed) originals are handled automatically.
If an upload used runtime-defined sizes, include their names so those variants are deleted too:
By default, uploads are limited to 20 MiB per file, 40 MiB total, 20 files, and 20 image size requests per call. The maxImagePixels limit is 40 million pixels when resizing runs. These limits can be adjusted or disabled in config/documan.php.
Available Default Sizes
| Size | Width | Height | Method |
|---|---|---|---|
| big | 1600 | 1600 | ->big() |
| medium | 800 | 800 | ->medium() |
| thumbnail | 400 | 400 | ->thumbnail() |
| small | 170 | 170 | ->small() |
| tiny | 50 | 50 | ->tiny() |
All sizes can be overridden in config/documan.php under defaultImageSizes, or per-call by passing a ['width' => x, 'height' => y] array to the named method:
For a fully ad-hoc size, use custom():
Validation Rule
Use the DocumanFile rule to validate uploaded files against Documan's supported MIME groups before uploading:
Supported groups: image, excel, document, powerpoint, pdf.
Using the Cast
Cast an Eloquent column to DocumanCast to get automatic upload-on-save and URL-resolution-on-read:
Reading — the attribute returns a Documan instance; chain a size method to get the URL:
Writing — pass the HTML input name and Documan uploads automatically:
Remote Disk
Use remoteDisk() to build URLs against a remote host (e.g. a CDN) instead of using the local filesystem URL:
Return Format
Links and Paths
By default, upload() includes a links key with full URLs for every variant. You can also request absolute local filesystem paths via the paths key. Both can be toggled in config or at runtime:
Array vs Collection
By default upload() returns a plain PHP array. Set defaultReturn to 'Collection' in config/documan.php to receive a DocumanCollections object instead.
S3 / Cloud File Visibility
By default, files uploaded to cloud disks (such as S3) are stored as public, meaning they can be accessed directly via their URL. This is controlled by the s3_visibility config key.
Config default
Set it to 'private' to make all uploads private by default (useful when you serve files via signed URLs or a CDN).
Runtime override
Use the ->visibility() method to change visibility for a single upload without touching the config:
The ->visibility() call is chainable and can be placed anywhere before ->upload().
Note: Visibility is passed as an option to every
Storage::disk()->put()call, including resized variants and WebP copies. For local disks the option is silently ignored by Laravel, so it is safe to set it globally even in mixed-disk setups.
Using Remote Disks (S3-Compatible)
Documan fully supports S3-compatible remote disks. Image resizing, uploads, and display URLs all work the same way as with a local disk — you only need to point disk at a disk configured with the s3 driver.
Documan does not define or control disk configuration itself — it simply uses whatever disk you've configured in your app's config/filesystems.php, exactly as Laravel resolves it via Storage::disk(). Configure your s3 disk following Laravel's own filesystem documentation, then reference it by name:
How image resize behaves with a remote disk
- The uploaded file itself is always read from PHP's local temp upload location — no change there.
- The original and every resized variant are written straight to the remote disk via
Storage::disk($disk)->put(...), the same code path used for local disks. - If Documan ever needs to re-read an already stored remote object for processing (for example when resizing from a stored file name rather than a fresh upload), the object is streamed from the disk into a secure local temp file (
tempnam()), processed, and the temp file is deleted immediately afterwards in afinallyblock — it is never left behind. - Nothing assumes a local
rootpath exists for the disk; disk config without arootkey (as is the case fors3) works out of the box.
Public vs private objects and URL retrieval
- For public objects (
s3_visibility/->visibility('public')), display URLs are generated withStorage::disk($disk)->url($path), which returns the disk's configured public URL —Storage::path()is never used for remote disks since it has no meaning there. - For private objects,
Storage::disk($disk)->url()will return a signed/private URL only if your driver supports it; otherwise generate a temporary URL yourself (e.g.Storage::disk($disk)->temporaryUrl($path, now()->addMinutes(5))) and pass it through->plain(). show()/localPath()and thepathskey inupload()'s return value are local-disk concepts. On a remote disk,localPath()(the read-side helper) falls back to the disk URL instead of a filesystem path, while the upload-sidepathskey staysnull(there is no local root to report) — use thelinkskey for the public URL instead.
Async / Queue Processing
Set queue.enabled = true in config/documan.php to dispatch each resized variant as a background job. The original is always stored synchronously first so the queue job has a source image to read from.
External Adapter
Documan supports plugging in a third-party upload/show adapter (e.g. a cloud AI service). Enable and configure it in config/documan.php:
Upload adapters must implement externalUpload($file): array.
Show adapters must implement externalShow($fileName, $size): string.
When enabled, upload() and show() are fully delegated to your adapter classes; the built-in storage logic is bypassed.
Global Helper Functions
| Function | Description |
|---|---|
documan(string $disk = '') |
Resolve a fresh Documan instance from the container |
convertImageToBase64($documanInstance, string $size = 'original') |
Read a local file via localPath() in chunks and return its Base64-encoded content; remote URLs are not fetched |
Full Configuration Reference
Migration from Earlier Versions
| What changed | Old behaviour | New behaviour |
|---|---|---|
| Original file name on disk | original_AbCdEfGhIj.jpg |
AbCdEfGhIj.jpg (plain base_name) |
| Original storage | Optional (keepOriginalSize config) |
Always stored (mandatory) |
keepOriginalSize config key |
Present | Removed — replace with the delete block |
| Delete | Permanent only | hard (permanent) or soft (move to trash) |
No action is needed for existing files. Documan reads and deletes both the old original_-prefixed files and the new un-prefixed originals automatically.
License
This package is open-sourced software licensed under the MIT license.