Download the PHP package tetranyble/storage without Composer

Tetranyble Storage

Production-oriented storage, media-library, upload, sharing, cloud-drive, processing, and file-management infrastructure for Laravel 12 and 13.

CI is verified by GitHub Actions and a verification-only CircleCI fallback; stable tags/releases remain gated through GitHub. See docs/CIRCLECI.md.

The package is designed around one rule: application/domain rules decide; storage providers and Laravel adapters implement them. It supports workspace isolation, ACL-aware queries, quota accounting, resumable and direct uploads, media processing/quarantine, derivative assets, retention, bulk operations, and operational health checks.

Requirements

• PHP ^8.2
• Laravel / Illuminate ^12.0 | ^13.0
• ext-fileinfo
• GD is optional but required for image derivatives
• Provider SDKs are optional and installed only when that provider is used

Install

Package HTTP routes are disabled by default. Enable them explicitly:

If activity logging is required:

then run migrations again.

Architecture

The package uses modular Hexagonal architecture with selective tactical DDD. Dependency direction and capability ownership are enforced by composer run architecture. Domain code has zero Laravel/Eloquent/Symfony HTTP dependencies. Lifecycle-heavy behavior such as direct/resumable uploads, sharing access and version-group allocation is exercised by a dependency-free state-machine gate.

See docs/PROVIDER_STRATEGY_REGISTRY.md.

Host model integration

Storage-owned records are package-owned. The host integration points are only the user and workspace models.

For the common belongs-to workspace model:

Package persistence currently requires integer/BIGINT host user/workspace keys.

Model media relationships

Use only the capabilities a model needs:

HasMedia provides relationships/read helpers. ManipulatesMedia provides convenient upload/attach/metadata/lifecycle operations.

Uploads

The configured upload ceiling is enforced below HTTP, so controller, job, service, remote-import, connected-drive, resumable, and direct-upload paths cannot bypass it.

Canonical application upload

Resumable uploads

The resumable flow provides serialized chunk writes, single-active-session identifiers, exact declared-size enforcement, finalization locking, and failure compensation.

HTTP routes:

Direct S3-compatible uploads

Direct uploads are optional. Install the S3 adapter:

Enable:

The flow reserves quota before transfer, signs single PUT or multipart requests, verifies exact provider size and full-file SHA-256, finalizes idempotently into the canonical Media lifecycle, and releases quota on terminal failure/cancellation/expiry.

Unsupported disks can fall back to the normal server-mediated uploader.

Storage quota

Quota changes use database-level atomic updates. Active direct-upload reservations are included in authoritative usage.

Useful operations:

storage:health is read-only; reconciliation is always explicit.

ACL and large-workspace queries

Visibility is pushed into SQL before pagination. Restricted ancestors, folder grants, media grants, workspace access, stars, and activity filtering share the same visibility model.

High-volume global query surfaces use cursor pagination only:

Search returns independent folder and file cursors. Query page size is clamped below HTTP with:

An opt-in query benchmark is included:

It reports query count, elapsed time, memory, and query plans against a synthetic ACL tree. Release CI runs the benchmark on PostgreSQL and MySQL and enables lazy-loading prevention to catch N+1 regressions.

Media trust and processing

Stored bytes are inspected with fileinfo before derivatives are generated. High-confidence MIME mismatches fail closed.

Processing can run after commit through a queue:

The media row is the durable processing intent: queue handoff uses a lease and bounded retry timing, so a crash before/after dispatch can be recovered without a second generic outbox table. The processing pipeline is ordered content inspection → malware scan → derivatives, and derivatives never run after an unsafe/failed scan.

Recover pending work, stale queue handoffs, and stale worker leases (use --retry-failed for terminal worker failures):

Malware scanning

Scanning is optional:

When quarantine is enabled, package-owned download/share/email/export paths remain blocked until policy permits delivery. Private storage is required by default while malware quarantine is active.

First-class derivatives

Thumbnails and previews are stored as media_derivatives rows. A derivative owns its own:

• kind and variant
• format and MIME type
• disk/path
• byte size
• dimensions
• SHA-256
• primary selection
• generation metadata

There is no thumbnail_path mirror on media.

Derivative object keys are content-addressed. Replacement writes a new object, commits metadata/primary selection under the parent Media lock, then retires the old object. A database failure leaves the previous derivative intact.

Configuration example:

JPEG EXIF orientation is normalized before resize. GD WebP/AVIF output is used when the runtime supports it. Image dimensions/pixel count are validated before GD expands compressed image data.

Storage lifecycle and orphan recovery

Physical object storage cannot participate in the SQL transaction, so mutation flows use compensation and durable cleanup intents.

