File Manager Laravel Package

Product Decisions This Supports

• Build vs. buy for file management UI. This package is effectively a "buy" with a zero price tag: it ships the whole browsing surface — directory tree with lazy-load, grid/list views, filters, sorting, breadcrumbs, search, drag-and-drop upload and multi-item move, lightbox preview, trash with restore and retention — so the team is deciding whether to integrate, not whether to build a file browser. That is normally 3–6 weeks of frontend work plus ongoing bug surface.
• Retire a service, not just a library. The migration table is the strongest product argument in the README: it collapses a Next.js/React app, an HTTP proxy, RS256 JWT issuance, .pem key management, an iframe and a postMessage handshake into a Livewire component that runs inside the existing Laravel auth/session. That is an infrastructure deletion decision — fewer deployables, fewer secrets to rotate, one less runtime to patch.
• Unblocking form-attachment workflows across the back office. The <x-file-manager::picker> is the real adoption driver. It emits a plain <input type="hidden" name="...">, so existing FormRequest validation, mass assignment and controller code keep working. Product can greenlight "attach a file to X" features on any entity without a per-screen upload widget.
• Per-tenant / per-level content scoping as a roadmap unlock. root_resolver returning null, a string, or an array of roots lets one deployment serve users confined to their own subtree ("sees only conteudos/optivisao and below", trash filtered by originalPath, path traversal blocked by PathGuard). That converts a single-tenant admin tool into a plausible multi-client content console without a second codebase.
• De-risking the storage roadmap. Multi-disk via Laravel's Filesystem means the local → S3 move is a config change (FILE_MANAGER_DISK, media_url = route/storage/auto) rather than a rewrite. Worth citing when someone asks "what happens when the media volume outgrows the box?"
• Feature-parity gap closure in the legacy tool. Search did not exist in the old FM; trash retention was hardcoded to 60 seconds while the docs claimed 30 days; restore did not exist. If any of those were open support tickets or verbal complaints, this release is the closure vehicle.
• Localisation. PT/EN with publishable translations — small, but it decides whether the tool can be handed to non-English-speaking operators or clients.

When to Consider This Package

Adopt when most of these are true:

• The application is Laravel 10.49+/11/12 on PHP 8.1+ and already on Livewire v4 — or you are willing to make Livewire v4 an application-level commitment. This is a hard pin, not a soft preference; it is the single biggest gating criterion.
• You need an internal/admin-facing file browser and a form picker, not a customer-facing asset library.
• The app compiles Tailwind (add the package views to content) or you accept publishing the prebuilt stylesheet. Either way, there is a styling step — budget it or the first demo looks broken.
• You have (or will add) a scheduler entry for file-manager:prune-trash. Without it, trash_retention_days is decorative and files accumulate in apagados forever — a silent storage-cost and data-retention issue.
• You want the per-user root scoping story and can write a small invokable resolver class (the docs include a back-office reference implementation).
• The team is comfortable being an early adopter. Zero stars, zero dependents, one maintainer, single-digit months of public history: treat it as an internally-owned component with a friendly name, not a vetted third-party dependency.

Look elsewhere (or build) when any of these hold:

• Livewire 3 or no Livewire. Upgrading the whole app to adopt a file browser is a bad trade.
• A non-Laravel or headless frontend needs the same files. This is server-rendered Livewire; there is no REST/JSON surface. If a mobile app or a separate SPA must list the same tree, you will end up writing an API anyway.
• You need real DAM capabilities: versioning, alt text/metadata, tagging, image transformations and responsive derivatives, virus scanning, duplicate detection, audit trail of who touched what. None of that is here, and bolting it on is a project.
• Large-file or high-volume uploads are core. Uploads go through Livewire's temporary-upload path with a configurable max_size (default 50 MB) and mimes allowlist. If users routinely push multi-hundred-MB video, you want direct-to-S3 presigned uploads instead.
• Fine-grained authorisation beyond a root prefix. root_resolver answers "which subtree may this user see?"; it does not answer "who may delete, who may restore, who may permanently purge." Keep those rules in your own policies, or the permissions model will drift into config.
• You need vendor SLA, security review sign-off, or a support contract. There is no community to lean on. Mitigate by wrapping it behind a thin internal adapter (a service class or Blade wrapper) so a swap is a contained change rather than a find-and-replace.
• Compliance requires evidence of testing. No test suite is advertised. If your release gate needs coverage numbers on third-party code, this fails on paper regardless of quality.
• The picker's filter is your only validation. It is a UI affordance, not a boundary — the hidden input is tamperable. If nobody owns server-side validation of the submitted path, do not ship it.

Practical sizing: a picker swap into one existing form is a half-day to a day. A full rollout — publish and read the config end to end, Tailwind wiring, scheduler, root_resolver, migrating legacy path conventions, and rewriting ad-hoc upload widgets — is closer to one to two weeks with a proper review of the security surface.

How to Pitch It (Stakeholders)

For executives — one paragraph: We can delete a service. Today the file manager runs as a separate Next.js/React application that our Laravel app reaches through an iframe and authenticates with a bespoke JWT scheme: extra deployment, extra secrets to rotate, extra on-call surface, and a UI that cannot reuse our login. This package rebuilds the same functionality as a native component inside the Laravel app — same authentication, same session, no iframe, no tokens, no external host. We also pick up functionality the old tool never had: working search, restore from trash, configurable retention with scheduled cleanup, and storage that can move to S3 by changing a config value. The cost is integration work measured in days, not a licence, and the payoff is one fewer thing to deploy, secure and pay for.

For engineering — the honest short version: Install is composer require plus package discovery; routes, the Livewire component and the Blade components register themselves. Three things must not be skipped, because all three fail quietly: add ./vendor/proside/file-manager/resources/views/**/*.blade.php to Tailwind's content (or publish the prebuilt CSS); schedule file-manager:prune-trash daily; and publish then actually read config/file-manager.php — disk => public, root => conteudos, trash => apagados are real assumptions about our filesystem, not placeholders. Store relative disk paths on models, never full URLs. Treat <x-file-manager::picker>'s filter as cosmetic and validate the submitted path in the FormRequest with a regex anchored to the configured root. The picker emits file-manager-selected with { paths: [...] } — always an array, even for single selection. root_resolver handles per-user scoping and PathGuard blocks traversal, but authorisation for destructive actions (delete, purge, restore) stays in our policies.

The caveats to state up front, not discover later: Livewire v4 is a hard requirement — that is an application-level upgrade decision, and it gates the whole conversation. The dependency itself is at zero stars, zero dependents, one maintainer, no advertised test suite: for planning purposes this is a first-party component we happen to consume, so we should assign an internal owner, wrap it behind a thin adapter, and accept that Livewire version bumps are coupled. No metadata/DAM features, no image derivatives, no virus scanning, no API — if any of those land on the roadmap within the year, they are our work, not the package's.