prooph/documentation

Event Store Documentation

This documentation is available at http://docs.getprooph.org/. Pages are built with DocFX.

What follows is documentation for how to use and contribute to the Event Store documentation. If you’re planning to make updates or contributions then read on. Otherwise, head on over to the website.

Documentation Theme

If you would like to improve the theme for the documentation site, then you can find its repository here.

Running DocFX Locally

You can generate the site locally and test your changes. Follow the instructions here to install DocFX and dependencies, then run:

docfx build docfx.json --serve

This builds the site to the /_site folder and serves it at http://localhost:8080.

Running DocFX with Docker

Assuming you have a directory ~/code/prooph with 2 repositories there documentation and docs-template:

docker run -itv ~/code/prooph/:/tmp tsgkadot/docker-docfx:latest docfx build /tmp/documentation/docfx.json

Small Edits

1. Make changes (fix typos or grammar, improve wording etc).
2. Send a pull request!

New Pages and Sections

1. Create new pages and/or sections. Follow the Conventions below.
2. If you create a new section add an entry for it to the toc.md file. This file determines the order of sections in the navigation sidebar and helps DocFX build internal navigation.
3. Send a pull request!

Conventions

File Names

• File and directory names are all lowercase.
• Replace spaces with dashes.
• Markdown files take the .md extension.

Formatting and Typesetting

The content of our documentation has multiple authors. Formatting and style guidelines help maintain a consistent use of language throughout the docs.

• Acronyms and abbreviations: Use uppercase (e.g. API, HTTP, PHP)
• Brand names: Use correct typesetting (e.g. cURL, Event Store)
• Example code should not have a line length of more than 80 characters

documentation's Issues

Add link to the php client in the official doc of EventStore.org

Hello,

I guess this is on your todo list, but I'm opening an issue to keep track of it.
Feel free to close it, if you think this is overkill!

Here's the EventStore.org API page listing available community clients: https://eventstore.org/docs/getting-started/which-api-sdk/index.html

Read model blueprint

I've experienced a few issue while setting up a persistent subscription to update my readl model.
I will try to list them here in a concise way, let's discuss about it afterward.

• The UserEventAppeared example class in the read model section should implement EventAppearedOnPersistentSubscription.
• The documentation doesn't tell much about persistent subscription creation. That is especially troublesome because the suggested blueprint uses PersistentSubscriptionSettings::create() ->build(); which will NOT resolve links and set startFrom to -1.
  • Not resolving links will prevent to retrieve recorded event data (unless I have not understood something). I've also had to manually decode this data
  • Using startFrom: -1 will ignore all the previous events of the stream. As it is suggested to enable the $by_category projection juste before setting up the persistent subscription, no events will be handled by the mysql subscriber. That is quite tricky to understand IMO.

Here's my read model subscriber:

<?php
declare(strict_types=1);

namespace App\Contribution\Infrastructure\ReadModel;

use Amp\Promise;
use App\Contribution\Application\ReadModel\Contributions;
use Prooph\EventStore\Async\EventAppearedOnPersistentSubscription;
use Prooph\EventStore\Async\EventStorePersistentSubscription;
use Prooph\EventStore\ResolvedEvent;
use Doctrine\DBAL\Connection;
use Amp\Success;
use Prooph\EventStore\Util\Json;

final class PostgreSQLContributions implements Contributions, EventAppearedOnPersistentSubscription
{
    private const TABLE_NAME = 'contributions';

    private $connection;

    public function __construct(Connection $connection)
    {
        $this->connection = $connection;
    }

    public function __invoke(
        EventStorePersistentSubscription $subscription,
        ResolvedEvent $resolvedEvent,
        ?int $retryCount = null
    ): Promise {
        $event = $resolvedEvent->event();
        $data = Json::decode($event->data());

        switch ($event->eventType()) {
            case 'contribution-opened':
                $sql = 'INSERT INTO %s (id, title, url, state, created_at, updated_at) VALUES (:id, :title, :url, \'opened\', :created_at, :updated_at)';
                $this->connection->executeUpdate(sprintf($sql, self::TABLE_NAME), [
                    'id' => $data['id'],
                    'title' => $data['title'],
                    'url' => $data['url'],
                    'created_at' => $data['createdAt'],
                    'updated_at' => $data['updatedAt'],
                ]);
                break;

            case 'contribution-closed':
                $sql = 'UPDATE %s SET state = \'closed\', closed_at = :closed_at WHERE id = :id';
                $this->connection->executeUpdate(sprintf($sql, self::TABLE_NAME), [
                    'id' => $data['id'],
                    'closed_at' => $data['closedAt'],
                ]);
                break;

            case 'contribution-merged':
                $sql = 'UPDATE %s SET state = \'merged\' WHERE id = :id';
                $this->connection->executeUpdate(sprintf($sql, self::TABLE_NAME), [
                    'id' => $data['id'],
                ]);
                break;
        }

        return new Success();
    }

    public function all(): array
    {
    }
}

Missing `connectAsync` call in the AggregateRepository blueprint

I've also detected an issue with the AggregateRepository blueprint as it never calls connectAsync (nor close) on the eventStoreConnection property.

This results in the following error when calling getAggregateRoot:

[2019-12-05 12:55:27] app.DEBUG: EventStoreNodeConnection 'app': enqueing message StartOperationMessage [] []
[2019-12-05 12:55:27] app.DEBUG: EventStoreNodeConnection 'app': enqueing message CloseConnectionMessage [] []
[2019-12-05 12:55:27] app.DEBUG: EventStoreNodeConnection 'app': CloseConnection, reason Connection close requested by client, exception <none> [] []
[2019-12-05 12:55:27] app.DEBUG: EventStoreNodeConnection 'app': CloseTcpConnection IGNORED because connection === null [] []
[2019-12-05 12:55:27] app.INFO: EventStoreNodeConnection 'app': Closed. Reason: Connection close requested by client [] []

images are not generated

Somehow, images are not generated (I got a 404 on http://localhost:8080/event-store-v7/tutorial/why_event_sourcing/img/process_to_uml.png for instance)

References to unknown class/interface

There are also references to unknown EventStoreAsyncConnectionFactory and EventStoreSyncConnectionFactory classes on the /getting-started/step-1/index.html page.

I've found an EventStoreConnectionFactory class, but I'm not sur if it handles both sync and async connection.

I believe that namespaces have been reworked.
Prooph\EventStoreClient\EventStoreConnectionFactory allows creation of instances of Prooph\EventStore\Async\EventStoreConnection.

Interface Prooph\EventStore\EventStoreConnection also exists, although it does seem to have any concretion.