Forem: Anastasiia Lysenko

Cutting Edge: Using PHP 8.0 in Enterprise

Anastasiia Lysenko — Fri, 26 Feb 2021 10:53:45 +0000

In this article I am planning to describe perks and features of PHP 8.0, that we are already using or going to use in the one of our new microservices in existing chatbot messaging project.

As many of PHP developers, my team can't wait to try new version of PHP as soon as possible. So, right in time when new microservice got from strategy planning stage to solution architecture choices, I already knew what it's going to be. Long story short, Symfony 5 and PHP 8.0 were the winners. Here I should mention, that we use microservices coupled with DDD business principles and Onion architecture in almost each of them. Here you can dive in. This strong decoupling made this 'on edge move' possible in such short time.

Meanwhile, what we like and use from the new features:

Duplicated Properties Are Dead! Long Live The Constructor

We all have so many Value Objects and Entities. And each of them looks like this:

PHP 8.0 and Nikita Popov gave us freedom from properties boilerplate for all simple cases, when you set your properties in constructor:

Nice and easy. We use it with all our new value objects and entities, as well as other resembling classes.
Be careful: those properties are not allowed in abstract classes and interfaces as well as callable and nullable properties. Surely, you can't declare them twice: as properties and in constructor.

Let's make a Union with Types

It's definitely the blast! I personally voted for them, because it's such a strong adding to 'typed properties' from the one side and flexibility from the other.

Either you need different types of a number, string, arrays or interfaces: you can now describe all of possible types as input parameters in your methods, class variables and method return. This way you enforce types, so mistakes can be caught early, types are checked during inheritance, enforcing the Liskov Substitution Principle (L from SOLID). You can freely use Reflection, because union types are available through Reflection. The last, but not least, the syntax needs less amount of efforts, than phpdoc.

So, the question is: what types can't we have as 'union typed'. The following list would be the answer:

The void type could not be part of a union, as void means that a function does not return any value.
The nullable type notation (?Type) is allowed, so we can do Type|null, but we are not allowed to include the ?Type notation in union types (?Type1|Type2 is not allowed and we should use Type1|Type2|null instead).

As many internal functions include false among the return types, the false pseudo-type is also supported for backward compatibility.
That capability was only added to support legacy code. So, we are not planning to use it for any new code, so should not anyone.

ValueError Exception

From now on we can catch even more bugs on early stages.

If $emptyArray will be empty, that you have ValueError Exception, that extends Exception:

PHP throws this exception every time you pass a value to a function, which has a valid type, but can not be used for the particular operation (for example, empty arrays, negative number in case with json_decode, etc.).

Sure, we will not catch this specific Error each time, but before PHP 8, all those wrong cases throws just a warning, so it was not possible to catch it with Exception, as it is now.

Say hello to `Throw` as an expression

Finally, we can have more readable 'possibly wrong' code with even less amount of 'exception handling' code.

For those of you, who does not need en $exception as variable in catch block, it's now possible to not define it:

String it

PHP 8 gives us a Stringable interface that corresponds to an object having the __toString() magic method.

A class may implement a Stringable interface that defines a method public function __toString(): string. Useful fact: if it doesn’t, but still implements that method, the engine will add the method and return type automatically. So, we can now check type in the union type, for example, like this:

Static in return

Many of us get into the situations, when we need to call class methods in chain and get the result from the last one, for example. All those years of JS jokes saying out loud at last gives us chained methods with late static binding from now on. Self, parent and static can now be used in different usecases with chained methods.

Do not mix with mixed

From 8.0 you can do this:

Maybe, it's necessary in some rare cases, but even those cases we refactored to union types in our project. Try to avoid this 'type' as much as possible. Personally, I think it's equal to 'no type at all'.

Safe and sound with null

Personally, one of my favorites. No more if or strange looking chains with null coalescence operators.

We have a match!

And my second favorite is match. It is pretty similar to well-known switch but with safer semantics and allowing to return values. So you don't need the variable for it anymore.

Der Teufel steckt im Detail.

While switch compares values loosely (==) potentially leading to unexpected results, match comparison is an identity check (===). I think, it's a huge difference and we are definitely will use match instead of switch.

The match may also contain multiple comma-separated expressions, that give us opportunity to have more shortened syntax:

More functions, we need more functions

str_contains will definitely come in handy for almost all of us.

Say 'no' to every PHP developer nightmare with looking for a match in string. Everytime it's strstr combined with strpos and checking to bigger than zero. Say 'yes' to one simple function instead of it:

str_starts_with() and str_ends_with() are here for you if you need even more precise search.

You name it

I see the main advantage of named arguments is that they allow to specify only arguments we want to change. So it's not necessary to specify default arguments if we don’t want to overwrite default values. The following example makes it clear:

Sugar, baby

$object::class is a new get_class().

Thanks to Nikita Popov, now instead of remembering another internal function, we can just get the class for an object as simple as that ::class.

What we are definitely planning to use attributes. As for well-known new feature JIT, I do not see the extreme necessary or gaining some big value for our project in using it at the moment. We have opcache enabled, as it is by default and using Go for sockets, long time parsers, etc. But, who knows, maybe we'll try it later.

