Forem: AlessandroMinoccheri

8 Code reviews tips and tricks

AlessandroMinoccheri — Tue, 30 Aug 2022 06:31:42 +0000

Code reviews are a largely accepted best practice for software development teams. There are a lot of benefits to using them and there is always something to learn as a reviewer. But adopting from zero code reviews isn’t so easy and immediate.

It’s important to share why they are so important for a team and what are their goals:

Quality control: code reviews can increase the quality because we can find new solutions and improvements
Sharing knowledge: It’s easy to end up in a situation where one developer deals with a certain part of the codebase because they’re most familiar with it. in short-period seems a win but it’s not for the future. When ownership is shared, teams become more motivated and autonomous.
Increasing developer's knowledge: we can learn through code reviews, by asking questions about a piece of code that we don’t understand, or by sharing a different method to solve the problem

So after sharing why code reviews are so important it’s time to understand what are some tips and tricks for using them correctly and take advantage of them.

1 Keep Pull requests small

Keeping the Pull requests smaller as possible allows for the easiest review and, usually, more contribution and focus on it.
If you create a bug pull request with 120 files changed, 12000 lines added and 3500 lines removed it’s very difficult to find problems or better solutions. It’s totally a waste of time reviewing such a big pull request and it takes too many hours for doing it.
For that reason, it’s better to split the pull request into different pull requests with a specific code review.

A SmartBear study of a Cisco Systems programming team revealed that developers should review no more than 200 to 400 lines of code (LOC) at a time because the brain can only effectively process so much information at a time; beyond 400 LOC, the ability to find bugs, defects diminishes.

In practice, a review of 200–400 LOC over 60 to 90 minutes should yield 70–90% defect discovery. So, if 10 defects existed in the code, a properly conducted review would find between 7 and 9 of them.

2 Don’t review for more than 1 hour

Usually, it’s not a best practice to review code too quickly, on the other side you shouldn’t review for too long because performance starts to decrease after about 1 hour.
Our brain needs a break to refresh to have good performance and to review well the code.
It’s important to keep the focus on the review to discover and understand every single part of the pull request.
Doing a superficial review it’s not a good practice and decreases the credibility of the process for the whole team.

3 Add a clear description

To help reviewers to do their job it’s important to add a description to the pull request to share:

which problem are you trying to solve
why did you choose that solution
doubts about something
question about the implementation
…

It’s also important to add a clear description for the future, for example, after some months you would like to understand why that piece of code was added. There are a lot of benefits to adding a clear description!

4 Use Pull Request template

Many tools, like GitHub, provide a template to create Pull Requests, in this way you have a standard and it’s easier to create a new one and review it. If you want to add the template.
GitHub you need to create a new file .github/pull_request_template.md

Github Documentation: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository

Using a template allows the team to create a standard pull request to help each member of the team.

5 Number of reviewers

What is the correct number of accepted reviews to merge a pull request? There isn’t a specific rule again but it’s important to decide it in the team and try to understand what is the correct number.
Usually, you don’t need that every member of the team accepts the pull request, except for some critical features.
Sometimes one or two accepted reviews are good enough to merge the pull request.
Why not everyone?
Because you can create a bottleneck and your deployment can be blocked by some reviewer that didn’t see it already for other reasons.

6 Empathy

Empathy is an important skill during the review.
As a reviewer, you need to understand what the author is trying to solve, what was his thought, and why it’s implemented in this way.
You need to be kind when you comment on the pull request without being rude.
Don’t try to give a new solution, instead ask questions about the implementation like: “Is this the only way to solve the problem?” “It seems a little bit coupled with this code, what do you think? Is there a better way?”

If you liked a piece of code or you learn a new thing write a comment like: “this is perfect, I never thought about it” or “I didn’t know about this function! Amazing, it seems very useful!”
Try to foster a positive code review culture!

7 Delegate static analysis

Using a tool to automate static analysis checks it’s important because during reviews you need to focus on behaviors, business logic, and patterns you don’t have to focus on spaces, missing commas, or things that the static analysis tool can check.
All the automatable static analysis checks should be delegated to these tools during a CD/CI process.
This delegation can save you a lot of time and allows the team to focus on the business logic and the high-level approach to the implementation.

8 Run a retrospective

After a month or two of reviews it’s important to understand if the process is good or not and how can you improve it.
To do it I can suggest running a retrospective to understand it.
It’s important to find an external facilitator so all the team can discuss together what was good and what was not.
There is a lot of different type of retrospectives and the facilitator can use one of them.
Every month or two it’s important to run the retrospective, especially in the early stage of the adoption process, to improve it and create a feedback process for all the team.

Conclusion

Code reviews are a fantastic tool but you need to know how to manage them to get all the benefits.
There is always something to learn and improve in this process to discover with your team and discuss it.
I enjoy creating pull requests and reviewing the code of others, I always learn something and understand other points of view.
Never stop learning.

Add images to a React project with Typescript

AlessandroMinoccheri — Fri, 22 Jul 2022 09:34:23 +0000

In every single project, usually, you need to add an image to your React project to show something or to represent a graph and create a beautiful page for your audience.

Adding an image with React is very simple and fast, this is an example:



import React from "react";
import imageToAdd from "./../assets/images/logo.png";
function YourComponent() {
   return <img src={imageToAdd} alt="Image" />;
}
export default YourComponent;

This works like a charm in a React project built using CRA or Vite.
but if your project has a custom bundler, created using Typescript + Webpack, with the code above you will receive this error:



Cannot find module  './../assets/images/logo.png'

The first time I saw that error, I thought “It’s a bug!”, but after searching and understanding typescript well, I discovered that receiving an error is the correct behavior.

By default in typescript, the module resolution resolves the import using only the files with extension: .ts .tsx or .d.ts and this is the reason why in the previous case the module couldn't be found.

So, how can we fix the problem?
To solve the problem, usually, you have to:

add a directory called types on your project's root
create inside of that folder a file called index.d.ts with the following content



declare module "*.jpg";
declare module "*.png";

N.B. the extension depends on the file type you are adding.

install the file-loader dependence using npm, yarn or pnpm



npm install --save-dev file-loader

update your webpack config file to use the file-loader module like this



...
{ test: /\\.(png|jp(e*)g|svg|gif)$/, use: ['file-loader'], }
...

Then, you can run your application, your build will succeed and your image will appear! 🎩

Server-Sent events with PHP and Symfony

AlessandroMinoccheri — Wed, 25 May 2022 10:05:37 +0000

In the magic world of PHP, there is a library for many things that you don’t know, every day new libraries are born and it’s impossible to know each of them.

For this reason, I try always to follow on Twitter, LinkedIn, and GitHub good developers that are sharing new approaches and libraries.

For one of our customers, we needed an application where the server can send data to all clients.

So we need to build the software with a Server-Sent events approach in a short time to release the product as soon as possible to validate the customer idea.

If you would like more about Server-Sent events, what it means, advantages and limits, you can read my previous article here.

To realize a Server-Sent Events in PHP we found a Symfony library symfony/mercure, I saw this library in some article on LinkedIn and it’s the proof that following the right people can be very important.

How to install it

We can use Flex to install it so, you can write into your CLI:

composer require mercure

After that, you can configure Mercure environment variables into the file: config/packages/mercure.yaml

