README

SurvosMediaBundle provides a deterministic, URL‑centric media registry for Symfony applications.

It is intentionally not a media processor. Instead, it:

Registers media references (URLs or local files)
Assigns deterministic IDs derived from URLs
Stores application‑local media metadata
Syncs with a centralized media server (future step)
Generates thumbnail URLs via imgproxy‑style patterns (future step)

This mirrors the relationship between babel‑bundle and lingua‑server:

Applications own their media tables
A central service owns the binaries and heavy processing

Core Concept: Deterministic Media IDs

Every media item has a stable, deterministic ID derived from its URL.

use Survos\MediaBundle\Service\MediaRegistry;

$id = MediaRegistry::idFromUrl('https://example.com/image.jpg');

The algorithm:

Base64‑encodes the URL
Converts it to URL‑safe base64
Removes padding

This is the same philosophy used by imgproxy.

Why this matters

No database lookups to resolve URLs
IDs are reversible
Same URL → same ID across apps
Safe primary key for Meilisearch

Registering Media

The primary entry point is MediaRegistry.

foreach ($data->images as $imageUrl) {
    $media = $mediaRegistry->ensureMedia($imageUrl);
}

Behavior

Defaults to Photo
No duplicate URLs
Bulk‑safe (flush: false)
No network calls

Local files are also supported:

$media = $mediaRegistry->ensureMedia($uploadedFile);

Local files are assigned a temporary local:// URL until synced.

Receiving mediary's callback

mediary POSTs a signed asset.analyzed webhook to /webhook/mediary when an image finishes analysis. This bundle supplies the two pieces that belong to it — a request parser (Survos\MediaBundle\Webhook\MediaWebhookRequestParser) and a consumer that calls MediaUpdateApplier, the same write path media:sync uses. It contributes no route and no controller; the endpoint is FrameworkBundle's own.

In the app:

# config/routes/webhook.yaml
webhook:
    resource: '@FrameworkBundle/Resources/config/routing/webhook.php'
    prefix: /webhook

# config/packages/webhook.yaml
framework:
    webhook:
        routing:
            mediary:
                service: Survos\MediaBundle\Webhook\MediaWebhookRequestParser
                secret: '%env(default::MEDIARY_WEBHOOK_SECRET)%'

# config/packages/messenger.yaml — REQUIRED, or the endpoint's 202 is a lie
framework:
    messenger:
        routing:
            'Symfony\Component\RemoteEvent\Messenger\ConsumeRemoteEventMessage': media_callback

Set MEDIARY_WEBHOOK_SECRET to the same value mediary signs with, and point MEDIA_CALLBACK_URL at https://your-app/webhook/mediary.

To react to updates, listen for MediaUpdatedEvent — mediary never learns your entity shape.

Full contract, including how to run several webhooks on separate queues: kit-bundle/docs/webhooks.md.

Replaced the unauthenticated MediaCallbackController at /media/callback, where anyone who could reach the URL could rewrite a media row. See survos-sites/mediary#8.

Probing Mediary (Polling Fallback)

When webhook callbacks are unavailable (for example, local dev tunnels are down), poll mediary directly via the bundle service.

use Survos\MediaBundle\Service\MediaBatchDispatcher;

$result = $mediaBatchDispatcher->dispatch('museum', [$url], [
    'callback_url' => 'https://my-app.example/webhook/media',
]);

$assetId = $result->media[0]->mediaKey;
$probe = $mediaBatchDispatcher->probe($assetId);

if ($probe->isComplete()) {
    // use $probe->meta / $probe->context / $probe->ocr / $probe->ai
}

Available methods:

probe(string $assetId): MediaProbeResult → calls GET /fetch/media/{id}
probeMany(array $assetIds): array<MediaProbeResult> → calls POST /fetch/media/by-ids

Probe payload includes current workflow state (marking), variants/thumb URLs, metadata, and any OCR/AI context that has been written so far.

CLI helper:

bin/console media:probe 5c4e0c2d6f8a1b9e
bin/console media:probe "https://example.org/image.jpg"
bin/console media:probe --url "upload://sha256/abcd..."

Publishing Claims to Mediary

Apps run AI with survos/ai-workflow-bundle and store tracked metadata as claims. Media publishing should send the image plus selected source/AI/human claims to mediary, while mediary remains responsible for global media access and canonical image URLs. See docs/publishing.md.

What This Bundle Does Not Do

Download media
Resize images
Cache thumbnails
Perform OCR, tagging, or EXIF extraction

Those responsibilities belong to the media server and imgproxy.

Status

This bundle is intentionally minimal and evolving.

Next steps include:

media:sync command
Provider detection (YouTube, Flickr, etc.)
Thumbnail URL generation helpers

survos / media-bundle

Maintainers

Package info

Fund package maintenance!

Statistics

Security