Forem: Elijah Zobenko

Event Observer Pattern in Go

Elijah Zobenko — Tue, 18 Apr 2023 12:01:53 +0000

The Observer - is a behavioral design pattern that allows an object, called the subject, to notify a list of observers or subscribers about any changes to its state. In Go, this pattern can be used to maintain loosely coupled relationships between objects.

In a nut shell

The Observer Design Pattern is a great way to design a system where an object can notify a set of observers when its state changes. It's especially useful when we want to decouple objects that depend on each other. In Go, this pattern can be used to maintain loosely coupled relationships between objects. This pattern is part of the GoF patterns, which are a set of design patterns described by Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides in their book "Design Patterns: Elements of Reusable Object-Oriented Software".

In the Observer Design Pattern, the subject maintains a list of observers and notifies them when its state changes. The observers register with the subject to receive notifications, and the subject notifies the observers by calling their update method.

Why do we need it

The Observer Design Pattern is useful in several scenarios, including:

When there is a one-to-many relationship between objects, and a change to one object requires changes to other objects.
When an object should be able to notify other objects without making assumptions about who these objects are.
When an object should be able to notify other objects without knowing anything about them.

How can it help us

Observer Design Pattern solves several problems, including:

It reduces the coupling between objects.
It allows for better separation of concerns.
It promotes reusable code.

What to use

Several packages can simplify the implementation of the Observer Design Pattern in Go, including:

RxGo

github.com/reactivex/rxgo/v2 package provides a set of operators to work with observable streams in a similar way to ReactiveX libraries, allowing to easily implement the Observer Design Pattern in Go.

RxGo is a Go implementation of ReactiveX, which is a library for composing asynchronous and event-based programs. It provides a set of operators to work with observable streams, which are sequences of events that can be observed by multiple observers. RxGo allows developers to write code that is declarative, composable, and reusable.

Here is an example of how to use RxGo to implement the Observer Design Pattern in Go:

package main

import (
    "context"
    "fmt"

    "github.com/reactivex/rxgo/v2"
)

type Observer struct{}

func (o Observer) OnNext(item interface{}) {
    fmt.Printf("Received: %v\\n", item)
}

func (o Observer) OnError(err error) {
    fmt.Printf("Error: %v\\n", err)
}

func (o Observer) OnCompleted() {
    fmt.Println("Done!")
}

func main() {
    observable := rxgo.Just("Hello, dev.to!")
    _ = observable.Subscribe(context.Background(), Observer{})
}

In this example, we define an observer Observer that implements the rxgo.Observer interface. We then create an observable observable using the rxgo.Just method and subscribe to it using the Subscribe method. When the observable emits a value, the observer's OnNext method is called with that value. If the observable encounters an error, the observer's OnError method is called with that error. Finally, when the observable completes, the observer's OnCompleted method is called.

Go Cloud Pub/Sub

github.com/google/go-cloud/pubsub package provides a set of interfaces and tools to work with publish/subscribe messaging. This package allows easy communication between independent components by decoupling the sender and the receiver.

Go Cloud Pub/Sub is a set of libraries and tools for building cloud-native applications. It provides a set of interfaces and tools to work with publish/subscribe messaging, which allows for easy communication between independent components by decoupling the sender and the receiver.

Here is an example of how to use Go Cloud Pub/Sub to implement the Observer Design Pattern in Go:

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    "github.com/google/go-cloud/pubsub"
)

func main() {
    ctx := context.Background()

    // Create a Pub/Sub topic.
    topic, err := pubsub.OpenTopic(ctx, "dev-to-topic")
    if err != nil {
        log.Fatal(err)
    }

    // Create a Pub/Sub subscription.
    subscription, err := pubsub.OpenSubscription(ctx, "some-subscription")
    if err != nil {
        log.Fatal(err)
    }

    // Publish a message to the topic.
    msg := &pubsub.Message{
        Body: []byte("Hello, dev.to!"),
        Metadata: map[string]string{
            "key": "value",
        },
    }
    if err := topic.Send(ctx, msg); err != nil {
        log.Fatal(err)
    }

    // Receive the message from the subscription.
    ctx, cancel := context.WithTimeout(ctx, time.Second)
    defer cancel()
    receivedMsg, err := subscription.Receive(ctx)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Received: %s\\n", receivedMsg.Body)

    // Acknowledge the message.
    receivedMsg.Ack()

    // Close the subscription and topic.
    if err := subscription.Shutdown(ctx); err != nil {
        log.Fatal(err)
    }
    if err := topic.Shutdown(ctx); err != nil {
        log.Fatal(err)
    }
}

In this example, we create a Pub/Sub topic and subscription using the pubsub.OpenTopic and pubsub.OpenSubscription methods. We then publish a message to the topic using the topic.Send method. Finally, we receive the message from the subscription using the subscription.Receive method and acknowledge it using the msg2.Ack method.

Watermill

github.com/ThreeDotsLabs/watermill package provides a framework for building event-driven applications. It allows easy communication between independent components by decoupling the sender and the receiver.

Watermill is a Go library for building event-driven applications. It provides a framework for building event-driven applications and allows for easy communication between independent components by decoupling the sender and the receiver.

Here is an example of how to use Watermill to implement the Observer Design Pattern in Go:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/ThreeDotsLabs/watermill"
    "github.com/ThreeDotsLabs/watermill/message"
)

func main() {
    logger := watermill.NewStdLogger(false, true)

    // Create a new router.
    router, err := message.NewRouter(message.RouterConfig{}, logger)
    if err != nil {
        log.Fatal(err)
    }

    // Create a new publisher.
    publisher, err := message.NewPublisher(message.PublisherConfig{}, logger)
    if err != nil {
        log.Fatal(err)
    }

    // Subscribe to a topic.
    topic := "my-topic"
    subscriber, err := router.AddNoPublisherHandler(
        "my-subscriber",
        topic,
        func(msg *message.Message) error {
            fmt.Printf("Received: %s\\n", msg.Payload)
            return nil
        },
    )
    if err != nil {
        log.Fatal(err)
    }

    // Publish a message to the topic.
    msg := message.NewMessage(watermill.NewUUID(), []byte("Hello, dev.to!"))
    if err := publisher.Publish(topic, msg); err != nil {
        log.Fatal(err)
    }

    // Wait for the message to be processed.
    if err := subscriber.AwaitClose(); err != nil {
        log.Fatal(err)
    }
}

In this example, we create a new router and publisher using the message.NewRouter and message.NewPublisher methods. We then subscribe to a topic using the router.AddNoPublisherHandler method and publish a message to the topic using the publisher.Publish method. Finally, we wait for the message to be processed using the subscriber.AwaitClose method.

Conclusion

The Observer Design Pattern is a powerful tool that can be used to maintain loosely coupled relationships between objects in Go. By using packages like github.com/reactivex/rxgo/v2, github.com/google/go-cloud/pubsub, and github.com/ThreeDotsLabs/watermill, we can simplify the implementation of this pattern and create reusable, modular code. Happy coding!

PHP. Introduction

Elijah Zobenko — Tue, 02 Aug 2022 19:10:00 +0000

Personally, I hate introduction articles and lessons. It's usually covers really fundamental things which are known by many of us. But I understand that it's still important for those, who just begun learning a new tool. That's why it's here. But to save your time, here's what we gonna discuss in this article...

We'll get acquainted with the features of the PHP programming language, areas of application and principles of client-server interaction;
Find out what data types exist in PHP and how they interact with each other;
Learn how to use some language functions (readline, echo, var_dump);
Write and run our first PHP script.

Theory

What's PHP?

PHP is an interpreted general—purpose server-side programming language. It is one of the most popular web development tools, for which it was originally created. About 80% of all Internet websites are written on it and this value has not been decreasing for many years. The language is actively developing and new versions are regularly published, but this article series are dedicated to the version of the interpreter 7.4.

Where we can apply it?

Despite the fact that most of the Internet sites are written in PHP, the scope of its application is by no means limited to the Web, but it probably best reveals the potential of the language. The language can become a useful tool in the development of automation scripts, deferred tasks, or even as a backend part for a Desktop application.

Important! Considering the main area of application (web development), it is worth noting a very important detail: PHP is a server-side programming language. This means that the code is executed on a remote machine, and not in the user's browser. Therefore, it cannot be downloaded or affected by its operation. This gives certain advantages that determine the reasons for dividing website development into backend and frontend parts.

The principle of request processing

To understand as clearly as possible exactly how PHP works and at what exact moment it is used, consider an example familiar to everyone: visiting a web page.

Imagine that we open the browser and enter in the url input: https://dev.to/t/php. At this moment, a request is sent to the server. What is this request? It's says something like: "Server, please give me the content for the page dev.to/t/php". And the server will respond with large and understandable for the browser HTML. To the user, this process usually seems very simple and fast, but, in fact, in the interval between receiving a request and issuing a response, there are a lot of different processes necessary to form the final HTML page. These processes are performed by PHP or another server language.

If you have worked with HTML before, you may have a question, what, in fact, is the difference between the response generated by PHP and the usual request for an HTML document. The difference lies in the dynamism of the data. In the same example with dev.to, although it may seem that the data is static and does not change, there is a lot of "magic" performed by the interpreter, for example:

Fetching information from the database or search engine;
Getting a translation data;
Checking whether the user is authorized and with what accesses;
Fetching discussions and users to follow;
and so on...

This is just an example of operations that could be performed during our short communication with the server, and they demonstrate the main difference from working with a regular HTML document.

Important! Although PHP was created as a tool for generating dynamic HTML pages, this is far from the only response format available to us in our work. In large modern projects, it is more common to find a situation when small blocks of information in JSON format are returned in response to requests, which are further processed in the user's browser using JavaScript.

Types of requests

In the example we considered, we, using a browser, "asked" the server to give us a page at a certain address, but the use of the Internet is not limited to page requests. Very often we need to send some data to the server, for example, a login and password for authorization, or an address for pizza delivery. For such cases, special types of requests are provided, and in order to delve into the understanding of the principle of client-server interaction over the HTTP protocol, let's look at the most common of them:

GET is the most common type of request, used to get some information. Usually, it depends on the requested URL. Example: you just visit the page dev.to, the browser sends a GET request to display it;
POST is the next most frequently used type. It is used in cases when we want to send some information to the server. Example: We wrote a comment under a friend's photo. When the "Send" button is pressed, a POST request will be sent with the text of our comment. Just like GET, it relies on the URL, but in addition it very often uses the request body. In the example with the comment, the text we entered under the friend's photo would be passed in the request body.

In addition to GET and POST, the DELETE (deleting information) and PUT (updating data, but often replaced with POST) methods are also very often used, but we will not need them within this article series.

Important! In fact, all HTTP methods support the transmission of the request body, but it is highly discouraged to use such an approach when working with the GET type.

What a PHP script looks like

A standard PHP script is a plain text file with the extension *.php. On a computer, it can be opened and edited in any text editor.

The code in such files is very often a mixture of HTML markup with PHP separated by special tags: <?php - to indicate the beginning of PHP code, and ?> to indicate the end.

<body>
    <p>This is the plain and simple HTML part. It will be ignored by the PHP interpreter</p>

    <strong>
        <?php
            echo('Everything between <?php and ?> is a PHP code', "\n");
            echo('The interpreter will run it and paste the result here', "\n");
        ?>
    </strong>

</body>

If you run this code snippet, the interpreter will execute only the part that is between the PHP tags (<?php and ?>). The rest of the HTML/text will be output unchanged, in the order in which it is in the file.

Thus, the result of processing will be the following HTML fragment:

<body>
    <p>This is the plain and simple HTML part. It will be ignored by the PHP interpreter</p>

    <strong>
        Everything between <?php and ?> is a PHP code
        The interpreter will run it and paste the result here
    </strong>

</body>

PHP inherits the style of the code from its C-like counterparts. Therefore, after each described instruction, it is necessary to put a semicolon. Otherwise, the code cannot be executed.

