# Cloud PubSub Client - Class Topic (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 Topic.

A named resource to which messages are sent by publishers.

Example:

    use Google\Cloud\PubSub\PubSubClient;

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

    // You can also pass a fully-qualified topic name:
    $topic = $pubsub->topic('projects/my-awesome-project/topics/my-new-topic');

## Namespace

Google \\ Cloud \\ PubSub

## Methods

### __construct

Create a PubSub topic.

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `requestHandler` | `Google\Cloud\Core\RequestHandler` |
| `serializer` | `https://docs.cloud.google.com/php/docs/reference/gax/latest/Serializer.html` The serializer instance to encode/decode messages. |
| `projectId` | `string` The project Id |
| `name` | `string` The topic name |
| `encode` | `bool` Whether messages should be base64 encoded. |
| `info` | `array` A \[Topic\](<https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics> |
| `↳ name` | `string` The name of the topic. |
| `↳ labels` | `array` Key value pairs used to organize your resources. |
| `↳ kmsKeyName` | `string` The resource name of the Cloud KMS CryptoKey to be used to protect access to messages published on this topic. The expected format is `projects/my-project/locations/kr-location/keyRings/my-kr/cryptoKeys/my-key`. |
| `↳ enableCompression` | `bool` 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. |
| `↳ compressionBytesThreshold` | `int` 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.) |
| `clientConfig` | `array` \[optional\] Configuration options for the PubSub client used to handle processing of batch items through the daemon. For valid options please see [PubSubClient::__construct()](https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/PubSubClient#_Google_Cloud_PubSub_PubSubClient____construct__). *Defaults to*\* the options provided to the PubSub client associated with this instance. |

### name

Get the topic name

Example:

    echo $topic->name();

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `string` |   |

### create

See also:

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

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `options` | `array` Configuration Options |
| `↳ labels` | `array` Key value pairs used to organize your resources. |
| `↳ kmsKeyName` | `string` The resource name of the Cloud KMS CryptoKey to be used to protect access to messages published on this topic. The expected format is `projects/my-project/locations/kr-location/keyRings/my-kr/cryptoKeys/my-key`. |
| `↳ messageStoragePolicy` | `array` Policy constraining the set of Google Cloud Platform regions where messages published to the topic may be stored. If not present, then no constraints are in effect. | **Properties** || |---|---| | **Name** | **Description** | | `allowedPersistenceRegions` | `string[]` A list of IDs of GCP regions where messages that are published to the topic may be persisted in storage. Messages published by publishers running in non-allowed GCP regions (or running outside of GCP altogether) will be routed for storage in one of the allowed regions. An empty list means that no regions are allowed, and is not a valid configuration. | |
| `↳ schemaSettings.schema` | `string|https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Schema` The name of a schema that messages published should be validated against, or an instance of [Schema](https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Schema). |
| `↳ schemaSettings.encoding` | `string` The encoding of messages validated against schema. For allowed values, see constants defined on V1\\Encoding}. \</xref |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `array` | Topic information |

### update

See also:

- [Update Topic](https://cloud.google.com/pubsub/docs/reference/rest/v1/UpdateTopicRequest)

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `data` | `array` The Topic data. |
| `↳ labels` | `array` Key value pairs used to organize your resources. |
| `↳ messageStoragePolicy` | `array` Policy constraining the set of Google Cloud Platform regions where messages published to the topic may be stored. If not present, then no constraints are in effect. | **Properties** || |---|---| | **Name** | **Description** | | `allowedPersistenceRegions` | `string[]` A list of IDs of GCP regions where messages that are published to the topic may be persisted in storage. Messages published by publishers running in non-allowed GCP regions (or running outside of GCP altogether) will be routed for storage in one of the allowed regions. An empty list means that no regions are allowed, and is not a valid configuration. | |
| `↳ schemaSettings.schema` | `string|https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Schema` The name of a schema that messages published should be validated against, or an instance of [Schema](https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Schema). |
| `↳ schemaSettings.encoding` | `string` The encoding of messages validated against schema. For allowed values, see constants defined on V1\\Encoding}. \</xref |
| `options` | `array` Configuration options. |
| `↳ updateMask` | `array` A list of field paths to be modified. Nested key names should be dot-separated, e.g. `messageStoragePolicy.allowedPersistenceRegions`. Google Cloud PHP will attempt to infer this value on your behalf, however modification of map fields with arbitrary keys (such as labels or message storage policy) requires an explicit update mask. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `array` | The topic info. |

### delete