As conclusion, I should say, that PHP 8.0 got awesome changes and my team and I are so excited to try it in a real live project. We hope, that our code transforms to more clean and readable shape as well as gains performance and usability.

Time to try it by yourself :)

Keep your code clean and clear and yourself safe and sound!

How to handle Stripe?

Anastasiia Lysenko — Mon, 25 Jan 2021 13:46:30 +0000

This article is the second one of my 'HowTo:Stripe' series. Set of articles will be helpful for those of managers or developers, who are planning to use Stripe as a payment system or those of you, who already using it. I won't compare Stripe with analogs (let's just say, BrainTree is also a great fit for this purpose), but rather planning to provide a detailed instruction on how to implement a ready-and-working one-time checkout or subscription system with billing cycle of recurrent payments.

If you are already have answers on questions from the previous article, you are all-set to begin.

Game On

In Stripe game, any payment begins with creating Customer and Checkout Session for this Customer in Stripe (here the details how to do it). The moment we create those Entities in Stripe, we need to create our StripeCustomer and StripeCheckoutSession accordingly with necessary data, that Stripe gave to us (identifiers, dates, so on).
StripeCustomer: I recommend to save only necessary data here (for example, stripe customer id, createdAtStripe datetime and customer email) and link it One-to-One with your User identity via userId field.
StripeCheckoutSession: the best here is to save such data, as stripe session identifier, created and updated datetime and stripe customer identifier (Many-to-One with Customer here). In case you have a Subscription type checkout, there are two more fields, that are necessary here: subscriptionId (stripe subscription identifier, null at this moment) and product identifier (your 'subscription' identifier).

Important to know, that Session is always should be linked with your 'product' specification in order to control and respond to any stripe changes and save this 'product identifier' in StripeSubscription later on accordingly with Stripe Checkout Process and webhooks. Those 'Customer-CheckoutSession' actions should be handled by one CreateStripeCheckoutSession query. So, you can return 'ready-to-pay' Session object to the Web Client in response on CreateStripeCheckoutSession query. Note, that if you do not want to create a customer for every checkout session (every payment), you need to pass it to Stripe at the moment you create a CheckoutSession in Stripe. Our StripeCustomer linked with User comes in handy here: you can just look by your user identity identifier among all customers in your StripeCustomer table and use it after that.

One should not forget to setup 'keys': Stripe gives you public and private keys. The first one you are going to use in frontend queries and the second one should be set in any API query to Stripe from backend. You can find your keys at your project 'Dashboard' main page.

Now the client can proceed with payment and actually pay for your product in a one-time-checkout or subscribe to the billing cycle.

Take it all

The client is going to be redirected to the success_url, that you set up when initiated the Checkout Session, in case of successful checkout and to cancel_url page otherwise. If you have the one-time-checkout, than I have good news for you: it's almost done. You need to update the status of your checkout session in order to know, that everything paid in redirectToCheckout event handler and that's all.

#FollowMe #SubscribeMe

Meanwhile, with 'Subscription' type of payment, we are not done here. During the payment and redirect process, you need to receive and handle all necessary webhooks in order to show 'paid' invoices and 'active' subscription in his success page.

It means, that you are going to need a full cycle of recurrent payments. So, you have to operate with the next types of event entities:

Subscription,
Checkout Session,
Customer,
Invoice,
Charge.

All those entities have required and not required fields. Some of entity fields can be absent during specific event, but filled out in other. For example, subscription or pdf fields are absent during invoice.created or any other invoice event, which happens before subscription.created and so on. All event fields you can find in specific StripeEventInputType article (TBD)

So, in order to receive all important events, you need to listen to at least the following event list:

You can setup whatever stack you have as listener and create a Webhook point at your dashboard. Do not forget, that you should always listen to webhooks. Important to notice, that here you should check signature, that Stripe gave you as 'Signing Secret' on Webhhoks page. Do it for every query, that you receive.

All events, that come from Stripe, go directly to this Webhook point. Here you can respond directly or format it depending on the event type and send to your API to handle. Here, not dependently on event type, I recommend to save any of it as StripeEvent and respond to event accordingly with it's type only after that. Having it that way, you can always find all events, that you received from Stripe at any time by 'customerId' in your StripeEvent table or you can setup a view in your admin panel as well.

Here we come to the most not obvious and crazy thing, that I have not expected from a fancy world-wide-known system. Stripe send all webhooks asynchronously. So you can never know you can never know what comes first: subscription, invoice or checkout session webhook.

Why is that not convenient at all? At first, all data, that can be linked with is 'checkout session' for specific payment and 'customer' for user in general.
But the thing is 'checkout.completed' webhook you can receive at any time: after invoice.finalized or subscription.created. More to that, you can give invoice.finalized before invoice.created and so on with invoices. More to it, you can get 'subscription' at the end of webhooks list. In that way, you firstly getting an invoice, that you can save, but you can't attach it to subscription, because there are none at the moment and you can't attach it to your 'product' (e.g. subscription plan), because you can't identify the specific product in your DB with paid invoice. Sure thing, in order to deal with asynchronous Stripe events we got all cases handled. I am going to describe it in detail in the next article in this series. In a nutshell, the most important thing is to save and link Stripe subscription with invoices, checkout session with subscription and subscription with your product. Every event should be handled by different Handler, for example, it can look in the following way:

HandleStripeChargeWebhookSrevice
HandleStripeInvoiceWebhookService
HandleStripeCheckoutWebhookService

...
so on.

Useful Stripe Docs, that comes in handy:

Webhooks
Event types
Subscriptions
Cards to test billing
Stripe CLI

In the next article I am going to specify ways to handle 'asynchronous' webhooks and how each event may look like.

Keep your code clean and yourself safe and sound.

To pay or not to pay with Stripe: subscriptions from 'zero' to 'cycling'

Anastasiia Lysenko — Mon, 25 Jan 2021 13:26:06 +0000

This article is the first one of my 'HowTo:Stripe' series. Set of articles will be helpful for those of managers or developers, who are planning to use Stripe as a payment system or those of you, who are already using it. I won't compare Stripe with analogs (let's just say, BrainTree is also a great fit for this purpose), but rather planning to provide a detailed instruction on how to implement a ready-and-working one-time checkout or subscription system with billing cycles.

As you may already know, Stripe has a great API. And I must say, that from my experience, it's totally true! In addition to that, there are a CLI for your needs, that also comes in handy, especially for testing purposes or if you have to register your 'products' dynamically. They even have a docker image with it inside. The documentation tells anyone everything one need to know.

Anyway, before you can set up your project payments via Stripe, you need to have answers on the following questions:

Is it going to be a 'one-time' payment or subscription?

In the first case, you just need to create a 'Product' and you set and go with One-Time-Checkout. The 'Product' is like an item to sell, but in more general way: newspaper subscription, business plan, set of plates are all 'Products' in the terms of the scope of Stripe. Meanwhile, in the last case you are going to need much more to work on. Anyway, you can find instructions on how to operate in both cases below.

Is amount of your 'items-to-be-paid-for' going to be a not very big and static value?

Why it is so important to know at the early stage of implementation? Because, there are a bad news for you in case you have a whole bunch of, let's just say, clothes with unique prices for each of them. In this case you need to clone payment details for every product in your store system in Stripe. More to it, it's necessary to do it twice: in the testing environment and in production. So, the flow for each new t-shirt will be the following: create it in your store ➡️ create it on stand ➡️ create it on production environment. Sure thing, you can do this via API query, but anyway it's time and code. The full picture looks different in the other case your 'Products' are 'subscriptions'. Also it's very convenient solution in case of not big and rarely changeable amount of items to sell.

What's a default currency for your merchant?

You can create a Product with just one for all countries currency, that will be automatically converted for most of the countries. You can find more about automated currency conversion and fees for it here.

Are you ready to have only one test stage and the same team working on test and live panel?

Despite of different Products and Webhooks setup, they really have only one team to manage Stripe at web panel. The list of Roles are also not so wide: only six of them and only two of them has 'read' access to Webhooks section, but along with it those users are going to have 'write' access to customers, subscriptions and so on. So, important to know: your 'Developers' are going to have broad list of possibilities on production environments. The full list is here.

If at this point you define Stripe as a fit, that fulfill your purposes, then you need to go to your Stripe Dashboard and setup your Stripe system with a branding, team and products.

On initial setup, you can leave all settings as they are, but you are definitely have to create a 'Product' and a 'Price' with default currency for each product. If it's a Subscription, then you need to choose a 'Billing cycle'. 'Billing cycle' and currency are customizable here. By default, it's 'month/half of year/year' as billing cycle and 'usd' as default currency.

The next article is ready for you on this Stripe journey.

Keep your code clean and yourself safe and sound.

GraphQL: Files, upload more files!

Anastasiia Lysenko — Wed, 06 Jan 2021 07:56:09 +0000

This article is a part of my 'graphql' articles series, so be free to check out other as well in case you are interested in 'three years long graphql adventure in real-life projects'.

Well, what is the one of the most needed and wide-use web features? Surely, it is file upload.
Pff, what’s a fuss, you may think of. Standard multipart/form-data, FILES array|FileInputStream|etc., attach validation and dunk. Various implementations in all kinds of languages, frameworks or vendors. At this moment you are possibly thinking and what's wrong with GraphQL, why can we implement it as usual? You can! And nothing will stop you from doing it the standard way. Well, wait, except, one thing. If you upload files via from an PHP Files array (or any other backend language solution), your query handler (resolver) will know literally nothing about the uploaded files. It’s simply a query without files in it. You are going to handle it as usual, but on the Application layer: obtain the file structure and work with it. We have this type of uploading on my first DDD with GraphQL project and it has nothing good with it. To mix layers logic is always a bad decision in any project architecture. It was no good then and I always want to change that and know that in any project from scratch I’ll do the right thing. And in the current project it has been successfully implemented by me and my fellow teammates.

GraphQL enthusiasts and developers have ready and working solution for you. Let’s meet an UploadType - the custom type for uploaded files, that has been implemented by Ecodev developers.
Arguments, and as to be more specific, one parameter to load file with this type looks pretty simple:

