Cloud PubSub Client - Class PubSubClient (1.50.0)

Version 1.50.0

• 2.2.0 (latest)
• 2.1.2
• 1.50.0
• 1.49.0
• 1.48.0
• 1.47.0
• 1.46.5
• 1.45.2
• 1.44.0
• 1.43.2
• 1.42.1
• 1.41.3
• 1.40.1
• 1.39.3

Reference documentation and code samples for the Cloud PubSub Client class PubSubClient.

Google Cloud Pub/Sub allows you to send and receive messages between independent applications. Find more information at the Google Cloud Pub/Sub docs.

To enable the Google Cloud Pub/Sub Emulator, set the PUBSUB_EMULATOR_HOST environment variable.

This client supports transport over REST or gRPC.

In order to enable gRPC support please make sure to install and enable the gRPC extension through PECL:

$ pecl install grpc

NOTE: Support for gRPC is currently at an Alpha quality level, meaning it is still a work in progress and is more likely to get backwards-incompatible updates.

When using gRPC in production environments, it is highly recommended that you make use of the Protobuf PHP extension for improved performance. Protobuf can be installed via PECL.

$ pecl install protobuf

Example:

use Google\Cloud\PubSub\PubSubClient;

$pubsub = new PubSubClient();

// Using the Pub/Sub Emulator
use Google\Cloud\PubSub\PubSubClient;

// Be sure to use the port specified when starting the emulator.
// `8900` is used as an example only.
putenv('PUBSUB_EMULATOR_HOST=localhost:8900');

$pubsub = new PubSubClient();

Namespace

Google \ Cloud \ PubSub

Methods

__construct

Create a PubSub client.

Parameters
Name	Description
config	array Configuration Options.
↳ apiEndpoint	string The hostname with optional port to use in place of the default service endpoint. Example: foobar.com or foobar.com:1234.
↳ projectId	string The project ID from the Google Developer's Console.
↳ authCache	CacheItemPoolInterface A cache for storing access tokens. Defaults to a simple in memory implementation.
↳ authCacheOptions	array Cache configuration options.
↳ authHttpHandler	callable A handler used to deliver Psr7 requests specifically for authentication.
↳ credentialsFetcher	FetchAuthTokenInterface A credentials fetcher instance.
↳ httpHandler	callable A handler used to deliver Psr7 requests. Only valid for requests sent over REST.
↳ keyFile	array The contents of the service account credentials .json file retrieved from the Google Developer's Console. Ex: json_decode(file_get_contents($path), true).
↳ keyFilePath	string The full path to your service account credentials .json file retrieved from the Google Developers Console.
↳ requestTimeout	float Seconds to wait before timing out the request. Defaults to 0 with REST and 60 with gRPC.
↳ retries	int Number of retries for a failed request. Defaults to 3.
↳ scopes	array Scopes to be used for the request.
↳ quotaProject	string Specifies a user project to bill for access charges associated with the request.
↳ transport	string The transport type used for requests. May be either grpc or rest. Defaults to grpc if gRPC support is detected on the system.

createTopic

See also:

• Create Topic

Parameters
Name	Description
name	string The topic name
options	array [optional] Configuration Options. For available configuration options, refer to Google\Cloud\PubSub\Topic::create() { @type bool $enableCompression Flag to enable compression of messages before publishing. Set the flag to true to enable compression. Defaults to false. Messsages are compressed if their total size >= compressionBytesThreshold, whose default value has been experimentally derived after performance evaluations. @type int $compressionBytesThreshold The threshold byte size above which messages are compressed. This only takes effect if enableCompression is set to true. Defaults to 240. (This value is experiementally derived after performance evaluations.) }.

Returns
Type	Description
Google\Cloud\PubSub\Topic

topic

Lazily instantiate a topic with a topic name.

No API requests are made by this method. If you want to create a new topic, use Google\Cloud\PubSub\Topic::createTopic().

Example:

// No API request yet!
$topic = $pubsub->topic('my-new-topic');

// This will execute an API call.
echo $topic->info()['name']; // `projects/my-awesome-project/topics/my-new-topic`

Parameters
Name	Description
name	string The topic name
options	array [optional] Configuration Options { @type bool $enableCompression Flag to enable compression of messages before publishing. Set the flag to true to enable compression. Defaults to false. Messsages are compressed if their total size >= compressionBytesThreshold, whose default value has been experimentally derived after performance evaluations. @type int $compressionBytesThreshold The threshold byte size above which messages are compressed. This only takes effect if enableCompression is set to true. Defaults to 240. (This value is experiementally derived after performance evaluations.) }

Returns
Type	Description
Google\Cloud\PubSub\Topic

topics

See also:

• List Topics

Parameters
Name	Description
options	array Configuration Options
↳ pageSize	int Maximum number of results to return per request.
↳ resultLimit	int Limit the number of results returned in total. Defaults to 0 (return all results).
↳ pageToken	string A previously-returned page token used to resume the loading of results from a specific point.

Returns
Type	Description
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\pubsub\topic>

subscribe

See also:

• Create Subscription

Parameters
Name	Description
name	string A subscription name
topic	Google\Cloud\PubSub\Topic|string The topic to which the new subscription will be subscribed.
options	array [optional] Please see Google\Cloud\PubSub\Subscription::create() for configuration details.

Returns
Type	Description
Google\Cloud\PubSub\Subscription

subscription

Lazily instantiate a subscription with a subscription name.

