Forem: Ian Rodrigues

Writing value objects in PHP

Ian Rodrigues — Sun, 03 Nov 2019 16:30:00 +0000

If you already have heard about DDD (Domain-Driven Design), you probably also may have heard about Value Objects. It is one of the building blocks introduced by Eric Evans in "the blue book".

A value object is a type which wraps data and is distinguishable only by its properties. Unlike an Entity, it doesn't have a unique identifier. Thus, two value objects with the same property values should be considered equal.

A good example of candidates for value objects are:

phone number
address
price
a commit hash
a entity identifier
and so on.

When designing a value object, you should pay attention to its three main characteristics: immutability, structural equality, and self-validation.

Here's an example:

<?php declare(strict_types=1);

final class Price
{
    const USD = 'USD';
    const CAD = 'CAD';

    /** @var float */
    private $amount;

    /** @var string */
    private $currency;

    public function __construct(float $amount, string $currency = 'USD')
    {
        if ($amount < 0) {
            throw new \InvalidArgumentException("Amount should be a positive value: {$amount}.");
        }

        if (!in_array($currency, $this->getAvailableCurrencies())) {
            throw new \InvalidArgumentException("Currency should be a valid one: {$currency}.");
        }

        $this->amount = $amount;
        $this->currency = $currency;
    }

    private function getAvailableCurrencies(): array
    {
        return [self::USD, self::CAD];
    }

    public function getAmount(): float
    {
        return $this->amount;
    }

    public function getCurrency(): string
    {
        return $this->currency;
    }
}

Immutability

Once you instantiate a value object, it should be the same for the rest of the application lifecycle. If you need to change its value, it should be done by entirely replacing that object.

Using mutable value objects is acceptable if you are using them entirely within a local scope, with only one reference to the object. Otherwise, you may have problems.

Taking the previous example, here's how you can update the amount of a Price type:

<?php declare(strict_types=1);

final class Price
{
    // ...

    private function hasSameCurrency(Price $price): bool
    {
        return $this->currency === $price->currency;
    }

    public function sum(Price $price): self
    {
        if (!$this->hasSameCurrency($price)) {
            throw \InvalidArgumentException(
                "You can only sum values with the same currency: {$this->currency} !== {$price->currency}."
            );
        }

        return new self($this->amount + $price->amount, $this->currency);
    }
}

Structural Equality

Value objects don't have an identifier. In other words, if two value objects have the same internal values, they must be considered equal. As PHP doesn't have a way to override the equality operator, you should implement it by yourself.

You can create a specialized method to do that:

<?php declare(strict_types=1);

final class Price
{
    // ...

    public function isEqualsTo(Price $price): bool
    {
        return $this->amount === $price->amount && $this->currency === $price->currency;
    }
}

Another option is to create a hash based on its properties:

<?php declare(strict_types=1);

final class Price
{
    // ...

    private function hash(): string
    {
        return md5("{$this->amount}{$this->currency}");
    }

    public function isEqualsTo(Price $price): bool
    {
        return $this->hash() === $price->hash();
    }
}

Self-Validation

The validation of a value object should occur on its creation. If any of its properties are invalid, it should throw an exception. Putting this together with immutability, once you create a value object, you can be sure it will always be valid.

Taking the Price type example once again, it doesn't make sense to have a negative amount for the domain of the application:

<?php declare(strict_types=1);

final class Price
{
    // ...

    public function __construct(float $amount, string $currency = 'USD')
    {
        if ($amount < 0) {
            throw new \InvalidArgumentException("Amount should be a positive value: {$amount}.");
        }

        if (!in_array($currency, $this->getAvailableCurrencies())) {
            throw new \InvalidArgumentException("Currency should be a valid one: {$currency}.");
        }

        $this->amount = $amount;
        $this->currency = $currency;
    }
}

Using with Doctrine

Storing and retrieving value objects from the database using Doctrine is quite easy using Embeddables. According to the documentation, Embeddables are not entities. But, you embed them in entities, which makes them perfect for dealing with value objects.

Let's suppose you have a Product class, and you would like to store the price in that class. You will end up with the following modeling:

<?php declare(strict_types=1);

