Download the PHP package tihloh/prefab-files without Composer

Prefab Files

Prefab Files provides framework-independent file storage, retrieval, organization, metadata and named-disk management for PHP applications.

Input decides whether a file is acceptable. Files decides where and how it is stored.

Prefab Files is standalone. Small applications can configure one local root and immediately call put()/read(). Larger systems can add named disks, public URLs, collision policies, checksums, storage usage, lifecycle hooks, temporary signed URLs and custom storage drivers without replacing the basic API.

Requirements

• PHP 8.1 or newer
• ext-fileinfo
• Composer when installed as a package

Installation

When published:

1. Quick start

Nothing else is required for a small application.

2. Named disks

Use the default disk:

Choose another disk:

Inspect disks:

Public/private intent is deliberately easiest to express at disk level. A disk with a configured base URL can produce public URLs; a private disk without one cannot.

3. Safe relative paths

Application paths are relative to the selected disk root:

If the disk root is:

the physical path is:

Traversal attempts are rejected:

Applications should normally persist the storage-relative path, not the machine-specific absolute path.

4. Atomic local writes

LocalDisk writes string and stream content to a temporary file first and then renames it into place.

This reduces the chance of readers observing a partially written local file.

5. Strings, streams and existing files

String contents:

Stream:

Existing local file:

For large content, prefer streams.

6. Prefab Input integration

prefab-files does not depend on prefab-input, but storeUploaded() accepts an upload-like object exposing tmpPath().

The responsibility split is intentional:

Prefab Files generates a random filename by default instead of trusting the original browser-supplied filename.

7. Filename collision policies

The default behavior is overwrite, preserving the simple historical API.

Choose a policy when needed:

Supported policies:

Example:

If report.pdf already exists, the returned path may be:

The same collision option is available for stream writes, putFile(), uploads, copy and move operations.

8. Reading and streams

Read the entire file:

Read as a stream:

The caller owns returned streams.

9. File metadata

FileInfo exposes:

MIME type is detected from the stored contents using fileinfo, not only from the extension.

10. Checksums

Choose another PHP-supported hash algorithm:

Checksums are useful for transfer verification, corruption checks, duplicate detection and change detection.

11. File and directory size

File size:

Directory usage:

Entire selected disk:

Prefab exposes measurements but deliberately does not turn Files into a billing/quota system. Applications can implement quotas using these values when needed.

12. Public URLs

Only disks configured with url produce a direct public URL:

Result:

A private disk returns null from url().

This keeps private/public intent explicit without maintaining fragile per-file visibility state in the core package.

13. Temporary signed URLs

For local private files, Prefab can generate an application URL containing an expiry and HMAC signature.

Configure once:

Generate a 10-minute URL:

A route/controller verifies the query parameters:

If valid, the application may stream the file. Files signs/verifies the token but intentionally does not bypass Auth or Permissions. Authorization policy remains the application's responsibility.

Future object-storage drivers may implement their own native presigned URL behavior through an adapter without changing application-level storage paths.

14. Transport-neutral downloads

The returned FileDownload exposes:

Prefab Files does not automatically call header() or terminate the request. The host application, Prefab HTTP, another framework or a controller decides how to emit the response.

Inline delivery is available:

15. Copy, move and delete

Copy/move support the same collision policies as writes.

16. Directories

Create:

Check:

List immediate directories:

List recursively:

Delete an empty directory:

Delete recursively:

17. Listing files

Direct files:

Recursive:

The result is an array of FileInfo objects rather than backend-specific filesystem entries.

18. Driver capability detection

Storage backends do not all behave identically. Instead of pretending they do, adapters advertise optional capabilities:

For the built-in local driver:

A future S3-compatible driver may support native temporary URLs but not a local filesystem path.

19. Lifecycle hooks

Applications can observe file operations without making Files depend on Logs, Events or another module.

Available manager events include:

A future Prefab Events or Logs adapter can subscribe to these hooks while Files remains standalone.

Hooks are synchronous and lightweight. Heavy background processing belongs in a jobs/events layer rather than the storage core.

20. Protected/private files

Private files should normally live outside the web server document root:

A protected route can authorize and then create a download descriptor:

Then the controller resolves the stored path and uses:

Confidential files should not depend on obscure filenames for protection.

21. Custom storage drivers

FileManager depends on DiskInterface, not LocalDisk specifically.

The contract includes:

Possible adapters include:

A custom disk can be registered directly:

Cloud/network SDKs remain outside the small core package until an adapter explicitly needs them.

22. What Prefab Files deliberately does not do

To preserve the Prefab goal, Files stays focused on storage infrastructure.

It does not own:

This prevents prefab-files from becoming a mini framework.

23. Practical document upload

Persist the relative path and business metadata in the application's own database model.

24. API quick reference

25. Design philosophy

The simple API remains valid throughout:

The core principle is: keep storage simple for small applications, expose the abstractions large systems actually need, and keep validation, authorization and specialized file processing outside the storage core.