This method will NOT perform any API calls. If you wish to create a new subscription, use Google\Cloud\PubSub\PubSubClient::subscribe().

Unless you are sure the subscription exists, you should check its existence before using it.

Example:

$subscription = $pubsub->subscription('my-new-subscription');

Parameters
Name	Description
name	string The subscription name
topicName	string [optional] The topic name

Returns
Type	Description
Google\Cloud\PubSub\Subscription

subscriptions

See also:

• List Subscriptions

Parameters
Name	Description
options	array Configuration Options
↳ pageSize	int Maximum number of results to return per request.
↳ resultLimit	int Limit the number of results returned in total. Defaults to 0 (return all results).
↳ pageToken	string A previously-returned page token used to resume the loading of results from a specific point.

Returns
Type	Description
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\pubsub\subscription>

createSnapshot

Create a snapshot.

Please note that this method may not yet be available in your project.

Example:

$subscription = $pubsub->subscription($subscriptionName);
$snapshot = $pubsub->createSnapshot('my-snapshot', $subscription);

Parameters
Name	Description
name	string The snapshot name.
subscription	Google\Cloud\PubSub\Subscription The subscription to take a snapshot of.
options	array [optional] Configuration options.

Returns
Type	Description
Google\Cloud\PubSub\Snapshot

snapshot

Lazily create a snapshot instance.

Example:

$snapshot = $pubsub->snapshot('my-snapshot');

Parameters
Name	Description
name	string The snapshot name.
info	array [optional] Snapshot info.

Returns
Type	Description
Google\Cloud\PubSub\Snapshot

snapshots

Get a list of the snapshots in the project.

Please note that this method may not yet be available in your project.

Example:

$snapshots = $pubsub->snapshots();
foreach ($snapshots as $snapshot) {
     $info = $snapshot->info();
     echo $info['name'];
}

Parameters
Name	Description
options	array Configuration Options
↳ pageSize	int Maximum number of results to return per request.
↳ resultLimit	int Limit the number of results returned in total. Defaults to 0 (return all results).
↳ pageToken	string A previously-returned page token used to resume the loading of results from a specific point.

Returns
Type	Description
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\pubsub\snapshot>

schema

Lazily instantiate a schema object.

Example:

$schema = $pubsub->schema('my-schema');

Parameters
Name	Description
schemaId	string The schema ID. Must exist in the current project.
info	array [optional] The schema resource info.

Returns
Type	Description
Google\Cloud\PubSub\Schema

createSchema

See also:

• Create Schema

Parameters
Name	Description
schemaId	string The desired schema ID.
type	string The schema type. Allowed values are AVRO and PROTOCOL_BUFFER.
definition	string The definition of the schema. This should contain a string representing the full definition of the schema that is a valid schema definition of the type specified in type. See Schema for details.
options	array [optional] Configuration options

Returns
Type	Description
Google\Cloud\PubSub\Schema

schemas

See also:

• List Schemas

Parameters
Name	Description
options	array Configuration Options
↳ view	string The set of Schema fields to return in the response. If not set, returns Schemas with name and type, but not definition. Set to FULL to retrieve all fields. For allowed values, use constants defined on Google\Cloud\PubSub\V1\SchemaView.
↳ pageSize	int Maximum number of results to return per request.
↳ resultLimit	int Limit the number of results returned in total. Defaults to 0 (return all results).
↳ pageToken	string A previously-returned page token used to resume the loading of results from a specific point.

Returns
Type	Description
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\pubsub\schema>

validateSchema

See also:

• Validate Schema

Parameters
Name	Description
schema	array The schema to validate. See Schema for available parameters.
options	array [optional] Configuration options

Returns
Type	Description
void

validateMessage

See also:

• Validate Message

Parameters
Name	Description
schema	Google\Cloud\PubSub\Schema|string|array The schema to validate against. If a string is given, it should be a fully-qualified schema name, e.g. projects/my-project/schemas/my-schema. If an instance of Google\Cloud\PubSub\Schema is provided, it must exist in the current project. If an array is given, see Schema for definition. The array representation allows for validation of messages using ad-hoc schema; these do not have to exist in the current project in order to be used for validation.
message	string The base64 encoded message to validate.
encoding	string Either JSON or BINARY.
options	array [optional] Configuration options

Returns
Type	Description
void

consume

Consume an incoming message and return a PubSub Message.

This method is for use with push delivery only.

Example:

$httpPostRequestBody = file_get_contents('php://input');
$requestData = json_decode($httpPostRequestBody, true);

$message = $pubsub->consume($requestData);

Parameter
Name	Description
requestData	array

Returns
Type	Description
Google\Cloud\PubSub\Message

timestamp

Create a Timestamp object.

Example:

$timestamp = $pubsub->timestamp(new \DateTime('2003-02-05 11:15:02.421827Z'));

Parameters
Name	Description
timestamp	DateTimeInterface
nanoSeconds	int [optional] The number of nanoseconds in the timestamp.

Returns
Type	Description
Google\Cloud\Core\Timestamp

duration

Create a Duration object.

Example:

$duration = $pubsub->duration(100, 00001);

Parameters
Name	Description
seconds	int The number of seconds in the duration.
nanos	int [optional] The number of nanoseconds in the duration. Defaults to 0.

Returns
Type	Description
Google\Cloud\Core\Duration

__debugInfo

Constants

VERSION

Value: '1.50.0'

FULL_CONTROL_SCOPE

Value: 'https://www.googleapis.com/auth/pubsub'