Start updating the readme (#114)

* Start updating the readme

* Update readme with more details

* Remove older dapr versions from tests

Author: withinboredom

.github/workflows/php.yml

@@ -204,7 +204,7 @@ jobs:
     timeout-minutes: 5
     strategy:
       matrix:
-        dapr-version: [ 1.3.0-rc.4, 1.2.0, 1.2.1, 1.2.2 ]
+        dapr-version: [ 1.3.0, 1.2.1, 1.2.2 ]
     steps:
       - name: Download Caddy Image
         uses: actions/download-artifact@v2
@@ -248,8 +248,7 @@ jobs:
     strategy:
       matrix:
         dapr-version:
-          - 1.3.0-rc.4
-          - 1.2.0
+          - 1.3.0
           - 1.2.1
           - 1.2.2
         example:

readme.md

@@ -8,7 +8,62 @@ Add the library to your `composer.json`:
 
 > composer require dapr/php-sdk
 
-Some basic documentation is below, more documentation can be found [in the docs](https://docs.dapr.io/developing-applications/sdks/php/);
+Some basic documentation is below, more documentation can be
+found [in the docs](https://docs.dapr.io/developing-applications/sdks/php/);
+
+# Migrating to 1.2
+
+In preparation for gRPC support in this SDK, there's now a new DaprClient in `\Dapr\Client\DaprClient`. Please update
+your code to use the new client.
+
+There shouldn't be many changes to your code to upgrade to 1.2+ from a prior version. Namely, there are some
+deprecations:
+
+## Deprecations
+
+The following have been deprecated and will be removed in 1.4+.
+
+### \Dapr\SecretManager has been deprecated
+
+Simply use the new client instead.
+
+### \Dapr\Client has been deprecated
+
+Simply use the new client: `\Dapr\Client\DaprClient`.
+
+### \Dapr\PubSub\Publish has been deprecated
+
+Simply instantiate `\Dapr\PubSub\Topic` directly or use the new client directly.
+
+## Fallbacks and Upgrades
+
+### \Dapr\State\StateManager
+
+This class has been upgraded to use the new client. It shouldn't require any changes to your code, however, the old
+behavior can be utilized with `\Dapr\State\StateManagerOld`.
+
+### \Dapr\State\TransactionalState
+
+This class has been upgrade to use the new client. It shouldn't require any changes to your code, however, the old
+behavior can be utilized with `\Dapr\State\TransactionalStateOld`.
+
+# Creating a Dapr Client
+
+```php
+$client = \Dapr\Client\DaprClient::clientBuilder()->build();
+```
+
+## Using the Middleware
+
+The `App` object also implements a PSR-15 compatible middleware which implements the actor routes and subscribe routes
+for you.
+
+```php
+$app = \Dapr\App::create(configure: [
+    // custom configuration
+]);
+use_middleware($app);
+```
 
 # Accessing Secrets
 
@@ -17,19 +72,25 @@ You can access secrets easily:
 ```php
 <?php
 
-$app = Dapr\App::create();
-$app->get('/a-secret/{name}', function(string $name, \Dapr\SecretManager $secretManager) {
-    return $secretManager->retrieve(secret_store: 'my-secret-store', name: $name);
-});
-$app->get('/a-secret', function(\Dapr\SecretManager $secretManager) {
-    return $secretManager->all(secret_store: 'my-secret-store');
-});
-$app->start();
+// retrieve a single secret
+$client->getSecret(storeName: 'kubernetes', key: 'test');
+
+// retrieve all secrets
+$client->getBulkSecret(storeName: 'kubernetes');
 ```
 
 # Accessing State
 
-State is just Plain Old PHP Objects (POPO's) with an attribute:
+There are several ways to access state. You can access state directly via the client or abstract access via an object.
+
+## Accessing State Directly
+
+```php
+['value' => $value, 'etag' => $etag] = $client->getStateAndEtag(storeName: 'statestore', key: 'key', asType: SomeClass::class, consistency: \Dapr\consistency\EventualLastWrite::instance());
+$value = $client->getState(storeName: 'statestore', key: 'key', asType: 'string',consistency: \Dapr\consistency\StrongFirstWrite::instance())
+```
+
+## Abstract via Object
 
 ```php
 <?php
@@ -47,9 +108,9 @@ class MyState {
     public array $complex_type;
 
     /**
-      * @var Exception 
+      * @var SomeObject 
       */
-    public Exception $object_type;
+    public SomeObject $object_type;
 
     /**
      * @var int 
@@ -82,7 +143,19 @@ $app->start();
 ## Transactional State
 
 You can also use transactional state to interact with state objects by extending `TransactionalState` with our state
-objects.
+objects or commit transactions directly.
+
+### Directly with the client
+
+```php
+$transaction = [
+    \Dapr\Client\StateTransactionRequest::upsert(key: 'key', value: $client->serializer->as_json($new_value)),
+    \Dapr\Client\StateTransactionRequest::delete(key: 'key');
+];
+$client->executeStateTransaction(storeName: 'statestore', operations: $transaction);
+```
+
+### Abstracted via an Object
 
 ```php
 #[\Dapr\State\Attributes\StateStore('statestore', \Dapr\consistency\StrongFirstWrite::class)]
@@ -180,9 +253,21 @@ use Dapr\Actors\ActorProxy;
 $app->start();
 ```
 
+You can also call an actor without an interface:
+
+```php
+$client->invokeActorMethod(
+    httpMethod: 'GET', 
+    actor: new \Dapr\Actors\ActorReference(id: 'id', actor_type: 'Counter'), 
+    method: 'increment', 
+    parameter: 1
+ );
+```
+
 ## Actor Limitations
 
-1. There's no re-entrance to an actor, this can cause deadlocks if you're not careful.
+1. There's no re-entrance to an actor, by default. You'll need to enable it in the `ActorConfig`
+   and [in Dapr](https://docs.dapr.io/operations/support/support-preview-features/).
 2. By design, static functions don't work.
 3. There's overhead cost in calling "getter" functions.
 
@@ -195,18 +280,24 @@ implemented in this SDK.
 
 ## Publishing
 
-In order to publish an event, you just instantiate the `Publish` object with the `FactoryInterface`:
+In order to publish an event, you just instantiate the `Topic` object:
 
 ```php
 <?php
 $app = \Dapr\App::create();
-$app->get('/publish', function(\DI\FactoryInterface $factory) {
-    $publisher = $factory->make(\Dapr\PubSub\Publish::class, ['pubsub' => 'redis-pubsub']);
-    $publisher->topic('my-topic')->publish(['message' => 'arrive at dawn']);
+$app->get('/publish', function(\Dapr\Client\DaprClient $client) {
+    $topic = new \Dapr\PubSub\Topic(pubsub: 'pubsub', topic: 'topic', client: $client);
+    $topic->publish(['message' => 'arrive at dawn']);
 });
 $app->start();
 ```
 
+or you can use the new client like:
+
+```php
+$client->publishEvent(pubsubName: 'pubsub', topicName: 'topic', data: ['message' => 'arrive at dawn'], contentType: 'application/json');
+```
+
 ## Subscribing
 
 ```php
@@ -238,13 +329,18 @@ $app->get('/', function(\Dapr\Serialization\ISerializer $serializer) {
 $app->start();
 ```
 
-# Development
+## Using the new client
+
+```php
+$client = \Dapr\Client\DaprClient::clientBuilder()
+    ->withDeserializationConfig($configuration)
+    ->withSerializationConfig($configuration)
+    ->build()
+```
 
-Simply run `composer start` on a machine where `dapr init` has already been run. This will start the daprd service on
-the current open terminal. Then navigate to [http://localhost:9502/do_tests](http://localhost:9502/do_tests) to let the
-integration tests run.
+# Development
 
-# Tests
+## Tests
 
 Simply run `composer test` to run the unit tests. You can lint using `composer lint`.
 
@@ -255,15 +351,11 @@ You need [`docker-compose`](https://docs.docker.com/compose/gettingstarted/) and
 Build and start the environment, then run the integration tests and clean up.
 
 ```bash
-# clean up any existing environment
-docker-compose down -v
-# build and deploy the containers
-composer start
-# run and display the test rusults
-composer integration-tests | jq .
+make
 ```
 
 You should see output like:
+
 ```json
 {
   "/test/actors": {

src/lib/Client/StateTransactionRequest.php

@@ -10,4 +10,28 @@
  */
 abstract class StateTransactionRequest
 {
+    public static function upsert(
+        string $key,
+        array|string|null $value,
+        string $etag = '',
+        array $metadata = [],
+        Consistency|null $consistency = null
+    ): UpsertTransactionRequest {
+        return new UpsertTransactionRequest(
+            key:         $key,
+            value:       $value,
+            etag:        $etag,
+            metadata:    $metadata,
+            consistency: $consistency
+        );
+    }
+
+    public static function delete(
+        string $key,
+        string $etag = '',
+        array $metadata = [],
+        Consistency|null $consistency = null
+    ): DeleteTransactionRequest {
+        return new DeleteTransactionRequest(key: $key, etag: $etag, metadata: $metadata, consistency: $consistency);
+    }
 }

src/lib/consistency/Consistency.php

@@ -21,7 +21,9 @@ abstract class Consistency
      *
      * @return string
      */
-    public abstract function get_consistency(): string;
+    abstract public function get_consistency(): string;
 
-    public abstract function get_concurrency(): string;
+    abstract public function get_concurrency(): string;
+
+    abstract public static function instance(): Consistency;
 }

src/lib/consistency/EventualFirstWrite.php

@@ -10,6 +10,12 @@
  */
 class EventualFirstWrite extends Consistency
 {
+    public static function instance(): EventualFirstWrite
+    {
+        static $instance;
+        return $instance ??= new EventualFirstWrite();
+    }
+
     public function get_consistency(): string
     {
         return self::EVENTUAL;

src/lib/consistency/EventualLastWrite.php

@@ -9,6 +9,12 @@
  */
 class EventualLastWrite extends Consistency
 {
+    public static function instance(): EventualLastWrite
+    {
+        static $instance;
+        return $instance ??= new EventualLastWrite();
+    }
+
     public function get_consistency(): string
     {
         return self::EVENTUAL;

src/lib/consistency/StrongFirstWrite.php

@@ -9,6 +9,12 @@
  */
 class StrongFirstWrite extends Consistency
 {
+    public static function instance(): StrongFirstWrite
+    {
+        static $instance;
+        return $instance ??= new StrongFirstWrite();
+    }
+
     public function get_consistency(): string
     {
         return self::STRONG;

src/lib/consistency/StrongLastWrite.php

@@ -9,6 +9,12 @@
  */
 class StrongLastWrite extends Consistency
 {
+    public static function instance(): StrongLastWrite
+    {
+        static $instance;
+        return $instance ??= new StrongLastWrite();
+    }
+
     public function get_consistency(): string
     {
         return self::STRONG;