Actors

    In the PHP SDK, there are two sides to an actor, the Client, and the Actor (aka, the Runtime). As a client of an actor, you’ll interact with a remote actor via the class. This class generates a proxy class on-the-fly using one of several configured strategies.

    When writing an actor, state can be managed for you. You can hook into the actor lifecycle, and define reminders and timers. This gives you considerable power for handling all types of problems that the actor pattern is suited for.

    Whenever you want to communicate with an actor, you’ll need to get a proxy object to do so. The proxy is responsible for serializing your request, deserializing the response, and returning it to you, all while obeying the contract defined by the specified interface.

    In order to create the proxy, you’ll first need an interface to define how and what you send and receive from an actor. For example, if you want to communicate with a counting actor that solely keeps track of counts, you might define the interface as follows:

    It’s a good idea to put this interface in a shared library that the actor and clients can both access (if both are written in PHP). The DaprType attribute tells the DaprClient the name of the actor to send to. It should match the implementation’s DaprType, though you can override the type if needed.

    1. <?php
    2. $app->run(function(\Dapr\Actors\ActorProxy $actorProxy) {
    3.     $actor = $actorProxy->get(ICount::class, 'actor-id');
    4.     $actor->increment(10);

    Here’s the counter actor:

    The most important bit is the constructor. It takes at least one argument with the name of id which is the id of the actor. Any additional arguments are injected by the DI container, including any you want to use.

    An actor is instantiated via the constructor on every request targeting that actor type. You can use it to calculate ephemeral state or handle any kind of request-specific startup you require, such as setting up other clients or connections.

    After the actor is instantiated, the on_activation() method may be called. The on_activation() method is called any time the actor “wakes up” or when it is created for the first time. It is not called on every request.

    Next, the actor method is called. This may be from a timer, reminder, or from a client. You may perform any work that needs to be done and/or throw an exception.

    Actor state is a “Plain Old PHP Object” (POPO) that extends ActorState. The ActorState base class provides a couple of useful methods. Here’s an example implementation:

    1. <?php
    2. class CountState extends \Dapr\Actors\ActorState {
    3.     public int $count = 0;
    4. }

    Dapr expects to know what actors a service may host at startup. You need to add it to the configuration:

    If you want to take advantage of pre-compiled dependency injection, you need to use a factory:

    All that is required to start the app:

    1. <?php
    4. $app = \Dapr\App::create(
    5.     configure: fn(\DI\ContainerBuilder $builder) => $builder->addDefinitions('config.php')->enableCompilation(__DIR__)
    6. );
    7. $app->start();

    All that is required to start the app:

    1. <?php
    3. require_once __DIR__ . '/vendor/autoload.php';
    5. $app = \Dapr\App::create(configure: fn(\DI\ContainerBuilder $builder) => $builder->addDefinitions('config.php'));