FileUploaderResolver:

'args' => [ 'file' => new UploadType()]

FileUpload Mutation Example:

mutation(
   $file: Upload
) {
   uploadYourFileHere(
       file: $file
   ) {
      File {
          path,        
          name
      }
}

More to say, after you create a resolver and use this object type in it, your additional application logic actions with this file will be identical to the version with standard file uploading. Frontend developers should download a file and send it in map schema.

For example, request payload:

--------------------------cec8e8123c05ba25
Content-Disposition: form-data; name="operations"

{ "query": "mutation ($file: Upload!) { uploadYourFileHere(file: $file) { id } }", "variables": { "file": null } }
--------------------------cec8e8123c05ba25
Content-Disposition: form-data; name="map"

{ "0": ["variables.file"] }
--------------------------cec8e8123c05ba25
Content-Disposition: form-data; name="0"; filename="a.txt"
Content-Type: text/plain
Alpha file content.

--------------------------cec8e8123c05ba25--

And list of files (difference will be only in 'map' here and List(Upload) as mutation param accordingly):

Content-Disposition: form-data; name="map"

{ "0": ["variables.files.0"], "1": ["variables.files.1"] }

You can explore all the details in the GraphQl Multipart Request documentation or in tests in the Ecodev library.

After uploading, you can store files in any preferable way. As Cloud adept, I prefer to store them in AWS S3 with links in DB.

Keep your code clean and yourself safe and sound.

GraphQL: change for the best

Anastasiia Lysenko — Thu, 10 Dec 2020 15:58:38 +0000

Today I’d like to share with you real-life code and schema example how one can successfully integrate GraphQL into PHP and how to optimize the result. At the moment it’s hardly unlikely to meet web-developer, who doesn’t know or doesn’t hear a thing about GraphQL. And it’s understandable: more and more developers choose to begin or continue to use it in their projects due to various advantages. Such as single end-point, extendable hierarchy, strict types, flexibility among others.
Despite the well-known fact that we are living and developing in the stackoverflow and medium era, each of us is constantly stuck with a ‘can not be googled’ type of task once in a while. Usually it happens when you want or should to create something big or try the new approach and in those cases you need as much information as one can get. The documentation always comes in handy in those cases and one begins with deep dive into it.

This step is totally where you got covered with any type of information from the official site. But theory is cheap, you are not going to be getting paid for it, right? So, on the next step, that includes taking off pink glasses and turning theory into a practice, you are totally limited by project language or framework. Today I’d like to present a solution for using GraphQL with PHP as a server side language. You are not going to hear a detailed explanation of a GraphQL documentation or PHP ports for GraphQL. What you will definitely get in detail is an example of an GraphQL integration into a PHP project, like one you can see on your screen. I mean, if someone had provided me the full example of an enterprise project three years ago, I would be more than happy. But no, it was not gonna happen then, but now I have one for you. More to it, I’m going to describe how you can solve the most common issues that you are most likely to get into and the most working ways to optimize queries.

Firstly, you should choose a GraphQL port that you’ll be working with. To fulfill that purpose, one can simply open the official GraphQL site and look for the PHP section in it. You’ll see a short list with three general-use libraries and a few of framework-use. I am actively using the first one from the WebOnyx for about three years for now and don’t have any major issues for now. They have a bit specific error handling as for me, but we solved this with a custom error handler.
In addition to the vendor library, you’ll most likely be in need for the schema documentation generator. This one seems to be a perfect fit for all GraphQL projects that I’ve worked with. It’s simple in use and setup and your schemes will be always up to date (while you run on deploy the specific command for it, of course).

Meanwhile, for a ready and working GraphQL API you’ll need:

To design and to build request and response resolvers, design and handle schemes and data view models
Choose the most fitting pagination invariant and integrate it in code
Create a ResultHandler and an ErrorHandler (it’s nothing easy in this world)
Create endpoint
Send a query

Let’s review each step in detail:

Well, let’s assume you have a GraphQL request parameters and know what response it should return in its body. So now you should resolve this specific request into a specific response. The main tasks of any Resolver are “query a request” and 'return a response', that’s why it has only four methods:

query Here you can wrap parent vendor query method with necessary redefining of ‘resolve’ param)
createRequest In this method we can shape the request, that we have from the endpoint by adding query variables and query body as separate data attributes
createResponse The perfect method for initializing assemblers for the usecases (as analogy, I can describe it with calling application service). Use case in general in DDD is an Application Service. But besides it we additionally have to integrate the middle-ware layer (application validation check, do authorization check, data access check, etc.) and initialize Use Case with data. In general, we need to assemble query data into Use Case and return response from it. So, I call it UseCaseAssembler. You can read about DDD and it's live project implementation here.
and the last method is an abstract method response that needs to be implemented in each specific Resolver.

Well, to get a better understanding, we can get a look into specific query example. Well, you have an entity Wishlist, an object of which you need to create. Creation query may look exactly like on your screens. Each query contains fields of two types: type and arguments. The type tells us that we are going to get a Wishlist interface and structured data in response as a result. And the second field type is ‘arguments’, where you obviously have the set of input variables. You can always get a good look into input variables types on the official GraphQL site or WebOnyx as well.

