MediaObject
extends AbstractBaseApi
in package
MediaObject API
Provides functionality for managing media objects and their tracks in Canvas LMS
Table of Contents
Properties
- $canAddCaptions : bool|null
- Whether the current user can upload media_tracks (subtitles) to this Media Object
- $mediaId : string|null
- The unique identifier for the media object
- $mediaSources : array<string|int, MediaSource>|null
- Array of MediaSource objects with different encodings
- $mediaTracks : array<string|int, MediaTrack>|null
- Array of MediaTrack objects associated with this media
- $mediaType : string|null
- The type of media (video, audio)
- $title : string|null
- The display title of the media object
- $userEnteredTitle : string|null
- Custom title entered by the user
- $methodAliases : array<string, array<string|int, string>>
- Define method aliases
Methods
- __callStatic() : mixed
- Magic method to handle function aliases
- __construct() : mixed
- Constructor
- all() : array<string|int, static>
- Get all pages of results
- fetchAttachments() : array<string|int, MediaObject>
- Fetch all media attachments (global context)
- fetchAttachmentsByCourse() : array<string|int, MediaObject>
- Fetch media attachments for a specific course
- fetchAttachmentsByGroup() : array<string|int, MediaObject>
- Fetch media attachments for a specific group
- fetchByCourse() : array<string|int, MediaObject>
- Fetch media objects for a specific course
- fetchByGroup() : array<string|int, MediaObject>
- Fetch media objects for a specific group
- find() : static
- Find a specific media object by ID Note: Canvas API doesn't support direct media object retrieval
- get() : array<string|int, MediaObject>
- Fetch all media objects (global context)
- getTracks() : array<string|int, MediaTrack>
- Get media tracks for this media object
- getTracksByAttachment() : array<string|int, MediaTrack>
- Get media tracks by attachment ID
- overrideApiClient() : void
- Set an API client for this class only, leaving other resources on the shared default.
- paginate() : PaginationResult
- Get paginated results with metadata
- resetApiClients() : void
- Clear the shared default client and all per-class overrides.
- setApiClient() : void
- Set the shared default API client used by ALL resource classes.
- stream() : Generator<int, static>
- Stream all items across all pages one at a time.
- toArray() : array<string, mixed>
- Convert the MediaObject to an array
- update() : self
- Update the media object
- updateByAttachment() : self
- Update the media object by attachment ID
- updateTracks() : array<string|int, MediaTrack>
- Update media tracks for this media object
- updateTracksByAttachment() : array<string|int, MediaTrack>
- Update media tracks by attachment ID
- castValue() : DateTime|mixed
- Cast a value to the correct type
- checkApiClient() : void
- Check if the API client is set, if not, instantiate a new one
- convertPaginatedResponseToModels() : array<string|int, static>
- Helper method to convert paginated response data to model instances
- createConfiguredHttpClient() : HttpClient
- Create an HttpClient with configured middleware
- createPaginationResult() : PaginationResult
- Helper method to create PaginationResult from paginated response
- getAliasMap() : array<string, string>
- Build a flat alias-to-method lookup from $methodAliases.
- getApiClient() : HttpClientInterface
- Get the API client, initializing if necessary
- getEndpoint() : string
- Get the endpoint for this API resource MediaObjects don't have a single endpoint, so this throws an exception
- getPaginatedResponse() : PaginatedResponse
- Helper method to get paginated response from API endpoint
- hydrate() : void
- Assign API response data to properties with type coercion.
- parseJsonResponse() : array<string|int, mixed>
- Parse JSON response from API safely handling StreamInterface
- populate() : void
- Populate the object with new data
- toDtoArray() : array<string|int, mixed>
- Convert the object to an array
- validateContext() : void
- Validate a context type path segment against an allowlist.
Properties
$canAddCaptions
Whether the current user can upload media_tracks (subtitles) to this Media Object
public
bool|null
$canAddCaptions
= null
$mediaId
The unique identifier for the media object
public
string|null
$mediaId
= null
$mediaSources
Array of MediaSource objects with different encodings
public
array<string|int, MediaSource>|null
$mediaSources
= null
$mediaTracks
Array of MediaTrack objects associated with this media
public
array<string|int, MediaTrack>|null
$mediaTracks
= null
$mediaType
The type of media (video, audio)
public
string|null
$mediaType
= null
$title
The display title of the media object
public
string|null
$title
= null
$userEnteredTitle
Custom title entered by the user
public
string|null
$userEnteredTitle
= null
$methodAliases
Define method aliases
protected
static array<string, array<string|int, string>>
$methodAliases
= ['get' => ['fetch', 'list'], 'all' => ['fetchAllPages', 'getAll', 'fetchAll'], 'paginate' => ['getPaginated', 'withPagination'], 'find' => ['one', 'getOne']]
Methods
__callStatic()
Magic method to handle function aliases
public
static __callStatic(string $name, array<string|int, mixed> $arguments) : mixed
Parameters
- $name : string
- $arguments : array<string|int, mixed>
Tags
__construct()
Constructor
public
__construct([array<string, mixed> $data = [] ]) : mixed
Parameters
- $data : array<string, mixed> = []
all()
Get all pages of results
public
static all([array<string, mixed> $params = [] ]) : array<string|int, static>
Parameters
- $params : array<string, mixed> = []
-
Query parameters
Return values
array<string|int, static>fetchAttachments()
Fetch all media attachments (global context)
public
static fetchAttachments([array<string, mixed> $params = [] ]) : array<string|int, MediaObject>
Parameters
- $params : array<string, mixed> = []
-
Query parameters
Tags
Return values
array<string|int, MediaObject> —Array of MediaObject instances
fetchAttachmentsByCourse()
Fetch media attachments for a specific course
public
static fetchAttachmentsByCourse(int $courseId[, array<string, mixed> $params = [] ]) : array<string|int, MediaObject>
Parameters
- $courseId : int
-
The course ID
- $params : array<string, mixed> = []
-
Query parameters
Tags
Return values
array<string|int, MediaObject> —Array of MediaObject instances
fetchAttachmentsByGroup()
Fetch media attachments for a specific group
public
static fetchAttachmentsByGroup(int $groupId[, array<string, mixed> $params = [] ]) : array<string|int, MediaObject>
Parameters
- $groupId : int
-
The group ID
- $params : array<string, mixed> = []
-
Query parameters
Tags
Return values
array<string|int, MediaObject> —Array of MediaObject instances
fetchByCourse()
Fetch media objects for a specific course
public
static fetchByCourse(int $courseId[, array<string, mixed> $params = [] ]) : array<string|int, MediaObject>
Parameters
- $courseId : int
-
The course ID
- $params : array<string, mixed> = []
-
Query parameters
Tags
Return values
array<string|int, MediaObject> —Array of MediaObject instances
fetchByGroup()
Fetch media objects for a specific group
public
static fetchByGroup(int $groupId[, array<string, mixed> $params = [] ]) : array<string|int, MediaObject>
Parameters
- $groupId : int
-
The group ID
- $params : array<string, mixed> = []
-
Query parameters
Tags
Return values
array<string|int, MediaObject> —Array of MediaObject instances
find()
Find a specific media object by ID Note: Canvas API doesn't support direct media object retrieval
public
static find(int $id[, array<string|int, mixed> $params = [] ]) : static
Parameters
- $id : int
-
The media object ID (not used - Canvas doesn't support this)
- $params : array<string|int, mixed> = []
-
Optional query parameters
Tags
Return values
staticget()
Fetch all media objects (global context)
public
static get([array<string, mixed> $params = [] ]) : array<string|int, MediaObject>
Parameters
- $params : array<string, mixed> = []
-
Query parameters
Tags
Return values
array<string|int, MediaObject> —Array of MediaObject instances
getTracks()
Get media tracks for this media object
public
getTracks([array<string, mixed> $params = [] ]) : array<string|int, MediaTrack>
Parameters
- $params : array<string, mixed> = []
-
Query parameters (include[] options)
Tags
Return values
array<string|int, MediaTrack> —Array of MediaTrack objects
getTracksByAttachment()
Get media tracks by attachment ID
public
getTracksByAttachment(int $attachmentId[, array<string, mixed> $params = [] ]) : array<string|int, MediaTrack>
Parameters
- $attachmentId : int
-
The attachment ID
- $params : array<string, mixed> = []
-
Query parameters (include[] options)
Tags
Return values
array<string|int, MediaTrack> —Array of MediaTrack objects
overrideApiClient()
Set an API client for this class only, leaving other resources on the shared default.
public
static overrideApiClient(HttpClientInterface $apiClient) : void
Parameters
- $apiClient : HttpClientInterface
paginate()
Get paginated results with metadata
public
static paginate([array<string, mixed> $params = [] ]) : PaginationResult
Parameters
- $params : array<string, mixed> = []
-
Query parameters
Return values
PaginationResultresetApiClients()
Clear the shared default client and all per-class overrides.
public
static resetApiClients() : void
setApiClient()
Set the shared default API client used by ALL resource classes.
public
static setApiClient(HttpClientInterface $apiClient) : void
Calling this on any resource (e.g. Course::setApiClient()) replaces the client for every resource, because relationship methods cross class boundaries ($course->enrollments() calls Enrollment internally). Use overrideApiClient() to scope a client to a single class, and resetApiClients() in test teardown to avoid state leaking.
Parameters
- $apiClient : HttpClientInterface
stream()
Stream all items across all pages one at a time.
public
static stream([array<string|int, mixed> $params = [] ]) : Generator<int, static>
Unlike all(), only one page of raw data is held in memory at a time, making this safe for very large datasets (e.g. tens of thousands of enrollments):
foreach (User::stream(['per_page' => 100]) as $user) {
processUser($user);
}
Parameters
- $params : array<string|int, mixed> = []
-
Query parameters for the request
Tags
Return values
Generator<int, static>toArray()
Convert the MediaObject to an array
public
toArray() : array<string, mixed>
Return values
array<string, mixed>update()
Update the media object
public
update(array<string, mixed>|UpdateMediaObjectDTO $data) : self
Parameters
- $data : array<string, mixed>|UpdateMediaObjectDTO
-
Update data
Tags
Return values
selfupdateByAttachment()
Update the media object by attachment ID
public
updateByAttachment(int $attachmentId, array<string, mixed>|UpdateMediaObjectDTO $data) : self
Parameters
- $attachmentId : int
-
The attachment ID
- $data : array<string, mixed>|UpdateMediaObjectDTO
-
Update data
Tags
Return values
selfupdateTracks()
Update media tracks for this media object
public
updateTracks(array<string|int, array<string, mixed>>|UpdateMediaTracksDTO $tracks[, array<string, mixed> $params = [] ]) : array<string|int, MediaTrack>
Parameters
- $tracks : array<string|int, array<string, mixed>>|UpdateMediaTracksDTO
-
Track data
- $params : array<string, mixed> = []
-
Query parameters (include[] options)
Tags
Return values
array<string|int, MediaTrack> —Array of MediaTrack objects
updateTracksByAttachment()
Update media tracks by attachment ID
public
updateTracksByAttachment(int $attachmentId, array<string|int, array<string, mixed>>|UpdateMediaTracksDTO $tracks[, array<string, mixed> $params = [] ]) : array<string|int, MediaTrack>
Parameters
- $attachmentId : int
-
The attachment ID
- $tracks : array<string|int, array<string, mixed>>|UpdateMediaTracksDTO
-
Track data
- $params : array<string, mixed> = []
-
Query parameters (include[] options)
Tags
Return values
array<string|int, MediaTrack> —Array of MediaTrack objects
castValue()
Cast a value to the correct type
protected
castValue(string $key, mixed $value) : DateTime|mixed
Parameters
- $key : string
- $value : mixed
Tags
Return values
DateTime|mixedcheckApiClient()
Check if the API client is set, if not, instantiate a new one
protected
static checkApiClient() : void
convertPaginatedResponseToModels()
Helper method to convert paginated response data to model instances
protected
static convertPaginatedResponseToModels(PaginatedResponse $paginatedResponse) : array<string|int, static>
Parameters
- $paginatedResponse : PaginatedResponse
Return values
array<string|int, static>createConfiguredHttpClient()
Create an HttpClient with configured middleware
protected
static createConfiguredHttpClient() : HttpClient
Return values
HttpClientcreatePaginationResult()
Helper method to create PaginationResult from paginated response
protected
static createPaginationResult(PaginatedResponse $paginatedResponse) : PaginationResult
Parameters
- $paginatedResponse : PaginatedResponse
Return values
PaginationResultgetAliasMap()
Build a flat alias-to-method lookup from $methodAliases.
protected
static getAliasMap() : array<string, string>
Return values
array<string, string>getApiClient()
Get the API client, initializing if necessary
protected
static getApiClient() : HttpClientInterface
Return values
HttpClientInterfacegetEndpoint()
Get the endpoint for this API resource MediaObjects don't have a single endpoint, so this throws an exception
protected
static getEndpoint() : string
Tags
Return values
stringgetPaginatedResponse()
Helper method to get paginated response from API endpoint
protected
static getPaginatedResponse(string $endpoint[, array<string|int, mixed> $params = [] ]) : PaginatedResponse
Parameters
- $endpoint : string
-
The API endpoint path
- $params : array<string|int, mixed> = []
-
Query parameters for the request
Return values
PaginatedResponsehydrate()
Assign API response data to properties with type coercion.
protected
hydrate(array<string|int, mixed> $data) : void
Shared by the constructor and populate() so objects keep the same type guarantees after save()/update() round-trips as on creation.
Parameters
- $data : array<string|int, mixed>
parseJsonResponse()
Parse JSON response from API safely handling StreamInterface
protected
static parseJsonResponse(ResponseInterface $response) : array<string|int, mixed>
Parameters
- $response : ResponseInterface
Return values
array<string|int, mixed>populate()
Populate the object with new data
protected
populate(array<string|int, mixed> $data) : void
Parameters
- $data : array<string|int, mixed>
Tags
toDtoArray()
Convert the object to an array
protected
toDtoArray() : array<string|int, mixed>
Return values
array<string|int, mixed>validateContext()
Validate a context type path segment against an allowlist.
protected
static validateContext(string|null $contextType, array<int, string> $allowed) : void
Context types are interpolated into URL paths; validating against the contexts Canvas actually supports prevents crafted values from injecting extra path segments or query parameters.
Parameters
- $contextType : string|null
-
The context type (plural, e.g. 'courses'); null is ignored
- $allowed : array<int, string>
-
Allowed context types