/** @Embeddable */
final class Price
{
    /** @Column(type="float") */
    private $amount;

    /** @Column(type="string") */
    private $currency;

    public function __construct(float $amount, string $currency = 'USD')
    {
        // ...

        $this->amount = $amount;
        $this->currency = $currency;
    }

    // ...
}

/** @Entity */
class Product
{
    /** @Embedded(class="Price") */
    private $price;

    public function __construct(Price $price)
    {
        $this->price = $price;
    }
}

Doctrine will automatically create the columns from the Price class into the table of the Product class. By default, it prefixes the database columns after the Embeddable class name, in this case: price_amount and price_currency.

Conclusion

Value objects are useful for writing clean code. Instead of writing:

public function addPhoneNumber(string $phone): void {}

You can write:

public function addPhoneNumber(PhoneNumber $phone): void {}

Which makes it easy to read and reason about it, also you don't need to figure out which phone format you should use.

Since their attributes define them, and you can share them with other different entities, they can be cacheable forever.

They can help you to reduce duplication. Instead of having multiples amount and currency fields, you can use a pure Price class.

Of course, like everything in life, you should not abuse of value objects. Imagine you converting tons of objects to primitive values to store them in the database, or converting those back to value objects when fetching them from the database.Indeed, you can have performance issues. Also, having tons of granular value objects can bloat your codebase.

With value objects, you can reduce the primitive obsession. Use them to represent a field or group of fields of your domain that require validation or can cause ambiguity if you use primitive values.

Thanks for reading, and happy coding!

Deploying containers to production with Terraform and AWS Fargate – Containerization

Ian Rodrigues — Mon, 15 Jul 2019 03:09:30 +0000

In the previous post, I've covered some of the services available to run containers on AWS. Also, I've presented Terraform, a tool to declare and provision those services using codes. This time, I'm gonna set up the project to run on Docker either locally and in production, using almost the same configuration.

Though I have more experience with PHP, I'm gonna provision a REST API written in Python (Django), since I've been working with it lately a lot. Please, don't focus on the application itself; it's written only for the sake of this post. Also, I'm sure you can apply the same principles I will use here for any language or framework. So, let's get the hands dirty!

Setting up the local environment

First, let's set up the local environment to run with Docker. This way, we will end up with an environment to work with identical to the production one. For this, we'll use Docker Compose. Create a new file called docker-compose.yml on the root directory:

version: '3.7'

volumes:
  postgres-data:
    driver: local

services:
  django:
    build: .
    volumes:
      - .:/usr/local/app
    ports:
      - 8000:8000
    depends_on:
      - database

  database:
    image: postgres:11-alpine
    volumes:
      - postgres-data:/var/lib/postgresql
    environment:
      POSTGRES_USER: wannajob
      POSTGRES_PASSWORD: wannajob
      POSTGRES_DB: wannajob

I won't get into details of the docker-compose.yml file. If you wanna learn more about it, check this out. Let's now create a Dockerfile. Docker Compose will use it to build the Django's container:

FROM python:3.6-slim-stretch

ENV PYTHONUNBUFFERED 1

WORKDIR /usr/local/app

RUN pip install --upgrade pip safety bandit pylint flake8 pytest coverage

COPY requirements.txt /usr/local/app/requirements.txt
RUN pip install -r requirements.txt

CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]

Again, I won't get into details of the Dockerfile. If you wanna learn more about it, check this out. Everything's set up, it's time to get the project up and running:

$ docker-compose up -d

Finally, run the migrations:

$ docker-compose run --rm --no-deps django python manage.py migrate

See? The project is ready for local development using Docker. Now, it's easy to start up the project anywhere. You can share it with your entire team, and everyone will have the same environment. No more, "But it works on my machine!".

Preparing for production

Now that the project is running locally, we can spend some time and make a few adjustments to prepare it for production. While locally we are using the runserver command – a lightweight development webserver – to serve the application, in production we'll need a "real" webserver. Here is where Nginx comes in. Yet, we can't serve the app directly through Nginx as it cannot process Python. We need something (a WSGI) to where Nginx will forward the request, process the Python code, send back to Nginx, and then return the response to the client. For this, we will use Gunicorn.

