YouTubePHP Documentation

Http
in package
implements HttpInterface

FinalYes

Non-blocking transport for the YouTube Data API.

Calls queue behind a concurrency ceiling. Each attempt is charged to the Meter when one is set, and a call today's quota cannot pay for is refused before it is sent. Errors come back as the exception Google's reason code means (HttpException::fromResponse()).

Retries:

  • Rate limits are waited out, for Retry-After when YouTube says and with a doubling back-off when it does not. They mean the request was not processed, so every verb is retried.
  • Server errors and dropped connections back off and retry too, but only for verbs that can be repeated safely. A POST that failed halfway may have posted a chat message already, and a second copy is worse than an error, so a POST is retried only on a 503.
  • Quota is not retried: nothing comes back until midnight Pacific.
Tags
link
https://developers.google.com/youtube/v3/docs/errors
since
1.0.0
author

Valithor Obsidion valithor@valgorithms.com

Table of Contents

Interfaces

HttpInterface
The transport {@see \YouTube\YouTube} sends every API call through.

Constants

BASE_URL  : mixed = 'https://youtube.googleapis.com/'
The API root.
CONCURRENT_REQUESTS  : mixed = 8
In-flight request ceiling.
MAX_ATTEMPTS  : mixed = 4
Give up after this many attempts at one request.
IDEMPOTENT  : mixed = ['GET', 'HEAD', 'PUT', 'DELETE']
Verbs a retry cannot turn into a duplicate.

Properties

$apiKey  : ?string
$backoff  : float
$baseUrl  : string
$driver  : ?DriverInterface
$inFlight  : int
$logger  : LoggerInterface
$loop  : LoopInterface
$meter  : ?Meter
$queue  : SplQueue<string|int, PendingRequest>
$token  : ?string

Methods

__construct()  : mixed
create()  : self
A transport with the default ReactPHP driver on the shared event loop.
getMeter()  : ?Meter
request()  : PromiseInterface<string|int, mixed>
Sends one API call.
setApiKey()  : void
An API key, sent when there is no access token. It reads public data only: anything about the signed-in account needs OAuth.
setDriver()  : void
setMeter()  : void
setToken()  : void
The OAuth access token to send, or null to send none.
stream()  : PromiseInterface<string|int, ResponseInterface>
Opens a server-streamed call: a GET whose response keeps arriving for as long as the server has more to send. Not retried.
url()  : string
The absolute URL for a path and its query. A list repeats its key, the way Google reads repeated parameters; null values are left out.
authorize()  : Request
Adds the credentials, fresh for each attempt: a retry may follow a refresh.
buffer()  : PromiseInterface<string|int, string>
The whole body of a response, streamed or not.
handleResponse()  : void
handleTransportError()  : void
mapError()  : HttpException
The exception an error response stands for. A streamed method wraps its error in a one-element list, which is unwrapped first.
prepare()  : Request
pump()  : void
Dispatches queued requests up to the concurrency ceiling.
retry()  : void
retryDelay()  : ?float
Seconds to wait before trying a failed request again, or null to give up.
scalar()  : string
send()  : void

Constants

BASE_URL

The API root.

public mixed BASE_URL = 'https://youtube.googleapis.com/'

CONCURRENT_REQUESTS

In-flight request ceiling.

public mixed CONCURRENT_REQUESTS = 8

MAX_ATTEMPTS

Give up after this many attempts at one request.

public mixed MAX_ATTEMPTS = 4

IDEMPOTENT

Verbs a retry cannot turn into a duplicate.

private mixed IDEMPOTENT = ['GET', 'HEAD', 'PUT', 'DELETE']

Properties

$apiKey

private ?string $apiKey = null

$backoff read-only

private float $backoff = 1.0

$baseUrl read-only

private string $baseUrl = self::BASE_URL

$inFlight

private int $inFlight = 0

$logger

private LoggerInterface $logger

$loop read-only

private LoopInterface $loop

$queue

private SplQueue<string|int, PendingRequest> $queue

$token

private ?string $token = null

Methods

__construct()

public __construct(LoopInterface $loop[, ?LoggerInterface $logger = null ][, ?DriverInterface $driver = null ][, string $baseUrl = self::BASE_URL ][, float $backoff = 1.0 ]) : mixed
Parameters
$loop : LoopInterface
$logger : ?LoggerInterface = null
$driver : ?DriverInterface = null
$baseUrl : string = self::BASE_URL
$backoff : float = 1.0

Multiplies every wait before a retry. 0 retries at once, for tests.

create()

A transport with the default ReactPHP driver on the shared event loop.