It is very important to understand that an interpreter is required to execute PHP code. This means that if you just open the file using a browser, you will see its contents, not the result of execution. For the code to work in the browser, you will need a configured web server. It can be one of many available solutions, for example, Nginx, Apache, PHP-FPM, an embedded PHP server, or even a combination of solutions. You can also execute the code by running it from the command line using the same interpreter. For example, on a Windows computer, you can execute the code with the command php.exe script.php where script.php – is the name of your PHP file.

Important! In the first several articles of this series, we will run PHP code from the command line, developing console applications/scripts, without affecting the work through the web server for some time. This will allow you to start implementing your ideas and practical tasks much faster.

Our first PHP script

Now that we have gotten acquainted with what a PHP script is, let's figure out how PHP files are created and how they are run from the command line.

We can use any text editor to write PHP code, but it's highly recommended to draw attention to the one of the IDE's, as VS Code or PHPStorm.

New project with PHPStorm

Launch the IDE and create a new project "PHP Empty Project". Specify any directory convenient for you as the path.

After the project is created, pay attention to the area "Project" (By default located on the left side of PhpStorm). Project files are managed in this area. To create a new script, right-click on the project name (in our case, it's PHP_1_1) and select New -> PHP File.

Enter the script file name and click OK. In fact, when working with PHP from the command line, the file name does not matter at all, but in order to speak the "same language", let's name the file as "script.php".

When the file is created, PhpStorm will automatically open it. You may notice that the PHP opening tag is already present, thanks to IDE for that.

Running script

There is a solid tradition in the programming world that the first program should be "Hello, world". We will follow this rule.

To do this, in our new file script.php enter the following code:

<?php

echo("Hello, world!\n");

The entered code should output the message "Hello, world" to the console. A special construction echo is used for this. We will get to know it a little later in this article. For now, it's enough to make sure that our code is executed.

Now, to run the script, use the terminal built into PhpStorm. Usually, it can be found at the bottom of the program window, but if for some reason it is not there, you can use the menu View -> Tool Windows -> Terminal. In the terminal window that appears, type the following command and press Enter:

php script.php

If all actions are performed correctly, you should see the line "Hello, world!" in the command line.

Data types

Variables are perhaps the most basic part of any programming language. So let's start our acquaintance with PHP with them.

Variables are a kind of containers capable of storing information of different types. They are used everywhere and in PHP are always indicated by the dollar symbol ($) at the beginning.

<?php

$someVariable = 1;

Variables can be of different types, and in PHP this is determined by what value they are initialized with. The following types are most commonly used:

Bool or Boolean — true or false, zero or one, signal or no signal. The most basic type that has an analogy in any programming language;
Integer — type for integer numbers. It can contain both positive and negative values;
Float — used when working with floating-point numbers. It can contain both integer and fractional values.;
String — string or character. Allows you to work with text;
NULL — a type indicating the absence of a value;

In addition to the listed data types, arrays, objects, resources and links are very often used, but we will talk about them in the following articles.

When creating a variable, you must follow certain rules:

The variable is declared with the dollar symbol ($);
It can contain uppercase and lowercase letters, underscores, and numbers in its name;
The variable name cannot start with a number.

Also, while working with variables, two simple functions will be very useful to us:

var_dump — outputs the type of the variable, as well as its value;
echo — outputs the value of the variable.

We will talk about functions in detail in the following articles, but for now, the main thing is to know that a function is a specific programming language command that performs any useful actions. To use them, write the function name and parentheses at the end. Don't forget to put a semicolon.

Values or variables that are inside parentheses are called function arguments. They are needed to specify/transmit the data required by the function to work. echo and var_dump can take as many arguments as your want, but they require at least one. Here is an example of using these tools:

<?php

echo(100);
var_dump(500);

Now that we know how to declare a variable, check its type and value, let's take a closer look at the possible data types.

Numbers and its operations

There are many situations when we need to work with numbers. Whether it's calculating the cost of goods in the cart, estimating any probability, or even just working with phone numbers. Numbers surround us, and this makes this type of variable one of the most common.

There are two basic numeric types in PHP: integer (integer/int) and floating point (float). Declaring them differs only in the value that you pass.

Important! Here and further along the code you can find explanatory lines starting with the double "slash" character ( // ). Such lines are comments. They serve solely to give hints or explanations. The PHP interpreter ignores them.

<?php

$someInteger = 5; // Common integer number
$someFloat = 1.5; // A number with a floating point. 
// The only difference they have is the dot in the $someFloat value

// To create float var with "integer" value, we can do:
$anotherFloat = 5.0;

var_dump($someInteger, $someFloat, $anotherFloat);
//int(5)
//float(1.5)
//float(5)

Of course, we can perform arithmetic operations on numbers of any type.

To add values, we use plus ("+"). For subtraction, respectively, minus ("-").

<?php
$sum = 50 + 15.4; // float(65.4)
$diff = $sum - 0.4; // float(65)

// But if we work with integer numbers...
$sum = 50 + 5; // int(55) - We get integer as the result
$diff = $sum - 10; // int(45)

The asterisk ("*") and backslash ("/") symbols are used for multiplication and division, respectively

<?php

$multiplied = 100500 * 2; // int(201000)
$divided = 100500 / 300; // int(335)

5 * 2.5; // float(12.5)

Exponentiation is performed using a double asterisk ("**"), but, most often, you can find an implementation through a special pow() function.

<?php

2**10; // int(1024)
pow(2, 10) // int(1024)

Another very useful operation applied to numbers is getting the remainder of the division (division modulo). Imagine that you need to determine whether the number is even or not. This can be done by dividing it by 2. If there is no remainder, the number is even, and the remainder is odd. Such operations are performed using the "percentage" operator. It looks like this:

<?php

$even = 26 % 2; // int(0)
$odd = 27 % 2; // int(1)

Very often there are cases when we perform some arithmetic operation on the value of a variable, and then immediately write the result of the calculation to the same variable. The code for such situations may look like this:

<?php

$someVariable = 10; // int(10)
$someVariable = $someVariable + 50; // int(60)
$someVariable = $someVariable - 20; // int(40)

But it can be optimized using a shortened form of arithmetic operations.

<?php

$someVariable = 10; // int(10)
$someVariable += 50; // int(60)
$someVariable -= 20; // int(40)

$other = 0; // int(0)
$other += 5; // int(5)
$other -= 2; // int(3) 
$other *= 6; // int(18)
$other /= 9; // int(2)
$other %= 2; // int(0)

// We also have a shorter version for +1

$someVariable++; // Same as $someVariable += 1; 
// Or $someVariable = $someVariable + 1;

$someVariable--; // Same as $someVariable -= 1;
// Or $someVariable = $someVariable - 1;

Strings

Strings are a special data type that allows you to store individual characters, whole sentences of text, or arbitrary character sequences. To create a string variable, initialize it with a value in single or double quotes.

<?php

$newVariable = 'Hello, world';
var_dump($newVariable); //string(12) "Hello, world"

An important difference in the approach to working with strings in PHP from other languages is the method of the concatenation of strings. The dot symbol is used for this.

<?php

$name = 'John';
'Hello, my name is ' . $name; // "Hello, my name is John"

Strings support control constructs. This means that you can specify, for example, a line break by specifying the sequence "\n" in it.

<?php

echo "We have a city\nto burn";

// We have a city
// to burn

Despite the fact that the control construction in this example merges with the word "to", the correct division of the sentence into two lines will occur.

Most often you will have to work with the following types of sequences:

\n – Line break
\t – Horizontal tab character
\$ – Displays the dollar sign
\” or \’ – Outputs a double or single quote character, respectively
\\ – Outputs a backslash

Now let's talk about the differences between declaring strings in single and double quotes.

All the sequences discussed above (except for the escaped output of quotes \” and \’) work only when declared in double-quotes. This is the main difference: single ones are used to output strings "as is", without performing any additional processing inside, and double ones support additional string parsing.

In addition to sequences, variables can be used in a string with double quotes.

<?php

$object = 'airplane';

var_dump("$object is the value of \$object variable");
// string(41) "airplane is the value of $object variable"

At the same time, if you do all the same actions, but in single quotes, the result will be different:

<?php

$object = 'airplane';

var_dump('$object is the value of \$object variable');
// string(41) "$object is the value of \$object variable"

Since the interpreter performs additional computational operations on strings in double quotes, in cases where the string does not contain control sequences or variables, it is worth using a single quote. The reverse situation will not cause any errors and warnings, but this rule is very often used in professional development.

NULL

Null is both the type and the only value of this type. Means no value. A variable gets null as a value in only three cases:

When it is explicitly set to null ($variable = null;);
When a variable is created, but the value has not been set;
When the variable is not created or deleted.

This type can be useful when working with functions. We'll get to know them later, but for now, it's just important to understand what null is and where it comes from.

Type cast

PHP is a dynamic typing language. This means that the interpreter tries to perform self-automatic type conversion in those situations when it is required. Example:

<?php

$stringNumber = "150";
$integerNumber = 75;

var_dump($stringNumber + $integerNumber); // int(225)

In this example, we are trying to add an integer 75 with a lowercase 150. Perhaps this is due to dynamic typing. PHP understands that actions are performed on numbers (remember, we use the dot symbol to add strings. If there is a "+" symbol here, then we add up the numbers) and converts the string "150" into a regular number.

This also works in the opposite direction. If we replace the addition operation with string concatenation, we get a different result:

<?php

$stringNumber = "150";
$integerNumber = 75;

var_dump($stringNumber . $integerNumber); // string(5) "15075"

We can perform such transformations not only in the context of operations but also independently in arbitrary places of the code. This transformation is called a custom. This is done as follows:

<?php

$floatVariable = 5.16;
$integerVariable = (int)$floatVariable; // int(5)
(bool)$floatVariable; // true
(string)$integerVariable; // string(1) "5"

Despite the fact that the language performs a lot of transformations and makes development quite simple and fast, try not to rely too much on dynamic typing. This does not mean that it is necessary to cast all variables, but try to avoid moments when, for example, you had a variable with a value of type bool, and you overwritten a string into it. The stricter your approach to the code, the higher your skills will be valued.

Boolean

The simplest and most common type is Boolean or bool. It is used to express truth and can contain only two values: true and false.

A variable of this type is declared, as usual in PHP, simply by setting the required value:

<?php

$someBoolean = true;

var_dump($someBoolean); // bool(true)

Similar values, like any other logical expressions, can be inverted – converted to the opposite. To do this, use the exclamation mark symbol at the beginning of the expression.

<?php

$someBoolean = true; 

var_dump($someBoolean); // bool(true)
var_dump(!$someBoolean); // bool(false)

In addition to explicitly declaring a value, numerical comparisons can be applied:

<?php

$number = 5;
$number > 10; // Will be true, if $number value greater than 10. Else it will be `false`. In this case - false
$number <= 5; // true, if $number value less than 10 or equal to it.
// In this case it's true
$number < 5; // false
$number >= 2; // true

Also we can perform equivalence reconciliation. To do this, a special operator is used — double equal sign (==). In cases where the values are the same, we will get true in the result, otherwise false.

<?php

$isEqual = 5 == 5; // true
5 == 4; // false
false == false; // true
true == !false; // true

Of course, if there is an equivalence comparison (equality of values), there is also a check for their difference from each other. To do this, an inverted version is used, consisting of the characters exclamation mark and equals (!=). Consider a usage example:

<?php

true != false; // true
2 + 2 != 5; // true
2 + 2 != 4; // false

Important! Double equals is a "soft" equivalence check. Therefore, if you, for example, compare the number 5 and the lowercase value "5", you will get "true" as a result. This happens because PHP tries to bring the values to a single type and turns the string "5" into a regular number and compares them already. If you want to make a strict comparison involving type checking, use triple equals (===).

<?php

var_dump(5 == "5"); // bool(true)
var_dump(5 === "5"); // bool(false)
var_dump("false" == true); // bool(true)

Pay special attention to the last example "false" == true. The result of such a comparison is true, all for the same reason. PHP tries to convert the string value "false" to a Boolean type and gets true as a result. Therefore, in the end, the comparison looks like true == true.

User Interaction

Data output to the console

We have already got acquainted with the echo function and you may have noticed that in some cases we do not call it a function, but a construction. This is an important feature of echo, which allows you to use it not only with parentheses, but also without them

<?php

echo("Hello, World\n");
// can be replaced with
echo "Hello, World\n";

The second version of the record is used much more often. In the following examples, we will use exactly this option.
In addition to echo, PHP provides another output function to the console — print. The method of using it is very similar to the functional style of echo:

<?php

print("Hello, World\n");

There are some differences between these two tools, despite their similarity:

echo can accept any number of arguments for output, print accepts only one;
echo does not return any values, while print always returns 1. Now it may seem pointless, but in future articles we will analyze examples where such behavior is more convenient.

It is important to note that the difference between echo and print is often asked as a question in interviews.

Handling the input

It is very useful to output information to the user, but in order to achieve greater flexibility and dynamism of the code, we will often need to receive data from it.

In order to get user input from the command line, the readline function is used. As an argument, you can pass it the text that will be displayed before reading the input. It is used as follows:

<?php

$someVariable = readline("What's up?\n");

The readline function will read user input until the Enter button is pressed. To consolidate this knowledge with practice, let's rework our script so that it asks for the user's name and greets him. To begin with, we will output a greeting and ask for a name.

<?php

$name = readline("Hey, what's your name?\n");

A line break at the end of the greeting is not required, but thanks to it, interaction on the command line is perceived more comfortably.

When the user enters the name and presses Enter, we will get it into the $name variable and can use it anywhere. If the name is not entered (the user immediately pressed Enter), we will get just an empty string. For now, we will not make any safety nets and just output a personalized greeting.

<?php

$name = readline("Hey, what's your name?\n");
echo "Glad to meet you, $name\n";

Now let's run our script. Enter the startup command again in the terminal:

php script.php

Please note that the program, having reached the processing of the readline() function, will stop and continue execution only after receiving a press on Enter from the user in the console.

Practice

Implement a script to run from the command line. When running, the script should ask the user for his name, and after receiving the answer, ask a question about his age. After receiving all the necessary data, output the result in the following form: "Your name is your {NAME}. {AGE} years old"
Refine the script implemented in the previous task as follows: Replace the age question with a chain of interviews about important things planned for the day (three tasks). The program asks: "What task you 're facing today?". The user responds with text and presses Enter. The next question of the program is: "How long will this task take approximately?". The user responds with a number and presses Enter. Note that the number of tasks is strictly limited in the code and is equal to three. The probability of entering incorrect values in this task is ignored. After three questions , the result is displayed as follows:

John, you have 3 tasks planned for the day:
- Walk with the cat (1h)
- Drink coffee (2h)
- Lie on the couch (4h)
Approximate execution time of the plan = 7h

TypeScript. Advanced Project Setup

Elijah Zobenko — Tue, 18 Jan 2022 08:12:41 +0000

In the previous article, we talked a little about the reasons for the appearance of TypeScript, and also examined its use in comparison with JavaScript. In this article, we will prepare our working environment for more efficient and high-quality work.

Setting up EditorConfig

In order for the formatting of all the files we create to be correct, let's set up EditorConfig. EditorConfig is a tool that regulates some basic settings of files created in the editor: encoding, line break character and tab parameters. This is an extremely convenient way to configure the above parameters, which guarantees uniformity when working in different code editors and even different operating systems.

The tool is supported by a huge number of development environments. In some of them by default, in some through the installation of the plugin. Information about support and links to plugins for all editors can be found on the official page of the utility.

Now the actual setup. In the project's root, create a file .editorconfig and put the following content there:

root=true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true

[*.{js,ts}]
indent_style = space
indent_size = 2

[{package.json,tsconfig*.json}]
indent_style = space
indent_size = 2

This configuration sets UTF-8 encoding for all files in the project, as well as line wrapping if and adding an empty line to the end of the file when saving it, as is customary in Unix systems.

There is a generally accepted code standard in the JavaScript ecosystem, which we will get to know better later. It regulates two spaces as a tab character. Therefore, we set these settings for the files package.json, tsconfig.json and all *.js, *.ts files.

To make sure that everything works, you can open the file index.ts and using the tab character. Also, when saving, one empty line should be added at the end of the file. Make sure that the file is formatted correctly, if not, make the necessary changes.

If everything works and is formatted properly, we can move on.

Basic configuration of tsconfig.json

Up to this moment, when calling the build, we passed the parameters directly to the command line command. In practice, this is rare, since usually a project contains a fairly large number of options, so it can be inconvenient to pass them as arguments. For these purposes, there is a configuration file tsconfig.json. When the tsc command is called, this file is searched for and parameters are read from it.

In this article, we will get acquainted with the “essentials” options. And in the future we will consider more advanced settings. In the root of the project, create a file tsconfig.json and add the following content to it:

{
  "compilerOptions": {
    "outDir": "public/scripts",
    "target": "es2015",
    "module": "es2015",
    "moduleResolution": "node"
  },
  "files": [
    "src/index.ts"
  ]
}

For greater clarity, the project will be developed to work in the browser, so the OutDir parameter has been changed to public/scripts. The name "public" is a common name on the web for a folder that stores "assets", such as scripts, style sheets, images and html pages.

The target option has already been installed by us earlier. The parameter determines which version of the ECMAScript standard the source TypeScript code will be compiled into. It is absolutely normal practice in web development to write code using the latest language specifications, which may not yet be supported by all browsers, and in the process of building the project to transform the code into older versions of the language. The es2015 (ES6) specification has fairly broad support in modern browsers. So first let's leave target with the value es2015.

The module option allows you to define the modular system that will be used for connecting files. The ES6 specification has its own import and export syntax for these purposes. Also in the JavaScript ecosystem there are other, older modular systems such as CommonJS and AMD. We can safely use the ES6 standard code, but at the same time redefine the modular system to another one. A little later we'll look at why this might be necessary, but for now let's set module to es2015 as well.

The moduleResolution option is quite specific and practically unnecessary in everyday life. However, some options depend on each other and one option may implicitly change the value of another if its value has not been explicitly set. This behavior can lead to compilation errors. So 'moduleResolution' when installing module in some values changes automatically to the outdated value classic, which was used in TypeScript. To cancel such unforeseen cases, let's explicitly set moduleResolution to the current value of node.

The file to compile from the tsc command argument has moved to the files option. As you can see, the option accepts an array of files, so if you need to transpile several unrelated files, for example, for different pages of the application, then they can be placed here.

It should be noted that if the file index.ts contains the connection code (import) of other *.ts files, then they will be automatically included in the build and there is no need to specify them in files.

Now let's edit the package.json:

{
  "name": "dev-to-project",
  "version": "1.0.0",
  "scripts": {
    "build": "tsc",
    "start": ""
  },
  "devDependencies": {
    "typescript": "^4.2.4"
  }
}

We cleaned up a little extra for convenience. We removed the empty description, the now unnecessary main and the redundant author and license. We also removed the test script. The start script has been left empty for now and the build command has simply been changed to tsc.

Let's run the build and make sure that the file is being created public/scripts/index.js. We will delete the dist folder from the last build.

Setting up the launch in the browser

To begin with, we will bring the code to a more "natural" form. In real projects, they don't write everything in one file. Select the entity Book in a separate file book.ts, and the set of books in book-collection.ts.

//book.ts
export class Book {
  name: string
  genre: string
  pageAmount: number

  constructor (name: string, genre: string, pageAmount: number) {
    this.name = name
    this.genre = genre
    this.pageAmount = pageAmount
  }
}

// book-collection.ts
import { Book } from './book.js'

export const books = [
  new Book('Harry Potter', 'fantasy', 980),
  new Book('The Fellowship of the Ring', 'fantasy', 1001),
  new Book('How to be productive', 'lifestyle', 500),
  new Book('A Song of Ice and Fire', 'fantasy', 999) 
]

// index.ts
import { Book } from './book.js'
import { books } from './book-collection.js'

function findSuitableBook (
  genre: string,
  pagesLimit: number,
  multipleRecommendations = true
): Book | Book[] {
  const findAlgorithm = (book: Book) => {
    return book.genre === genre && book.pageAmount <= pagesLimit
  }

  if (multipleRecommendations) {
    return books.filter(findAlgorithm)
  } else {
    return books.find(findAlgorithm)
  }
}

const recommendedBook = findSuitableBook('fantasy', 1000)

if (recommendedBook instanceof Book) {
  console.log(recommendedBook.name)
} else {
  console.log(recommendedBook[0].name)
}

It is fair to note that the js extension is used in the import, not ts, despite the fact that the attached files actually have the ts extension in the source code base. You cannot use the ts extension in the import construction.

Let's build a project - npm run build

It's time to run our code in the browser. To do this, create a file ** in the public folderindex.html ** with the following contents:

<!--index.html-->
<!DOCTYPE html>
<head>
    <script type="module" src="/scripts/index.js"></script>
</head>

Important! Due to the fact that we use ES6 imports, when connecting the script tag, it is necessary to set the type attribute equal to module. Without this, an error will occur when executing the script.

Since the initial slash in the script address is /scripts/index.js means that the script needs to be searched on the same server. That is, open index.html just as a file is not enough. We need to start the server. To do this, install the following package:

npm install --save-dev http-server

Also, let's add the server startup command to the package.json:

{
  "name": "dev-to-project",
  "version": "1.0.0",
  "scripts": {
    "build": "tsc",
    "start": "http-server -p 3000"
  },
  "devDependencies": {
    "http-server": "^0.12.3",
    "typescript": "^4.2.4"
  }
}

Let's start the server by executing 'npm start'. The http-server utility will host the contents of the public folder on the server at http://localhost:3000. Let's open this address in the browser, open the console and make sure that we see the message "Harry Potter”.

Setting up tsconfig.json for different environments

We made sure that everything is configured correctly and the build is running. Since we have to edit a lot of code, it would be great to rebuild the project automatically when files are changed, rather than starting the build manually. This is extremely convenient for development, but it is absolutely not necessary to create a production assembly. Therefore, we need to create two build commands: build - for the production environment and build:dev - for development.

Each of these commands will use its own tsconfig.json with slightly different parameters and delete the result of the previous build before starting a new process.

First, let's make changes to the package.json:

{
  "scripts": {
    "build": "rm -rf public/scripts && tsc",
    "build:dev": "rm -rf public/scripts && tsc -p tsconfig-dev.json",
    "start": "http-server -p 3000"
  },
  "devDependencies": {
    "http-server": "^0.12.3",
    "typescript": "^4.2.4"
  }
}

Important! If you are running on Windows, the build and build:dev commands must be specified as follows: rd -r public\\scripts 2>null & tsc and rd -r public\\scripts 2>null & tsc -p tsconfig-dev.json.

The rm -rf public/scripts command will delete the folder with the previously prepared code and immediately after that start the build process. The build command as before, it uses the tsconfig.json file, and build:dev uses the -p argument to specify the path to another configuration file - tsconfig-dev.json. Let's create it:

{
    "extends": "./tsconfig.json",
    "compilerOptions": {
        "watch": true,
        "inlineSourceMap": true,
        "inlineSources": true
    }
}

Here we use the extends option to inherit the settings from the original configuration file. This avoids duplication and the support of two configs. We only redefine the options that interest us. In this case, we specify the watch option with the value true to tell the compiler that we want to monitor changes to the source files and run the build every time they change.

But the differences between production and development environments do not end there. We have added two more flags. In order to understand why they are needed, we need to open the page of our application and pay attention to the line "Harry Potter” in the console. There you can notice that the message was created by line number 19 of the file index.js.
In other words, the browser shows the origin of the message in the already compiled code. This will not be convenient in the future when searching and correcting errors. For these purposes, we added the inlineSourceMap and inlineSources flags. They include its source code in the compiled code, which allows the browser to refer to the original code during debugging.

Let's see what it looks like and check how it works in practice. Run the command npm run build:dev. The first thing we can notice is that the console has not returned control to us, instead we see a message like:

[6:23:22 PM] Starting compilation in watch mode...

[6:23:23 PM] Found 0 errors. Watching for file changes.

The compiler keeps track of the source files. Let's open the file book-collection.ts, add “and the Philosopher\'s Stone" to the title of the book “Harry Potter" and save the file. Now open the compiled book-collection file.js and check its contents.

It can be seen that the title of the book has changed and we did not have to run the build manually for this. You can also notice a large line starting with the characters "//# sourceMappingURL" - this is the source code map. In order to test it in action, let's refresh the application page and look at the message "Harry Potter and the Philosopher's Stone". Now we see that the message refers to the source file index.ts line 21.

So, we have completed the configuration of our project at this stage. At the end of the series of articles, we will return to this issue to learn more about all kinds of TypeScript options.

Setting up ESLint

Before taking the next steps in the direction of TypeScript, we will prepare a working environment according to all industry standards. We have already set up EditorConfig so that all the files we create comply with certain rules. ESLint is a code quality control tool. It allows you to describe a list of rules for formatting code, language constructs used, and so on. This allows you to write code in a single style. If these rules are not followed, the code will be underlined in the editor. You can also run the check from the console.

It is considered good practice to run checks on the git hook pre-commit and before building the project during deployment. Since this does not relate to the topic of this article, we will not dwell on it here. Just configure the checks in the IDE and the commands to run through the console.

The Webstorm IDE has ESLint support by default, and a plugin must be installed for Visual Studio Code. The plugin exists for other code editors as well.

There are a large number of ready-made configurations. Several of them are the main accepted standards in the industry, for example, Airbnb JavaScript Style Guide or JavaScript Standard Style. But they will be redundant for our training project. Included with ESLint standard config with minimal settings is which we will use.

In addition to ESLint itself, we will need additional packages to support TypeScript syntax. We will install all the necessary dependencies:

npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

In order for the IDE to start validating the code, you need to create a configuration file .eslintrc in the root of the project:

{
    "root": true,
    "parser": "@typescript-eslint/parser",
    "plugins": [
      "@typescript-eslint"
    ],
    "extends": [
      "eslint:recommended",
      "plugin:@typescript-eslint/eslint-recommended",
      "plugin:@typescript-eslint/recommended"
    ]
}

This configuration file will "teach" ESLint to understand TypeScript syntax and apply the most standard rules recommended by the ESLint team.
It is normal practice to modify the config to suit your needs if necessary. Since the standard config has a minimum of settings, we will add some options there:

{
  "root": true,
  "parser": "@typescript-eslint/parser",
  "plugins": [
    "@typescript-eslint"
  ],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/eslint-recommended",
    "plugin:@typescript-eslint/recommended"
  ],
  "rules": {
    "quotes": ["error", "single"],
    "indent": ["error", 2]
  }
}

In the rules section, we added a couple of mandatory conditions - single quotes and two space characters for indentation must be used. The full list of rules can be found on the official ESLint website and in the repository of the TypeScript ESLint plugin.

The IDE should now respond to the use of double quotes or tab characters. Try using four spaces instead of two or double quotes instead of single ones. If the code is underlined in these places, it means that everything is configured correctly. Do not rush to fix these errors, we will do it using ESLint. First, let's add the linting scripts for the command line. To do this, add to the scripts section of project.json file two more commands:

"scripts": {
  "build": "rm -rf public/scripts && tsc",
  "build:dev": "rm -rf public/scripts && tsc -p tsconfig-dev.json",
  "start": "http-server -p 3000",
  "lint": "eslint src --ext .js --ext .ts",
  "lint-fix": "eslint src --ext .js --ext .ts --fix"
}

By running npm run lint we should see all the errors in the console. And by running npm run lint-fix, automatic error correction will be performed. Those errors that are not corrected automatically must be corrected manually.

And so, we got a little acquainted with TypeScript and prepared an effective environment with a lot of important tools that we will use regularly. In the next articles in the series, we will get to know TypeScript and, in particular, data types more closely.

TypeScript. First glance

Elijah Zobenko — Mon, 17 Jan 2022 20:45:24 +0000

Why TypeScript?

A script is a sequence of commands, instructions in a programming language used to automate routine tasks. JavaScript was originally developed as a small scripting language that could allow you to perform simple operations on the browser side to improve the user experience. Its capabilities were very modest and were used for such purposes as: to show a notification to the user (alert), start a timer, make a running line or falling snowflakes. The main work of the site lay on the server side, including the generation of HTML markup.

Over time, more and more work began to be done on the browser side: form validation, creating stylized modal windows, carousels, slideshows, and so on. In order to simplify interaction with JavaScript and provide support between different browsers, various libraries such as Prototype, MooTools and jQuery began to appear.

So over time, more and more work began to be done on the client side, various frameworks appeared. In addition, JavaScript has been used to write the backend, CLI utilities, and even for mobile and desktop programs.

Despite the fact that JavaScript has increased in its capabilities, fundamentally little has changed in it. Thus, the level of language capabilities remained at the level of a simple scripting language, and the level of tasks that are solved on it has increased many times. It is extremely difficult to write and maintain modern, industrial applications in JavaScript.

Exactly for this reason, the TypeScript language was created. It is designed to bring the missing features to JavaScript and compensate for its shortcomings. At the same time, TypeScript is eventually compiled into JavaScript, which makes it possible to run it in any browser and in Node.js.

What exactly are the disadvantages of JavaScript in question and how TypeScript helps to solve them for clarity, we will consider examples. But to do this, we first need to make a minimal setup of the project.

Create new project

Let's start a TypeScript project. Let's create a folder for it, for example dev-to-project, and initialize packacke.json in it. To do that, run the following commands in the console:

mkdir dev-to-project
cd dev-to-project
npm init

If you don't have npm installed locally, check this article to find out how to do that

Now we need to install TypeScript in our project as a dependency. To do this, open the console and type:

npm install --save-dev typescript

This command will create a node_modules folder containing the installed typescript and package-lock.json file that captures versions of installed dependencies. In addition, a devDependencies section will be created in package.json file with the specified typescript version.

Now you can open the project folder in the code editor. In the root of the project, create an src folder with the index.ts file. And traditionaly, let's write some Hello, world in it:

console.log('Hello World!')

Before going further, make sure that the structure of your project looks like this:

.
├── node_modules
│   ├── .bin
│   │   ├── tsc -> ../typescript/bin/tsc
│   │   └── tsserver -> ../typescript/bin/tsserver
│   └── typescript # bunch of sub-dirs inside
├── package-lock.json
├── package.json
├── src
│   └── index.ts

We cannot run TypeScript code without additional actions. We must first transpile any TypeScript code into JavaScript, and then run the already converted code.

To do this, you need to configure the build. Open the package.json file and change it as follows:

{
  "name": "dev-to-project",
  "version": "1.0.0",
  "description": "",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc src/index.ts --outDir dist --target es2015",
    "start": "node .",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Elijah Zobenko",
  "license": "ISC",
  "devDependencies": {
    "typescript": "^4.2.4"
  }
}

We have added the build command that uses the TypeScript compiler tsc along the path node_modules/.bin/tsc. The compiler will take our file src/index.ts, and the result will be sent by the OutDir directive to the dist folder, which will be created automatically. The target parameter sets the ECMAScript version to which our code will be converted.

We also created the start command, which launches the application. The node . construction will read the value of main from package.json and will launch the specified file.

Therefore, we changed the main option, specifying the path to the main executable file according to where it will be located after the build is executed - dist/index.js

Let's now assemble and run our code. To do this, run the following in the console:

npm run build
npm start

As a result, a message will appear in the console:

Hello World!

That should be enough for now. We'll come back to the settings later in this tutorial. In the meantime, let's get to know the TypeScript language directly.

Meet TypeScript

Let's look at some basic TypeScript features that will immediately help demonstrate its best sides. In order to make the examples more visual, we will compare a similar piece of code written in JavaScript and TypeScript.

The code will contain a small set of books and a function that selects a suitable book for the user by genre and number of pages.

Let's create a temporary file src/playground.js and put the following code in it:

class Book {
    constructor (name, genre, pageAmount) {
        this.name = name
        this.genre = genre
        this.pageAmount = pageAmount
    }
}

const books = [
    new Book('Harry Potter', 'fantasy', 980),
    new Book('The Fellowship of the Ring', 'fantasy', 1001),
    new Book('How to be productive', 'lifestyle', 500),
    new Book('A Song of Ice and Fire', 'fantasy', 999) 
]

function findSuitableBook (genre, pagesLimit) {
    return books.find((book) => {
        return book.genre === genre && book.pageAmount <= pagesLimit
    })
}

At first glance, there is nothing unusual in the code. On the one hand, it is so. Now let's try using the findSuitableBook function. To do this, add the following code:

console.log(findSuitableBook('fantasy', 980))
console.log(findSuitableBook('fantasy', '1000'))
console.log(findSuitableBook('fantasy'))
console.log(findSuitableBook(1000, 'fantasy'))
console.log(findSuitableBook(1000))
console.log(findSuitableBook())

Despite the fact that the correct version of the call is only the first one, we do not receive any error messages. Besides the fact that we can swap arguments and pass a string instead of a number, we can not pass arguments at all. JavaScript does not react to this at all.

Let's run the following command in the console to look at all the call results:

node src/playground.js

Here's what we'll get:

Book { name: 'Harry Potter', genre: 'fantasy', pageAmount: 980 }
Book { name: 'Harry Potter', genre: 'fantasy', pageAmount: 980 }
undefined
undefined
undefined
undefined

Despite the incorrectness of the second option, (findSuitableBook('fantasy', '1000')) it will work as needed because of converting types. During execution, the string '1000' will be converted to a number, since it is compared with another number - this is the internal JavaScript behavior. We can say that JavaScript has "fixed" the user's error. But how does JavaScript "fix” missing arguments? The missing arguments will be assigned the value undefined. The language itself will decide what the result should be when comparing a string with undefined and mathematically comparing a number with undefined.

A JavaScript developer may not notice problems in what is happening, as he is used to such behavior. However, at least two drawbacks can be noted - poor readability and non-obvious behavior of the code.

Poor readability lies in the fact that without reading the code, we will not be able to understand the types of arguments and which of them are mandatory and which are not. The genre argument could be a number equal to the ID of the genre. And if there is a condition in the code to check the pagesLimit parameter before using it, this would mean that the parameter can not be passed. Thus, when developing in JavaScript, you constantly have to reread the code before using it.

The non-obvious behavior of the code lies in the fact that the developer never knows exactly how the program will react, because it is simply impossible to know and take into account every detail of the internal structure of JavaScript. Non-obviousness leads to the concealment of problems that will sooner or later make themselves felt. And finding the cause and correcting it in such conditions is quite a difficult task.

Let's add another function call:

console.log(findSuitableBook().name)

Up to this point, JavaScript solved all the problems by itself, hiding them from us and thereby depriving us of the opportunity to write high-quality code. Let's check what will happen now. Let's run the code execution as shown earlier.

Now we see an exceptional situation, the application has crashed with the following message:

console.log(findSuitableBook().name)
                              ^

TypeError: Cannot read property 'name' of undefined

So, JavaScript couldn't figure out how to take a field from a non-existent value and decided to fall. Belatedly, we find out that there were problems in the code. Even in a small piece of code, we are faced with non-self-explanatory, non-obvious code that hides problems. Now let's look at what TypeScript has to offer.

Let's copy the code from playground.js in index.ts. You can immediately notice that some lines of code are underlined in red in the editor. TypeScript immediately found some problems in the code. Let's try to build a project and run it:

npm run build

Errors will appear in the console. Exactly the same ones that were underlined in the code editor. The code editor displays errors to improve the user experience. But the appearance of errors during assembly execution is a key point. Such a build ends with a non-zero status code. The developer not only sees the list of errors, but the process itself ends with an error. This is an important point because the build command is always executed during the deployment of the project. This behavior ensures that the code containing errors cannot physically be in production. At the same time, we have not yet used any feature of the TypeScript language.

Let's put the code in order so that the build is successful. Let's start with the Book class. From the JavaScript point of view, this section does not contain any problems. However, from the TypeScript point of view, the assignment of the properties name, genre and pageAmount cannot be performed because the properties are not declared in the class. We need to fix this. At the same time, we will immediately limit the types of values that these properties can take. The name and genre should be a string, and the pageAmount should be a number.

class Book {
    name: string
    genre: string
    pageAmount: number

    constructor (name: string, genre: string, pageAmount: number) {
        this.name = name
        this.genre = genre
        this.pageAmount = pageAmount
    }
}

Here we use TypeScript syntax for the first time. By putting a colon when declaring properties and constructor arguments, we specify their types. In this example, these are strings and numbers. We will get to know the type system more closely in the next lesson.

At this stage, the main thing to understand is that in this way we prevent the creation of all kinds of erroneous variations of creating a copy of the book. All the following lines of code contain errors and will not be skipped by the TypeScript compiler:

new Book(),
new Book('Harry Potter'),
new Book('Harry Potter', 'fantasy')
new Book('Harry Potter', 'fantasy', '980'),
new Book(980, 'Harry Potter', 'fantasy'),

And it's just wonderful! Every time a developer makes a mistake, he finds out about it instantly. At the same time, it receives information about the file, line, and even the essence of the problem. Such a problem can be easily and quickly localized.

We still have errors in the findSuitableBook function call block. It's easy enough to fix them. To begin with, we will delete all the lines that are marked as erroneous. Instead of seven lines, we will have only three. Here they are:

console.log(findSuitableBook('fantasy', 1000))
console.log(findSuitableBook('fantasy', '1000'))
console.log(findSuitableBook(1000, 'fantasy'))

It is necessary to write the function in such a way that it is obvious to the developer and compiler how it works. Now you can describe the action of the function as follows: the “find a suitable book" function accepts the "genre” and the page limit. That doesn't sound detailed enough. We need to do this: the “find a suitable book" function accepts the genre as a string and the pageAmount as a number, and should return the Book. Let's write it down like this:

function findSuitableBook (genre: string, pagesLimit: number): Book {
    return books.find((book) => {
        return book.genre === genre && book.pageAmount <= pagesLimit
    })
}

Now it is enough for the developer to read the first line of the function (its signature) to understand the meaning of what it does. The compiler easily cuts off the remaining incorrect options. Let's check that everything works as it should:

npm run build
npm start

The following should appear on the screen:

Book { name: 'Harry Potter', genre: 'fantasy', pageAmount: 980 }

If you look at the file dist/index.js, then you can see that the code in it is one to one as it was in our playground.js. However, it has passed the transpilation stage from TypeScript, which means that it is secured. In addition, you will never have to work with it, because the work is done in the source src/*.ts files, and everything that is in dist/*.js is only needed for execution.

It is worth noting that there is a system for JavaScript that tried to bring a similar experience to the language, namely, to bring transparency with respect to input arguments and return values of functions. The implementation of the system is a special syntax of JSDoc comments. This syntax is supported by many code editors. This is how special comments look for our findSuitableBook function:

/**
 * @param {string} genre
 * @param {number} pagesLimit
 * @returns {Book}
 */
function findSuitableBook (genre, pagesLimit) {
    return books.find((book) => {
        return book.genre === genre && book.pageAmount <= pagesLimit
    })
}

However, this approach has limited effectiveness for several reasons. Firstly, the presence or absence of comments is entirely the responsibility and care of the developer. Secondly, non-compliance with the described signatures does not lead to errors, so problems in the code may continue to go unnoticed. Thirdly, such comments are not part of the language, so the code can be edited and the comments remain unchanged, which leads to even more confusion.

Let's talk a little bit about declaring the return value type. In the example above, in the file index.ts the result of the function execution is declared as Book. This helps in several cases. Firstly, readability improves, as we mentioned earlier. Secondly, it makes it impossible to return a value other than the specified one. For example, the following code will result in an error:

function findSuitableBook (genre: string, pagesLimit: number): Book {
    return {
        name: 'Harry Potter',
        // we just missed the `genre` property
        pageAmount: 980
    }
}

Now let's refactor the function so that it can return both one and several results. In this case, by default, the function will return multiple results.

/**
 * @param {string} genre
 * @param {number} pagesLimit
 * @returns {Book}
 */
function findSuitableBook (genre, pagesLimit, multipleRecommendations = true) {
    const findAlgorithm = (book) => {
        return book.genre === genre && book.pageAmount <= pagesLimit
    }

    if (multipleRecommendations) {
        return books.filter(findAlgorithm)
    } else {
        return books.find(findAlgorithm)
    }
}

const recommendedBook = findSuitableBook('fantasy', 1000)
console.log(recommendedBook.name)

We added a new argument multipleRecommendations, which by default has the value true, changed the search algorithm and left only the correct function call. Here you can immediately notice several things. Since the default argument is true, this affects all existing code. At the same time, the new argument was lost in JSDoc, and the return value type remained the same - a common thing. Therefore, the code console.log(recommended Book.name ) remained unchanged and will currently result in a request for the name field from the array. Again, non-obvious behavior with hiding problems in the code.

Let's make similar changes in the TypeScript code:

function findSuitableBook (
    genre: string,
    pagesLimit: number,
    multipleRecommendations = true
): Book {
    const findAlgorithm = (book: Book) => {
        return book.genre === genre && book.pageAmount <= pagesLimit
    }

    if (multipleRecommendations) {
        return books.filter(findAlgorithm)
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    } else {
        return books.find(findAlgorithm)
    }
}

const recommendedBook = findSuitableBook('fantasy', 1000)
console.log(recommendedBook.name)

In this case, we will get a compilation error due to the discrepancy between the described return value type and the real one. Let's fix it:

function findSuitableBook (
    genre: string,
    pagesLimit: number,
    multipleRecommendations = true
): Book | Book[] {
    const findAlgorithm = (book: Book) => {
        return book.genre === genre && book.pageAmount <= pagesLimit
    }

    if (multipleRecommendations) {
        return books.filter(findAlgorithm)
    } else {
        return books.find(findAlgorithm)
    }
}

const recommendedBook = findSuitableBook('fantasy', 1000)
console.log(recommendedBook.name)
                            ~~~~

We replaced Book with Book | Book[], which means that either one book or an array of books will be returned. To which the compiler immediately reacted with another error. The fact is that before taking a name from a book, you need to make sure that it is not an array of books. Let's finalize the code as follows:

const recommendedBook = findSuitableBook('fantasy', 1000)

if (recommendedBook instanceof Book) {
    console.log(recommendedBook.name)
} else {
    console.log(recommendedBook[0].name)
}

The solution lies in adding an additional check. In this case, we checked whether the result is an instance of the Book class. As you can see, TypeScript will always find an error and tell you where to look for it. Let's make sure everything works correctly. The following should appear in the console:

Harry Potter

Great! You can delete the file src/playground.ts, we won't need it anymore.
So far, we have considered only a tiny part of the TypeScript features. With each article, we will learn more about the language, and in the next one we'll set up the project for convenient further work on it.

Boosting up PHP-project with cache

Elijah Zobenko — Fri, 01 Oct 2021 10:22:37 +0000

The growth of the project and its load can be a real challenge for the developer. The website begins responding with a delay and the question of scaling is being raised more often. There are many effective solutions to increase the stability of the project and the load capability, and one of the most basic is caching.

Caching is the saving of data in highly accessible places temporarily so that their retrieval is performed faster than from the source. The most common example of using a cache is getting data from a database. When a product is first received from the database, for example, it is stored in the cache for a certain time, so each subsequent request to this product will not disturb the database, since the data will be received from another storage.

What are the approaches?

There are many approaches to caching. You can check the list of PHP-compatible tools on the php-cache page. However, the most common ones are:

APCu
Array
Memcached
Redis

Let's look at their differences and features.

APCu

One of the most common and easy-to-configure caching tools. Saves the data into RAM (and also knows how to cache intermediate code, but that's a completely different story ...). To get started with APCu, you need to make sure that it is installed. To do that, run the following command on the command line:

php -i | grep 'apc.enabled'
# We're expecting to see:
# apc.enabled => On => On

Another way to check it: create a file index.php and put the phpinfo() function call in it. Make sure that you have a web server configured for the directory you are using and open the script in the browser via the server address. We are interested in the APCu section, if there is an APCu Support: Enabled item inside it, then everything is fine, we can move on.

If you don't have APCu installed, you can do it in the following way:

Launch a terminal window (Linux/macOS) or a command prompt (Windows. Enter "cmd" in the search)
Run the command: pecl install apcu apcu_bc

Open the php.ini configuration file via any text editor and make sure that the following lines are present:

# Windows
extension=php_apcu.dll
extension=php_apcu_bc.dll

apc.enabled=1
apc.enable_cli=1

#Linux / MacOS
extension="apcu.so"
extension="apc.so"

apc.enabled=1
apc.enable_cli=1

If there are no specified lines, add them and save the configuration file
Repeat the check for the installed APCu

To use this caching approach, we will need the basic functions. Here is an example of their application.

$cacheKey = 'product_1';
$ttl = 600; // 10 minutes.

// Checking APCu availability
$isEnabled = apcu_enabled();

// Checks if there is data in the cache by key
$isExisted = apcu_exists($cacheKey);

// Saves data to the cache. Returns true if successful
// The $ttl argument determines how long the cache will be stored (seconds)
$isStored = apcu_store($cacheKey, ['name' => 'Demo product'], $ttl);

// Retrieves data from the cache by key. If not, returns false
$data = apcu_fetch($cacheKey);

// Deletes data from the cache by key
$isDeleted = apcu_delete($cacheKey);

var_dump([
    'is_enabled'   => $isEnabled,
    'is_existed'   => $isExisted,
    'is_stored'    => $isStored,
    'is_deleted'   => $isDeleted,
    'fetched_data' => $data,
]);

Any cache works on the principle of key-value storage, which means that the stored data is stored with a special key, which is accessed. In this case, the key is stored in the $cacheKey variable.

Important! This approach only works in the website mode, i.e. when running from the command line, you will not receive data from the cache, and everything that you have saved to it will be cleared when the script completes. However, this will not cause any errors.

Array-cache

A simpler, but not always applicable, caching method. If the APCu saves data and makes it available for subsequent execution by all processes, then the Array cache stores it only for the request being processed.

What does it mean? Imagine that you have a page with user comments. One user can leave several messages, and when we collect an array of this data, we do not want to fetch the same user from the database several times. What we can do is set the received data to an array so that if there is one, we don't make a request again. This principle is very simple and just as easy to implement. Let's write a class that will perform such a save.

class CustomArrayCache
{
    /**
     * Array is static and private
     * – private – so that it can be accessed only from the
     * methods of the class
     * – static – so that the property is available in all instances
     */
    private static array $memory = [];

    // Method for storing data in memory
    public function store(string $key, $value): bool
    {
        self::$memory[$key] = $value;

        return true;
    }

    // Method for getting data from memory
    public function fetch(string $key)
    {
        return self::$memory[$key] ?? null;
    }

    // Method for deleting data from memory
    public function delete(string $key): bool
    {
        unset(self::$memory[$key]);

        return true;
    }

    // Method for checking the availability of key data
    public function exists(string $key): bool
    {
        return array_key_exists($key, self::$memory);
    }
}

This approach is very simple, but due to its limitations, it is rarely used. However, it is useful to know about it.

Memcached & Redis

The most advanced caching approaches. They require a server (daemon) running separately. From PHP, we connect to this server at the address and port. The configuration of these solutions is more complicated than setting up an APCu, but the data storage method is very similar (RAM). Their most important advantages are:

Isolation from PHP. Separate services are responsible for the cache;
Clustering capability. If the load on your project is very high, clustering of caching services will help to cope with it;

In this article, we will not go into the details of configuring Memcached and Redis. At this stage, we need to remember that if the load is very high– we should look towards these solutions since they have a good potential for scaling.

PSR-16 Standard

PSR has two standards dedicated to caching: PSR-6 (normal caching interface) and PSR-16 (Simple caching interface) – we will focus on PSR-16.

This standard offers a special interface (CacheInterface) that classes that perform the caching function can satisfy. According to it, such classes should implement the following methods:

get($key, $default) - Getting data from the cache. The second argument passes the value that will be returned if this data is missing.;
set($key, $value, $ttl = null) - Saving data to the cache. As we saw earlier, the third parameter is passed the storage time in seconds. If left empty (null), the default value from the cache configuration will be substituted;
delete($key) - Deletes key data;
clear() - Clears the entire storage;
getMultiple($keys, $default) - Allows you to get data for several keys at once;
setMultiple($values, $ttl = null) - Allows you to record multiple values at once. As $value we pass an associative array, where the key is $key for the cache, and the value is the data to save;
deleteMultiple($keys) - Deletes data for multiple keys;
has($key) - Checks the availability of key data.

As you can see, the interface is very simple, and even the functions that we considered in the example for APCu are enough to write your cache service following PSR-16. But why is it necessary?

The main advantages of compliance with PSR standards:

They are supported by the most popular libraries;
Many PHP programmers adhere to PSR and will easily get used to your code;
Thanks to the interface, we can easily change the service used to any other that supports PSR-16.

Let's take a closer look at the last point and its benefits.

Usage of PSR-16 libraries

Libraries that create a "wrapper" over existing caching tools to match the interface are called adapters. For example, consider the adapters of the methods that we have already discussed:

All of them satisfy PSR-16 and therefore are applied the same way, but each has its own logic "under the hood".

For an example of usage, let's load APCu and array adapters using composer into our project.

composer require cache/array-adapter
composer require cache/apcu-adapter
# Or
composer req cache/apcu-adapter cache/array-adapter

Let's imagine that we have a special class for getting products from a database. Let's call it ProductRepository, it has a find($id) method that returns a product by its ID, and if there is no such product, null.

class ProductRepository
{
    /**
     * In order not to complicate the example, we will stipulate that
     * an array is returned as a product, and if it is not, null
     */
    public function find(int $id): ?array
    {
        // ...
        // Getting data from the database
        return $someProduct;
    }
}

If we want to enable caching, we should not do it inside the repository, because its responsibility is to return data from the database. Where then will we add the cache? There are several popular solutions, the simplest is an additional provider class. All he will do is try to get data from the cache, and if it didn't work out, he will contact the repository. To do this, we will define two dependencies in the constructor of such a class – our repository and CacheInterface. Why the interface? Because we will be able to use absolutely any of the mentioned adapters or other classes that satisfy PSR-16.

use Psr\SimpleCache\CacheInterface;

class ProductDataProvider
{
    private ProductRepository $productRepository;
    private CacheInterface $cache;

    public function __construct(ProductRepository $productRepository, CacheInterface $cache)
    {
        $this->productRepository = $productRepository;
        $this->cache             = $cache;
    }

    public function get(int $productId): ?array
    {
        $cacheKey = sprintf('product_%d', $productId);

        // Trying to get the product from the cache
        $product = $this->cache->get($cacheKey);
        if ($product !== null) {
            // If there is a product, we return it
            // Temporarily output echo to understand that the data is from the cache
            echo 'Data from cache' . PHP_EOL; // PHP_EOL is a line break
            return $product;
        }
        // If there is no product, we get it from the repository
        $product = $this->productRepository->find($productId);

        if ($product !== null) {
            // Now we will save the received product to the cache for future requests
            // Also temporarily output echo
            echo 'Data from DB' . PHP_EOL;
            $this->cache->set($cacheKey, $product);
        }

        return $product;
    }
}

Our class is ready. Now let's look at its application in combination with an APCu adapter.

use Cache\Adapter\Apcu\ApcuCachePool;

// Connect the Composer autoloader
require_once 'vendor/autoload.php';

// Our repository
$productRepository = new ProductRepository();
// APCu-cache adapter. Does not require any additional settings
$cache = new ApcuCachePool();

// Creating a provider, passing dependencies
$productDataProvider = new ProductDataProvider(
    $productRepository,
    $cache
);

// If there is such a product in the database, it will come back to us
$product = $productDataProvider->get(1);
var_dump($product);

If we want to replace APCu caching with an Array adapter or any other approach, we'll just pass it to the provider instead, because they all implement CacheInterface.

use Cache\Adapter\PHPArray\ArrayCachePool;
// ...
$productRepository = new ProductRepository();
//$cache = new ApcuCachePool();
$cache = new ArrayCachePool();
$productDataProvider = new ProductDataProvider(
    $productRepository,
    $cache
);
// ...

Race condition and data updating

The cache works as long as we keep it up to date. This means that if a user wants to update a product, it must be updated both in the database and in our cache. However, there is one important nuance here.

Imagine that our project is used by a very large number of users. And two of them update the same entity at the same time. In this case, the following situation may occur:

User 1 received an entity from the cache
User 1 updated the entity in the DB
User 2 got the entity from the cache
User 1 has updated the data in the cache
User 2 updated the entity in the database but overwritten it with old data because the entity was irrelevant at the time of receipt
and so on...

This situation is called a race condition when several processes access the same resource at the same time and a version conflict may occur. To avoid such a problem, one simple rule should be followed:

When you receive any entity in the code to update it, always use data from the database.

In any situation when we need to get a product and we are not going to update it, we use a cache. If we want to update it - use data from the database.

You can either refer to ProductRepository in the right places, instead of ProductDataProvider or add an argument to the data provider's method. For example ($fromCache):

class ProductDataProvider
{
    // ...
    public function get(int $productId, bool $fromCache = true): ?array
    {
        $cacheKey = sprintf('product_%d', $productId);

        $product = $fromCache 
            ? $this->cache->get($cacheKey) 
            : null;
        if ($product !== null) {
            return $product;
        }
        $product = $this->productRepository->find($productId);

        if ($product !== null) {
            $this->cache->set($cacheKey, $product);
        }

        return $product;
    }
}

Conclusion

Caching requires additional efforts from the developer when making a project and its use may not always be appropriate. The decision to apply it or not should be based on the expected (or actual) load and your expectations of the response speed to the user.

However, regardless of whether you will use these approaches in your current projects or not, they should be studied and put into practice, because this skill will be useful to you when working in large teams.

Summing up the article, let's look at the key ideas:

Compliance with PSR-16 (or PSR-6) will allow you to easily connect a third-party library for caching and make your code understandable to other developers;
For small projects, APCu is a good caching solution, because it is easy to configure and uses RAM, access to which is very high;
For all PHP-compatible caching tools, some adapters can be viewed on the website php-cache.com;
Caching is a separate responsibility. Try to implement working with the cache in separate classes;
If we are going to update an entity, it should be obtained from the database. If we need an entity only for viewing– we can request it from the cache;
In large projects, Memcached or Redis are used to get the ability to scale.

Secure integrations with Circuit Breaker in Go

Elijah Zobenko — Wed, 22 Sep 2021 19:34:10 +0000

Modern web projects rarely exist without any external service integrations. It can be SMS gates, partner's API, ad pixels, and so on. But what risks does it bring for us?

Let's say we have a high load online store with SMS notifications on order creation. Message sends via some external API and it has gone offline. We'll experience timeouts from it and how will our app handle it? It depends on the client configuration, but in any case, it will lead to a lower response rate, extra resource usage, and the queue of the requests.

Another example: we have a personalized products feed on the main page and we use Redis to reduce the response rate (since it responses in 1ms the whole feed of 20 products will take 20ms). But in case of Redis goes rebalancing (or worse if it has lost the node) the response rate will increase to 500 ms for each product and 10 seconds for the whole feed.

Are there any solutions to prevent or minimize such occasions? Well, that's the case when the "Circuit Breaker" pattern comes in handy.

Pattern overview

The main principle of the pattern is easy as a cake:

If the external API is not available – it is useless to send requests to it, it won't respond.

And vice versa: if an external API is available – you can request it, perhaps it will respond with something useful.

To visualize it we'll stick to the SMS gate example. Let's imagine all that logic as a toggle. When the service is up we'll pass requests to it. That state is called "Closed" so you can memorize it as a real circuit toggle.

And, when it's down – we break the chain (The "Open" state).

What to do in the "Open" state is up to you and usually depends on the integration purpose. You can:

Return the last successful response while it's fresh enough;
Return default value;
Use different strategies;
Just return an error.

Since we're going to notify users, we may implement an email notification for such situations.

And the last question to be answered: who'll change the state of the circuit? "Red button" to control it manually would be useful, but not as the only solution. I don't think anybody wants to keep their finger on the pulse. Then we need rules to do that automatically.

Let's say we're going to break the chain on every error from the API. But when to get it back to the "Closed" state? To do that we have to introduce one more state - "Half-open". The purpose of it is to pass some requests to check if the API is alive. So it works as an intermediate level on the path from "Open" to "Closed" state.

So then the logic is simple: on any error we switch to the Open and prevent requesting the API. When some time exceeded we switch to the Half-open state and pass request to check is everything ok. In case of error, we switch back to the Open and on success – to the closed.

And to make it more efficient we need to add two things:

Error policies – to ignore some of the expected errors;
Thresholds or the braking strategy – to describe the rule of breaking the chain.

Summarizing everything mentioned let's look at the activity diagram:

Hands-on

API

Before we start, let's create a test environment. Our go-app should listen for two HTTP endpoints. One will serve as our SMS gateway API mock. And second, will toggle the server's status "good" → "broken" and back. Let's do that in a separate file.



// server.go
package main

import (
    "log"
    "net/http"
    "os"
)

// ExampleServer is a test server to check the "CircuitBreaker" pattern
type ExampleServer struct {
    addr   string
    logger *log.Logger
    isEnabled bool
}

// NewExampleServer creates the instance of our server
func NewExampleServer(addr string) *ExampleServer {
    return &ExampleServer{
        addr: addr,
        logger: log.New(os.Stdout, "Server\t", log.LstdFlags),
        isEnabled: true,
    }
}

// ListenAndServe starts listening on the address provided 
// on creating the instance.
func (s *ExampleServer) ListenAndServe() error {
    // The main endpoint we will request to
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        if s.isEnabled {
            s.logger.Println("responded with OK")
            w.WriteHeader(http.StatusOK)
        } else {
            s.logger.Println("responded with Error")
            w.WriteHeader(http.StatusInternalServerError)
        }
    })

    // Toggle endpoint to switch on and off responses from the main one
    http.HandleFunc("/toggle", func(w http.ResponseWriter, r *http.Request) {
        s.isEnabled = !s.isEnabled
        s.logger.Println("toggled. Is enabled:", s.isEnabled)
        w.WriteHeader(http.StatusOK)
    })

    return http.ListenAndServe(s.addr, nil)
}