The first thing to do is to update the Dockerfile. We will make use of the Docker Multi-Stage Build, see:

##############
# Base Stage
##############
FROM python:3.6-slim-stretch AS base

ENV PYTHONUNBUFFERED 1

WORKDIR /usr/local/app

RUN pip install --upgrade pip gunicorn

COPY requirements.txt /usr/local/app/requirements.txt
RUN pip install -r requirements.txt

CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--log-level", "warning", "--reload", "wannajob.wsgi:application"]


#####################
# Development Stage
#####################
FROM base AS development

RUN pip install --upgrade safety bandit pylint flake8 pytest coverage


####################
# Production Stage
####################
FROM base AS production

ENV DJANGO_SETTINGS_MODULE 'wannajob.settings.production'

COPY . /usr/local/app


#################
# Statics Stage
#################
FROM production AS statics

RUN python manage.py collectstatic --no-input --clear


############################
# Production (Nginx) Stage
############################
FROM nginx:1.17-alpine AS nginx

COPY ./docker/nginx/django.conf /etc/nginx/conf.d/default.conf

WORKDIR /usr/local/app

RUN mkdir statics
COPY --chown=nginx:nginx --from=statics /usr/local/app/static /usr/local/app/static

Then, create the docker/nginx/django.conf file:

server {
  listen 80;

  location = /favicon.ico {
    access_log    off;
    log_not_found off;
  }

  location /static/ {
    alias /usr/local/app/static/;
  }

  location / {
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_pass http://django:8000;
  }
}

And finally, update the docker-compose.yml, to use Nginx:

version: '3.7'

volumes:
  postgres-data:
    driver: local

services:
  django:
    build:
      context: .
      target: development
    volumes:
      - .:/usr/local/app
    depends_on:
      - database

  nginx:
    image: nginx:1.17-alpine
    volumes:
      - ./docker/nginx:/etc/nginx/conf.d
      - ./static:/usr/local/app/static
    ports:
      - 8000:80
    depends_on:
      - django

  database:
    image: postgres:11-alpine
    volumes:
      - postgres-data:/var/lib/postgresql
    environment:
      POSTGRES_USER: wannajob
      POSTGRES_PASSWORD: wannajob
      POSTGRES_DB: wannajob

Let's rebuild the application:

$ docker-compose up -d --build

Now, the project is being served through Nginx locally, there's no difference from what we will be doing in production in the future. Also, thanks to the Docker Multi-Stage Build, we have all the necessary development tools locally, but we can get rid of them when running in production, which will result in a more lightweight image.

Have a look at the size of the development and production images:

$ docker images --filter reference=ianrodrigues/wannawork-app 
REPOSITORY                   TAG                 IMAGE ID            CREATED             SIZE
ianrodrigues/wannawork-app   production          29a4de730436        3 minutes ago       196MB
ianrodrigues/wannawork-app   development         cf3a9bf4ca10        2 hours ago         223MB

Pretty cool, huh?!

As you could see, it's simple to set up Docker for a project to run locally, and with a few modifications, you can use the same setup ready for production. Thanks to Docker Multi-Stage Build, you can create flexible Dockerfiles that will result in more lightweight images, which is pretty suitable for production.

The source code used in this post is available on Github. If you have questions or suggestions, please let me know in the comments. In the next post, I'll set up the environment on the AWS using Terraform, stay tuned!

Deploying containers to production with Terraform and AWS Fargate – Introduction

Ian Rodrigues — Tue, 09 Jul 2019 01:24:52 +0000

With the advent of Docker these days, it's pretty straightforward to set up a local development environment to build our applications. It would be even high if we could deploy that same container to production with the same ease.

It's not only possible as you will learn how to do it. Today, I'll start a series of posts to show you all how to provide the necessary infrastructure on AWS to get your containerized application up and running. At this first part, I'll explain a few key concepts like what is AWS EC2 Container Service and AWS Fargate and how to write infrastructure code using Terraform.

Let's get started!

First of all, what is ECS?

Well, EC2 Container Service (ECS) is an AWS service responsible for orchestrating a cluster of Docker containers. It's a high-performance and compelling alternative to Docker Swarm and Kubernetes.

