Download the PHP package takepart-media/vidiq without Composer

vidiQ — 3q.video Integration for Statamic

A Statamic addon that integrates the 3q.video hosting platform into the Statamic Control Panel asset browser. Videos hosted on 3q appear as browsable, deletable assets with thumbnail previews. A Blade component is provided for embedding videos in frontend templates.

This addon has only been tested with Statamic 6 and 3Q's SDN API v2.

Features

• Asset browser integration — 3Q videos appear in Statamic's CP file browser with thumbnail previews and release-status colour strips (published / unpublished / draft)
• Asset editor player — opening a video in the CP asset editor replaces the default <video> element with the 3Q player iframe
• Fieldtype support — videos selected via an Assets fieldtype display thumbnails and status indicators in entry forms
• Read-only (for now) — browse videos directly from the CP; write operations (upload, delete, rename, move) are currently unsupported — manage content in 3Q's own dashboard. Full write support may be added in a future release.
• CP Cache Utility — manage the vidiq cache directly from the Statamic Control Panel (Utilities → vidiQ Cache) with Warm and Clear buttons
• Cache warm-up command — vidiq:warm-cache Artisan command pre-populates listing and embed-code caches during deployment
• Flysystem v3 adapter — custom ThreeQAdapter implements the Flysystem interface backed by the 3Q SDN API
• Embed codes — fetches the full FileEmbedCodes array per video via the 3Q playout API (cached)
• Virtual meta files — generates .meta/ YAML on the fly so Statamic stores title, thumbnail URL, video ID and release status without writing to disk
• Blade component — <x-vidiq::embed> for embedding the 3Q player in frontend templates

Requirements

• PHP 8.3+
• Statamic 6.x
• GuzzleHTTP 7.x
• A 3q.video account with API access

Version compatibility

Statamic 5 support was dropped in 3.0.0. Statamic 6 rebuilt the Control Panel on Inertia/Vue and removed the Blade chrome the CP Cache Utility relied on (statamic::partials.breadcrumb, the card/btn/badge-pill-sm classes). The utility view is now a fragment built from Statamic 6's global ui-* components, which do not exist in Statamic 5. Projects still on Statamic 5 should stay on ^2.0.

Installation

Install the package via Composer:

Statamic will auto-discover the addon's service provider. No additional registration steps are needed.

Environment variables

Add the following to your .env file:

Asset container

Create content/assets/vidiq.yaml in your Statamic project:

Statamic will display this container as "3Q Videos" in the CP under Assets.

How It Works

Flysystem adapter (ThreeQAdapter)

The adapter connects to the 3Q SDN REST API and implements League\Flysystem\FilesystemAdapter:

Path convention

Each video's path is its sanitized display title (e.g. My Interview.mp4). If two videos share the same title, the last 6 characters of the FileId are appended to avoid collisions. The FileId→path mapping is stored in the listing cache.

Virtual meta files

listContents also yields a virtual .meta/{path}.yaml entry for every video. This YAML contains:

Statamic reads this file automatically; because the file exists virtually, Statamic skips calling writeMeta() and leaves the adapter's read-only behaviour intact.

CP thumbnails (server-side)

Statamic 6 renders a thumbnail for any asset whose CP payload carries a thumbnail key. 3Q videos have no local file Glide could work on, so the addon hooks the three CP asset resources and passes the 3Q poster URL through:

The poster URL comes from the asset's own meta data (thumbnail_url, written by the adapter's virtual .meta/ file), so no extra request and no client-side patching is involved.

CP player (vidiq_player fieldtype)

The asset editor renders <video :src="asset.url"> for video assets, and a read-only 3Q container has no asset URL. The addon ships a vidiq_player fieldtype instead: it resolves the 3Q player URL server-side in preload() and its Vue component teleports an iframe into the editor's preview column, hiding the core <video>.

Add it to the container's asset blueprint to activate it — see below. Outside the asset editor the field renders inline.

Asset blueprint

Create resources/blueprints/assets/{container}.yaml in your Statamic project:

Blueprint fields are listed before Statamic's own asset columns (File, Size, Last Modified, …), so to move the status column to the end, set the container's column preference — either by reordering the columns in the CP and saving them as default, or in resources/preferences.yaml:

Columns missing from that list are hidden.

release_status is filled from the 3Q metadata (published / unpublished / draft). The vidiq_status fieldtype renders it as a coloured, translated badge — green for published, amber for unpublished, grey for draft — both as a table column in the asset browser and in the asset editor. Labels come from the addon's translations (lang/{locale}/messages.php).

Searchable 3Q metadata

By default Statamic's asset browser only searches the file path, which for 3Q assets means the video title. VIDIQ_METADATA_FIELDS pulls additional fields out of the 3Q Metadata block, stores them as asset data and matches them in the CP search alongside the filename — in the asset browser as well as in the assets fieldtype.

Each key is stored under its snake_cased name, so Category becomes category and ProgramId becomes program_id. Values that 3Q returns as lists of objects (Category, People, …) are flattened to their labels and joined with commas. Empty values are omitted, an empty variable disables the feature.

The fields are captured while the 3Q listing is fetched, so changing the list requires a cache refresh:

Add a field to the blueprint to also show it as a column. Mark it read_only, because edits to asset meta are persisted by the adapter and would then shadow the value coming from 3Q:

Blade Component

<x-vidiq::embed>

Embeds a 3Q video using one of three output methods. The method defaults to the config value vidiq.embed_fallback_method (default: JavaScript).

Props

Methods

Configuration

config/vidiq.php (addon)

config/vidiq-disk.php (addon)

Configures the 3q Laravel filesystem disk that is registered automatically by the ServiceProvider. The disk uses the custom 3q driver backed by ThreeQAdapter.

Multiple Projects

To connect a second 3Q project, add another disk entry in config/filesystems.php and a matching asset container YAML:

After that update .env with the new credentials and clear or refresh caches:

Development

Clone the repository and install dependencies:

Build CP assets

Cache management

CP Utility

The addon registers a vidiQ Cache utility in the Statamic Control Panel under Utilities → vidiQ Cache. It displays the number of cached videos and the current cache mode (TTL or Permanent). Two actions are available:

• Warm — dispatches a background queue job (WarmCacheJob) that flushes all vidiq caches, re-fetches the listing from the 3Q API, and pre-fetches embed codes for every video.
• Clear — immediately flushes all vidiq-specific cache entries (listing, embed codes, meta edits).

Warm the cache (CLI)

Pre-populate the video listing cache (and optionally embed codes) so the first frontend request avoids an API round-trip:

This is intended to run once during deployment (e.g. in a post-deploy script or CI pipeline).

Flush caches

The vidiq:warm-cache command automatically flushes all vidiq-specific cache entries (listing, embed codes, meta edits) before re-populating.

License

The MIT License (MIT). Please see the LICENSE file for more information.