Download the PHP package sarkis-sh/spray-media without Composer

Spray Media — Secure, Signed, Developer-First Media for Laravel

Spray Media gives you signed links, a hardened upload flow, and swappable building blocks so you can ship secure media delivery (view/download) quickly and confidently.

Table of Contents

• Why Spray Media
• Requirements
• Install
• Configuration Essentials
• Default Routes
  • Update filename endpoint
• Database Schema
• Quickstart (3 Steps)
• Helpers & Resource
• How It Works
• Security Notes
• Performance
• Extensibility
• Translations
• Testing
• License

Why Spray Media

• :lock: HMAC-signed URLs with optional expiration and embedded metadata.
• :inbox_tray: HTTP upload endpoint with size/MIME controls, custom rules, and automatic filename sanitizing.
• :page_facing_up: Inline or attachment responses with Cache-Control, ETag, and 304 support.
• :zap: Helpers, Resource, and Facade ready to drop into APIs or views.
• :wrench: Fully swappable components: uploader, storage, URL generator, validator, file server, repository, response adapter.
• :globe_with_meridians: Built-in translations (en/ar), configurable routes, and ready migrations.

Requirements

• PHP >= 8.1
• Laravel 10, 11, or 12

Install

Configuration Essentials

Full config lives in src/Config/media.php. Key options:

Default Routes

Defined in src/Routes/api.php (prefix/path/middleware are configurable):

Update filename endpoint

• Path: PUT /api/media-items/{id}/update-filename
• Body (JSON or form):
  • new_file_name (string, required) — the desired base name (extension stays the same)

Example:

Database Schema

Migration: src/Database/Migrations/0001_01_01_000003_create_media_items_table.php

• Columns: path, disk, formatted_filename, filename, extension, mime_type, size, timestamps.

Quickstart (3 Steps)

1) Upload via HTTP

Validation applies max/mime/mimetypes/custom_rules from config.

Sample success payload (see src/Infrastructure/Http/DefaultResponseAdapter.php):

2) Generate a signed URL (inline or download)

Links carry data (base64 JSON) + signature (HMAC). Pass expiration_minutes => null for non-expiring links.

3) Serve the file Hit the signed URL. The package validates signature/expiry, sets headers based on action (inline/attachment), and emits Cache-Control/ETag.

Helpers & Resource

• media_item_upload_file($file, ?$dir, ?$disk) returns storage metadata only.
• media_item_upload_and_create($file, $attributes = []) uploads and creates the record.
• media_item_generate_protected_url($media, MediaAction::VIEW, $options = []) signed URL helper.
• media_item_with_signed_url($media, $action, $options) and media_item_collection_with_signed_url(...) wrap in Resource with url and expires_at set (src/Http/Resources/MediaItemResource.php).
• media_item_get_absolute_path($media) returns filesystem path.

How It Works

1) Upload: FilenameSanitizer. 2) Persist: MediaItemManager persists metadata through the repository binding. 3) Sign: HmacMediaItemUrlGenerator builds payload, base64 encodes, signs with HMAC. 4) Validate: HmacPayloadValidator checks presence, signature (hash_equals), payload JSON, action, and expiry. 5) Serve: LocalFileServer streams inline/attachment, applies Cache-Control/ETag, returns 304 when ETag matches.

Security Notes

• Rotate hmac.secret per environment; keep it distinct from APP_KEY when possible.
• Choose a strong hmac.algorithm (sha256+). Links can be expiring or non-expiring per call.
• Filenames are sanitized to a slug to avoid header/FS issues.
• Validator rejects missing/invalid signatures, malformed payloads, wrong actions, or expired links.

Performance

• If expires_at is present, Cache-Control uses the remaining lifetime automatically; otherwise uses the configured header.
• ETag is based on id + updated_at to enable 304 responses.

Extensibility

• Swap any contract via spray-media.bindings in src/Config/media.php: repository, uploader, url_generator, payload_validator, file_server, response_adapter.
• Override model/resource via spray-media.model and spray-media.resource to expose custom fields or relations.
• Routes, names, and middleware are fully configurable for API compatibility.

Translations

• English and Arabic strings ship with the package; publish lang to customize.

Testing

License

MIT