Client

What we gonna do is to create a simple Client structure with a single method Send. We'll send the request to the / endpoint to emulate an external integration. And visiting localhost:8080/toggle will switch the server's response to the error. Let's create our client.



// client.go
package main

import (
    "errors"
    "net/http"
)

type NotificationClient interface {
    Send() error // We ignore all the arguments to simplify the demo
}

type SmsClient struct {
    baseUrl string
}

func NewSmsClient(baseUrl string) *SmsClient {
    return &SmsClient{
        baseUrl: baseUrl,
    }
}

func (s *SmsClient) Send() error {
    url := s.baseUrl + "/"
    resp, err := http.Get(url)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    if resp.StatusCode < 200 || resp.StatusCode >= 300 {
        return errors.New("bad response")
    }

    return nil
}

The client is ready. All we need to make it work is to initialize everything in our main.go file.



// main.go
package main

import (
    "log"
    "os"
    "time"
)

func main() {
    logger := log.New(os.Stdout, "Main\t", log.LstdFlags)
    server := NewExampleServer(":8080")

    go func() {
        _ = server.ListenAndServe()
    }()

    client := NewSmsClient("http://127.0.0.1:8080")

    for {
        err := client.Send()
        time.Sleep(1 * time.Second)
        if err != nil {
            logger.Println("caught an error", err)
        }
    }
}

