moved from othillo/broadway-sensitive-data (#1)

.gitignore

@@ -0,0 +1,2 @@
+/vendor/
+composer.lock

.travis.yml

@@ -0,0 +1,20 @@
+language: php
+
+matrix:
+  include:
+    - php: 5.6
+    - php: 7
+
+before_install:
+  - composer self-update
+
+install:
+  - composer install
+
+script:
+  - ./vendor/bin/phpunit --exclude-group=none
+
+branches:
+  only:
+    - master
+    - develop

LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2016 Broadway project
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1 +1,45 @@
-# broadway-sensitive-data
+broadway/sensitive-data
+=======================
+
+Helpers for handling sensitive data with Broadway.
+
+[![Build Status](https://travis-ci.org/broadway/broadway-sensitive-data.svg?branch=master)](https://travis-ci.org/broadway/broadway-sensitive-data)
+
+## Installation
+
+```
+$ composer require broadway/broadway-sensitive-data
+```
+
+## About
+In an Event Sourced environment you may have to deal with sensitive (e.g. personal) data
+ending up in your event stream. You could encrypt your event stream or remove sensitive data
+from your event stream after a certain amount or time (upcasting). Or you could choose not to
+store sensitive data in you event stream altogether. That's where this project helps out.
+
+Imagine the use case where a customer wants to pay an order with a credit card and you're not 
+allowed to store the credit card number.
+
+A `PayWithCreditCardCommand` (with credit card number) should lead to a
+`PaymentWithCreditCardRequestedEvent` (without the credit card number) but the `Processor` that
+handles the event does need to know the credit card number.
+
+This project introduces a `SensitiveDataManager` which can be injected into a `CommandHandler`
+to capture the sensitive data from the command and make it available to the `SensitiveDataProcessor`
+hereby bypassing the event store.
+
+Pros:
+* sensitive data is not stored in your event stream
+* no need for encryption or upcasting of your events
+
+Cons:
+* handling of sensitive data can only be done once per request
+
+## Example
+
+A detailed example with a test case can be found in the [`examples/`][examples] directory.
+
+[examples]: examples/
+
+## License
+This project is licensed under the MIT License - see the LICENSE file for details

composer.json

@@ -0,0 +1,33 @@
+{
+  "name": "broadway/sensitive-data",
+  "description": "helpers for handling sensitive data with Broadway",
+  "type": "library",
+  "license": "MIT",
+  "require": {
+    "broadway/broadway": "^0.10"
+  },
+  "require-dev": {
+    "phpunit/phpunit": "^5.2"
+  },
+  "authors": [
+    {
+      "name": "othillo",
+      "email": "othillo@othillo.nl"
+    }
+  ],
+  "autoload": {
+    "psr-4": {
+      "Broadway\\BroadwaySensitiveData\\EventHandling\\": "src/"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "Broadway\\BroadwaySensitiveData\\EventHandling\\": "test/"
+    }
+  },
+  "extra": {
+    "branch-alias": {
+      "dev-master": "0.2.x-dev"
+    }
+  }
+}

examples/HandlingSensitiveData.php

@@ -0,0 +1,138 @@
+<?php
+
+/*
+ * This file is part of the broadway/sensitive-data package.
+ *
+ * (c) 2016 Broadway project
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+/**
+ * Invitation aggregate root.
+ */
+class Invitation extends Broadway\EventSourcing\EventSourcedAggregateRoot
+{
+    private $invitationId;
+
+    /**
+     * Factory method to create an invitation.
+     */
+    public static function invite($invitationId, $name)
+    {
+        $invitation = new Invitation();
+
+        // After instantiation of the object we apply the "InvitedEvent".
+        $invitation->apply(new InvitedEvent($invitationId, $name));
+
+        return $invitation;
+    }
+
+    /**
+     * Every aggregate root will expose its id.
+     *
+     * {@inheritDoc}
+     */
+    public function getAggregateRootId()
+    {
+        return $this->invitationId;
+    }
+
+    /**
+     * The "apply" method of the "InvitedEvent"
+     */
+    protected function applyInvitedEvent(InvitedEvent $event)
+    {
+        $this->invitationId = $event->invitationId;
+    }
+}
+
+/**
+ * A repository that will only store and retrieve Invitation aggregate roots.
+ *
+ * This repository uses the base class provided by the EventSourcing component.
+ */
+class InvitationRepository extends Broadway\EventSourcing\EventSourcingRepository
+{
+    public function __construct(Broadway\EventStore\EventStoreInterface $eventStore, Broadway\EventHandling\EventBusInterface $eventBus)
+    {
+        parent::__construct($eventStore, $eventBus, 'Invitation', new Broadway\EventSourcing\AggregateFactory\PublicConstructorAggregateFactory());
+    }
+}
+
+/*
+ * When using CQRS with commands, a lot of times you will find that you have a
+ * command object and a "dual" event. Mind though that this is not always the
+ * case. The following classes show the commands and events for our small
+ * domain model.
+ */
+
+/* All commands and events below will cary the id of the aggregate root. For
+ * our convenience and readability later on we provide base classes that hold
+ * this data.
+ */
+
+class InviteCommand
+{
+    public $invitationId;
+    public $name;
+    public $password;
+
+    public function __construct($invitationId, $name, $password)
+    {
+        $this->invitationId = $invitationId;
+        $this->name         = $name;
+        $this->password     = $password;
+    }
+}
+
+class InvitedEvent
+{
+    public $invitationId;
+    public $name;
+
+    public function __construct($invitationId, $name)
+    {
+        $this->invitationId = $invitationId;
+        $this->name         = $name;
+    }
+}
+
+/*
+ * A command handler will be registered with the command bus and handle the
+ * commands that are dispatched. The command handler can be seen as a small
+ * layer between your application code and the actual domain code.
+ *
+ * In the end a command handler listens for commands and translates commands to
+ * method calls on the actual aggregate roots.
+ */
+class InvitationCommandHandler extends Broadway\CommandHandling\CommandHandler
+{
+    private $repository;
+    private $sensitiveDataManager;
+
+    public function __construct(
+        Broadway\EventSourcing\EventSourcingRepository $repository,
+        \Broadway\BroadwaySensitiveData\EventHandling\SensitiveDataManager $sensitiveDataManager
+    ) {
+        $this->repository           = $repository;
+        $this->sensitiveDataManager = $sensitiveDataManager;
+    }
+
+    /**
+     * A new invite aggregate root is created and added to the repository.
+     */
+    protected function handleInviteCommand(InviteCommand $command)
+    {
+        $invitation = Invitation::invite($command->invitationId, $command->name);
+
+        $this->sensitiveDataManager->setSensitiveData(
+            new \Broadway\BroadwaySensitiveData\EventHandling\SensitiveData(['password' => $command->password])
+        );
+
+        $this->repository->save($invitation);
+    }
+}

examples/HandlingSensitiveDataTest.php

@@ -0,0 +1,84 @@
+<?php
+
+/*
+ * This file is part of the broadway/sensitive-data package.
+ *
+ * (c) 2016 Broadway project
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Broadway\CommandHandling\SimpleCommandBus;
+use Broadway\Domain\DomainMessage;
+use Broadway\EventHandling\SimpleEventBus;
+use Broadway\EventHandling\TraceableEventBus;
+use Broadway\EventStore\InMemoryEventStore;
+use Broadway\BroadwaySensitiveData\EventHandling\SensitiveData;
+use Broadway\BroadwaySensitiveData\EventHandling\SensitiveDataManager;
+use Broadway\BroadwaySensitiveData\EventHandling\SensitiveDataProcessor;
+
+require_once __DIR__ . '/HandlingSensitiveData.php';
+
+/**
+ * This test demonstrates that
+ * - sensitive data is not stored in the event stream
+ * - sensitive data is available for one-off processing
+ */
+class HandlingSensitiveDataTest extends PHPUnit_Framework_TestCase
+{
+    private $commandBus;
+    private $eventBus;
+    private $sensitiveDataProcessor;
+
+    public function setUp()
+    {
+        $this->commandBus = new SimpleCommandBus();
+        $this->eventBus   = new TraceableEventBus(new SimpleEventBus());
+
+        $this->sensitiveDataProcessor = new MySensitiveDataProcessor();
+        $sensitiveDataManager         = new SensitiveDataManager([$this->sensitiveDataProcessor]);
+
+        $commandHandler = new InvitationCommandHandler(
+            new InvitationRepository(
+                new InMemoryEventStore(),
+                $this->eventBus
+            ),
+            $sensitiveDataManager
+        );
+
+        $this->commandBus->subscribe($commandHandler);
+        $this->eventBus->subscribe($sensitiveDataManager);
+    }
+
+    /**
+     * @test
+     */
+    public function it_handles_sensitive_data()
+    {
+        $this->eventBus->trace();
+
+        $this->commandBus->dispatch(new InviteCommand('1583c029-de76-40ec-8674-de26767617d2', 'asm89', 'p4ssw0rd'));
+
+        // the event should not contain sensitive data
+        $this->assertEquals([new InvitedEvent('1583c029-de76-40ec-8674-de26767617d2', 'asm89')], $this->eventBus->getEvents());
+
+        // the sensitive data should be available for the processor
+        $this->assertEquals([new SensitiveData(['password' => 'p4ssw0rd'])], $this->sensitiveDataProcessor->getRecordedSensitiveData());
+    }
+}
+
+class MySensitiveDataProcessor extends SensitiveDataProcessor
+{
+    private $recordedSensitiveData = [];
+
+    protected function applyInvitedEvent(InvitedEvent $event, DomainMessage $domainMessage, SensitiveData $data = null)
+    {
+        $this->recordedSensitiveData[] = $data;
+    }
+
+    public function getRecordedSensitiveData()
+    {
+        return $this->recordedSensitiveData;
+    }
+}

examples/README.md

@@ -0,0 +1,22 @@
+Handling sensitive data
+=======================
+
+A small example of an implementation of a small domain model. The example
+consists of three files. The first file `HandlingSensitiveData` contains the implementation of
+the domain model. The second file `HandlingSensitiveDataTest` contains a PHPUnit test suite
+demonstrating the handling of sensitive data.
+
+The files contain comments about what is happening.
+
+The PHPUnit tests can be run by changing to this directory and running:
+
+```bash
+$ phpunit .
+PHPUnit 5.6.2 by Sebastian Bergmann.
+
+.
+
+Time: 22 ms, Memory: 4.00Mb
+
+OK (1 tests, 2 assertions)
+```