From 35c356839d96466f7648dc31aa4c66fb454d922b Mon Sep 17 00:00:00 2001
From: roxblnfk <roxblnfk@ya.ru>
Date: Mon, 22 Jan 2024 12:02:11 +0400
Subject: [PATCH] Add docs about factories; move buggregator/trap to `dev`
 section

---
 README.md     | 69 +++++++++++++++++++++++++++++++++++++++++++++++++--
 composer.json |  7 ++++--
 2 files changed, 72 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 8a491ff..298146e 100644
--- a/README.md
+++ b/README.md
@@ -30,9 +30,69 @@ composer require temporal-php/support
 
 ## Usage
 
-### Activity and Worker factories
+### Factories
 
+The package provides factories to create Activity and Worker stubs in a more convenient way.
+With these factories, there is less code because all nested options are moved to the parameters of one method.
 
+Use the `\Temporal\Support\Factory\ActivityStub` factory to create an Activity stub:
+
+```php
+use \Temporal\Support\Factory\ActivityStub;
+
+#[\Temporal\Workflow\WorkflowInterface]
+class HelloWorkflow {
+    #[\Temporal\Workflow\WorkflowMethod]
+    public function run(string $user) {
+        yield ActivityStub::activity(
+            class: UserService::class,
+            startToCloseTimeout: 60,
+            retryAttempts: 5,
+        )->getContactEmail($user)->then(
+            fn (string $email) => ActivityStub::activity(
+                class: HelloService::class,
+                startToCloseTimeout: '10 minutes',
+                retryAttempts: 5,
+            )->sendHelloEmail($user, $email),
+        );
+    }
+}
+```
+
+Use the `\Temporal\Support\Factory\WorkflowStub` factory to create a Workflow stub in a client scope:
+
+```php
+use \Temporal\Support\Factory\WorkflowStub;
+/**
+ * @var \Temporal\Client\WorkflowClient $client
+ */
+$stub = WorkflowStub::workflow($client, HelloWorkflow::class, executionTimeout: '1 day');
+$run = $client->start($stub, 'User');
+// ...
+```
+
+Or create a Child Workflow stub in a workflow scope:
+
+```php
+use \Temporal\Support\Factory\WorkflowStub;
+
+#[\Temporal\Workflow\WorkflowInterface]
+class RegisterWorkflow {
+    #[\Temporal\Workflow\WorkflowMethod]
+    public function run(string $user) {
+        yield \Temporal\Promise::all([
+            WorkflowStub::childWorkflow(GreetingWorkflow::class, executionTimeout: '1 hour'),
+            WorkflowStub::childWorkflow(SubscribeNewsWorkflow::class, executionTimeout: '10 minutes'),
+            WorkflowStub::childWorkflow(PrepareUserEnvironmentWorkflow::class, executionTimeout: '1 hour'),
+        ])->then(
+            // Suppress failures
+            onRejected: static fn () => null,
+        );
+
+        // ...
+    }
+}
+```
 
 ### Attributes
 
@@ -62,7 +122,12 @@ $stub = \Temporal\Support\Factory\WorkflowStub::workflow(
 ```
 
 > [!NOTE]
-> Attributes will work only if you use the Activity and Worker factories from this package.
+> Attributes will work only if you use the Activity and Worker factories from this package.  
+
+> [!WARNING]
+> Use attributes on the definitions that you use in factories.
+> So, if you separate interfaces and implementation, apply attributes to the interfaces.
+
 
 ### VirtualPromise interface
 
diff --git a/composer.json b/composer.json
index cb49941..0994237 100644
--- a/composer.json
+++ b/composer.json
@@ -38,10 +38,13 @@
     "prefer-stable": true,
     "require": {
         "php": ">=8.1",
-        "temporal/sdk": "^2.7",
-        "buggregator/trap": "^1.3"
+        "temporal/sdk": "^2.7"
+    },
+    "suggest": {
+        "buggregator/trap": "For better debugging and protobuf messages dumping"
     },
     "require-dev": {
+        "buggregator/trap": "^1.3",
         "dereuromark/composer-prefer-lowest": "^0.1.10",
         "phpunit/phpunit": "^10.4",
         "vimeo/psalm": "^5.18"