Resolver

CreateWishlistResolver.php

Wishlist schema may look like that one. Any schema should have an interface and object that implements it. So, there are Wishlist interface and Wishlist object. The various output GraphQL types are always there: on the official site.

WishlistSchema.php

If GraphQL adepts talking about pagination, there is always a war. The infinite war between two clans: the first one is 'Cursor' and the second one is 'Offset'. In truth, as usual with almost all wars sides, they have not so many differences in schema. The main difference will be at looking up in persistent storage. 'Cursor' charter looks like:

Meanwhile, there is a light at the end of a tunnel. If you roll a dice and choose a pagination side, you should create a PageInfo schema class (it looks exactly like WishlistSchema, that you saw before). And… understand, that method render is not gonna help us anymore, just because it fits only one data record and doesn’t have pagination in it. So, that’s a moment when you understand that you're gonna need two types of response presenters: for one node and another one, that fits the collection of nodes.

CollectionPresenter.php

NodePresenter.php

Naturally, our frontend developers nicely ask or not so nicely demand 24/7 valid schema and fine-structured handled errors, preferably with error codes in case if something goes wrong. As you can notice from the render methods on previous screens, there is always a method getResultFields() in each of the render method. As one can suppose from the method name, it returns the schema of general result fields. Any query result is going to have this schema. In case of any errors it will consist of ‘errors’ set of fields and you work with response respectively to it.

AbstractPresenter.php

The result handling schema may look something like you see on display:

ResultSchema.php

Also, as I explained earlier, we definitely need to return an error message and code in case of any errors, so whoever gets a response can notice that something went wrong and may handle errors accordingly with their codes. That's how we provide the maximum possible error handling strategy and do not leave any of ‘unpredictable’ for the API user cases as a result. Your frontend engineers will thank you for that, you’ll see. It’s worse to mention, that GraphQL schema errors (like wrong type or absence of required field) are going to be catched and returned by the vendor library, so you can add your own Exception for those types of errors. It definitely helps you to get human readable exception traces.

We have two points left from the our conquer GraphQL plan: make an endpoint and send a query.

To make an endpoint it’s a specific task, I’ll explain how you can possibly do it with our case. Historically, we are using Laravel, so our endpoint is a one and only controller with two methods. The first one is for all GraphQL queries, obviously and the second one graphQLResponse is about making a PSR7 json Response from the response data of the query.

Meanwhile, there's only one thing left. We need to actually send a query to the endpoint URL. We are actively using Insomnia and Postman and I can recommend both of them.

Controller.php

Well, congratulations! You can do a full circle of GraphQL query in PHP.
Hope that you have learned some practical or theoretical things that come in handy to those who want to use GraphQL with PHP or already using it. Every cook praises his own broth.

Keep your code clean and yourself safe and sound.

CQRS code example "Requested"

Anastasiia Lysenko — Mon, 30 Nov 2020 14:17:24 +0000

This post is linked with the detailed article Real-life DDD in an "onionshell" and explains with code examples specific version of a standard CQRS command requests. This customization allows us to handle different types of command requests integrating with bounded contexts.

Our service has two types of API requests: external "usecase" type and "command request" type, that can be external and internal. The second type can be managed differently, depending on it’s goal. It can be a simple external request to handle a command. Another time it can be a complex task with transaction in it. So we should use a different approach for every version of the task according to the configuration pre-set. Either way we create a task request and manage it using a message broker.

We have "usecase" and "request-commands" concept. Last one should be used for any server-to-server or context-to-context interaction.
Request command should be created via CommandRunner (RequestCommandHandlerService), that operates with command handlers and have the following interface:

/**
 * Interface CommandRunner
 * @package Utility\RequestCommand
 */
interface CommandRunner
{
    /**
     * @param TaskRequestInterface $taskRequest
     * @throws JsonException
     */
    public function send(TaskRequestInterface $taskRequest): void;

    /**
     * @param TaskRequestInterface $taskRequest
     * @throws CommandRequestException
     */
    public function run(TaskRequestInterface $taskRequest): void;
}

All of handle pairs should be determined in configuration config.php/requestCommand.php. For example,

If request command is going to be called externally you are going to need alias for this call:

/*
|------------------------------------------------------------
| Handlers Aliases
|------------------------------------------------------------
*/
'requestAliases' => [
    'makeMessage' => MakeMessageTaskRequest::class,
    'createTeam'  => CreateTeamTaskRequest::class,
],

That's way we can add multi-purpose Handler-Request pair to 'requestCommand'. It can be simple peer-to-peer:

AddScenarioStatisticTaskRequest::class => AddScenarioStatisticHandler::class

Or transaction mode (all handlers are going to be committed in one transaction):

MakeMessageTaskRequest::class => [
     MakeMessageTaskRequest::class => MakeMessageHandler::class,
     UpdateSessionLastSeenTaskRequest::class => UpdateSessionLastSeenHandler::class
],

