From 9e355ff0fbed9020a0a92c8a0e507bbc2bb03f10 Mon Sep 17 00:00:00 2001 From: John Pedrie Date: Fri, 30 Jun 2017 17:52:26 -0400 Subject: [PATCH] Bump pubsub to beta, mark batch as experimental (#558) --- README.md | 84 +++++++++++------------ src/Core/Batch/BatchConfig.php | 5 ++ src/Core/Batch/BatchDaemon.php | 5 ++ src/Core/Batch/BatchJob.php | 5 ++ src/Core/Batch/BatchRunner.php | 5 ++ src/Core/Batch/BatchTrait.php | 5 ++ src/Core/Batch/ConfigStorageInterface.php | 5 ++ src/Core/Batch/HandleFailureTrait.php | 5 ++ src/Core/Batch/InMemoryConfigStorage.php | 5 ++ src/Core/Batch/ProcessItemInterface.php | 5 ++ src/Core/Batch/Retry.php | 5 ++ src/Core/Batch/SysvConfigStorage.php | 5 ++ src/Core/Batch/SysvProcessor.php | 5 ++ src/Core/Batch/SysvTrait.php | 5 ++ src/Logging/LoggingClient.php | 7 +- src/Logging/PsrLogger.php | 3 +- src/PubSub/BatchPublisher.php | 5 ++ src/PubSub/Topic.php | 4 ++ src/Trace/Reporter/AsyncReporter.php | 5 ++ 19 files changed, 129 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 710fc7f51e23..e33c1ec0f9f8 100644 --- a/README.md +++ b/README.md @@ -16,10 +16,10 @@ This client supports the following Google Cloud Platform services at a [Beta](#v * [Google BigQuery](#google-bigquery-beta) (Beta) * [Google Cloud Natural Language](#google-cloud-natural-language-beta) (Beta) +* [Google Cloud Pub/Sub](#google-cloud-pubsub-beta) (Beta) * [Google Cloud Vision](#google-cloud-vision-beta) (Beta) This client supports the following Google Cloud Platform services at an [Alpha](#versioning) quality level: -* [Google Cloud Pub/Sub](#google-cloud-pubsub-alpha) (Alpha) * [Cloud Spanner](#cloud-spanner-alpha) (Alpha) * [Google Cloud Speech](#google-cloud-speech-alpha) (Alpha) * [Google Cloud Video Intelligence](#google-cloud-video-intelligence-alpha) (Alpha) @@ -305,47 +305,7 @@ Google Cloud Natural Language can be installed separately by requiring the `goog $ require google/cloud-language ``` -## Google Cloud Vision (Beta) - -- [API Documentation](http://googlecloudplatform.github.io/google-cloud-php/#/docs/latest/vision/visionclient) -- [Official Documentation](https://cloud.google.com/vision/docs) - -#### Preview - -```php -require 'vendor/autoload.php'; - -use Google\Cloud\Vision\VisionClient; - -$vision = new VisionClient([ - 'projectId' => 'my_project' -]); - -// Annotate an image, detecting faces. -$image = $vision->image( - fopen('/data/family_photo.jpg', 'r'), - ['faces'] -); - -$annotation = $vision->annotate($image); - -// Determine if the detected faces have headwear. -foreach ($annotation->faces() as $key => $face) { - if ($face->hasHeadwear()) { - echo "Face $key has headwear.\n"; - } -} -``` - -#### google/cloud-vision - -Google Cloud Vision can be installed separately by requiring the `google/cloud-vision` composer package: - -``` -$ require google/cloud-vision -``` - -## Google Cloud Pub/Sub (Alpha) +## Google Cloud Pub/Sub (Beta) - [API Documentation](http://googlecloudplatform.github.io/google-cloud-php/#/docs/latest/pubsub/pubsubclient) - [Official Documentation](https://cloud.google.com/pubsub/docs) @@ -392,6 +352,46 @@ Google Cloud Pub/Sub can be installed separately by requiring the `google/cloud- $ require google/cloud-pubsub ``` +## Google Cloud Vision (Beta) + +- [API Documentation](http://googlecloudplatform.github.io/google-cloud-php/#/docs/latest/vision/visionclient) +- [Official Documentation](https://cloud.google.com/vision/docs) + +#### Preview + +```php +require 'vendor/autoload.php'; + +use Google\Cloud\Vision\VisionClient; + +$vision = new VisionClient([ + 'projectId' => 'my_project' +]); + +// Annotate an image, detecting faces. +$image = $vision->image( + fopen('/data/family_photo.jpg', 'r'), + ['faces'] +); + +$annotation = $vision->annotate($image); + +// Determine if the detected faces have headwear. +foreach ($annotation->faces() as $key => $face) { + if ($face->hasHeadwear()) { + echo "Face $key has headwear.\n"; + } +} +``` + +#### google/cloud-vision + +Google Cloud Vision can be installed separately by requiring the `google/cloud-vision` composer package: + +``` +$ require google/cloud-vision +``` + ## Cloud Spanner (Alpha) - [API Documentation](http://googlecloudplatform.github.io/google-cloud-php/#/docs/latest/spanner/spannerclient) diff --git a/src/Core/Batch/BatchConfig.php b/src/Core/Batch/BatchConfig.php index 663d0219a94a..ca943810b535 100644 --- a/src/Core/Batch/BatchConfig.php +++ b/src/Core/Batch/BatchConfig.php @@ -19,6 +19,11 @@ /** * Hold configurations for the {@see \Google\Cloud\Core\Batch\BatchRunner}. + * + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ class BatchConfig { diff --git a/src/Core/Batch/BatchDaemon.php b/src/Core/Batch/BatchDaemon.php index 6c6d30944ea4..31833ad7917a 100644 --- a/src/Core/Batch/BatchDaemon.php +++ b/src/Core/Batch/BatchDaemon.php @@ -24,6 +24,11 @@ * * The system test is responsible for testing this class. * {@see \Google\Cloud\Tests\System\Core\Batch} + * + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ class BatchDaemon { diff --git a/src/Core/Batch/BatchJob.php b/src/Core/Batch/BatchJob.php index 60ad6dfc0179..0ff6d8a03009 100644 --- a/src/Core/Batch/BatchJob.php +++ b/src/Core/Batch/BatchJob.php @@ -19,6 +19,11 @@ /** * Represent batch jobs. + * + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ class BatchJob { diff --git a/src/Core/Batch/BatchRunner.php b/src/Core/Batch/BatchRunner.php index 33666ee87910..1254ee57e062 100644 --- a/src/Core/Batch/BatchRunner.php +++ b/src/Core/Batch/BatchRunner.php @@ -19,6 +19,11 @@ /** * A class for executing jobs in batch. + * + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ class BatchRunner { diff --git a/src/Core/Batch/BatchTrait.php b/src/Core/Batch/BatchTrait.php index 5df9806d6f91..a7f9edc47ba0 100644 --- a/src/Core/Batch/BatchTrait.php +++ b/src/Core/Batch/BatchTrait.php @@ -19,6 +19,11 @@ /** * A trait to assist in the registering and processing of batch jobs. + * + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ trait BatchTrait { diff --git a/src/Core/Batch/ConfigStorageInterface.php b/src/Core/Batch/ConfigStorageInterface.php index cff9bbbb6bd1..0b4b4b7b076b 100644 --- a/src/Core/Batch/ConfigStorageInterface.php +++ b/src/Core/Batch/ConfigStorageInterface.php @@ -19,6 +19,11 @@ /** * An interface for storing the configuration. + * + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ interface ConfigStorageInterface { diff --git a/src/Core/Batch/HandleFailureTrait.php b/src/Core/Batch/HandleFailureTrait.php index 1b161ee1e690..6e5efc634bbb 100644 --- a/src/Core/Batch/HandleFailureTrait.php +++ b/src/Core/Batch/HandleFailureTrait.php @@ -19,6 +19,11 @@ /** * A utility trait for handling failed items. + * + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ trait HandleFailureTrait { diff --git a/src/Core/Batch/InMemoryConfigStorage.php b/src/Core/Batch/InMemoryConfigStorage.php index 95b249a0f783..14b46d7be532 100644 --- a/src/Core/Batch/InMemoryConfigStorage.php +++ b/src/Core/Batch/InMemoryConfigStorage.php @@ -19,6 +19,11 @@ /** * In-memory ConfigStorageInterface implementation. + * + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ final class InMemoryConfigStorage implements ConfigStorageInterface, diff --git a/src/Core/Batch/ProcessItemInterface.php b/src/Core/Batch/ProcessItemInterface.php index 76d6919e63bd..d2568342b89d 100644 --- a/src/Core/Batch/ProcessItemInterface.php +++ b/src/Core/Batch/ProcessItemInterface.php @@ -19,6 +19,11 @@ /** * An interface for processing the items. + * + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ interface ProcessItemInterface { diff --git a/src/Core/Batch/Retry.php b/src/Core/Batch/Retry.php index 0d6e267065f3..15edf6050506 100644 --- a/src/Core/Batch/Retry.php +++ b/src/Core/Batch/Retry.php @@ -19,6 +19,11 @@ /** * A class for retrying the failed items. + * + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ class Retry { diff --git a/src/Core/Batch/SysvConfigStorage.php b/src/Core/Batch/SysvConfigStorage.php index 2cfc72b4c68a..92c8e4e5565e 100644 --- a/src/Core/Batch/SysvConfigStorage.php +++ b/src/Core/Batch/SysvConfigStorage.php @@ -19,6 +19,11 @@ /** * ConfigStorageInterface implementation with SystemV IPC shared memory. + * + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ class SysvConfigStorage implements ConfigStorageInterface { diff --git a/src/Core/Batch/SysvProcessor.php b/src/Core/Batch/SysvProcessor.php index 03886f89a85a..e0a3fdcce2c0 100644 --- a/src/Core/Batch/SysvProcessor.php +++ b/src/Core/Batch/SysvProcessor.php @@ -19,6 +19,11 @@ /** * ProcessItemInterface implementation with SysV IPC message queue. + * + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ class SysvProcessor implements ProcessItemInterface { diff --git a/src/Core/Batch/SysvTrait.php b/src/Core/Batch/SysvTrait.php index 943065223cf7..c3e92f018c10 100644 --- a/src/Core/Batch/SysvTrait.php +++ b/src/Core/Batch/SysvTrait.php @@ -19,6 +19,11 @@ /** * A utility trait related to System V IPC. + * + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ trait SysvTrait { diff --git a/src/Logging/LoggingClient.php b/src/Logging/LoggingClient.php index 0baf663c6fd8..88dc737a3e90 100644 --- a/src/Logging/LoggingClient.php +++ b/src/Logging/LoggingClient.php @@ -123,6 +123,10 @@ class LoggingClient * BatchRunner. * } * @return PsrLogger + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. **/ public static function psrBatchLogger($name, array $options = []) { @@ -506,7 +510,8 @@ function (array $entry) { * **Defaults to** ['batchSize' => 1000, * 'callPeriod' => 2.0, * 'workerNum' => 2]. Applies only when - * `batchEnabled` is set to `true`. + * `batchEnabled` is set to `true`. Note that this option is + * currently considered **experimental** and is subject to change. * @type array $clientConfig Configuration options for the Logging client * used to handle processing of batch items. For valid options * please see diff --git a/src/Logging/PsrLogger.php b/src/Logging/PsrLogger.php index 3de8ff0b589b..60ef15bb287a 100644 --- a/src/Logging/PsrLogger.php +++ b/src/Logging/PsrLogger.php @@ -92,7 +92,8 @@ class PsrLogger implements LoggerInterface, \Serializable * automatically chosen provider, based on detected environment * settings. * @type bool $batchEnabled Determines whether or not to use background - * batching. **Defaults to** `false`. + * batching. **Defaults to** `false`. Note that this option is + * currently considered **experimental** and is subject to change. * @type bool $debugOutput Whether or not to output debug information. * **Defaults to** false. Applies only when `batchEnabled` is set * to `true`. diff --git a/src/PubSub/BatchPublisher.php b/src/PubSub/BatchPublisher.php index 2b3657c56b3d..e6359aaae992 100644 --- a/src/PubSub/BatchPublisher.php +++ b/src/PubSub/BatchPublisher.php @@ -35,6 +35,11 @@ * 'data' => 'An important message.' * ]); * ``` + * + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ class BatchPublisher { diff --git a/src/PubSub/Topic.php b/src/PubSub/Topic.php index 29612a1ec156..c39e2b140d98 100644 --- a/src/PubSub/Topic.php +++ b/src/PubSub/Topic.php @@ -383,6 +383,10 @@ public function publishBatch(array $messages, array $options = []) * Example: `pubsub-topic-mytopic`. * } * @return BatchPublisher + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ public function batchPublisher(array $options = []) { diff --git a/src/Trace/Reporter/AsyncReporter.php b/src/Trace/Reporter/AsyncReporter.php index 018065b05446..d2c47bbd4f53 100644 --- a/src/Trace/Reporter/AsyncReporter.php +++ b/src/Trace/Reporter/AsyncReporter.php @@ -25,6 +25,11 @@ /** * This implementation of the ReporterInterface use the BatchRunner to provide * asynchronous reporting of Traces and their TraceSpans. + * + * @experimental The experimental flag means that while we believe this method + * or class is ready for use, it may change before release in backwards- + * incompatible ways. Please use with caution, and test thoroughly when + * upgrading. */ class AsyncReporter implements ReporterInterface {