With it, you don't have to install or manage an orchestration software, neither manage or scale virtual machines or containers as it abstracts all of this for you.

Some key concepts surrounding ECS are:

Cluster: a group of EC2 instances where your containers run;
Task Definition: a JSON file that describes one or more containers;
Task: an instantiation of a Task Definition within a Cluster;
Service: it's responsible for instantiating and maintain a given number of Tasks running on your cluster.

"Serverless" containers with Fargate

Initially, you needed to set up a cluster of EC2 instances where your containers did run. You had to select the instance types, manage auto-scaling, and optimize cluster utilization. However, things had changed.

In 2017 AWS introduced Fargate, a compute engine that enables you to run containers without the need to worry about the underlying infrastructure. Now you can set up your ECS cluster without having to manage servers. With Fargate, you only have to think about the containers. It eliminates the need to manage EC2 instances. You no longer have to deal with servers or configurations. Now, you can only focus on the application itself.

Infrastructure-as-Code and Terraform

At this point, you may have noticed that ECS/Fargate are made up of a lot of small parts. Also, it is necessary to provide the whole underlying part of the environment. Here is where Terraform comes in.

Terraform is a tool for building, changing, and versioning infrastructure safely and efficiently. It can manage existing and popular service providers as well as custom in-house solutions. With it, you can describe your infrastructure in configuration files with the advantage to use the same Terraform configuration to set up identical staging, QA, and production environments.

Basic Hello World!

The best way to explain how Terraform works is to show it in action. Let's provision a t2.micro EC2 instance on AWS using Terraform.

I'll to assume that you already have Terraform installed. If you don't have, check their website.

First, create a file called main.tf (you can use whatever name you want) in a directory of your choice (it is your working directory) with the following content:

provider "aws" {
  profile = "default"
  region  = "us-east-1"
}

resource "aws_instance" "webserver" {
  ami           = "ami-2757f631"
  instance_type = "t2.micro"
}

With the file in place, you need to run terraform init to initialize the working directory. It is usually the first step after writing new Terraform code or cloning a new repository, as it downloads all the necessary providers' plugins to provision your infrastructure.

$ terraform init

Initializing the backend...

Initializing provider plugins...
- Checking for available provider plugins...
- Downloading plugin for provider "aws" (terraform-providers/aws) 2.18.0...

Terraform has been successfully initialized!

Great, Terraform has initialized your working directory, and you're ready to go. The next step is to create an execution plan, that is, Terraform will analyze the "current" state of your infrastructure and then determine what is necessary to achieve the "desired" state. It will print all these required actions on the screen for you to review.

$ terraform plan

...

Terraform will perform the following actions:

  # aws_instance.webserver will be created
  + resource "aws_instance" "webserver" {
      + ami                          = "ami-2757f631"
      + instance_type                = "t2.micro"
      ...

Plan: 1 to add, 0 to change, 0 to destroy.

After reviewing the execution plan, it's time to apply those changes. Terraform will print the required actions once again and ask if you want to proceed and perform those actions. Type yes and let it go.

$ terraform apply

...

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

Congratulations! You've provisioned your first resource using Terraform. It is a pretty straightforward example but, imagine provisioning a cluster of EC2 instances, databases, and cache clusters. Or rather, imagine provisioning those same resources for staging, QA, and production environments using the same code. It surely will save much time.

Conclusion

AWS EC2 Container Service and AWS Fargate are practical tools that help you to deploy your dockerized application and, provisioning that infrastructure can be a pretty easy task by writing Terraform configuration files.

In the next blog post, you will see the application I'll deploy and how I have structured it to be able to run it either locally and on the cloud. See you next time!

Forem: Ian Rodrigues

Writing value objects in PHP

Immutability

Structural Equality

Self-Validation

Using with Doctrine

Conclusion

Further Reading

Deploying containers to production with Terraform and AWS Fargate – Containerization

Setting up the local environment

Preparing for production

Deploying containers to production with Terraform and AWS Fargate – Introduction

First of all, what is ECS?

"Serverless" containers with Fargate

Infrastructure-as-Code and Terraform

Basic Hello World!

Conclusion