Pay attention here: you should create only one request via command handler, for example 'MakeMessageTaskRequest' and all other requests are going to be created automatically according with your chain of requests/handlers.

After that you can create specific TaskRequest with entity-specific DTO in Infrastructure/TaskRequest and Handler for it in Application/CommandHandler.
TaskRequest example:

Yep, it's going to be DeactivateUserTariffPlanDTO instead of RequestDTO immediately after we update PHP version to 8.0 :)

CommandHandler example (it can be in any context):

As you can see, handler 'process' method should call Application Service accordingly with procedure, that you need. Add Middleware Validators for each of them accordingly in Handler.

Handler without Transactions should implement RequestCommandHandler interface and Transaction Handlers should implement RequestCommandHandler,TransactionRequestCommandHandler interfaces.

There are two types of transaction handlers: "insiders" and "closing". Insiders (implements InsiderTransactionRequestCommandHandler interface as well) should create DTO for the next transaction request in the process() method via creating

$this->nextTransactionRequestDTO and return it in the following way:

/**
 * @return bool
 */
public function isInTransaction(): bool
{
    return true;
}

/**
 * @return RequestDTO|null
*/
public function getNextTransactionRequestDTO(): RequestDTO
{
    return $this->nextTransactionRequestDTO;
}

Closing one closes transaction (the last request on the list), so it should only implement isInTransaction method:

/**
 * @return bool
*/
public function isInTransaction(): bool
{
    return false;
}

I am planning to create two different strategies for "insiders" and "closing" request, but it haven't done yet.
TaskHandler is going to handle all inner processes, such as setup transactions decorator service with UnitOfWork, obtain and handle request-commands pairs and request data from the configuration service, handle low-level exceptions and so on.