Uploads clean failed objects and release quota. Permanent deletion commits database/quota truth with durable cleanup records, then removes physical objects. Rename/move operations use copy → database commit → retire old object. Orphan cleanup uses bounded backoff and marks exhausted records abandoned_at; health reports abandoned cleanup as critical instead of retrying a poison object forever.

Retention

Retention is explicit and dry-run by default:

Destructive execution requires both configuration and --apply:

Retention uses the same permanent-deletion lifecycle as normal media deletion and includes derivative quota/object cleanup.

Bulk operations

Bulk trash, restore, move, and optional permanent delete reuse the canonical single-item use cases. They do not bypass ACL, lifecycle compensation, events, or quota accounting.

HTTP routes:

Permanent bulk delete is hidden unless explicitly enabled.

Sharing

Share downloads enforce expiry, password, access level, and download ceiling. Slot consumption is an atomic database mutation, so concurrent requests cannot both consume the last available download.

Cloud drives

Supported integrations include local, Google Drive, OneDrive, Dropbox, S3-compatible storage, Azure Blob, Google Cloud Storage, and Cloudinary. Provider dependencies remain optional. Adapter construction, dependency requirements and credential validation are owned by registered CloudProviderStrategy implementations; ConnectedDriveService no longer contains a provider factory/switch.

Examples:

OneDrive uses Microsoft Graph HTTP directly rather than requiring the generated Graph PHP SDK. The CloudProviderRegistry is container-managed and intentionally supports strategy replacement/registration for host-specific provider implementations.

Observability and health

StorageTelemetry is provider-neutral. The Laravel implementation emits structured records through logging and StorageTelemetryRecorded. Sensitive values including credentials, tokens, object paths/keys, and signed URLs are stripped.

Health checks cover database/storage connectivity, quota drift, orphan backlog, resumable/direct-upload health, processing backlog, and connected-drive status.

See docs/OPERATIONS.md.

Routes

Routes are disabled by default. When enabled, package routes are mounted under /storage and protected by configured middleware. Public share delivery uses the separate public middleware configuration.

Controllers are configurable in tetranyble-storage.routes.controllers if a host needs custom HTTP adapters while keeping the application services.

Facades

Available convenience facades:

Application use cases are preferred for business flows; facades are convenience access to lower-level package capabilities.

Testing and quality gates

CI covers:

• Laravel 12 / PHP 8.2–8.5
• Laravel 13 / PHP 8.3–8.5
• PostgreSQL 17 and MySQL 8.4 real-database suites on both Laravel 12 and Laravel 13
• cross-process concurrency tests for quota, share limits, direct finalization and cloud-drive default election
• MinIO S3-compatible provider contract tests, including completed multipart uploads
• PostgreSQL/MySQL large-workspace query budgets and N+1/lazy-loading checks

The MinIO job builds the current community server and verifies Laravel/Flysystem and raw S3 direct-upload operations address the same physical objects, including configured disk roots and complete multipart upload/inspection.

production:gate is the release-facing local gate. Architecture debt is ratcheted: Domain/Application framework debt is now zero, while remaining oversized classes may only decrease during the Hexagonal/DDD refactor. See docs/RELEASE_CHECKLIST.md.

Operational commands

First-release status

This repository is the clean first-release baseline. It intentionally contains no pre-release namespace aliases, legacy manager facade, thumbnail_path compatibility field, historical upgrade migrations, or duplicate legacy query APIs.

See docs/HANDOFF.md for continuation notes.

HTTP production hardening

When package routes are enabled, they use fail-closed authenticated middleware, named public/authenticated rate limiters, stable JSON error codes, and security headers. See docs/STEP_10_LARAVEL_HTTP_HARDENING.md. StorageServiceProvider also validates security-sensitive configuration during registration so invalid deployments fail before serving storage traffic.

Production reliability matrix

composer architecture:reliability protects the package's real-database race tests, queue recovery, compensation/orphan contracts, provider-outage isolation, Eloquent relationship resolution and MinIO multipart completion coverage. The real PostgreSQL/MySQL suite runs on both supported Laravel majors. See docs/STEP_11_PRODUCTION_RELIABILITY.md.

Final release hardening

composer architecture:release verifies stable package metadata, fail-closed defaults, the 46-endpoint HTTP compatibility surface, flattened first-release migrations, release-critical indexes, CI coverage, safe deployment examples and distribution hygiene. See docs/STEP_12_RELEASE_HARDENING.md.

CI/CD and releases

Every pull request and main push runs the supported PHP/Laravel matrix, architecture/static-analysis/format/test gates, PostgreSQL/MySQL integration tests, query budgets and MinIO S3 contracts. Stable publication is performed through the gated GitHub Release workflow; it creates the tested Git tag and GitHub Release, after which the existing Packagist GitHub integration indexes the version. See docs/CI_CD.md.