# Cloud PubSub Client - Class PubSubClient (2.19.3)

2.19.3 (latest) 2.19.2 2.18.0 2.17.0 2.16.2 2.15.1 2.14.0 2.13.2 2.12.0 2.11.3 2.10.1 2.9.1 2.8.2 2.7.0 2.6.0 2.5.2 2.4.0 2.3.0 2.2.1 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](https://cloud.google.com/pubsub/docs/).

To enable the [Google Cloud Pub/Sub Emulator](https://cloud.google.com/pubsub/emulator),
set the [`PUBSUB_EMULATOR_HOST`](https://cloud.google.com/pubsub/emulator#env)
environment variable.

This client supports transport over
[REST](https://cloud.google.com/pubsub/docs/reference/rest/) or
[gRPC](https://cloud.google.com/pubsub/docs/reference/rpc/).

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](https://pecl.php.net).

    $ pecl install protobuf

Example:

    use Google\Cloud\PubSub\PubSubClient;

    $pubsub = new PubSubClient(['projectId' => 'my-project']);

    // 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(['projectId' => 'my-project']);

## Namespace

Google \\ Cloud \\ PubSub

## Methods

### __construct

Create a PubSub client.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `config` | `array` Configuration Options. |
| `↳ projectId` | `string` The project ID from the Google Developer's Console. |
| `↳ apiEndpoint` | `string` The hostname with optional port to use in place of the default service endpoint. Example: `foobar.com` or `foobar.com:1234`. |
| `↳ credentials` | `FetchAuthTokenInterface|CredentialsWrapper` This option should only be used with a pre-constructed FetchAuthTokenInterface or CredentialsWrapper object. Note that when one of these objects are provided, any settings in $credentialsConfig will be ignored. **Important** : If you are providing a path to a credentials file, or a decoded credentials file as a PHP array, this usage is now DEPRECATED. Providing an unvalidated credential configuration to Google APIs can compromise the security of your systems and data. It is recommended to create the credentials explicitly `use Google\Auth\Credentials\ServiceAccountCredentials; use Google\Cloud\PubSub\PubSubClient; $creds = new ServiceAccountCredentials($scopes, $json); $options = new PubSubClient(['credentials' => $creds]);` <https://cloud.google.com/docs/authentication/external/externally-sourced-credentials> |
| `↳ credentialsConfig` | `array` Options used to configure credentials, including auth token caching, for the client. For a full list of supporting configuration options, see [Google\\ApiCore\\CredentialsWrapper::build()](https://docs.cloud.google.com/php/docs/reference/gax/latest/CredentialsWrapper.html#_Google_ApiCore_CredentialsWrapper__build__) . |
| `↳ transport` | `string|TransportInterface` The transport used for executing network requests. May be either the string `rest` or `grpc`. Defaults to `grpc` if gRPC support is detected on the system. *Advanced usage* : Additionally, it is possible to pass in an already instantiated [Google\\ApiCore\\Transport\\TransportInterface](https://docs.cloud.google.com/php/docs/reference/gax/latest/Transport.TransportInterface.html) object. Note that when this object is provided, any settings in $transportConfig, and any $apiEndpoint setting, will be ignored. |
| `↳ transportConfig` | `array` Configuration options that will be used to construct the transport. Options for each supported transport type should be passed in a key for that transport. For example: $transportConfig = \[ 'grpc' =\> \[...\], 'rest' =\> \[...\], \]; See the [Google\\ApiCore\\Transport\\GrpcTransport::build()](https://docs.cloud.google.com/php/docs/reference/gax/latest/Transport.GrpcTransport.html#_Google_ApiCore_Transport_GrpcTransport__build__) and [Google\\ApiCore\\Transport\\RestTransport::build()](https://docs.cloud.google.com/php/docs/reference/gax/latest/Transport.RestTransport.html#_Google_ApiCore_Transport_RestTransport__build__) methods for the supported options. |
| `↳ logger` | `false|LoggerInterface` A PSR-3 compliant logger. If set to false, logging is disabled, ignoring the 'GOOGLE_SDK_PHP_LOGGING' environment flag |

### createTopic

See also:

- [Create Topic](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/create)

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `name` | `string` The topic name |
| `options` | `array` \[optional\] Configuration Options. For available configuration options, refer to [Topic::create()](https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Topic#_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** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/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 [Topic::create()](https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Topic#_Google_Cloud_PubSub_Topic__create__).

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** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Topic` |   |

### topics

See also:

- [List Topics](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/list)

| **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** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-core/latest/Iterator.ItemIterator.html<https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Topic>` |   |

### subscribe

See also:

- [Create Subscription](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/create)

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `name` | `string` A subscription name |
| `topic` | `https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Topic|string` The topic to which the new subscription will be subscribed. |
| `options` | `array` \[optional\] Please see [Subscription::create()](https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Subscription#_Google_Cloud_PubSub_Subscription__create__) for configuration details. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/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 [PubSubClient::subscribe()](https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/PubSubClient#_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** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Subscription` |   |

### subscriptions

See also:

- [List Subscriptions](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/list)

| **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** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-core/latest/Iterator.ItemIterator.html<https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/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` | `https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Subscription` The subscription to take a snapshot of. |
| `options` | `array` \[optional\] Configuration options. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/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** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/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** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-core/latest/Iterator.ItemIterator.html<https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/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** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Schema` |   |

### createSchema

See also:

- [Create Schema](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas/create)

| **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](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas#Schema) for details. |
| `options` | `array` \[optional\] Configuration options |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Schema` |   |

### schemas

See also:

- [List Schemas](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas/list)

| **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 [V1\\SchemaView](https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/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** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-core/latest/Iterator.ItemIterator.html<https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Schema>` |   |

### validateSchema

See also:

- [Validate Schema](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas/validate)

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `schema` | `array` The schema to validate. See [Schema](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas#Schema) for available parameters. |
| `options` | `array` \[optional\] Configuration options |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `void` |   |

### validateMessage

See also:

- [Validate Message](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas/validateMessage)

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `schema` | `https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/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 [Schema](https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Schema) is provided, it must exist in the current project. If an array is given, see [Schema](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas#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** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/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** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-core/latest/Timestamp.html` |   |

### 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** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-core/latest/Duration.html` |   |

### __debugInfo

## Constants

### FULL_CONTROL_SCOPE

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