And that's it! we've created all the required environments and if we run the code it will log to the standard output for every response of the server.



Server 2021/09/22 21:51:30 responded with OK
Server 2021/09/22 21:51:31 responded with OK
Server 2021/09/22 21:51:32 responded with OK
Server 2021/09/22 21:51:32 toggled. Is enabled: false
Server 2021/09/22 21:51:33 responded with Error
Main   2021/09/22 21:51:34 caught an error bad response
Server 2021/09/22 21:51:34 responded with Error
Main   2021/09/22 21:51:35 caught an error bad response

Everything works as we expected. Now we have an "unstable" API and out insecure client. So to make things better we can implement the "Circuit Breaker" method.

Circuit Breaker

As it usually happens with useful patterns there are a lot of implementations of it. So if you want to create your solution – you can use the scheme above. But in this article, we're going to use a great library of Sony:

sony / gobreaker

Circuit Breaker implemented in Go

gobreaker

gobreaker implements the Circuit Breaker pattern in Go.

Installation

go get github.com/sony/gobreaker/v2

Usage

The struct CircuitBreaker is a state machine to prevent sending requests that are likely to fail. The function NewCircuitBreaker creates a new CircuitBreaker. The type parameter T specifies the return type of requests.

func NewCircuitBreaker[T any](st Settings) *CircuitBreaker[T]

