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();
$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');
Methods
__construct
Create a PubSub topic.
connection
Google\Cloud\PubSub\Connection\ConnectionInterface
A connection to the Google Cloud Platform service
projectId
string
The project Id
name
string
The topic name
encode
bool
Whether messages should be base64 encoded.
info
↳ 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
.
clientConfig
array
[optional] Configuration options for the PubSub client used to handle processing of batch items through the daemon. For valid options please see {@see}. Defaults tothe options provided to the PubSub client associated with this instance.
name
Get the topic name
Example:
echo $topic->name();
string
create
Create a topic.
Example:
$topicInfo = $topic->create();
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.
allowedPersistenceRegions
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|Schema
The name of a schema that messages published should be validated against, or an instance of {@see}.
↳ schemaSettings.encoding
string
The encoding of messages validated against schema. For allowed values, see constants defined on {@see}.
array
update
Update the topic.
Note that the topic's name and kms key name are immutable properties and may not be modified.
Example:
$topic->update([
'messageStoragePolicy' => [
'allowedPersistenceRegions' => ['us-central1']
]
]);
// Updating labels with an explicit update mask
$topic->update([
'labels' => [
'foo' => 'bar'
]
], [
'updateMask' => [
'labels'
]
]);
topic
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.
allowedPersistenceRegions
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|Schema
The name of a schema that messages published should be validated against, or an instance of {@see}.
↳ schemaSettings.encoding
string
The encoding of messages validated against schema. For allowed values, see constants defined on {@see}.
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.
array
delete
Delete a topic.
Example:
$topic->delete();
options
array
[optional] Configuration Options
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 {@see}.
Example:
if ($topic->exists()) {
echo 'Topic exists';
}
options
array
[optional] Configuration Options
bool
info
Get topic information.
Currently this resource returns only the topic name, if the topic exists. It is mostly useful therefore for checking if a topic exists.
Since this method will throw an exception if the topic is not found, you may find that Topic::exists() is a better fit for a true/false check.
This method will use the previously cached result, if available. To force a refresh from the API, use {@see}.
Example:
$info = $topic->info();
echo $info['name']; // projects/my-awesome-project/topics/my-new-topic
options
array
[optional] Configuration Options
array
reload
Get topic information from the API.
Currently this resource returns only the topic name, if the topic exists. It is mostly useful therefore for checking if a topic exists.
Since this method will throw an exception if the topic is not found, you may find that Topic::exists() is a better fit for a true/false check.
This method will retrieve a new result from the API. To use a previously cached result, if one exists, use {@see}.
Example:
$topic->reload();
$info = $topic->info();
echo $info['name']; // projects/my-awesome-project/topics/my-new-topic
options
array
[optional] Configuration Options
array
publish
Publish a new message to the topic.
$message must provide at least one of data
and attributes
members.
Example:
$topic->publish([
'data' => 'New User Registered',
'attributes' => [
'id' => '1',
'userName' => 'John',
'location' => 'Detroit'
]
]);
message
Google\Cloud\PubSub\Message
|array
An instance of {@see}, or an array in the correct Message Format .
options
array
[optional] Configuration Options
array
publishBatch
Publish multiple messages at once.
Note that if ordering keys are provided, all members of given messages set must provide the same ordering key. Multiple ordering keys in a single publish call is not supported.
Example:
$topic->publishBatch([
[
'data' => 'New User Registered',
'attributes' => [
'id' => '1',
'userName' => 'John',
'location' => 'Detroit'
]
], [
'data' => 'New User Registered',
'attributes' => [
'id' => '2',
'userName' => 'Steve',
'location' => 'Mountain View'
]
]
]);
messages
array< Google\Cloud\PubSub\Message
>|array[]
A list of messages. Each message must be in the correct Message Format , or be an instance of {@see}.
options
array
[optional] Configuration Options
array
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'
]
]);
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
.
↳ batchOptions
array
A set of options for a BatchJob. {@see} 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 {@see}. Defaults tothe 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 toa 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{@see} if the opis/closure
library is installed.
subscribe
Create a subscription to the topic.
Example:
$subscription = $topic->subscribe('my-new-subscription');
name
string
The subscription name
options
array
[optional] Please see {@see} for configuration details.
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');
name
string
The subscription name
subscriptions
Retrieve a list of active subscriptions to the current topic.
Example:
$subscriptions = $topic->subscriptions();
foreach ($subscriptions as $subscription) {
echo $subscription->name();
}
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.
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\pubsub\subscription>
iam
Manage the IAM policy for the current Topic.
Example:
$iam = $topic->iam();
Google\Cloud\Core\Iam\Iam
__debugInfo
Present a nicer debug result to people using php 5.6 or greater.
array
