One stable API
Keep application business logic independent from provider-specific SDKs and response objects.
A unified, driver-based storage and transfer layer for Laravel. Move files across providers with one consistent interface—without coupling your application to a single backend.
Start with the product model, understand the driver boundary, then follow the implementation roadmap. Storix is a backend-only Composer package; it does not ship a dashboard or frontend.
Read the Product Requirements Document for goals, scope, user journeys, and acceptance criteria.
Study System Architecture and Storage Drivers before changing boundaries.
Begin with E01 Foundation: Composer metadata, service provider, configuration, CI, and conventions.
Use the Testing Strategy and Acceptance Checklist. Documentation alone is not implementation evidence.
Storage providers expose different APIs and capabilities. Large transfers introduce interruptions, duplicate requests, rate limits, partial writes, and uncertainty about data integrity. Storix centralizes those concerns behind a consistent Laravel API.
Keep application business logic independent from provider-specific SDKs and response objects.
Persist sessions and chunk state so eligible transfers can recover after interruptions.
Verify chunks and final content with SHA-256 where bytes are available. Never infer success from metadata alone.
Integrate with the service container, queues, events, migrations, scheduler, cache, and filesystem.
A provider adapter implementing a provider-neutral contract. Each driver declares its capabilities and operational limits.
Application-facing metadata and opaque identifiers. Physical provider keys stay private to infrastructure.
A durable workflow tracking intent, state, retries, ownership, and completion evidence.
A bounded part of a transfer with an offset, expected size, state, checksum, and provider reference.
Describes whether a driver supports streaming, range reads, multipart writes, atomic finalize, or pause/resume.
Allows safe request replay and duplicate detection without crossing tenant or owner boundaries.
The following are planned capabilities defined by the current engineering specification.
Put, stream, inspect, list, rename, and delete files/directories through a unified API, subject to driver capabilities.
Configurable chunk planning, bounded parallelism, chunk checksums, and durable transfer state.
Reconcile persisted state, reuse verified chunks within the same security scope, and retry transient failures.
Bytes, percentage, speed, ETA when measurable, chunk counts, lifecycle events, and structured diagnostics.
Owner/tenant scopes, policy hooks, path safety, quotas, secret redaction, and integrity checks.
Service provider, config, migrations, facade, queues, scheduler, optional Redis optimizations, and optional REST adapter.
Storix uses a modular, domain-oriented core. Application services depend on contracts; infrastructure adapters integrate provider SDKs and Laravel facilities.
Laravel Application / CLI / Optional REST
|
Storix PHP API
|
Application Services + Domain
+-------+--------+
Authorization Metadata DB Transfer Orchestrator
|
Laravel Queue
|
Chunk + Integrity Engine
|
Driver Manager
+----------+----------+
Local Telegram Future Drivers
For detailed sequences and consistency rules, read System Architecture and Database Design.
| Driver | Purpose | Scope |
|---|---|---|
| Local | Baseline filesystem-backed storage | Planned first usable driver |
| Telegram | Optional remote provider adapter | Requires current official API/policy validation |
| S3-compatible / R2 | Object storage backends | Future extensions |
| Custom | Application/vendor-specific backend | Via driver contract |
Expected high-level lifecycle:
pending → preparing → transferring → verifying → completed
| |
+--- retry_wait-+
Terminal states: failed · cancelled · expired
Optional state: paused (only where safely supported)
See Transfer Engine for protocol and failure handling.
Every read, write, list, resume, share, and delete operation must enforce owner and tenant access.
Generate opaque keys independently of user filenames; normalize paths and reject traversal.
Never expose provider tokens, signed URLs, private storage references, or raw exception traces.
Bound file size, chunk size, concurrency, queue attempts, quotas, and temporary disk usage.
Read the complete Security Design before implementing access or sharing features.
E05 implements a stream-first, single-object upload workflow on the existing Local driver and persistence layer and is merged into main.
Readable PHP streams, 64 MiB configured default (also capped by driver limits), 8 MiB memory spool threshold, and validation while bytes are read.
Scoped file and transfer records, a validated state lifecycle, tenant/owner-aware directory lookup, and private-only visibility.
Compare staged bytes, driver write metadata, stat size, and an independent streamed SHA-256 read-back.
Scoped idempotency returns an existing completed upload only for the same request fingerprint; conflicts never overwrite an object.
Implementation specifications: E05 Basic Upload and E06 Chunk Engine.
Expected Composer installation after a compatible package release is published:
composer require shamimstack/storix
The intended primary interface is PHP services/facade. Exact signatures and DTOs are subject to implementation and API review.
use ShamimStack\\Storix\\Facades\\Storix;
$file = Storix::files()->put(
source: $uploadedFile,
directory: 'invoices/2026',
options: ['visibility' => 'private'],
);
$stream = Storix::files()->readStream($file->id);
$transfer = Storix::uploads()->start($source, [
'directory' => 'backups',
'idempotency_key' => $requestId,
]);
$status = Storix::transfers()->status($transfer->id);
See Core PHP API and REST API for suggested routes, response envelopes, and error conventions.
Configuration is expected to cover default driver, driver credentials/settings, chunk policy, concurrency, retry policy, session retention, progress persistence, quotas, and optional REST adapter settings.
return [
'default_driver' => env('STORIX_DRIVER', 'local'),
'transfers' => [
'chunk_size' => 8 * 1024 * 1024,
'max_concurrency' => 3,
'max_attempts' => 5,
],
'api' => [
'enabled' => false,
'prefix' => 'api/v1/storix',
],
];
Values are illustrative only. See Configuration & Operations for the complete example and operational guidance.
Redis may improve queue/progress workloads but should not replace durable relational metadata.
State machine, chunk planner, fingerprinting, retry policy, DTO validation, and progress math.
Common behavior for stream read/write, stat, delete, capability declarations, and error mapping.
Laravel container, migrations, queues, events, filesystem, and end-to-end local transfers.
IDOR, tenant isolation, path traversal, secret redaction, memory bounds, concurrency, and realistic benchmarks.
| Epic | Scope |
|---|---|
| E01 | Foundation — Composer, provider, config, CI |
| E02 | Contracts & PHP API |
| E03 | Persistence & state machine |
| E04 | Local storage driver |
| E05 | Basic upload |
| E06 | Chunk engine |
| E07 | Resume & idempotency |
| E08 | Recovery & retry |
| E09 | Download engine |
| E10 | Progress & events |
| E11 | Performance & benchmarks |
| E12 | Optional Telegram driver after validation |
| E13 | Optional REST adapter & security hardening |
| E14 | Release & operations |
Implement sequentially. Do not begin provider-specific work before core contracts and transfer state are stable. See the full roadmap.
Each document is the detailed source of truth for its subject.
No. It is a backend-only package. Applications can build their own UI using the PHP API, events, or optional REST adapter.
No. Telegram is an optional driver. The core architecture is provider-neutral, and Telegram Serverless is excluded.
No. These behaviors depend on driver capabilities and execution mode. Storix must expose support explicitly instead of promising identical behavior for every provider.
No. This documentation describes the intended design and roadmap. Consult repository code, tests, and release notes for verified implementation status.
Only after the driver finalizes the object and the required integrity verification succeeds.