You can configure CircuitBreaker by the struct Settings:

type Settings struct {
    Name          string
    MaxRequests   uint32
    Interval      time.Duration
    Timeout       time.Duration
    ReadyToTrip   func(counts Counts) bool
    OnStateChange func(name string, from State, to State)
    IsSuccessful  func(err error) bool
}

Name is the name of the CircuitBreaker.
MaxRequests is the maximum number of requests allowed to pass through when the CircuitBreaker is half-open If MaxRequests is 0, CircuitBreaker allows only 1 request.
Interval is the cyclic period…

View on GitHub

So to download it just type:



go get github.com/sony/gobreaker

We can connect it right in the client's implementation but it would be a bit messy. I prefer wrapping such structures with proxies. Let's create that proxy and implement the NotificationClient interface to make the interaction equal.



// circuit_breaker.go
package main

import (
    "log"
    "os"
    "time"

    "github.com/sony/gobreaker"
)

type ClientCircuitBreakerProxy struct {
    client NotificationClient
    logger *log.Logger
    gb     *gobreaker.CircuitBreaker // downloaded lib structure
}

// shouldBeSwitchedToOpen checks if the circuit breaker should
// switch to the Open state
func shouldBeSwitchedToOpen(counts gobreaker.Counts) bool {
    failureRatio := float64(counts.TotalFailures) / float64(counts.Requests)
    return counts.Requests >= 3 && failureRatio >= 0.6
}