public static create([?LoggerInterface $logger = null ][, ?LoopInterface $loop = null ][, array<string, mixed> $socketOptions = [] ][, string $baseUrl = self::BASE_URL ]) : self
Parameters
$logger : ?LoggerInterface = null
$loop : ?LoopInterface = null
$socketOptions : array<string, mixed> = []

Forwarded to the socket connector.

$baseUrl : string = self::BASE_URL
Return values
self

request()

Sends one API call.

public request(string $endpoint, string $method, string $path[, array<string|int, mixed> $query = [] ][, array<string|int, mixed>|JsonSerializable|null $body = null ][, ?Media $media = null ][, ?string $uploadPath = null ][, bool $download = false ]) : PromiseInterface<string|int, mixed>
Parameters
$endpoint : string

The API method, e.g. liveChatMessages.list, for quota and logs.

$method : string

The HTTP verb.

$path : string

Relative to the API root, e.g. youtube/v3/liveChat/messages.

$query : array<string|int, mixed> = []

Null values are left out; a list repeats its key.

$body : array<string|int, mixed>|JsonSerializable|null = null

Sent as JSON.

$media : ?Media = null

A file to upload, sent to $uploadPath.

$uploadPath : ?string = null

Where uploads for this method go, e.g. /upload/youtube/v3/videos.

$download : bool = false

Resolve with the response body as it is: a caption file, say.

Return values
PromiseInterface<string|int, mixed> —

The decoded JSON, null for an empty response, or the body when downloading.

setApiKey()

An API key, sent when there is no access token. It reads public data only: anything about the signed-in account needs OAuth.

public setApiKey(?string $apiKey) : void
Parameters
$apiKey : ?string

setMeter()

public setMeter(?Meter $meter) : void
Parameters
$meter : ?Meter

setToken()

The OAuth access token to send, or null to send none.

public setToken(?string $token) : void
Parameters
$token : ?string

stream()

Opens a server-streamed call: a GET whose response keeps arriving for as long as the server has more to send. Not retried.

public stream(string $endpoint, string $path[, array<string|int, mixed> $query = [] ]) : PromiseInterface<string|int, ResponseInterface>
Parameters
$endpoint : string
$path : string
$query : array<string|int, mixed> = []
Return values
PromiseInterface<string|int, ResponseInterface> —

Resolves once the headers of a 200 arrive, with a body that is a React\Stream\ReadableStreamInterface. Rejects with the mapped exception for any other status.

url()

The absolute URL for a path and its query. A list repeats its key, the way Google reads repeated parameters; null values are left out.

public url(string $path[, array<string, mixed> $query = [] ]) : string
Parameters
$path : string
$query : array<string, mixed> = []
Return values
string

authorize()

Adds the credentials, fresh for each attempt: a retry may follow a refresh.

private authorize(Request $request) : Request
Parameters
$request : Request
Return values
Request

buffer()

The whole body of a response, streamed or not.

private static buffer(ResponseInterface $response) : PromiseInterface<string|int, string>
Parameters
$response : ResponseInterface
Return values
PromiseInterface<string|int, string>

handleResponse()

private handleResponse(PendingRequest $pending, ResponseInterface $response) : void
Parameters
$pending : PendingRequest
$response : ResponseInterface

handleTransportError()

private handleTransportError(PendingRequest $pending, Throwable $e) : void
Parameters
$pending : PendingRequest
$e : Throwable

mapError()

The exception an error response stands for. A streamed method wraps its error in a one-element list, which is unwrapped first.

private mapError(ResponseInterface $response, string $body, string $endpoint) : HttpException
Parameters
$response : ResponseInterface
$body : string
$endpoint : string
Return values
HttpException

prepare()

private prepare(string $endpoint, string $method, string $path, array<string, mixed> $query, array<string, mixed>|JsonSerializable|null $body, ?Media $media, ?string $uploadPath) : Request
Parameters
$endpoint : string
$method : string
$path : string
$query : array<string, mixed>
$body : array<string, mixed>|JsonSerializable|null
$media : ?Media
$uploadPath : ?string
Tags
throws
JsonException
Return values
Request

pump()

Dispatches queued requests up to the concurrency ceiling.

private pump() : void

retry()

private retry(PendingRequest $pending, float $delay) : void
Parameters
$pending : PendingRequest
$delay : float

retryDelay()

Seconds to wait before trying a failed request again, or null to give up.

private retryDelay(PendingRequest $pending, HttpException $e) : ?float
Parameters
$pending : PendingRequest
$e : HttpException
Return values
?float

scalar()

private static scalar(mixed $value) : string
Parameters
$value : mixed
Return values
string

send()

private send(PendingRequest $pending) : void
Parameters
$pending : PendingRequest
On this page

Search results