Init project

spiral-packages · Feb 13, 2022 · 48d1dc7 · 48d1dc7
1 parent 71d3137
commit 48d1dc7
Show file tree

Hide file tree

Showing 25 changed files with 586 additions and 321 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,6 @@
 # Changelog
 
-All notable changes to `:package_name` will be documented in this file.
+All notable changes to `Cqrs` will be documented in this file.
 
 ## 1.0.0 - 202X-XX-XX
 

diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) :vendor_name <author@domain.com>
+Copyright (c) spiral-packages <butschster@gmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -1,19 +1,14 @@
-# :package_description
+# (CQRS) Command/Query bus implementation for Spiral Framework
 
-[![PHP](https://img.shields.io/packagist/php-v/:vendor_slug/:package_slug.svg?style=flat-square)](https://packagist.org/packages/:vendor_slug/:package_slug)
-[![Latest Version on Packagist](https://img.shields.io/packagist/v/:vendor_slug/:package_slug.svg?style=flat-square)](https://packagist.org/packages/:vendor_slug/:package_slug)
-[![GitHub Tests Action Status](https://img.shields.io/github/workflow/status/:vendor_slug/:package_slug/run-tests?label=tests&style=flat-square)](https://github.com/:vendor_slug/:package_slug/actions?query=workflow%3Arun-tests+branch%3Amain)
-[![Total Downloads](https://img.shields.io/packagist/dt/:vendor_slug/:package_slug.svg?style=flat-square)](https://packagist.org/packages/:vendor_slug/:package_slug)
-<!--delete-->
----
-This repo can be used to scaffold a Spiral Framework package. Follow these steps to get started:
+[![PHP](https://img.shields.io/packagist/php-v/spiral-packages/cqrs.svg?style=flat-square)](https://packagist.org/packages/spiral-packages/cqrs)
+[![Latest Version on Packagist](https://img.shields.io/packagist/v/spiral-packages/cqrs.svg?style=flat-square)](https://packagist.org/packages/spiral-packages/cqrs)
+[![GitHub Tests Action Status](https://img.shields.io/github/workflow/status/spiral-packages/cqrs/run-tests?label=tests&style=flat-square)](https://github.com/spiral-packages/cqrs/actions?query=workflow%3Arun-tests+branch%3Amain)
+[![Total Downloads](https://img.shields.io/packagist/dt/spiral-packages/cqrs.svg?style=flat-square)](https://packagist.org/packages/spiral-packages/cqrs)
 
-1. Press the "Use template" button at the top of this repo to create a new repo with the contents of this skeleton.
-2. Run `php ./configure.php` to run a script that will replace all placeholders throughout all the files.
----
-<!--/delete-->
-This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
+It's a lightweight messaging facade. It allows you to define the API of your model with the help of messages.
 
+- Command messages describe actions your model can handle.
+- Query messages describe available information that can be fetched from your (read) model.
 
 ## Requirements
 
@@ -22,28 +17,178 @@ Make sure that your server is configured with following PHP version and extensio
 - PHP 8.0+
 - Spiral framework 2.9+
 
-
-
 ## Installation
 
 You can install the package via composer:
 
 ```bash
-composer require :vendor_slug/:package_slug
+composer require spiral-packages/cqrs
 ```
 
 After package install you need to register bootloader from the package.
 
 ```php
 protected const LOAD = [
     // ...
-    \VendorName\Skeleton\Bootloader\SkeletonBootloader::class,
+    \Spiral\Cqrs\Bootloader\CqrsBootloader::class,
 ];
 ```
 
-> Note: if you are using [`spiral-packages/discoverer`](https://github.com/spiral-packages/discoverer), 
+> Note: if you are using [`spiral-packages/discoverer`](https://github.com/spiral-packages/discoverer),
 > you don't need to register bootloader by yourself.
 
+## Usage
+
+You can also register command and query handlers via attributes
+
+### Commands
+
+#### Command definition
+
+```php
+class StoreUser implements \Spiral\Cqrs\CommandInterface
+{
+    public function __construct(
+        public Uuid $uuid,
+        public string $username,
+        public string $password,
+        public \DateTimeImmutable $registeredAt,
+    ) {
+    }
+}
+```
+
+#### Command handler definition
+
+To register command handler you just need to add attribute on method that should be invoked.
+
+```php
+class StoreUserHandler
+{
+    public function __construct(
+        private EntityManagerInterface $entityManager
+    ) {
+
+    }
+
+    #[\Spiral\Cqrs\Attribute\CommandHandler]
+    public function __invoke(StoreUser $command)
+    {
+        $this->entityManager->persist(
+            new User(
+                $command->uuid,
+                $command->username,
+                $command->password,
+                $command->registeredAt
+            )
+        );
+
+        $this->entityManager->run();
+    }
+}
+```
+
+#### Dispatch command
+
+```php
+use Ramsey\Uuid\Uuid;
+
+class UserController 
+{
+    public function store(UserStoreRequest $request, \Spiral\Cqrs\CommandBusInterface $bus)
+    {
+        $bus->dispatch(new StoreUser(
+           $uuid = Uuid::uuid4(), 
+           $request->getUsername(), 
+           $request->getPassword(), 
+           new \DateTimeImmutable()
+        ));
+
+        return $uuid;
+    }
+}
+```
+
+### Queries
+
+#### Query definition
+
+```php
+class FindAllUsers implements \Spiral\Cqrs\QueryInterface
+{
+    public function __construct(
+        public array $roles = []
+    ) {
+    }
+}
+```
+
+```php
+class FindUserById implements \Spiral\Cqrs\QueryInterface
+{
+    public function __construct(
+        public Uuid $uuid
+    ) {
+    }
+}
+```
+
+#### Query handler definition
+
+```php
+class UsersQueries
+{
+    public function __construct(
+        private UserRepository $users
+    ) {
+    }
+
+    #[\Spiral\Cqrs\Attribute\QueryHandler]
+    public function findAll(FindAllUsers $query): UserCollection
+    {
+        $scope = [];
+        if ($query->roles !== []) {
+            $scope['roles'] = $query->roles
+        }
+
+        return new UserCollection(
+            $this->users->findAll($scope)
+        );
+    }
+
+    #[\Spiral\Cqrs\Attribute\QueryHandler]
+    public function findById(FindUserById $query): UserResource
+    {
+        return new UserResource(
+            $this->users->findByPK($query->uuid)
+        );
+    }
+}
+```
+
+#### Dispatch queries
+
+```php
+use Ramsey\Uuid\Uuid;
+
+class UserController 
+{
+    public function index(UserFilters $filters, \Spiral\Cqrs\QueryBusInterface $bus)
+    {
+        return $bus->dispatch(
+            new FindAllUsers($filters->roles())
+        )->toArray();
+    }
+
+    public function show(string $uuid, \Spiral\Cqrs\QueryBusInterface $bus)
+    {
+        return $bus->dispatch(
+            new FindUserById(Uuid::fromString($uuid))
+        )->toArray();
+    }
+}
+```
+
 ## Testing
 
 ```bash
@@ -64,7 +209,7 @@ Please review [our security policy](../../security/policy) on how to report secu
 
 ## Credits
 
-- [:author_name](https://github.com/:author_username)
+- [butschster](https://github.com/spiral-packages)
 - [All Contributors](../../contributors)
 
 ## License

diff --git a/composer.json b/composer.json
@@ -1,40 +1,46 @@
 {
-  "name": ":vendor_slug/:package_slug",
-  "description": ":package_description",
+  "name": "spiral-packages/cqrs",
+  "description": "Lightweight message bus supporting CQRS for Spiral Framework",
   "keywords": [
-    ":vendor_name",
+    "spiral-packages",
     "spiral",
-    ":package_slug"
+    "cqrs",
+    "command-bus",
+    "query-bus"
   ],
-  "homepage": "https://github.com/:vendor_slug/:package_slug",
+  "homepage": "https://github.com/spiral-packages/cqrs",
   "license": "MIT",
   "authors": [
     {
-      "name": ":author_name",
-      "email": "author@domain.com",
+      "name": "butschster",
+      "email": "butschster@gmail.com",
       "role": "Developer"
     }
   ],
   "require": {
     "php": "^8.0",
     "spiral/boot": "^2.9",
-    "spiral/console": "^2.9"
+    "spiral/core": "^2.9",
+    "spiral/config": "^2.9",
+    "spiral/console": "^2.9",
+    "spiral/tokenizer": "^2.9",
+    "spiral/attributes": "^2.9",
+    "symfony/messenger": "^6.0"
   },
   "require-dev": {
-    "mockery/mockery": "^1.5",
-    "phpunit/phpunit": "^9.5",
+    "spiral/framework": "^2.9",
     "spiral/testing": "^1.0",
     "vimeo/psalm": "^4.9"
   },
   "autoload": {
     "psr-4": {
-      "VendorName\\Skeleton\\": "src"
+      "Spiral\\Cqrs\\": "src"
     }
   },
   "autoload-dev": {
     "psr-4": {
-      "VendorName\\Skeleton\\Tests\\App\\": "tests/app",
-      "VendorName\\Skeleton\\Tests\\": "tests/src"
+      "Spiral\\Cqrs\\Tests\\App\\": "tests/app",
+      "Spiral\\Cqrs\\Tests\\": "tests/src"
     }
   },
   "scripts": {
@@ -47,7 +53,7 @@
   "extra": {
     "spiral": {
       "bootloaders": [
-        "VendorName\\Skeleton\\Bootloader\\SkeletonBootloader"
+        "Spiral\\Cqrs\\Bootloader\\CqrsBootloader"
       ]
     }
   },