func NewClientCircuitBreakerProxy(client NotificationClient) *ClientCircuitBreakerProxy {
    logger := log.New(os.Stdout, "CB\t", log.LstdFlags)

    // We need circuit breaker configuration
    cfg := gobreaker.Settings{
        // When to flush counters int the Closed state
        Interval: 5 * time.Second,
        // Time to switch from Open to Half-open
        Timeout: 7 * time.Second,
        // Function with check when to switch from Closed to Open
        ReadyToTrip: shouldBeSwitchedToOpen,
        OnStateChange: func(_ string, from gobreaker.State, to gobreaker.State) {
            // Handler for every state change. We'll use for debugging purpose
            logger.Println("state changed from", from.String(), "to", to.String())
        },
    }

    return &ClientCircuitBreakerProxy{
        client: client,
        logger: logger,
        gb:     gobreaker.NewCircuitBreaker(cfg),
    }
}

func (c *ClientCircuitBreakerProxy) Send() error {
    // We call the Execute method and wrap our client's call
    _, err := c.gb.Execute(func() (interface{}, error) {
        err := c.client.Send()
        return nil, err
    })
    return err
}

Let's take a look at our new Proxy. Here are two of the most important things:

ReadyToTrip setting defines the function, which detects when the chain should be broken;
Timeout setting describes how often we should recheck the API's health (and switch to the Half-open state).

