Overview
The MediaDownloadRef model tracks download references for both VOD streams and series episodes. It supports aria2 download management, retry logic, and error tracking.
Model Path: app/Models/MediaDownloadRef.php
Table: media_download_refs
Database Schema
Auto-incrementing primary key
Unique aria2 download GID (globally unique identifier)
Foreign key to users table (nullable)
Polymorphic foreign key to the media (Series or VodStream)
Polymorphic type (e.g., ‘App\Models\Series’ or ‘App\Models\VodStream’)
ID of the downloadable item (stream_id or episode_id)
Season number (only for series episodes, nullable for VODs)
Episode number (only for series episodes, nullable for VODs)
Whether the download should be paused
Timestamp when the download was canceled
Whether to delete partial files on cancellation
Last error code encountered during download
Last error message encountered
Number of retry attempts made
Scheduled timestamp for next retry attempt (indexed)
JSON array of downloaded file information
Record creation timestamp
Record last update timestamp
Fillable Attributes
[
'gid',
'user_id',
'media_id',
'media_type',
'downloadable_id',
'season',
'episode',
'desired_paused',
'canceled_at',
'cancel_delete_partial',
'last_error_code',
'last_error_message',
'retry_attempt',
'retry_next_at',
'download_files',
]
Type Casts
desired_paused → booleancanceled_at → immutable_datetimecancel_delete_partial → booleanlast_error_code → integerretry_attempt → integerretry_next_at → immutable_datetimedownload_files → array
Factory Methods
Create from VOD Stream
Create a download reference for a VOD stream:
public static function fromVodStream(
string $gid,
VodStream $vodStream,
User|int|null $owner = null
): self
$vod = VodStream::find(123);
$download = MediaDownloadRef::fromVodStream(
gid: 'abc123def456',
vodStream: $vod,
owner: auth()->user()
);
Create from Series Episode
Create a download reference for a series episode:
public static function fromSeriesAndEpisode(
string $gid,
Series $series,
Episode $episode,
User|int|null $owner = null
): self
$series = Series::find(456);
$episode = new Episode(/* episode data */);
$download = MediaDownloadRef::fromSeriesAndEpisode(
gid: 'xyz789abc012',
series: $series,
episode: $episode,
owner: 1 // user ID
);
Helper Methods
public function isVodStream(): bool
true if the download is for a VOD stream.
public function isSeriesWithEpisode(): bool
true if the download is for a series episode.
Example:
if ($download->isVodStream()) {
// Handle VOD download
} elseif ($download->isSeriesWithEpisode()) {
// Handle series episode download
}
Relationships
Get the associated media model (either VodStream or Series):
public function media(): MorphTo
$download = MediaDownloadRef::find(1);
$media = $download->media; // Returns VodStream or Series instance
Owner
Get the user who owns this download:
public function owner(): BelongsTo
$download = MediaDownloadRef::find(1);
$user = $download->owner;
Download Management
Retry Logic
Track failed downloads with automatic retry:
$download->update([
'last_error_code' => 500,
'last_error_message' => 'Connection timeout',
'retry_attempt' => $download->retry_attempt + 1,
'retry_next_at' => now()->addMinutes(5),
]);
Pause and Cancel
// Pause a download
$download->update(['desired_paused' => true]);
// Cancel a download
$download->update([
'canceled_at' => now(),
'cancel_delete_partial' => true,
]);
Query Pending Retries
// Get downloads ready for retry
$pendingRetries = MediaDownloadRef::whereNotNull('retry_next_at')
->where('retry_next_at', '<=', now())
->get();