omnipost/youtube API reference

Omnipost\YouTube

Api class

final class Api Api.php:24

The YouTube Data API v3, thin. Two ways in: a key (X-Goog-Api-Key), enough to read what is public; OAuth (a Bearer token drawn from the refresh token, kept for its hour), for what is the channel's own - uploading, deleting, "mine". Google's errors as Omnipost's: HTTP 401 and a refused grant are an UnauthorizedException, the rest a ProviderException with Google's reason (quotaExceeded, uploadLimitExceeded...).

Through the application's HTTP client when one is given.

const PROVIDER = 'youtube'

const BASE_URI = 'https://www.googleapis.com/youtube/v3'

const UPLOAD_URI = 'https://www.googleapis.com/upload/youtube/v3'

const TOKEN_URL = 'https://oauth2.googleapis.com/token'

Api::__construct()

public function __construct(readonly ?string $apiKey = null, readonly ?string $clientId = null, readonly ?string $clientSecret = null, ?string $refreshToken = null, ?string $accessToken = null, readonly string $baseUri = self::BASE_URI, readonly string $uploadUri = self::UPLOAD_URI, ?HttpClientInterface $http = null)

Api::clientId()

public function clientId(): ?string

Api::canAuthorize()

public function canAuthorize(): bool

Whether a call can go out as the channel: a token at hand, or what it takes to draw one.

Api::get()

public function get(string $path, array $query = [], bool $oauth = false): array

$oauth

as the channel, even when a key would do

Api::delete()

public function delete(string $path, array $query = []): void

Api::startUpload()

public function startUpload(array $metadata, string $mime, ?int $size): string

A resumable upload opened: the video's metadata sent, the URL the bytes go to answered.

$metadata

{snippet, status}

Api::upload()

public function upload(string $location, $stream, string $mime, ?int $size): array

The bytes, to the URL startUpload() gave.

Returns

the video

Api::download()

public function download(string $url): array

A file elsewhere, brought to a temporary one - a video that only has a URL - for upload() to send.

Returns

the stream rewound, its size, its content type

Api::token()

public function token(): ?Token

The access token at hand, null before the first one is drawn.

Api::refresh()

public function refresh(): Token

A fresh access token from the refresh token.

Api::grant()

public function grant(array $fields): Token

Google's token endpoint, the client's id and secret added; the tokens answered are the ones the calls go out with from now on.

YouTubeProvider class

final class YouTubeProvider implements PublisherInterface, FeedInterface, RefreshableInterface, OAuthInterface YouTubeProvider.php:38

A YouTube channel: who it is, its uploads, and a video uploaded - a Short when it is vertical and three minutes at most (YouTube decides, on the file: a REEL is uploaded as any video is).

Reading takes a key. Uploading and deleting take the channel's consent (OAuth: authorizationUrl(), exchange(), then the refresh token as an option). An upload is "private" unless the "privacy" option - or the post's own "privacy" option - says otherwise: the videos of an API project that has not passed Google's audit are locked private anyway, and the channel's owner makes them public in YouTube Studio.

const AUTHORIZE_URL = 'https://accounts.google.com/o/oauth2/v2/auth'

const SCOPES = ['https://www.googleapis.com/auth/youtube.upload', 'https://www.googleapis.com/auth/youtube.readonly']

Uploading, and reading the channel as its owner.

const SHORT_MAX_DURATION = 180.0

What YouTube takes for a Short, in seconds.

YouTubeProvider::__construct()

public function __construct(readonly Api $api, readonly ?string $channelId = null, readonly string $privacy = 'private', readonly ?string $categoryId = null, readonly Validator $validator = new Validator())

YouTubeProvider::getName()

public function getName(): string

YouTubeProvider::getPlatform()

public function getPlatform(): Platform

YouTubeProvider::capabilities()

public function capabilities(): Capabilities

A title is required; the caption is the description. No bound on the duration nor the ratio here, as they are the Short's alone, not the video's: validate() checks the Short's three minutes.

YouTubeProvider::validate()

public function validate(Post $post): array

The post against capabilities(), and against what they cannot say: the media is a video, and a REEL - a Short - lasts three minutes at most.

YouTubeProvider::publish()

public function publish(Post $post): Publication

The video uploaded in two calls (a resumable upload): its metadata, then its bytes - from Media::$path, or brought from Media::$url when there is no local file. A post scheduled goes up private, for YouTube to publish at that time (PENDING until then).

YouTubeProvider::status()

public function status(string $publicationId): Publication

YouTubeProvider::delete()

public function delete(string $publicationId): void

YouTubeProvider::account()

public function account(): Account

YouTubeProvider::feed()

public function feed(?string $cursor = null, int $limit = 25): Feed

The channel's uploads, newest first: the uploads playlist, then the videos themselves for what the playlist does not say (duration, views). A video of three minutes at most is given as a REEL - the API does not tell a Short, nor the ratio - any longer one as a VIDEO.

The item's url is the player's (to embed); its caption, the title.

YouTubeProvider::token()

public function token(): ?Token

The access token at hand - an hour's life - with the refresh token it was drawn from.

YouTubeProvider::refresh()

public function refresh(): Token

YouTubeProvider::authorizationUrl()

public function authorizationUrl(string $redirectUri, string $state, array $scopes = []): string

Offline access, consent asked again: that is what makes Google give a refresh token.

YouTubeProvider::exchange()

public function exchange(string $code, string $redirectUri): Token

The code for an access token and the refresh token to keep.

YouTubeProvider::seconds()

public static function seconds(string $duration): ?float

ISO 8601, as YouTube writes a duration: "PT1M30S" is 90.0.

YouTubeProviderFactory class

final class YouTubeProviderFactory extends ProviderFactory YouTubeProviderFactory.php:29

YouTube, through the Data API v3: the channel and its videos read with a key, videos and Shorts uploaded through OAuth.

options: api_key: '%env(default::YOUTUBE_API_KEY)%' # reading: the channel, its videos channel_id: '%env(default::YOUTUBE_CHANNEL_ID)%' # UC...; without it, the channel the OAuth token belongs to client_id: '%env(default::YOUTUBE_CLIENT_ID)%' # the Google OAuth client: uploading, deleting, connecting client_secret: '%env(default::YOUTUBE_CLIENT_SECRET)%' refresh_token: '%env(default::YOUTUBE_REFRESH_TOKEN)%' # what exchange() gave: access tokens are drawn from it access_token: ~ # or a token at hand (an hour's life) privacy: private # private, unlisted, public: what an upload is set to category_id: ~ # "10" is Music; YouTube's default otherwise base_uri: https://www.googleapis.com/youtube/v3 upload_uri: https://www.googleapis.com/upload/youtube/v3

Nothing is required to build the provider: capabilities() and authorizationUrl() need no credential. A call that needs one and finds none throws InvalidConfigException.

Options