After preparing all the configurations all we need to do is simply wrap the Client's method. And to start using proxy we need to add few lines to the main.go file.



// main.go
package main
// ...
func main() {
    // ...
    var client NotificationClient
    // Create a common Client
    client = NewSmsClient("http://127.0.0.1:8080")
    // And then wrap it
    client = NewClientCircuitBreakerProxy(client)

    for {
        err := client.Send()
        time.Sleep(1 * time.Second)
        if err != nil {
            logger.Println("caught an error", err)
        }
    }
}

Everything is done! Let's run the code and give it a try. When the server is active it works as before.



Server  2021/09/22 22:09:32 responded with OK
Server  2021/09/22 22:09:33 responded with OK
Server  2021/09/22 22:09:34 responded with OK

But if we toggle it via /toggle endpoint – our shouldBeSwitchedToOpen method enters the game.



Server  2021/09/22 22:11:12 responded with OK
Server  2021/09/22 22:11:12 toggled. Is enabled: false
Server  2021/09/22 22:11:13 responded with Error
Main    2021/09/22 22:11:14 caught an error bad response
Server  2021/09/22 22:11:14 responded with Error
Main    2021/09/22 22:11:15 caught an error bad response
Server  2021/09/22 22:11:15 responded with Error
Main    2021/09/22 22:11:16 caught an error bad response
Server  2021/09/22 22:11:16 responded with Error
Main    2021/09/22 22:11:17 caught an error bad response
Server  2021/09/22 22:11:17 responded with Error
CB      2021/09/22 22:11:17 state changed from closed to open
Main    2021/09/22 22:11:18 caught an error bad response
Main    2021/09/22 22:11:19 caught an error circuit breaker is open
Main    2021/09/22 22:11:20 caught an error circuit breaker is open

We configured it to recheck the API's health every 5 seconds. So that's how we can debug it – toggle the server's behavior to the active.



CB      2021/09/22 22:13:13 state changed from closed to open 
Main    2021/09/22 22:13:14 caught an error bad response
Main    2021/09/22 22:13:15 caught an error circuit breaker is open
Server  2021/09/22 22:13:15 toggled. Is enabled: true
Main    2021/09/22 22:13:16 caught an error circuit breaker is open
Main    2021/09/22 22:13:17 caught an error circuit breaker is open
Main    2021/09/22 22:13:18 caught an error circuit breaker is open
Main    2021/09/22 22:13:19 caught an error circuit breaker is open
Main    2021/09/22 22:13:20 caught an error circuit breaker is open
CB      2021/09/22 22:13:20 state changed from open to half-open
Server  2021/09/22 22:13:20 responded with OK

And that's it! That simple.

Anything else?

Yes, there are some tips to use that pattern. First of all, you need good monitoring. That means that logs with all the client's requests are required to have an opportunity to reproduce the error. And you need metrics to see how often switches happen and so as to react in time.

The next important thing is use cases. Some integrations require Retry-pattern, some – simple error handling with default values, and only integrations, which can slow your project down or even kill it deserves use with Circuit Breaker.

Hope you'll find it handy. Enjoy coding! <3

Investigating an incident: how to log effectively (PHP)

Elijah Zobenko — Tue, 14 Sep 2021 13:24:21 +0000

Why do we need loggers?

It's common for humans to make mistakes. That's so not only in the relation of developers but also users. And if while developing we control the process totally and can see the wrong behavior through with simple debugging, the same case on the productions environment wouldn't be so easy to investigate. In such cases the thing to help us are journals. But to gain a maximum value of its usage we should do it properly.

Logging – the process of maintaining such journals, and it helps to detect hidden errors, understand user problems and simply sort out what really happened. In the simplest implementation logs are written to the text files and contain an exact time and description of the event. There is a bunch of methods to do that, and what is good for us – the best practices were defined long ago.

In this article, we'll sort out how to organize logging in a PHP app, how to use it efficiently, and what libraries might be useful.

PSR-3 Standard. Log levels

PSR is a collection of general recommendations for PHP developers. It contains tips for code style, some interfaces, and other recommendations. One of its documents (PSR-3) is dedicated to a logger implementation.

I suggest that you start getting acquainted with these recommendations with the logging levels that it offers.

<?php

namespace Psr\Log;

class LogLevel
{
    const EMERGENCY = 'emergency';
    const ALERT     = 'alert';
    const CRITICAL  = 'critical';
    const ERROR     = 'error';
    const WARNING   = 'warning';
    const NOTICE    = 'notice';
    const INFO      = 'info';
    const DEBUG     = 'debug';
}

PSR-3 defines 8 different message levels. Proper usage of them will simplify searching for errors and will boost up an accident reaction speed. Let's go deeper and figure out when to use them.

DEBUG – debugging information that reveals the details of the event in detail;
INFO – any interesting events. For instance: user has signed in;
NOTICE – important events within the expected behavior;
WARNING – exceptional cases which are still not errors. For example usage of a deprecated method or wrong API request;
ERROR – errors to be monitored, but which don't require an urgent fixing;
CRITICAL – critical state or an event. For instance: unavailability of a component or an unhandled exception;
ALERT – error and an event to be solved in the shortest time. For example, the database is unavailable;
EMERGENCY – whole app/system is completely out of order.

Use of these levels means just adding it as some kind of prefix to your log message. For instance:

[2021-01-01 12:10:35] website.INFO: User has changed his password

Such levels as ALERT and EMERGENCY are commonly handled with an additional notification (SMS, Email, and so on). INFO allows you to reproduce the whole user's action sequence, while DEBUG will simplify exact values and function's results fetching.

PSR-3. Logger Interface

In addition to the class with levels, PSR-3 offers us an interface for implementing our own loggers - LoggerInterface. Its implementation is very useful because most existing libraries support it, and if you decide to replace your logger with another one, just connect a new class instead.

LoggerInterface requires the implementation of logging methods, in accordance with the previously reviewed levels. Let's create our own logger class that will correspond to this interface and writes messages to a text file.

But first, let's download the PSR-3 code with Composer.

composer req psr/log

The package we downloaded contains several classes, traits, and interfaces, among which the LogLevel we previously reviewed, and the LoggerInterface that is currently of our interest. Let's create a new class that implements that interface. Important: make sure that you have the autoloader class included (vendor/autoload.php).

<?php
// index.php

// Composer's autoloader
require_once 'vendor/autoload.php';
// Our new Logger class
require_once 'src/FileLogger.php';

<?php
// src/FileLogger.php

// If `use` was not added automatically, 
// be sure to add it yourself
use Psr\Log\LoggerInterface;

// Implement the downloaded interface
class FileLogger implements LoggerInterface
{
    // ...
}

We created the class, but in order for it to meet the requirements of the standard, you need to write all the methods described in the interface. The most important of them is log. The main logic of logging into the file will be written in it.

class FileLogger implements LoggerInterface
{
    // ...
    public function log($level, $message, array $context = []): void
    {
        // Current date in 1970-12-01 23:59:59 format
        $dateFormatted = (new \DateTime())->format('Y-m-d H:i:s');

        // Build the message with the current date, log level, 
        // and the string from the arguments
        $message = sprintf(
            '[%s] %s: %s%s',
            $dateFormatted,
            $level,
            $message,
            PHP_EOL // Line break
        );

        // Writing to the file `devto.log`
        file_put_contents('devto.log', $message, FILE_APPEND);
        // FILE_APPEND flag prevents flushing the file content on each call 
        // and simply adds a new string to it
    }
    // ...
}

To fully satisfy the LoggerInterface, we need to write an implementation for the emergency, alert, critical, error, warning, notice, info and debug methods, which correspond to the levels we have previously reviewed. Their implementation boils down to a very simple principle – we call the log method, passing the necessary level to it.

class FileLogger implements LoggerInterface
{
    // ...
    public function emergency($message, array $context = []): void
    {
        // Use the level from LogLevel class
        $this->log(LogLevel::EMERGENCY, $message, $context);
    }

