Filelib Laravel Package

Getting Started

Install the library and its optional companions (image handling lives in a separate package in the xi ecosystem):

composer require xi/filelib
# if you need thumbnails/versions:
composer require xi/filelib-image

The package targets PHP 5.5. On a modern runtime expect to need --ignore-platform-reqs plus some compatibility shimming before it boots cleanly.

Before writing any code, understand the three collaborators every operation depends on:

• Backend — persists file metadata (id, name, mimetype, size, folder, references). Typically Doctrine ORM or a custom SQL backend.
• Storage — stores the raw bytes (usually a filesystem storage; swap for object storage by implementing the interface).
• Publisher — turns a stored file into a public URL (symlink or copy strategy, served by your web server).

Look first at Xi\Filelib\FileLibrary (the façade), Xi\Filelib\File\File, and the Backend / Storage / Publisher interfaces. The first end-to-end use case is: upload a local file, read metadata, generate a public URL, delete it.

use Xi\Filelib\FileLibrary;

$filelib = new FileLibrary($backend, $storage);
// attach publisher + plugins during bootstrap (see below)

$file = $filelib->uploadFile('/tmp/photo.jpg');

echo $file->getId();
echo $file->getName();
echo $file->getMimetype();
echo $filelib->getPublisher()->getUrl($file);

Implementation Patterns

• Wrap the façade. Inject FileLibrary (or a thin FileService around it) into controllers/commands; don't let the raw library leak into domain code. This keeps the upgrade/swap path open, which matters for an unmaintained package.
• Storage is strategy, backend is truth. Implement Storage to move bytes to S3/GCS without touching metadata. Keep the Backend as the single source of truth for id/name/mimetype/folder.
• Prefer FileReference over full File in hot paths. References carry just the identity and resolve lazily — useful for lists, pagination, and templates that only need a URL.
• Folders for tenancy. Create folders first, upload into them; use them to segregate tenants, projects, or galleries instead of encoding that in filenames.
• Publisher strategy per environment. Symlink publisher locally for speed; copy/stream (or a CDN-backed publisher) in production. Keep the published path outside application code and behind the web server.
• Plugins are the extension layer. Register image/version plugins during bootstrap, and order them deliberately — version generation before watermarking, resizing after validation, etc.
• Offload heavy work. Upload writes to storage and backend; image derivatives add more work. Push thumbnail generation and post-processing into workers so request latency stays predictable.
• Testing. Use temp-dir Storage plus an in-memory/stub Backend; the library is easy to test this way, and it keeps integration tests fast.

A typical bootstrap order:

$filelib = new FileLibrary($backend, $storage);
$filelib->setPublisher($publisher);   // via config/plugin, depending on version
$filelib->addPlugin(new ImagePlugin(...));
$filelib->addPlugin(new VersionPlugin(...));

Gotchas and Tips

• It's a 5.5-era, effectively unmaintained package (22 stars, 0 dependents). Before adopting, confirm PHP/runtime compatibility and pin the version. On modern PHP, budget time for deprecations and typed-signature issues.
• Two writes, one operation. Upload persists bytes and metadata; delete removes both. If one half fails you get orphans. Add a reconciliation command (storage ↔ backend) and run it routinely.
• Publisher is not optional. "File saved but URL 404s" is almost always a publisher misconfiguration: wrong symlink target, docroot outside the published path, or publisher not attached. Check getUrl() output against ls -l on the link.
• Don't hand-craft paths. Resolve storage paths via Storage and public URLs via Publisher; backend-supplied names may be normalized, hashed, or sharded.
• Plugin order is behavior. Resizing before vs. after watermarking produces different output and cost; versioning before transforms will cache the wrong variant.
• Lazy resolution can surprise you. FileReference avoids hydration but may re-query on every method call — cache resolved files if you loop.
• Debugging checklist: backend row exists? storage file exists? publisher link resolves? correct plugin registered before the operation? Nine times out of ten the failing step is publisher or plugin ordering.
• Extension points to lean on: implement Backend, Storage, Publisher, or Plugin to adapt to your DB, cloud bucket, CDN, or watermarking rules — no forking required.
• License shows as NOASSERTION on GitHub; verify the actual terms in the repo before shipping in a commercial codebase.