mercure:  
  hubs:  
    default:  
      url: [https://mercure-hub.example.com/.well-known/mercure](https://mercure-hub.example.com/.well-known/mercure)  
      jwt:  
        secret: '!ChangeMe!'  
        publish: ['foo', '[https://example.com/foo](https://example.com/foo')']  
        subscribe: ['bar', '[https://example.com/bar](https://example.com/bar')']  
        algorithm: 'hmac.sha256'  
        provider: 'My\Provider'  
        factory: 'My\Factory'  
        value: 'my.jwt'

Let me explain what are the values to set into the configuration file:

secret: the key to use to sign the JWT (all other options, besides algorithm, subscribe, and publish will be ignored)

publish: a list of topics to allow publishing when generating the JWT (only usable when secret or factory are provided)

subscribe: a list of topics to allow subscribing to when generating the JWT (only usable when secret, or factory are provided)

algorithm: The algorithm to use to sign the JWT (only usable when the secret is provided)

provider: The ID of service to call to provide the JWT (all other options will be ignored)

factory: The ID of service to call to create the JWT (all other options, besides subscribe, and publish will be ignored)

value: the raw JWT to use (all other options will be ignored)

Automatically inside your .env will be updated with environment variables.

If you are using a Symfony version less than 6, the YAML file doesn’t exist and you need only to configure your environment variables into the .env file like this:

MERCURE_URL=[http://localhost:9090/.well-known/mercure](http://localhost:9090/.well-known/mercure)  
MERCURE_PUBLIC_URL=[http://localhost:9090/.well-known/mercure](http://localhost:9090/.well-known/mercure)  
MERCURE_JWT_SECRET=”JWT-AuctionEngine”

Using a specific Docker container

You can use an official docker for your local environment, with a simple configuration like this:

version: "3.5"
services:  
  mercure:  
    container_name: mercure_sse_poc  
    image: dunglas/mercure  
    environment:  
      SERVER_NAME: ':80'  
      MERCURE_PUBLISHER_JWT_KEY: 'JWT-AuctionEngine'  
      MERCURE_SUBSCRIBER_JWT_KEY: 'JWT-AuctionEngine'  
      MERCURE_CORS_ALLOWED_ORIGINS: '*'  
      MERCURE_EXTRA_DIRECTIVES: |-  
      cors_origins "*"  
      anonymous 1  
    ports:  
      — "9090:80"  
      — "4433:443"

JWT_KEY must be the same as your environment variables, in this little example, I declare that it’s not necessary to be authenticated and you can use Mercure from all domains.

In production, I recommend restricting those parameters to avoid undesired problems.

How to use Symfony/Mercure

To send data to your client you need to instantiate a Mercure object called Update with 2 arguments: the topic name where you want to send your data, and the data encoded.

After that, you can publish your event using an object that implements HubInterface (for this example).

But symfony/mercure has already its implementation so you can use it without writing your implementation.

Here is a little example:

public function send(Request $request, HubInterface $hub): void  
{  
    $update = new Update(  
       'channelname',  
       json_encode([  
           'foo' => 'bar'  
       ], JSON_THROW_ON_ERROR)  
    );  
    $hub->publish($update);  
}

The object Update has different arguments (directly from https://mercure.rocks/spec):

topic: The identifiers of the updated topic. It is RECOMMENDED to use an IRI as an identifier. If this name is present several times, the first occurrence is considered to be the canonical IRI of the topic, and other ones are considered to be alternate IRIs. The hub MUST dispatch this update to subscribers that are subscribed to both canonical or alternate IRIs.

data (optional): the content of the new version of this topic.

private (optional): if this name is set, the update MUST NOT be dispatched to subscribers not authorized to receive it. See authorization. It is recommended to set the value to on but it CAN contain any value including an empty string.

id (optional): the topic’s revision identifier: it will be used as the SSE’s id property. The provided id MUST NOT start with the # character. The provided id SHOULD be a valid IRI. If omitted, the hub MUST generate a valid IRI (RFC3987). A UUID (RFC4122) or a DID MAY be used. Alternatively, the hub MAY generate a relative URI composed of a fragment (starting with #). This is convenient to return an offset or a sequence that is unique for this hub. Even if provided, the hub MAY ignore the id provided by the client and generate its id.

type (optional): the SSE’s event property (a specific event type).

retry (optional): the SSE’s retry property (the reconnection time).

Frontend

The frontend client needs to subscribe to the topic, the following example is a piece of a React component:

const url = '[http://127.0.0.1:9090/.well-known/mercure?topic=auctions-1](http://127.0.0.1:9090/.well-known/mercure?topic=auctions-1`)';  
const eventSource = new EventSource(url);eventSource.onmessage = event => {  
  const results = JSON.parse(event.data);  
  console.log(results);  
}

You can use this code for example in a UseEffect function of React and you are telling that you want to subscribe to the topic auctions-1 and every event sent to that channel you will print it into the console to see what you have received and you can use those data for whatever you want.

What happens?

I have written a little example here to understand well what happens: https://github.com/AlessandroMinoccheri/sse-poc

Now if you clone the repository and follow the instructions to install the backend and frontend you can visit the page: http://localhost:8080/

You can see a simple form to submit a bid offer.

Now, if you open the browser network, select Fetch/XHR (for Chrome), and reload the page you can see a subscription request to a specific topic.

Then, if you insert a number into the text field and click the button to make a bid, you can see in the network tab a new POST request for the bid, but inside the previous request in the tab Events, you can see a new event sent by the server with new information!

So in the same subscription request, we can receive events for the server, for this reason, the Server-Sent events approach is considered a monodirectional communication because is the server that sends data to the client, and the client decides only to subscribe to topics.

If you make other bids you can see in the tab events all data sent from the server in the same HTPP connection.

Subscribe to multiple topics

Is it possible for the client to subscribe to multiple topics? Yes, absolutely, but how?

Well, you can easily do this thing into your frontend app (in this example using React):

const url = '[http://127.0.0.1:9090/.well-known/mercure?topic=auctions-1](http://127.0.0.1:9090/.well-known/mercure?topic=auctions-1`)';  
const eventSource = new EventSource(url);eventSource.onmessage = event => {  
  const results = JSON.parse(event.data);  
  console.log(results);  
}const anotherUrl = '[http://127.0.0.1:9090/.well-known/mercure?topic=anotherTopic](http://127.0.0.1:9090/.well-known/mercure?topic=anotherTopic`)';  
const anotherEventSource = new EventSource(anotherUrl);anotherEventSource.onmessage = event => {  
  const results = JSON.parse(event.data);  
  console.log(results);  
}

You can subscribe to many topics in this way because the server will send data to a specific topic.

You can use this approach to create a private topic for a single user, or group of users to send events only to them.

Asynchronous dispatching

You can write your implementation to dispatch asynchronous events, but this is not recommended because Mercure already sends them asynchronously.

But if you want, you can use Symfony Messenger to dispatch it by yourself.

Let’s see how the previous example could be with your own implementation:

public function send(Request $request, MessageBusInterface $customBus): void  
{  
   $update = new Update(  
      'channelname',  
      json_encode([  
          'foo' => 'bar'  
      ], JSON_THROW_ON_ERROR)  
   );  
   $customBus->publish($update);  
}

As you can see the code doesn’t change, you can use a different implementation.

But remember that Mercure already sends events asynchronously so it depends on you if you want to maintain by yourself the dispatching system.

Use Case Examples

There are many examples of using the Server-Sent events approach.

Imagine that you need to build a stock option client, the frontend application can subscribe to topics to receive data from the server only when a stock quote changes its value.

Or if you need to build a Twitter feed update, the server will send data when to every user (with a custom topic each) with new tweets.

Recently I built a push notification system where clients receive information and updates from the server like the common push notifications app on your phone.

Conclusions

There are a lot of useful resources and examples, in my opinion using symfony/mercure library has simplified my life because in some minutes you can create a system ready to send events to the client without a lot of configurations and code to do.

Using the right tool can be important to the success of the project, but to know it you don’t have to start from the implementation.

Start understanding what is the real problem to solve, I usually do an EventStorming before coding because we need to know the domain and business logic.

After that, you can understand better if Server-Sent Events is the right approach or not.

WebSocket vs Server-Sent events

AlessandroMinoccheri — Fri, 29 Apr 2022 08:25:37 +0000

Usually, I have heard more times the term WebSocket than server-sent events.

The reason could be that WebSocket is used more, but not always is the ideal approach.
Sometimes Server-sent events approach is better to solve problems and create good applications.

It’s very important to understand differences, limits, and ideal cases for both to solve your problem with the right solution.
Sometimes we have a cognitive bias that doesn’t allow us to take the right decision.
Cognitive bias is a systematic error in thinking that occurs when people are processing and interpreting information in the world around them and affects the decisions and judgments that they make.

(Image from https://uxdesign.cc/how-to-improve-experience-design-by-managing-cognitive-biases-d7b360d35b0a)

So, for example, if we have solved a problem using WebSocket, next time with a similar problem we could think that, again, it’s the right approach without considering the big picture, all information about the problem to solve.
For that reason, understanding deeply bot approaches can help us to reduce the cognitive bias and make the best decision.

Let’s try to explain both approaches and their characteristics.

Websocket

It’s a computer communications protocol, that provides full-duplex communication channels over a single TCP connection (Wikipedia). The protocol was standardized in 2011.

The WebSocket approach is used in many contexts and projects because has many benefits and pros in its favor.

Bidirectional communication

The client and server can both send data to the other part.
The client creates a TCP connection to the server and keeps it open as long as needed.
Both server and client can close the connection easily whenever they want.
To exchange data there is a handshake process that verifies the communication, and if it’s all ok, they can exchange data using the custom WebSocket protocol.

(Image from: https://www.onlyfullstack.com/polling-vs-server-sent-events-vs-websocket/)

Advantages

Bidirectional communication in real-time, connections can both send and receive data from the browser(example: chat).
Generally don’t use XmlHttpRequest and headers are not sent every time, so it reduces the expensive data loads being sent to the server.
Can transmit both binary data and UTF-8 format.

Limits

When connections are terminated, WebSocket doesn’t automatically recover them, you need to implement a reconnection system by yourself.
Browsers older than 2011 don’t support WebSocket connections.
Some enterprise firewalls with packet inspection have trouble dealing with WebSocket.
It cannot be placed behind container-based authentication methods with header-based security, it has to be query parameters (or hopefully, a token-based authentication where the token is established outside the WebSocket path).

Ideal cases

Chat: both client and server exchange data to send and receive messages
Multiplayer games
Collaborative editing/coding
Social feeds
Sport updates
… a lot more …

Server-Sent Events

It’s a server push technology enabling a client to receive automatic updates from a server via an HTTP connection.
It was born on September 1, 2006, so it’s been a while since it’s available.
It provides a memory-efficient implementation of XHR streaming.
Unlike a raw XHR connection, which buffers the full received response until the connection is dropped, an SSE connection can discard processed messages without accumulating all of them in memory.

Monodirectional communication

The client sends a request to subscribe to a specific channel and the server will send event/data into that request, so only the server can send data and the client receive automatically those events in the same HTTP connection.

(Image from: https://www.onlyfullstack.com/polling-vs-server-sent-events-vs-websocket/)

Advantages

Transported over simple HTTP instead of a custom protocol
Simpler protocol
Built-in support for re-connection and event-id
No troubles with corporate firewalls doing packet inspection

Limits

It’s limited to UTF-8 and does not support binary data.
When not used over HTTP/2, Server-Sent events approach is subject to limitations with regard to the maximum number of open connections. This can be especially painful when opening various tabs as the limit is per browser and set to a very low number (6).
It’s mono-directional
It doesn’t have native browser support. However, there are available workaround with poly-fill (replicate an API) in Javascript that simulates the SSE functionality to solve this issue. All modern browsers support server-sent events: Firefox 6+, Google Chrome 6+, Opera 11.5+, Safari 5+, Microsoft Edge 79+.

Ideal cases

Stock client updates: the client receives updates from the server when a stock changes its value
Twitter feed updates: the client receives a new tweet every time one is sent
push notifications

Conclusion

In conclusion, both approaches are valid and can be used to build specific software.
Websocket is more used and can be used also to develop an application that can use Server-sent events.
Server-sent Events have fewer ideal cases but for them, it’s very useful with less configuration and less time to create the updating system.

I have used both of them and no one is better than another, it depends on the specific context and what you need at that moment.

Knowing WebSocket and Server-sent events can help you in deciding which approach is better for every application.

How to test Github Actions locally

AlessandroMinoccheri — Mon, 07 Mar 2022 13:34:47 +0000

One of the first things that I do in a project is to create a CD/CI process using Github Actions usually.
Why?
Because I would like to deploy as soon as possible with a process that launches tests for me automatically to understand if I can merge the feature and deploy it.
Nowadays Github Actions has a lot of integrations, tools, and containers to run your application.

But every time you create a Github Actions you need to test it and usually, you try to commit something to trigger it, you are testing manually your CD/CI.
For me it’s like testing my application manually, clicking buttons instead of automatic tests.

For this reason for me, it’s important to test my Github Actions without committing something because it’s not necessary.

Photo by https://www.giuseppemaccario.com/it/wp-content/uploads/2021/10/Continuous-Deployment-con-GitHub-Actions.png

I found this library perfect for testing Github Actions: act.

This library is very useful and easy to use, you can run locally your Github Actions and you have fast feedback on your workflows.

How does it work?

Act simulates the actions we would like to perform in the container of our Github Actions.
It creates a container capable of performing all the steps by properly simulating all the steps.
So we can see all the steps of the Github Actions and their results through simple instruction.

Installation

If you are using Homebrew (Linux, macOS) you can launch this command from your CLI:

brew install act

If you are not using Homebrew I recommend checking the Installation section inside the README file of the project because there are many ways and options to add it.

How to use it

To run the tool you need to write into your CLI:

act

This command runs the default (push) event.
When you run for the first time act, it will ask you to choose an image to be used as default and it will save that information inside the file ~/.actrc that contains configuration flags.

If you want to run a specific event you can launch:

act pull_request

For the specific event, I mean Github Events: https://docs.github.com/en/developers/webhooks-and-events/events/github-event-types

To run a specific job you can launch:

act -j your_job

You can also launch command in dry mode like this:

act -n

Environment variables and Secret variables

Secrets and environment variables saved in GitHub can’t be used by act, but you can pass them and define them locally.

Secrets

act -s KEY=VALUE — To pass secret from CLI
act — secret-file my.secrets — load secrets values from local.secrets file.

Environment variables

act -n KEY=VALUE — To pass environment variable from CLI
act — env-file my.env — load environment variables from local.env file.

Use Case

I have used act many times in these months because I created many Github actions for my projects.
Every time that I change something I tried the action with act.

So, for me, it’s better to test it locally to save a lot of time.
The process could be:

create your first Github Actions
launch act to test changes
improve or fix your Github Actions
launch act to test changes

And then you can iterate until you are satisfied with your Githu Action.

Example

I have created a simple example to test act and you can find it following this link: https://github.com/AlessandroMinoccheri/act-example

It’s a simple example to test act and it took me 2 minutes to install and launch act.
It’s very useful to see the output of your GitHub Actions to understand if it’s all ok or not.

Limit

There are a few limitations by using act (https://github.com/nektos/act#known-issues):

Non-Linux Runners: act can works for Linux runners, not for the others, but it’s a Docker limitation on your workstation. You can work around this by setting DOCKER_HOST before running act, with e.g:

export DOCKER_HOST=$(docker context inspect — format ‘{{.Endpoints.docker.Host}}’)

Default images do not contain intentionally all the tools that GitHub Actions offers by default in their runners.

Conclusion

In my opinion, act can save you a lot of time to test your Github Actions without launching them every time.
It’s very easy and fast to use.
Usually, when you are running act and all it’s fine your Github Actions will not have problems.

2021 Recap and 2022 Goals

AlessandroMinoccheri — Thu, 27 Jan 2022 07:37:19 +0000

At the end of every year usually, I check my goals for the current year and I set them for the next year.
This is an activity that helps me to improve my skill build step by step career.

Building a career it’s difficult sometimes because you don’t know what you want next or what you want to achieve.
For this reason, I take some days to understand it and try to design the next steps for my career.
Sometimes I need to change a lot of things but it’s important to follow our dream.

Remember that a career is more than a job and every company (or most of them) is hiring developers.

So my goals for 2021 were:

read more than 30 books
learn React
5 meetup as a speaker
write at least 5 articles
release phparkitect

Learn React

Another goal for my 2021 was to learn React, and to learn React I meant to write a single page application with components and test obviously.
I have reached the goal before June following some articles and tutorials.
I did an application useful to manage my bank account.

I started watching some tutorials and create my first react Kata project.
A Kata is a project to learn something new without thinking about the idea. You can try new approaches, frameworks, and languages.

My first kata project with React was a simple to-do list where I had to create a list, edit it and view it.
After this, I have complicated the to-do list project with some features to understand well hooks and best practices.

5 meetup as a speaker

In 2021 I did exactly 5 talks:

PugRomagna 2 talks about hexagonal architecture in Symfony and another one about smart working
JUG Milano about hexagonal architecture in Kotlin
Ticino Software Craft about hexagonal architecture in Kotlin
PugRoma about hexagonal architecture

Speaking activities are moments where you share something with other people but you are learning at the same time because you need to study concepts deeply to explain them to others.
It’s important to open your mind to questions and different points of view.
Every time that I did a talk I learned something and I met a lot of clever developers, I recommend to all the developers to try to share their knowledge with others because it’s a moment to network and learn together every time.

Write at least 5 articles

In 2021 I wrote

It was very interesting to write these articles because explaining to others in a fluent and clear article sometimes could be difficult.
I tried to write small articles and answer all their questions.
Sometimes people contact me in private asking for advice or doubts about the article and their projects, and I am very happy to answer them and ask for a different point of view if it’s possible.

Release PHParkitect

The last goal was to release PHPArkitect in 2021.
It’s a library that helps you to keep your PHP codebase coherent and solid, by permitting you to add some architectural constraint check to your workflow.
The team is made up of a couple of people and I am one of them.
We developed the tool all year and we released it to all the world in May.
Nowadays we are working to improve the library day by day and at the moment we are using it in some projects.
I think that there are a lot of features to be done to improve the library.

Feel free to try it and give me feedback, please!

Goals 2022

For 2022 I take some hours and I walk alone to understand what I would like to achieve next year.
Learning sometimes could be easy but focusing on the right things it’s difficult.

I thought about my career path and what I can do in the next years and I understand that this year I would like to:

learn typescript because I think that it could be a good solution for many projects
read books that can help me to improve my hard skill and soft skill. I wrote a list of books that can help me, and these are the first two books that I will read: Clean Craftsmanship, Learning Domain-Driven Design
do at least 3 talks to continue my career as a speaker
write at least 10 articles to share my knowledge and to understand deeply some concepts to share

At the moment these are my goals for 2022, I have scheduled some moments to check every point, and write down a path to achieve them during the year.
It’s important not only to understand your goal but it’s important to measure them and create a path to understand how to achieve them.

To do it you need to ask yourself:

What is the definition of done to understand if this goal is achieved or not?
How can I achieve this goal?

Answering these questions you can understand well your next steps to improve yourself and your career.

Creating your career it’s one of the most difficult things to do because it depends on you usually.
You need to understand where do you want to go and what are next steps to achieve your goals.

It’s a never-ending path but could be amazing, it depends on you!

PHPArkitect: Put your architectural rules under test!

AlessandroMinoccheri — Mon, 03 Jan 2022 10:50:55 +0000

In every project there is at least an architectural rule usually like: every class inside Controller directory should be called with suffix Controller.

I have seen a lot of projects in my career with many different types of rules.
Other examples could be when a team tries to apply the hexagonal architecture and inside the domain, you shouldn’t call external libraries or framework classes (there are exceptions but this is out of scope).

Usually, a team shares those rules during retrospective or dedicated moments to improve the software and to establish rules to follow.
But after some months usually, those rules could be violated by new members of the team or someone that doesn’t remember them.
So the next step is to write down into a README file or in a file all the rules but again they can be violated.

Another good solution is to write ADR: Architectural Decision Records that explain the choice and the reason, but still, they can guarantee that will not be violated.

You need a tool to validate your architectural rules.
PHPArkitect can do it for you.

PHPArkitect is a tool that helps you to keep your PHP codebase coherent and solid, by permitting you to add some architectural constraint check to your workflow.
It was born in 2020 to satisfy the need to respect architectural rules in various projects.
In Java there is a similar tool from which we took inspiration: archunit.

Now PHPArkitect is public and you can find it here

Which problem is trying to solve PHPArkitect?

As I explained before, PHPArkitect was born to help teams to define architectural rules in a project.
With this tool, you can add a new step with it into your continuous integration and you have all your architectural rules in a file, so new developers can understand easily the constraints of the project.

How to install it?

To install PHPArkitect you can use composer launching this command into your CLI:

composer require — dev phparkitect/phparkitect

You can also use a .phar file because you can have some conflicts with one or more of Phparkitect’s dependencies.
The Phar can be downloaded from GitHub:

wget [https://github.com/phparkitect/arkitect/releases/latest/download/phparkitect.phar](https://github.com/phparkitect/arkitect/releases/latest/download/phparkitect.phar)
chmod +x phparkitect.phar
./phparkitect.phar check

How can you use it?

To use PHPArkitect it’s necessary to create a file inside your root called phparkitect.php with your rules written inside it like this:

<?php

declare(strict_types=1);

use Arkitect\ClassSet;
use Arkitect\CLI\Config;
use Arkitect\Expression\ForClasses\HaveNameMatching;
use Arkitect\Expression\ForClasses\ResideInOneOfTheseNamespaces;
use Arkitect\Rules\Rule;

return static function (Config $config): void {
 $classSet = ClassSet::fromDir(__DIR__ . ‘/src’);
 $r1 = Rule::allClasses()
 ->that(new ResideInOneOfTheseNamespaces(‘App\Order\Infrastructure\Controller’))
 ->should(new HaveNameMatching(‘*Controller’))
 ->because(“we want uniform naming”);

$config->add($classSet, $r1);
};

And now you can launch from your CLI the command:

./vendor/bin/phparkitect check

If you want to use a different name for your file you can specify it when you launch the command like this:

./vendor/bin/phparkitect check — config=/project/yourConfigFile.php

What can you do with PHPArkitect?

With this tool, you can write your own rules for your project.
At the moment you can check if a class:

depends on a namespace
extends another class
not extend another class
have a name matching a pattern
not have a name matching a pattern
implements an interface
not implement an interface
depends on a namespace
don’t have dependency outside a namespace
reside in a namespace
not reside in a namespace

Let’s make some examples:

Assume that if you want those classes inside a namespace that doesn’t depend on classes outside that namespace you can write this rule:

$rule = Rule::allClasses()
 ->that(new ResideInOneOfTheseNamespaces(‘App\Catalog\Domain’))
 ->should(new NotHaveDependencyOutsideNamespace(‘App\Catalog\Domain’))
 ->because(‘domain should not have external dependencies’);

If you want to be sure that classes inside a namespace are following certain naming rules you write a rule like this:

$rule = Rule::allClasses()
 ->that(new ResideInOneOfTheseNamespaces(‘App\Order\Infrastructure\Controller’))
 ->should(new HaveNameMatching(‘*Controller’))
 ->because(“we want uniform naming”);

If you want to be sure that all classes that extend a class are following certain naming rules you write a rule like this:

$rule = Rule::allClasses()
 ->that(new Extend(AbstractType::class))
 ->should(new HaveNameMatching(‘*Type’))
 ->because(‘we want uniform form type naming’);

You can also exclude some classes from the rules for example:

$rule = Rule::allClasses()

 ->exclude([‘App\Order\Application\Service\Foo’])

 ->that(new ResideInOneOfTheseNamespaces(‘App\Order\Application\Service’))

 ->should(new HaveNameMatching(‘*Service’))

 ->because(“we want uniform naming”);

How to contribute

PHPArkitect it’s young at the moment and a lot of things could be developed.
If you are interested you can:

try the tool
improve the documentation
try to write your own rule
open pull requests to fix bugs or to discuss new features with a draft
open issues to ask something or to reveal a bug

You can help with a little effort to improve this project and help other developers.

Learning a new programming language

AlessandroMinoccheri — Fri, 05 Nov 2021 08:03:40 +0000

In this period every day, a new programming language could be released and can become one of the most interesting in a few months.
So it’s difficult for a developer to learn every day a new different programming language because you need the time to explore it.
Many times other developers ask me:
“How can I learn a new programming language?”

Well in my opinion there isn’t the perfect recipe to learn a new programming language because it depends principally on how the developer can learn new things.
Some people need to learn from books or others that prefer coding directly etc.

SHU HA RI

Before going deep into the argument, I would like to share the concept of SHU-HA-RI, because I think that it’s important to know when you start to learn something:

Shu-ha-ri is a concept of Japanese martial arts and describes the stages from learning to mastery, therefore a path that involves the presence of a teacher accompanying a student.
This concept was taken into Toyota to indicate the skills development model.

(image from: https://leadagilesolutions.com.au/a-mental-model-for-the-phases-of-mastery/)

Shu-Ha-Ri is a way of thinking about how you learn a technique and can be divided into three steps:

Step one: Shu. The Sensei (the coach) protects the student by showing how to do it, without leaving room for errors and distortions. The practice must be performed as per the manual.
Step Two: Ha. The student, independently, applies the practices respecting the standard. Here the student will be wrong, but he will understand even more.
Step Three: Ri. The student applies the practice in complete autonomy, with strong creativity. He has understood the spirit and no longer feels “bound” by the rules. He might even revise the rules themselves.

This approach can be used in many different scopes: music, martial art, coding…

Usually, when I would like to learn a new programming language I try to follow the Shu-ha-ri approach trying to divide my learning time into different steps:

Read the documentation
Watch videos
Follow people on Twitter that shares context about that language
Find a mentor
Learning by Doing (kata)
Contributing to open-source projects
Teach What You Learn
Be Curious

Read the documentation

Sometimes it’s very annoying to read the documentation of something but don’t under evaluate this step because reading the documentation is the first approach to a new language, to understand how it works, how you can start, what you need in terms of software, tools, libraries.
Reading the “Get started” chapter, usually, helps you to enter into a new world and for me, it’s fantastic to see new things and how their work.

You don’t have to read all the documentation, my advice it’s to read the first parts, to understand how can you start to write something and step by step learn new things.
Sometimes the documentation is not updated or is superficial, feel free to open a pull request or contact the support to improve that part.
This is another good step to participate in something and learn new things.

Watch videos

Nowadays there are a lot of videos about all things.
So it’s very common to find developers that share videos about the language that you would like to learn.
I usually search for many videos or playlists and watch the first minutes to understand if the level of the video is correct or not for me at that moment.
For example, six months ago I studied for a new language and I found an amazing video by an advocate of that language and I stopped that after 3 minutes because the level was too high for me at that moment.
I marked the video as “Watch later” and after two months I saw all the videos understanding all the things.
It depends on your level and skills to find the best videos for that moment for you but believe me, you have a lot of options on the web nowadays to find the best video for you!

Follow people on Twitter that shares context about that language

Twitter is a social network where you can find a lot of developers that share powerful context about everything.
My advice is to search for some developers that frequently share interesting content, and follow them.
The next step is to interact with them to ask something to clarify your doubts.
I have found a lot of kind developers that help me a lot and vice versa.

Find a mentor

Finding a mentor sometimes seems difficult and impossible, but I can guarantee that it could be very easy.
When I have to find a mentor, usually I am thinking of my colleagues or ex-colleagues first because I know already their skills.
If no one has the required skills I am searching on Twitter for example or LinkedIn or participating in community meetings.
When you will find your mentor it’s important to share with him your goals to set up your expectations.
With him, you can establish a study plan to archive your goals.
Once you have specified those things you need to schedule a meeting every one or two weeks with your mentor to check your progress.
Don’t forget to ask a lot of things and thoughts in your mind to understand well what you are doing.

Learning by Doing

Learning by doing it’s one of my favorite steps because I love to touch directly the code and find problems, things not clear and interesting points of view about this new language.
It’s very important to practice a lot to become more confident with the new language.
I usually create Kata projects to make a lot of practice.
Kata means “way of doing” and they are projects that you create yourself to learn something: new coding language, different approaches, architectures, etc.
You can create a new little project and experiment with what you would like to explore.
There are a lot of Kata projects and you can create your own, this is a list of possible kata:
https://project-awesome.org/gamontal/awesome-katas

For example. I did twenty times the Tic-tac-toe game because every time I tried new things and a new way of doing it.

Contributing to open-source projects

Contributing to open-source projects could be another good solution to learn something about what you are studying, you can always ask questions creating issues or pull requests and you can try to create your first pull request starting from fixing some part of the documentation for example.
Open source projects can generate a lot of value and a new strategy to implement something.
You can write to contributors and maintainers to learn new things every day.
Don’t be scared to try something, open source can open to you a lot of doors.

Teach What You Learn

After studying something it’s important to share your knowledge with other developers. Try to teach what you have learned through a little talk with a few people or you can find a local meetup to try your new skills.
When you try to explain something to others you can realize if you know the argument or not, you can realize what you can study and see things from another point of view by answering questions during your talk.
Every time that I did a talk, after that, there were a lot of questions and we discussed those, understanding new approaches.

Be Curious

Every day you can learn something new, there are a lot of resources nowadays.
Now it’s up to you what you want to learn from today.
Be curious about new approaches, technologies, and all the things about your work.
Curiosity helps a developer with learning in two ways. First, it keeps you motivated during learning so you don’t get bored. Second, it highlights new learning opportunities that you would overlook.

Curiosity is what makes great engineers stand out from regular ones.

Push and publish Docker images with GitHub Actions

AlessandroMinoccheri — Sun, 02 May 2021 18:56:06 +0000

In many articles, I mentioned many times about using GitHub Actions because they are a good choice for a lot of reasons.

Nowadays I can admit that there is another choice that I have explored and used a lot these days.
What I mean is the functionality of pushing your docker image through your GitHub Actions during your CI process.

Usually, when I want to publish my docker images to DockerHub, I need to do it manually by the command line, like this:

Building the image

docker image build -t organization/project:0.1.0 .

Publishing to DockerHub

docker push organization/project:0.1.0

It’s not a lot of work, but every time you fix or add a new feature you need to remember to build a new image and publish it.
Usually, I try to avoid manual operations because human error is possible, and automating what is repetitive for me is a best practice everywhere.

So for this reason, in one open-source project Arkitect where I’m contributing nowadays, we have a Dockerfile that needs to be published every time there is a push on master, or a new release comes out.

I can build and publish the Docker image manually every time, but I prefer to avoid this and I have tried exploring GitHub Actions to automate this process.

Exploring GitHub’s actions to automate the process of publishing a docker image to DockerHub was interesting because I found a lot of other interesting GitHub actions and many projects that do the automation that I like.

First of all, I have inserted inside my GitHub project into Settings->Secrets, two important repository secrets:

DOCKERHUB_USERNAME: this is your username on Dockerhub or the name of your organization
DOCKERHUB_TOKEN: this is the token and you can get it going on DockerHub in Account Settings->Security. Here you can generate a new Access Token. You can take the value and put it on GitHub.

Next step, I have created a file for the workflow inside GitHub and named it docker-publish.yml

The file is something like this:

name: Arkitect
on:
  push:
    branches:
      — '*'
    tags:
      — '*'
 pull_request:
jobs:
  publish_docker_images:
    runs-on: ubuntu-latest
    steps:
    — name: Checkout
      uses: actions/checkout@v2
    — name: Docker meta
      id: meta
      uses: crazy-max/ghaction-docker-meta@v2
      with:
        images: phparkitect/phparkitect
        tags: |
          type=raw,value=latest,enable=${{ endsWith(GitHub.ref, 'master') }}
          type=ref,event=tag
        flavor: |
          latest=false
     — name: Login to DockerHub
       if: GitHub.event_name != 'pull_request'
       uses: docker/login-action@v1
       with:
         username: ${{ secrets.DOCKERHUB_USERNAME }}
         password: ${{ secrets.DOCKERHUB_TOKEN }}
     — name: Build and push
       uses: docker/build-push-action@v2
       with:
         context: .
         push: ${{ GitHub.event_name != 'pull_request' }}
         tags: ${{ steps.meta.outputs.tags }}
         labels: ${{ steps.meta.outputs.labels }}

But it’s not enough because this build will only start if the tests pass, so I have moved the content of this file inside my CI process to another workflow called: build.yml. This is the test suite.

So we need to create a new job that depends on the test job, thanks to the keyword “needs”, like this:

name: Arkitect
on:
  push:
    branches:
      — '*'
    tags:
      — '*'
    pull_request:
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    — uses: actions/checkout@v2
    - name: Install PHP
      run : //stuff to install PHP
    - name: Test
      run: ./bin/phpunit
  publish_docker_images:
    needs: build
    runs-on: ubuntu-latest
    if: GitHub.ref == 'refs/heads/master' || GitHub.event_name == 'release'
    steps:
    — name: Checkout
      uses: actions/checkout@v2
    — name: Docker meta
      id: meta
      uses: crazy-max/ghaction-docker-meta@v2
      with:
        images: phparkitect/phparkitect
        tags: |
          type=raw,value=latest,enable=${{ endsWith(GitHub.ref, ‘master’) }}
          type=ref,event=tag
        flavor: |
          latest=false
    — name: Login to DockerHub
      if: GitHub.event_name != 'pull_request'
      uses: docker/login-action@v1
      with:
        username: ${{ secrets.DOCKERHUB_USERNAME }}
        password: ${{ secrets.DOCKERHUB_TOKEN }}
    — name: Build and push
     uses: docker/build-push-action@v2
     with:
       context: .
       push: ${{ GitHub.event_name != 'pull_request' }}
       tags: ${{ steps.meta.outputs.tags }}
       labels: ${{ steps.meta.outputs.labels }}

In this example, as I said before, I have created a new job that depends on the job named “build”.
In this way, if the job named “build” fails, I don’t create a new docker image, because I want to create it only if the tests pass.

I have used these GitHub Actions:
crazy-max/ghaction-docker-meta@v2: it extracts metadata (tags, labels) for Docker.

docker/build-push-action@v2: it builds and pushes Docker images with Buildx with the full support of the features provided by Moby BuildKit builder toolkit.

A condition that I have added to my docker push job is:

if: GitHub.ref == 'refs/heads/master' || GitHub.event_name == 'release'

Because I want to execute this job only:

when there is a push on master
when a new tag is created

This is necessary for me because I don’t want to create a new docker image every time a pull request is created.

When there is a push on master the workflow, create a new docker image with the tag “latest”.
When a new tag is released, the workflow creates a new docker image, with the tag equal to the tag of the project and the tag “latest” is recreated.
In this way, I am sure to publish the last version of the docker image every time with new features or bugs fixed.

In conclusion, using GitHub Actions saves me a lot of time and repetitive work every time I need to publish my docker image for my project.
There are a lot of other processes that can be automated that I would like to explore and try in my projects, so as soon as possible I will publish other articles about this argument.

How dotfiles can save you a lot of time

AlessandroMinoccheri — Mon, 01 Mar 2021 15:29:13 +0000

As a developer, I try to automate and optimize all of my processes and workflow.

Sometimes it’s difficult to understand how you can optimize your work daily life, but for me, one of the best things that can help me a lot is sharing and discussing my ideas, my thoughts, my approaches, and my code with other developers.
Sharing and discussing your leaks with other developers can open your mind to new approaches and fixes.

Every time I try to talk to other developers about a problem, or a doubt, usually, in the end, I feel more conscious about the problem with a new idea in mind to develop.
The discussion can be done asynchronously or synchronously.

For example, a discussion could be synchronous when you are doing pair programming with someone or when you are in a meeting.
For asynchronous discussion, I mean for example: writing your problem in a chat and waiting for an answer from another developer.

Another discussion method could be using pull requests and waiting for other developers that review your code or open a new discussion about it.

All those practices are fine; it depends on the problem and on the team.
But trying to receive feedback about a solution or another point of view about a problem is one of the most important things to do to become better every day.

As a developer usually I work on many projects and sometimes with different machines with different configurations.
I try to understand an efficient way to optimize my work using my configurations wherever I want.

A couple of years ago, while discussing with other developers, I found that many people were sharing their configurations on GitHub.
Inside those repositories, there were configurations, discussions about optimizations, problems solved with bash scripts, and many other useful things.

For this reason, I have created my personal dotfiles repositories, and you can see it here: https://github.com/AlessandroMinoccheri/dotfiles

What is a dotfiles repository?

A dotfiles repository is a set of configurations that can be used, usually, on every Linux or OSX system.
You can change it on your personal computer, or inside a new server and you can always get that repository with your configurations in a few seconds.
My dotfiles repository is evolving day after day because sometimes I fix an issue, I insert a new shortcut, or I install a new useful plugin.
So it’s always in evolution, it depends on what you are using and what is useful for you.

But, pay attention, there are things that you don’t have to commit inside a dotfiles repository like:

passwords
API key
ssh key
…

So don’t commit personal information or secret passwords.
You must commit only things that everyone can see without problems.

My personal dotfiles repository

In my repository I have created some scripts:

./copy_dotfiles.sh

This script is used when you change something inside your shared configuration and you want to commit it into your dotfiles repository.
For example, I copy bash_profile and zsh configurations inside a folder with the same name:

printf “\nCopying profile configuration”
cp ~/.bash_profile bash_profile
printf “\nCopying personal zsh configuration”
cp -rf ~/.zsh/ zsh

After launching the copy script I make a commit with a significant message about the last changes.
Another essential script is:

./install_dotfiles.sh

The script is used when you want to import your configurations inside your actual system.
Example of code inside the script:

printf “\nInstalling profile configuration”
cp -f bash_profile ~/.bash_profile
printf “\nCopying personal zsh configuration”
cp -rf zsh/ ~/.zsh/

In this case, I take directories from my repository and copy those inside the correct path for my system.

Now you can copy and install your configurations whenever and wherever you want.
In my dotfiles repository I have put configurations for:

bash_profile
zsh
nvim
git
oh-my-zsh

As I wrote earlier in this article, sharing and discussing with other people can open your mind to new solutions.
In my case, I optimized a lot of my configurations by reading other dotfiles repositories and asking questions about some things that I couldn’t understand.

Also, it’s a good practice to open issues inside other dotfiles repositories for asking questions, fixing a problem, or asking for clarification.
It’s up to you now, you can create your dotfiles repository and try to share and discuss your configurations with other developers

Please write to me if you have any questions and follow me on Twitter to stay updated with new articles or tips.

Why you should deploy on Friday without fear

AlessandroMinoccheri — Mon, 25 Jan 2021 10:58:15 +0000

I have heard a lot of times: “Don’t deploy on Friday!”

Well, I understand why, but I disagree with 99% of the cases.
To understand my point of view, I would like to share some concepts about software.

I am always trying to create quality code and when I start to work on a legacy project or a starting project, usually I ask the team:
How often do you deploy the software?

Many times when you talk about deploy with developers you can see fear on their faces because sometimes deploying an application can be complicated or very delicate.

I have seen many different types of problems with deployment, and now I can share some stories.

This is a story about a legacy project that takes a lot of data from renewable energy systems every minute and generates a monthly report.
This software is used to understand how much energy is generated and how much clients have to pay.

After the introduction, I was starting to ask something about deploy to the team.

Me: “Well, tell me, How often do you deploy the software?”
Developer: “Uhm, usually once a week but not on Friday! You know, don’t deploy on Friday :)”
Me: “Ok, the frequency could be fine, and how do you deploy your software?”
Developer: “Well, we open our FTPClient and we transfer updated and new files into that, and all it’s done!”

In this example, the deployment frequency could be fine if you don’t make a lot of features or fixes, but in my opinion, the method to deploy manually is wrong because you have to know which files you need to upload or enter into the server to restart a process, for example.

You can make an error because you forget to upload a file or the internet connection goes down when you are uploading files (it happens).
So remove manual processes if it’s possible. It’s ideal to remove all manual processes, if possible.

Now we can explore another story, this story is about a financial project where a team of 5 developers created a lot of features.
Those features are deployed into a test server together, and after the customer approves them, they can deploy all the features to production.

Me: “Well, tell me, how often do you deploy the software?”
Developer: “We deploy our features usually once a month because we need approval from the customer”
Me: “Why does the approval only come once a month?”
Developer: “because the customer can review only twice a month and we develop a lot of features and it takes a long time, and sometimes there are some bugs that need to be solved”

In this example, there is a problem with the quantity of work developed, the approval time, and the frequency of deployment.

To solve this problem I can advise customers to check features every week at least and approve only those features.
When there is approval the team can deploy those features and restart the process.

Try to avoid a long time for the approval to limit errors, deployment frequency, and possible errors in production because if you need to check a lot of features the error % increase because you don’t pay the right attention to each feature.

Remember: small and frequent deployment can reduce errors and wasting time.

There are a lot of other examples but with these two we can now understand some deployment problems.

To avoid these problems we can try to deploy more frequently with continuous integration and continuous delivery.

Continuous integration (CI)

Continuous Integration is a development practice where developers merge code into a repository whenever possible, for example, many times a day.
Every merge is verified by an automated build that can try to understand if there is some problem.

Another advantage of the CI is that you have a solid build process where you trust it to understand if your code can be deployed or not in production. You can reduce or remove the time to check manually your features and reduce integration problems.

How to do it:

every team developer has the source code inside their local machine
when the developer completes a task or an important piece of feature, he commits to a specific branch for the feature
CI whenever a push event is emitted, it runs tests, it runs code analysis
if there is something wrong CI sends a failure message or an email, and the team fixes the problem
if all is okay the code is ready to be deployed

Continuous delivery (CD)

Continuous Delivery is very close to Continuous Integration and usually, it refers to the practice of releasing every time there is a successful build.
When all automated tests are passed, and every check is okay, it’s time to deploy your application automatically.

It’s a set of capabilities that enables us to integrate features, bug fixes, and configuration changes into production in a safe and quick way.
It’s important to understand that it is a culture and all people inside the project are responsible.

We need to work in small batches to reduce errors and become more efficient in delivering value.
Implementing CD means creating different feedback loops for high-quality software to be delivered to users frequently.

Applying continuous integration and continuous delivery to your process can reduce risks and find bugs more quickly.

https://www.slideshare.net/IzzetMustafaiev/fabric8-cicd

Creating a CD / CI culture and process means improving the quality of your software and the health of your teams.

To release your software more frequently, I have seen that limiting the “Work in progress” (WIP) improves your lead time.

By lead time, I mean the time from the moment that you start a feature, to the moment when that feature is released.

Tools

Usually when we have to create a CD/CI build we try to use external services that can be integrated into our process.
In my opinion, it’s important that every team can use its preferred tools for processes because every project is different, so they can need a different process.

The team can choose which software, check, and steps need to be used and implemented for a specific application because it depends on many things.
It’s not important to find the best choice immediately because after each deploy you can ask your team how to improve the process or if there is something wrong.

Sometimes we create little experiments to try new tools, processes, or other things.
Those experiments are small and in time-boxing to understand whether that improvement can be integrated into our process or not.
This enables teams to explore new solutions and improve the quality of the software.

Don’t be afraid of failure because you are trying to improve something in a little experiment without big consequences.

Example of a common CD/CI process in our project

Usually, we create a repository in GitHub.
Each developer has cloned the repository into his local machine and has coded new features into separate branches.

Every time a developer pushes inside a branch we have configured GitHub actions to run several processes like launch tests, run static code analysis

Example of Github actions configuration:

.github/ci.yml

name: ProjectName

on:
  push:
    branches:
      - '*'

  pull_request:
    branches: [ master ]

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2

    - name: Validate composer.json and composer.lock
      run: composer validate

    - name: Cache Composer packages
      id: composer-cache
      uses: actions/cache@v2
      with:
        path: vendor
        key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
        restore-keys: |
          ${{ runner.os }}-php-
    - name: Install dependencies
      #if: steps.composer-cache.outputs.cache-hit != 'true'
      run: composer install --prefer-dist --no-progress

    - name: Coding Standard Checks
      run: ./bin/php-cs-fixer fix --dry-run -v

    - name: Static Analysis
      run: ./bin/psalm

    - name: Test
      run: ./bin/phpunit

With this configuration file, every time a developer pushes on a branch it creates an environment with the latest ubuntu, checkouts the project, launches composer install to install dependencies, and after that, launches tools like php-cs-fixer (for coding standard), psalm (for static analysis) and phpunit (for tests).

If all is okay the branch could be merged into the main branch of the project.

When a branch is merged into the main branch we have created another process to automatically deploy the software with AWS in this project.

With AWS there are many systems to deploy your application and we have chosen for our project: CodeDeploy and CodePipeline.

To create an automatic deployment with these tools, you need to configure them on your AWS account and creates two files. For example:

File: appspec.yml is used to manage each deployment as a series of lifecycle event hooks, which are defined in the file

version: 1.0
os: linux
files:
  - source: /
    destination: /var/www/yourProject/
permissions:
  - object: /var/www/yourProject/var/
    owner: data
    group: data
    mode: 755
    type:
      - directory
hooks:
  BeforeInstall:
    - location: scripts/deploy/before-install-production.sh
      timeout: 180
  AfterInstall:
    - location: scripts/deploy/after-install-production.sh
      timeout: 180
  ValidateService:
    - location: scripts/deploy/validate-service.bat    
      timeout: 900

File: buildspec.yml is a collection of build commands and related settings, in YAML format, that CodeBuild uses to run a build

version: 0.2
phases:
 install:
 pre_build:
   commands:
     - apt-get update -y
     - apt-get install -y software-properties-common
     - add-apt-repository ppa:git-core/ppa -y
     - apt-get update -y
     - apt-get install -y build-essential python-pip git
 build:
   commands:
     - make backend_test_ci
     - make frontend_test_ci

I don’t want to go deep inside AWS processes, I think that I will write another article about that.
I have only shown you some examples to make it explicit that it’s not so difficult to create a CD/CI system with those tools.

Another way to deploy software is to use Kubernetes and deploy the docker images into production, we have used this solution for some projects with success.

All these processes and tools can help you create a solid automated build for your software that you can trust and improve your projects because it enables you to launch tests, static analyses, and other checks asynchronously.
You can improve your project step-by-step and code to create quality software day after day until you can feel comfortable to deploy on Friday without fear because you trust in your build and in your code.

But if you deploy something with an error?

Well, with these tools you can rollback to the previous version in a few moments and try to understand the problem locally if you want.
When you find a build problem (it happens) you should fix it and improve again your build by adding, for example, more checks or other processes and steps to avoid problems.

It’s better to add a check inside a build than to see bugs that appear in many parts of the software.
When you feel confident to deploy every time you want and on Friday also, you can feel less stressed and proud of your build and code.

The deploy frequency is one of the most important things that I try to understand when I analyze a new or legacy projects because it’s a powerful metric that can show you immediately the quality of the software.
In my opinion the deployment process is a mindset and culture that must be embraced and shared by the team.

For these reasons I believe that you should deploy on Friday without fear because if you trust in your code and your build process, it’s very easy to deploy and be calm when new code is going to production.

I can recommend a very interesting book that treats all these and more concepts: Accelerate: The Science of Lean Software and DevOps: Building and Scaling High Performing Technology Organizations.

If you need more help or try to improve or create an automated deploy feel free to contact me or the company where I actually work: Flowing

Deploy a Symfony application with AWS Lambda, a quick guide

AlessandroMinoccheri — Thu, 24 Dec 2020 09:19:42 +0000

When I first heard the word Serverless I thought I would soon lose my job. No more servers, no more code, no more work to do, it's simple, isn't it?

What happened instead is that, like all other back-end developers, I have a new tool to do my job better.

In this article, I will briefly explain what Serverless is and what advantages it brings us. We will see the Bref library and how to deploy a Symfony application on AWS Lambda.

In the next article I will go into the details of the deployment, analyzing the various components involved and proposing solutions and use cases for this architecture.

Let's begin!

What does it mean really serverless?

Serverless is a word that very often may misguide one into thinking that there is no server where the application is running.

Serverless just means that developers don't have to maintain the infrastructure anymore because AWS will take care of it: developers can focus only on the code.

AWS provides a serverless service called Lambda where you can run code without provisioning or managing servers. Lambda is based on two main concepts: functions and events. A function is a piece of code (which can be written using various languages) that performs some sort of operation. An event is something that happened in your infrastructure, for instance:

A file is uploaded on an S3 bucket
A record is inserted in an Amazon DynamoDB table

When an event happens it will trigger the Lambda function and our code will run.

A big advantage of AWS Lambda service is a “pay-per-use” model: you are charged only for the actual compute time used — there is no charge when your code is not running. Let's compare it to a “traditional” EC2 scenario. In the graph below, you can see costs (green areas) are constant during the time: you pay the same amount of money, regardless of the actual use of your servers (blue area).

In a serverless scenario, costs are always tied to the actual use of your infrastructure.

Lambda is a very cheap service: 0,0000002 USD per request (a function run) with the first million requests per month free. This will increase if you need more memory or some other configurations.

When Lambda was released it supported very few languages and PHP wasn't one of them. In December 2018 AWS announced:

“Native PHP support on Lambda wasn't one of those features, but the new AWS Lambda runtime API and layers capabilities give us the ability to build a clean, supportable implementation of PHP on Lambda of our own.”

This means that you can import PHP binaries file into Lambda layer, thus being able to run any PHP code, even your Symfony Application.

PHP binaries need to be created following certain rules. Creating and maintaining those files is a very expensive and time-consuming activity but, lucky for us, Matthieu Napoli has created an open-source library called Bref that helps developers to deploy PHP applications on Lambda.

It provides:

PHP runtimes for AWS Lambda
A library to interface PHP code with Lambda API
Rich documentation
Deployment tools

Image from https://blog.theodo.com/2019/05/serverless-symfony-on-aws-lambda-with-bref/

Requirements

To deploy a Symfony Application into a Lambda with Bref you need:

AWS account with Access Key ID, Secret Access Key
Install and configure the serverless framework
Install and initialize Bref library

The first step is to configure AWS with your command line interface with this command

aws configure

The terminal will ask you to enter the Access Key ID, the Secret Access Key, the default region name and default output format.

Now you need to install the serverless framework, a tool to develop, deploy, test, secure, and monitor your Serverless applications

npm install -g serverless

To use this tool you need to associate your credentials with it by the following command:

serverless config credentials — provider aws — key <key> — secret <secret>

Now your terminal is configured so we can start to work into our Symfony application.

Bref

After you have created and configured your Symfony Application you can install Bref

To install it you need to launch into your command line interface:

composer require bref/bref

Now you need to initialize the project by running

vendor/bin/bref init

When you initialize bref, it creates automatically two files into the project root:

index.php that contains the function code
serverless.yml that contains the configuration for deploying on AWS

Example of standard configuration:

    service: symfony-bref
        provider:
            name: aws
            region: eu-central-1
            runtime: provided
            environment:
                APP_ENV: prod
        plugins:
            - ./vendor/bref/bref
        functions:
            api:
            handler: public/index.php
            description: ''
            timeout: 30 # in seconds (API Gateway has a timeout of 30 seconds)
            layers:
            - ${bref:layer.php-73-fpm}
            events:
            - http: 'ANY /'
            - http: 'ANY /{proxy+}'

Usually, you have to add the environment with APP_ENV and change the region name.

Configure serverless to deploy your Symfony application

Before doing it, it's important to understand why the serverless framework can help us.

Some months ago bref make the deploy with AWS SAM an open-source framework that you can use to build serverless applications on AWS, it's a tool for CloudFormation with a not simple configuration.

AWS SAM has:

Template specification
Command-line interface

This is a standard SAM configuration:

    AWSTemplateFormatVersion: '2010–09–09'
    Transform: AWS::Serverless-2016–10–31
    Description: 'Symfony test'
    Resources:
        MyFunction:
        Type: AWS::Serverless::Function
        Properties:
        FunctionName: 'symfony-test'
        Description: ''
        CodeUri: .
        Handler: public/index.php
        Timeout: 30 # in seconds (API Gateway has a timeout of 30 seconds)
        MemorySize: 1024 # The memory size is related to the pricing and CPU power
        Runtime1sw: provided
        Layers:
            - 'arn:aws:lambda:eu-central-1:209497400698:layer:php-73-fpm:7'
        Events:
            # The function will match all HTTP URLs
            HttpRoot:
            Type: Api
            Properties:
            Path: /
            Method: ANY
            HttpSubPaths:
            Type: Api
            Properties:
            Path: /{proxy+}
            Method: ANY
        Environment:
            Variables:
            MY_CUSTOM_ENV_VARIABLES: 'this is my custom env variables'
            AWS_ENV_VARIABLES: '{{resolve:ssm:/env-aws-variable:1}}'
    # Outputs show up in the CloudFormation dashboard
        Outputs:
            DemoHttpApi:
            Description: 'URL of our function in the *Prod* environment'
            Value: !Sub 'https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/'

The configuration is more complex and longer than serverless framework configuration.

In serverless framework you can add SAM configuration for complex configuration and another advantage of serverless framework is the multi-provider: you can use it for AWS or Azure or other providers without changing the configuration. AWS SAM is only for AWS.

For these reasons, Bref community decided to switch from AWS SAM to serverless framework.

To start your deploy you need to install Composer dependencies optimized for production launching this command into your CLI:

composer install --optimize-autoloader --no-dev

Now launching this command you will deploy your application:

serverless deploy

Now some subroutines start and in the end, you can see a link, if you click on it you can see your application works!

What really happened?

When you deploy into a Lambda service you will do it through a CloudFormation stack.

A stack is simply a group of service that composes an application, for example:

Databases
S3 Buckets

The serverless framework translates configuration from serverless.yaml file and creates an AWS CloudFormation template from it.

Based on that template, a stack is created (if needed), with no resources except for an S3 Bucket used to store your code as a zip file.

Lambda will get the new code, unzip it and replace the older code.

Serverless framework optimizes these operations by comparing hashes of the files and performing a new deploy only if needed.

That's it, simple as promised, a Symfony application deployed on Lambda.
In the next article, I'll tackle some issues like Symfony tweaks, use of environment variable and trigger upon events.

Forem: AlessandroMinoccheri

8 Code reviews tips and tricks

1 Keep Pull requests small

2 Don’t review for more than 1 hour

3 Add a clear description

4 Use Pull Request template

5 Number of reviewers

6 Empathy

7 Delegate static analysis

8 Run a retrospective

Conclusion

Add images to a React project with Typescript

Server-Sent events with PHP and Symfony

How to install it

Using a specific Docker container

How to use Symfony/Mercure

Frontend

What happens?

Subscribe to multiple topics

Asynchronous dispatching

Use Case Examples

Conclusions

WebSocket vs Server-Sent events

Websocket

Bidirectional communication

Advantages

Limits

Ideal cases

Server-Sent Events

Monodirectional communication

Advantages

Limits

Ideal cases

Conclusion

How to test Github Actions locally

How does it work?

Installation

How to use it

Environment variables and Secret variables

Secrets

Environment variables

Use Case

Example

Limit

Conclusion

2021 Recap and 2022 Goals

Read more than 30 books

Learn React

5 meetup as a speaker

Write at least 5 articles

Release PHParkitect

Goals 2022

PHPArkitect: Put your architectural rules under test!

Which problem is trying to solve PHPArkitect?

How to install it?

How can you use it?

What can you do with PHPArkitect?

How to contribute

Learning a new programming language

SHU HA RI

Read the documentation

Watch videos

Follow people on Twitter that shares context about that language

Find a mentor

Learning by Doing

Contributing to open-source projects

Teach What You Learn

Be Curious

Push and publish Docker images with GitHub Actions

How dotfiles can save you a lot of time

What is a dotfiles repository?

My personal dotfiles repository

Why you should deploy on Friday without fear

Continuous integration (CI)

Continuous delivery (CD)

Tools

Example of a common CD/CI process in our project

But if you deploy something with an error?

Deploy a Symfony application with AWS Lambda, a quick guide

What does it mean really serverless?