    public function alert($message, array $context = []): void
    {
        $this->log(LogLevel::ALERT, $message, $context);
    }
    // and so on...
    // ...
}

Use of logger

Now that our class implements the interface proposed by the PSR-3 standard, we can easily use it anywhere. For example, in the file index.php:

<?php
// index.php

// Composer's autoloader
require_once 'vendor/autoload.php';
// Our new Logger class
require_once 'src/FileLogger.php';

$logger = new FileLogger();
$logger->debug('Message from index.php');

Or in any other class:

<?php

use Psr\Log\LoggerInterface;

class ExampleService
{
    /** @var LoggerInterface */
    private $logger;

    public function __construct(LoggerInterface $logger)
    {
        $this->logger = $logger;
    }

    public function doSomeAction(): void
    {
        // do some work
        $this->logger->debug('Message from ExampleService');
    }
}

Please note that we do not specify the final implementation (FileLogger) as the type of the constructor argument, but the interface of the PSR-3 standard. This is very convenient because it allows us to very easily replace the used logger with any other one that supports this interface.

Context

You may have noticed that all methods of the LoggerInterface contain the $context argument. Why is it needed?

The context is intended for transmitting auxiliary and, often, dynamic information. For example, if you are making a debug entry (debug level), you can pass the value of a variable to the context.

In order to apply this argument, we need to support it in the log method. Let's refine it, given that $context is an array.

class FileLogger implements LoggerInterface
{
    // ...
    public function log($level, $message, array $context = []): void
    {
        $dateFormatted = (new \DateTime())->format('Y-m-d H:i:s');

        // Let's convert $context array into json
        $contextString = json_encode($context);
        $message = sprintf(
            '[%s] %s: %s %s%s',
            $dateFormatted,
            $level,
            $message,
            $contextString, // Add context string
            PHP_EOL
        );

        file_put_contents('devto.log', $message, FILE_APPEND);
    }
    // ...
}

Now, at any place of the logger call, we can pass an array of additional information with the second argument.

<?php
// index.php
//...

$userName = 'Elijah';
$userEmail = 'elijah@dev.to';

$logger = new FileLogger();
$logger->debug('Message from index.php', [
    'user_name' => $userName,
    'user_email' => $userEmail,
]);

As a result, we will get a record of the following form:

[2021-09-02 13:00:24] debug: Message from index.php {"user_name":"Elijah","user_email":"elijah@dev.to"}

Regarding the context, there is one very simple rule: any dynamic information should be transmitted in it, but not in the message. That is, if you form a message into a log using sprintf or concatenation of string variables, most likely this information can be put into the context. Following this rule simplifies the search in the log because it eliminates the need to predict (or calculate) the values of variables.

The Monolog library

Despite the simplicity of the logging principle, there is a very wide scope for modifications in this area. We could support other record formats, implement SMS sending, or simply allow you to change the name of the final log file.

Fortunately, all this has been implemented in most libraries for a long time, and one of the most common is monolog.

Among the most significant advantages of this package are:

Full support for PSR-3;
Support for different principles of log handling, depending on the level;
Support for channel names (logger names);
Very wide support of frameworks.

To start using this beautiful tool, we will install it using Composer.

composer req monolog/monolog

The Monolog usage

The main idea of the monolog library is handlers. They allow you to set specific behavior for logging events. For example, to write a message to a text file we'll use StreamHandler. Let's replace the use of our class with the loaded library.

<?php

// index.php

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

// Composer's autoloader
require_once 'vendor/autoload.php';

// We pass a channel name as the argument for Logger
$logger = new Logger('devto-demo');
// Connect the handler. Argument for StreamHandler is a path to a file
$logger->pushHandler(new StreamHandler('devto.log'));

// Then we leave everything as it was
$userName = 'Elijah';
$userEmail = 'elijah@dev.to';
$logger->debug('Message from index.php', [
    'user_name' => $userName,
    'user_email' => $userEmail,
]);

If we run this code, the following entry will appear in the devto.log file:

[2021-09-02T13:16:14.122686+00:00] devto-demo.DEBUG: Message from index.php {"user_name":"Elijah","user_email":"elijah@dev.to"} []

This is very similar to what we had earlier, except for adding the channel name (devto-demo).

An important feature of Monolog handlers is that they can be set the level at which they work. For example, we can write all the errors in a separate file.

<?php

// index.php

use Monolog\Handler\StreamHandler;
use Monolog\Logger;
use Psr\Log\LogLevel;

// ...
$logger = new Logger('devto-demo');
$logger->pushHandler(new StreamHandler('devto.log'));
$logger->pushHandler(new StreamHandler('errors.log', LogLevel::ERROR));

// ...
$logger->emergency('It is not even an error. It is EMERGENCY!!!');

The handler connected to the ERROR level will take overall records of the ERROR level and higher. Therefore, the call to the emergency method falls into both files: devto.log and errors.log

This simple division of records into levels greatly simplifies our reaction to errors. After all, we no longer need to look for them among all the other entries in the log. This is a very simple and useful function.

Log records of the request

In the process of developing our project, the logs are read very simply. They are consistent and clear. But when several people use the product, the logs can get mixed up and just confuse to a greater extent than they help. There is a very simple trick to solve this problem. Instead of the channel name, use a unique session ID. You can get it using the built-in function session_id(). (The session must be started using session_start())

Let's look at an example of the implementation of such a technique:

<?php
// index.php

// Start the session
session_start();

// ...

// Pass the session id as a channel name
$logger = new Logger(session_id());
// ...

What does such a simple refactor give us? A very important feature is to group all records by user requests.

// First request records
[2021-09-02T13:35:54.155043+00:00] b30m8k1fvmf638au7ph0edb3o5.DEBUG: Message from index.php {"user_name":"Elijah","user_email":"elijah@dev.to"} []
[2021-09-02T13:35:54.156800+00:00] b30m8k1fvmf638au7ph0edb3o5.EMERGENCY: It is not even an error. It is EMERGENCY!!! [] []
// Another request records. They have different ids
[2021-09-02T13:36:03.528474+00:00] u7fi04mn99h0timg148rles1um.DEBUG: Message from index.php {"user_name":"Elijah","user_email":"elijah@dev.to"} []
[2021-09-02T13:36:03.529421+00:00] u7fi04mn99h0timg148rles1um.EMERGENCY: It is not even an error. It is EMERGENCY!!! [] []

What's next?

The Monolog supports a lot of very useful ready-made handlers that are worth paying attention to:

TelegramBotHandler – Sends logs via Telegram Bot. Very useful for high levels of logging;
SlackHandler – Very similar to the previous one, but sends records to Slack;
SwiftMailerHandler – Allows to send logs with email;
ChromePHPHandler – Gives access to logs directly from the Chrome browser in Live mode!

Conclusion

Logging is a simple and important tool. It will help you fix errors at an early stage, be sure that nothing is broken in the new version of the code, investigate the cases of your users and have general visibility on the project.

The main thing is to remember the simple rules:

Following PSR-3 will make it easier for you to replace logger classes in your code and will allow you to use external libraries;
Different logging levels will help you focus on what is important;
Separation of dynamic information into context will simplify the search through logs;
The Monolog library implements almost all possible programmer's requirements. Be sure to take the time to study it;
Using the session ID, you can separate log entries for each request;
It is better to write a lot of extra logs than not to add one important one.

PHP-backend Roadmap

Elijah Zobenko — Sat, 11 Sep 2021 19:35:24 +0000

There are tons of tools in IT to ease programmers' workflow and make a product more efficient. But in the very beginning of honing PHP that might be such a puzzle to pick the right direction and instruments to learn first. A common solution for such problems now – roadmaps – visual sequences which answer the question "what to learn next?". Subject I'd like to discuss in the article – where to invest your time and efforts to learn PHP faster and become an in-demand backend programmer.

PHP & Git basics

To learn the programming language – just a beginning. And even here it's important to make the right steps. Don't aim to learn and memorize everything about PHP and simply focus on tools you'll be using 90% of the time. And of course, always apply gathered skills in practice.

The next deserving attention thing after learning PHP – Git. You'll probably be using it on a daily basis regardless of your chosen programming language. In a nutshell, Git is a team cooperation tool, which allows you to save states of a code.

Composer and databases

Usage of external libraries is a great solution in most cases. Especially if they earned the community's trust. To use it efficiently you should learn the Composer – a packet manager to extremely ease the process of connecting and updating all your PHP dependencies.

And finally, we got to the databases. There are so many solutions in the market so it's even hard to list and not to forget any. However, there are few leaders of the field, which I personally recommend to pick for your stack. For relational databases it's PostgreSQL, and for NoSQL – MongoDB. PDO will be useful for understanding how all the interaction between PHP and your data happens, and ORMs – will boost the effectiveness and security of that communication.

Working flow optimization

For any programmer, speed is one of the most important factors. And debugging speed affects it directly. There are two main solutions to get rid of seeded echo and var_dump from a code, but my advice is to use the first and more common – xDebug. It's not ever hard to connect and configure it but it will always be bringing benefits.

But the quality of the code and its style may seem subjective things, but teamwork requires it really often. In the PSR-12 standard, you can find the list of recommendations on how to style it. That standard isn't the only existing one, but it's definitely the most common. To simplify following it you can use CodeSniffer. And in order to develop the habit of writing clean code, you can use Psalm, Phan, or PHPStan linters. There's no need to learn each – better to choose the one you like most. In my case it's Psalm.

What about HTML?

Talking about PHP there is less and less mentioning of Full-stack. Fields of work have long been divided and PHP has taken an honorable place at the backend. Therefore learning HTML isn't a requirement for us but rather an optimization. What is really important is to clearly understand how to implement interaction with the front-end. Essential things in this area for us are REST and JSON API. Web-browser might be replaced with Postman – an ultimate tool to debug API. Earning a habit of documenting interfaces using OpenAPI or Blueprint will save you from constant questions from colleagues and give you +10 to karma.

Boosting up the project

The high response rate of the project is due not only to the servers but also to high-quality code. Sometimes to increase it, it's enough to reduce the number of requests to the database or to remember the result of heavy calculations. Caching mechanisms can help us in this. You will find interfaces for organizing them in the PSR-6 and PSR-16 standards. And choose the final caching mechanism depending on the project.

Another common method of speeding up a project is to perform processing in the background. There are two categories of solutions here: task schedulers (Crontab) will be useful for performing mailings, recalculating tariffs, and other regular tasks. And message brokers will allow you to take heavy operations into the background and monitor their execution without slowing down the response to the user.

Testing and frameworks

Not all teams write tests for the code. This decision can be made on the basis of many factors. But understanding how to write the testable code is extremely important. Practicing with PHPUnit will help you gain knowledge in this area. And if you want to try other approaches, pay attention to Codeception.

When a lot of tools have been studied, it's time to combine them into a coherent system. In order not to reinvent the wheel, pay attention to one of the popular frameworks. In them, you will find the best modern practices, as well as get used to high-quality architecture. I suggest making a choice from the two most popular options:

Symfony – strict and exacting, used mostly in highly loaded applications.
Laravel – the most common and popular today.

Profiling and monitoring

When your project is launched, it is important to monitor its "health". Are the servers coping? Is there a DDoS attack? Is there a fatal exception on the prod? Monitoring is a simple and useful tool that will give you answers to all these questions. You should start with logging. The PSR-3 standard describes the interface, and Monolog will save you from having to write your own logging service. Sentry will help you to be up to date with errors, Grafana will build beautiful graphs, and Graylog or ELK will simplify log search and incident investigation.

However, there are cases that cannot be solved by simple monitoring. For example, if the application is abnormally slow in certain areas. Such incidents are most effectively solved with the help of profiling tools. You will not use them so often, but it is important to remember about their existence.

Of course, the PHP world is not limited to the listed tools and, after mastering them, there is still a lot to learn. But remember: at the beginning of your journey, you should focus on the main and most common things that you will meet in 80-90% of teams. All the listed programs and approaches were chosen according to this criterion. Save the roadmap, and check it in your educational adventure. And finally: success in studying and building a career.