All we have left to do is to start listen "request-command" queue via message broker (we use RabbitMQ, but it's going to work with any of brokers, anyway).

Example for DeactivateUserTariffPlan:

From any of bounded contexts services inside API:

$this->commandRunner->send(new DeactivateUserTariffPlanTaskRequest(new DeactivateUserTariffPlanDTO(['userId' => 1])));

From external services (for example, API Gateway):

Send json data to the "request-command" queue:

[
    'userId' => 1
]

Real-life Domain Driven Design in an "onionshell"

Anastasiia Lysenko — Fri, 27 Nov 2020 10:55:06 +0000

Domain-Driven Design (DDD) gives us the most real-world approach to defining what really has business value. Coupling it with Onion Architecture, we can achieve a good level of layers communication and abstract the technology specifications that are secondary to the business. The best way to explain Domain Storytelling is to see it in action, as well as any architectural pattern (like Onion) can be properly introduced via a clean and clear example. So, I’d like to present a lightweight blueprint that can be used by agile teams as guidance for designing large-scale development programs. Furthermore, it’s been over three years, as I’ve designed, built and maintained two projects using DDD and multi-layered architecture, so you can get your hands on ready-and-working enterprise design schema and code solutions.

Let’s start with business needs. Nowadays, if we are talking about some complex service solution, it’s always about services. When you have separate services that communicate with each other over the network, you have a distributed system. In these systems, choosing the wrong integration strategy might cause slow or unreliable systems that lead to negative business impacts. That’s why it’s very important for the Architect and Developers to understand the best approaches to building scalable distributed systems.
Having to distribute a system introduces the need to break it up into smaller deployable components. This is a moment where you understand that DDD is a most fitting design and perfect choice in cases with complex or ‘going-to-be’ complex systems.

Well, it’s time for the first Schema.

Some of you can recognize the standard Onion Architecture schematic introduced by Jeffrey Palermo in 2008. The idea of the Onion Architecture is to place the Domain and Application Layers at the center of your application. And the Presentation and Infrastructure layers are located in external circles. The main point of this architecture is data flow direction. From the UI through our Application Service to our Domain Model and back to the outside. It can be compared with cross-cutting the onion, but with dry eyes in this case. It is important to notice that all dependencies move inwards. The layers inside the application core define the interfaces that the outer layers can use. The outer layers thus depend on the inner layers interfaces.

Onion is an architectural pattern for a system, whereas DDD is a way to design a subset of the objects in the system. Therefore in my practice, Onion architecture is the best among others to be coupled with DDD design and to integrate DDD principles in the real-life projects. Let’s see how we can move from the 2-D flat circle to the 3-D representation. ~~Magically~~ circle turns to cylinder.

Mapping the implementation model back to the analysis model and ensuring they are bound to one another is hard. To guide developers and clarify designs, Evans has built upon the domain model pattern that was first cataloged in Martin Fowler’s book Patterns of Enterprise Application Architecture. Those patterns used to create domain models and tie implementation to analysis have continually evolved since Evans’s original text.

And today I shall introduce you to my implementation of a highly scalable autonomic distributive API, that effectively adapts DDD patterns with ‘Onion’ architecture. I know, it’s not simple from the first glance, but we’ll get through each layer together step by step and at the end it will be clean and clear.

Domain Layer

DDD is definitely NOT about technology. DDD is all about the business domain. As Eric Evans defines a domain layer in a project:

This layer is the heart of business software.

Let me describe domain layer of the enterprise project blueprint in detail:

DTO

It's an acronym which stands for Data Transfer Object. Although the main reason for using a Data Transfer Object is to batch up what would be multiple remote calls into a single call, it's worth mentioning that another advantage is to encapsulate all simple request data.

Exception

Understandably, there we keep exceptions, which we use in a project.

Repository interfaces

Repository is a critical part of the entity lifecycle that allows us to persist domain entities. In the domain layer we create a contract for application or domain services. Using that contract each service can access domain models directly to find the needed information. You could create a generic repository interface, defining all kinds of common methods. At this moment you are possibly asking yourself: and specifically in what place in schema I can see Repository Interface? Nowhere. But let’s look at Domain Services and we are going to get to the truth.

Domain services

These one encapsulates domain logic and concepts that are not naturally modeled as value objects or entities in your model. Domain services have no identity or state; their responsibility is to orchestrate business logic using entities and value objects. If the domain service implementation requires some specific technology (for example database access, or SMTP server access or whatever), its implementation must live in the infrastructure layer. The domain simply doesn't care about implementations, if the business experts talk about something and we decide to make this "something" a contract, it must live in the Domain layer. Therefore Repository Interface is a Domain Service and Repository is an Infrastructure Service.

Entities

An entity represents a concept in your domain that is defined by its identity rather than its attributes. Although an entity’s identity remains fixed throughout its lifecycle, its attributes may change. An example of an entity is a User. It’s unique identity won’t change once it is set but its name, address, etc., can be altered many times. Entities are mutable as the attributes can change.

Value objects (VO)

VO represent the elements of your domain that are known and defined only by their attributes. Value objects don’t need identity because they are always associated with another object and are therefore understood within a particular context. For instance, you may have an User entity that uses value objects to represent the user address, account information and so on. Not one of these characteristics needs identity itself because it only has meaning within the context of being attached to an order. An User Address that is not attached to User does not have meaning. Because they are defined by their attributes, value objects are treated as immutable. That means, once constructed, they can never alter their state.

I’ve provided in the project the following data flow bus, that elaborate relationship between domain elements: create DTO from request data, create VO from the DTO and persist Entity, initializing from the VO. And backwards: fetch Entity, create VO and return DTO in Response.

Domain events

signify something that has happened in the problem domain that the business cares about. You can use events to record changes to a model in an audit fashion, or you can use them as a form of communication across aggregates. Often an operation on a single aggregate root can result in side effects that are outside the aggregate root boundary. Other aggregates within the model can listen for events and act accordingly. We are using Doctrine lifecycle events and it’s a perfect example of Domain Events.

Application layer

This layer is responsible for the navigation between the UI and other layers in the bounded context as well as the interaction with application layers of other bounded contexts. There we can perform the basic (non business related) validation on the user input data before transmitting it to the other (lower) layers of the application. And it should not contain any business or domain related logic. But it definitely should perform tasks from the UI request via services.

Validator

Typically, the data received by your application will be some flavor of DTO. Having successfully parsed the command into types the domain model understands, the command is executed in the domain, which may still reject the command on the grounds that it would violate the business invariant (the account doesn't exist yet, the account is blocked, etc.). In other words, the business validation is going to happen in the domain model, after the application layer validates the inputs. The implementation of the validation rules will normally live either in the constructor of the value type, or within the factory method used to construct the value type. Basically, you restrict the construction of the objects so that they are guaranteed to be valid, isolating the logic in one place, and invoking it at the process boundaries.

Provider

It’s necessary to use providers to elaborate with our framework for orchestrating services in containers.

Command Handlers

This structure is semantically similar to the application service layer, because here we store handlers that operate with commands (or task requests in our case) and call services according to task. Command itself is a business intention, something you want a system to do. Keep the definition of the commands in the domain. Technically it is just a pure DTO and DTO is what we have for our commands. The name of the command should always be imperative, like "CreateUser", "DeleteScenario". One command is handled only by one command handler.

EventHandlers

There is a benefit to having event handlers that live in the application service layer in addition to those that live in the domain. These event handlers tend to carry out infrastructural tasks like sending e‐mails. Note that these handlers are not part of UL or the domain.
One important responsibility of application service layer handlers is that they trigger communication with external bounded contexts. We have Notifiers (sms, email) as an example of Event Handler.

Application Services

We are using them as orchestrators that receive a request from the client, look up the object(s) that know how to handle the request, ask them to handle the request, store the result and send back a response to the client. The application services should not need to make any decisions themselves.

Use Case

Use Case in general is a business scenario and DDD defines it this way in theory and as a pure analog with Application Service in diagram or code structure.
Although, in practice, with real code in real projects, we have to build a bridge between UI data and an application service. We additionally have to:

Firstly, integrate the middleware layer (application validation check, do authorization check, data access (permissions to perform the Use Case) check, etc.) and initialize Use Case with data. In general, we need to assemble UI data into Use Case. So, I call it UseCaseAssembler.
Secondly, call service according to use case purpose, transform data, returned by service into Use Case Response and pass it to the UI layer. It’s definitely Use Case itself.

Infrastructure Layer

It can be described by shared libraries for Domain, Application, and UI layers. As you can probably notice from schematic, this layer also communicates with external systems. What shall we have here?

Builder

If the creation of an entity or a value object is sufficiently complex, you should delegate the construction to a factory. A factory ensures that all invariants are met before the domain object is created. You can also use factories when re‐creating domain objects from persistent storage. And in our case it would be a builder, because DTO<->VO<->Entity transformation goes in here and we are building those domain elements.

Repositories

A domain model needs a methodology for persisting and hydrating an aggregate. Because an aggregate is treated as an atomic unit, you should not be able to persist changes to an aggregate without persisting the entire aggregate. A repository is a pattern that abstracts the underlying persistence store from the model allowing you to create a model without thinking about infrastructure concerns.

Service

Services in the infrastructure layer are services which implement an interface from the domain layer. In the domain layer, you define an interface with actions we want to have.

Hibernate[Doctrine] Directory

This is an example of real-world needed infrastructure implementation. We keep here custom ORM types that we are using in our Entities.

Task Request

It’s my own extended version of a standard CQRS command request. Our service has two types of API requests: external "usecase" type and command request type, that can be external and internal. The second type can be managed differently, depending on it’s goal. It can be a simple external request to handle a command. Another time it can be a complex task with transaction in it. So we should use a different approach for every version of the task according to the configuration pre-set. Either way we create a task request and manage it using a message broker. You can overlook it in my specific article if you are interested in this topic.

Presentation Layer (UI)

A UI Layer is responsible for presenting information to the user and interpreting user commands.So it should translate incoming requests to method calls for the application layer and in the case of web services, translate the return values to responses. It may also contain Controller classes as in classical MVC.
We are using GraphQL, so I am going to explain this Layer in example how we deal with requests and responses. We have one endpoint and specific types for input parameters and output data. So we can create a request from the input query and return a response after resolving this request. All of it takes place in a specific for each Use Case Resolver.
Our Schema is a data contract. We're telling anyone who uses this API, "hey, this is going to be the format that you can always expect to see from this API call". And you are going to need a Presenter to perform complex logic for composing data from entities in case you need it. More about it here.

Full blueprint

So, we almost did it. I mean, if someone had provided me the full example of an enterprise project three years ago, I would be more than happy. But no, it was not gonna happen then, but now I have one for you.

I’ve described all context directories, except one. And this one hidden gem is the Shared Kernel. It’s a way of cross-context communication in which two or more contexts share a common model. You can learn all other ways in Vaughn Vernon’s IDDD book (such as Customer Supplier, Conformist, Partnership and other). In my project I prefer to use the Shared Kernel concept linked with Anti Corruption Layer on one hand and Partnership relationship on the other. The first one combined approach will guarantee the integrity of models via read only access and usability. And Partnership is convenient to use via messaging patterns, that I described earlier.

When integrating your bounded contexts, it’s important to get an idea from the business what its nonfunctional requirements are so that you can choose an integration strategy that lets you meet them with the least amount of effort. Some options, such as messaging, take more effort to implement, but they provide a solid foundation for achieving high scalability and reliability. On the other hand, if you don’t have such strong scalability requirements, you can integrate bounded contexts with a small initial effort using database integration. You can then get on with shipping other important features sooner and integrate CQRS later on. Unfortunately, you can’t just ask the business how scalable a system needs to be or how reliable it should be. In my practice, trying to give them both scenarios and explaining the costs of each scenario is the best approach.

Thank you, all, who have read this "long read"! I hope, that you found it useful.

Keep your code clean and clear and yourself safe and sound!

Forem: Anastasiia Lysenko

Cutting Edge: Using PHP 8.0 in Enterprise

Duplicated Properties Are Dead! Long Live The Constructor

Let's make a Union with Types

ValueError Exception

Say hello to Throw as an expression

String it

Static in return

Do not mix with mixed

Safe and sound with null

We have a match!

More functions, we need more functions

You name it

Sugar, baby

How to handle Stripe?

Game On

Take it all

#FollowMe #SubscribeMe

To pay or not to pay with Stripe: subscriptions from 'zero' to 'cycling'

Is it going to be a 'one-time' payment or subscription?

Is amount of your 'items-to-be-paid-for' going to be a not very big and static value?

What's a default currency for your merchant?

Are you ready to have only one test stage and the same team working on test and live panel?

GraphQL: Files, upload more files!

GraphQL: change for the best

Resolver

CreateWishlistResolver.php

WishlistSchema.php

CollectionPresenter.php

NodePresenter.php

AbstractPresenter.php

ResultSchema.php

Controller.php

CQRS code example "Requested"

Real-life Domain Driven Design in an "onionshell"

Domain Layer

DTO

Exception

Repository interfaces

Domain services

Entities

Value objects (VO)

Domain events

Application layer

Validator

Provider

Command Handlers

EventHandlers

Application Services

Use Case

Infrastructure Layer

Builder

Repositories

Service

Hibernate[Doctrine] Directory

Task Request

Presentation Layer (UI)

Full blueprint

Say hello to `Throw` as an expression