See also:

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

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `options` | `array` \[optional\] Configuration Options |

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

### exists

Check if a topic exists.

Service errors will NOT bubble up from this method. It will always return
a boolean value. If you want to check for errors, use
[Topic::info()](https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Topic#_Google_Cloud_PubSub_Topic__info__).

Example:

    if ($topic->exists()) {
        echo 'Topic exists';
    }

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `options` | `array` \[optional\] Configuration Options |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `bool` |   |

### info

See also:

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

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `options` | `array` \[optional\] Configuration Options |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `array` | \[A representation of a Topic\](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics) |

### reload

See also:

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

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `options` | `array` \[optional\] Configuration Options |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `array` | \[A representation of a Topic\](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics) |

### publish

See also:

- [Publish Message](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/publish)

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `message` | `https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Message|array` An instance of [Message](https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Message), or an array in the correct [Message Format](https://cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage). |
| `options` | `array` \[optional\] Configuration Options |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `array` | A list of message IDs |

### publishBatch

See also:

- [Publish Message](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/publish)

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `messages` | `array<https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Message>|array[]` A list of messages. Each message must be in the correct [Message Format](https://cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage), or be an instance of [Message](https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/Message). |
| `options` | `array` \[optional\] Configuration Options |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `array` | A list of message IDs. |

### batchPublisher

Push a message into a batch queue, to be processed at a later point.

Example:

    $topic->batchPublisher()
        ->publish([
            'data' => 'New User Registered',
            'attributes' => [
                'id' => '2',
                'userName' => 'Dave',
                'location' => 'Detroit'
            ]
        ]);

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `options` | `array` Configuration options. |
| `↳ debugOutput` | `bool` Whether or not to output debug information. Please note debug output currently only applies in CLI based applications. **Defaults to** `false`. |
| `↳ debugOutputResource` | `resource` A resource to output debug output to. **Defaults to** Resource for `php://stderr`. |
| `↳ batchOptions` | `array` A set of options for a BatchJob. [Google\\Cloud\\Core\\Batch\\BatchJob::__construct()](https://docs.cloud.google.com/php/docs/reference/cloud-core/latest/Batch.BatchJob.html#_Google_Cloud_Core_Batch_BatchJob____construct__) for more details. **Defaults to** \['batchSize' =\> 1000, 'callPeriod' =\> 2.0, 'numWorkers' =\> 2\]. |
| `↳ clientConfig` | `array` Configuration options for the PubSub client used to handle processing of batch items. For valid options please see [PubSubClient::__construct()](https://docs.cloud.google.com/php/docs/reference/cloud-pubsub/latest/PubSubClient#_Google_Cloud_PubSub_PubSubClient____construct__). **Defaults to** the options provided to the client associated with the current `Topic` instance. |
| `↳ batchRunner` | `BatchRunner` A BatchRunner object. Mainly used for the tests to inject a mock. **Defaults to** a newly created BatchRunner. |
| `↳ identifier` | `string` An identifier for the batch job. **Defaults to** `pubsub-topic-{topic-name}`. Example: `pubsub-topic-mytopic`. |
| `↳ closureSerializer` | `ClosureSerializerInterface` An implementation responsible for serializing closures used in the `$clientConfig`. This is especially important when using the batch daemon. **Defaults to** Google\\Cloud\\Core\\Batch\\OpisClosureSerializer if the `opis/closure` library is installed. |
| `↳ enableCompression` | `bool` 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. |
| `↳ compressionBytesThreshold` | `int` 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/BatchPublisher` |   |

### subscribe

See also:

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

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `name` | `string` The subscription name |
| `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

This method will not run any API requests. You will receive a
Subscription object that you can use to interact with the API.

Example:

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

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `name` | `string` The subscription name |

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

### subscriptions

See also:

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

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `options` | `array` Configuration Options |
| `↳ pageSize` | `int` Maximum number of subscriptions to return. |
| `↳ 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>` |   |

### iam

See also:

- [PubSub Access Control Documentation](https://cloud.google.com/pubsub/access_control)
- [Get Topic IAM Policy](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/getIamPolicy)
- [Set Topic IAM Policy](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/setIamPolicy)
- [Test Topic Permissions](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/testIamPermissions)

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `Google\Cloud\Core\Iam\IamManager` |   |

### __debugInfo

Present a nicer debug result to people using php 5.6 or greater.

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `array` |   |

## Constants

### DEFAULT_COMPRESSION_BYTES_THRESHOLD

    Value: 240

### DEFAULT_ENABLE_COMPRESSION

    Value: false