This environment is based on my favorite and most frequently used tools:

• Docker for containerization
• Docker compose for container management
• Latest version of PHP
• Composer for PHP dependency management
• xDebug for application debugging
• RoadRunner for running the application in Long-Running mode
• PHP framework Yii3
• PostgreSQL database, as it supports keep-alive connections, unlike some others.

Unfortunately, I haven't yet formalized my familiar development environment into a template that could be used with the composer create project command. But it's not very convenient anyway, as the template changes and evolves from project to project. I take the version from the previous project for each new one. However, the basic principles haven't changed for a long time, and today I'll show you primarily these.

Dockerfile and state preservation

First, in the root of each project, I have a .docker folder where I put all project-specific things:

• Dockerfile for PHP container images and others
• Configs that are embedded inside container images or connected as volumes. For example, the main php.ini is added inside the image, while xDebug enablement is connected as a volume only in the local development environment
• Container state. I always save the DB state to disk (it's impossible not to do so in production), and in the dev environment - also the composer cache to make its commands run faster. Here's an example structure that I commit to the repository, from my latest project:

.docker
├──data
│  ├──composer
│     └──.gitignore
│  └──postgres
│     └──.gitignore
└──php
   ├──Dockerfile
   ├──php.ini
   └──xdebug.ini

• The data folder is for saving state from containers between restarts. Inside each subfolder is a .gitignore file with two lines: * to ignore everything in this folder and !.gitignore to commit this file itself.
• The php folder contains Dockerfile and configs for the PHP container
• If I need to build any other containers - I'll create another folder next to it, and put Dockerfile and all necessary configs in it as well.

And here's the starting version of my Dockerfile:

FROM php:8.3-cli-bullseye

RUN apt update \
    && apt install -y  \
        libicu-dev \
        linux-headers-generic \
        zip \
        libpq-dev \
    && apt install -y $PHPIZE_DEPS \
    && docker-php-ext-configure intl \
    && docker-php-ext-install -j$(nproc) \
        pdo \
        pdo_pgsql \
        pgsql \
        pcntl \
        sockets \
        intl \
        opcache \
    && pecl install xdebug \
    && docker-php-ext-enable intl \
    && pecl clear-cache \
    && apt purge -y $PHPIZE_DEPS \
    && apt clean

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

ADD .docker/php/php.ini /usr/local/etc/php/conf.d/40-custom.ini

WORKDIR /var/www

ARG USER_ID=1000
ARG GROUP_ID=1000

RUN groupadd -g $GROUP_ID appuser && \
    useradd -m -N -g $GROUP_ID -u $USER_ID appuser && \
    usermod -L appuser && \
    chown appuser:appuser .

USER appuser

COPY --chown=appuser:appuser ./composer.* configuration.php ./

RUN composer install \
        --prefer-dist \
        --no-ansi \
        --no-dev \
        --no-interaction \
        --no-plugins \
        --no-progress \
        --no-scripts \
    && vendor/bin/rr get --no-config -q -n

COPY --chown=appuser:appuser ./ ./
RUN composer du --classmap-authoritative

CMD ["./rr", "serve"]

The following happens in it:

1. Install all necessary system packages using apt, docker-php-ext, and pecl, enable PHP extensions.
   1. Note: I install xDebug, but do not enable it. I'll enable and configure it with a separate config file a bit later. I do this so that it doesn't work in production under any circumstances, including carelessness.
2. Install composer
3. Add the PHP config for production
4. Create a user under which the application will run. This is important because files will be created and modified inside the container (composer packages, logs, results of changes from phpcsfixer, etc.), and we need the user from the host system (ourselves) to be able to read and edit these files. We accept the user and group id values as arguments so that we can set them differently for different systems.
5. Separately add the composer.json, composer.lock, and configuration.php files (config for yiisoft/config) to the container, and install dependencies using composer install. And immediately download the RoadRunner binary. We do this step before copying the project files, as Docker will cache the result and won't repeat these actions until the two source files change, i.e., as long as the list of dependencies and their versions remains unchanged.
6. Add all project files
7. Execute composer du --classmap-authoritative. This step serves two purposes:
   1. Obvious: after adding project files, we optimize the autoloader's speed.
   2. Non-obvious: the merge map for yiisoft/config is generated by the dump-autoload command hook.

If you have any questions about its contents - I'm always happy to answer them in my Telegram channel.

Docker compose config

Secondly, there's always a docker-compose.yml file in the project repository. Yes, I should rename it to compose.yaml under the new standard, but I keep forgetting 😅 Here's its approximate must-have content:

version: "3.8"  
  
services:  
  php:  
    depends_on:  
      db:  
        condition: service_healthy
    build:  
      dockerfile: .docker/php/Dockerfile  
      context: ./  
      args:  
        USER_ID: ${USER_ID:-1000}  
        GROUP_ID: ${GROUP_ID:-1000}  
    command: "./rr serve -c .rr.dev.yaml"  
    user: "${USER_ID:-1000}:${GROUP_ID:-1000}"  
    restart: unless-stopped
    ports:
      - ${WEB_PORT:-80}:80
    volumes:
      - ./.docker/php/php.ini:/usr/local/etc/php/conf.d/40-custom.ini:ro
      - ./.docker/php/xdebug.ini:/usr/local/etc/php/conf.d/99-xdebug.ini:ro
      - ./.docker/data/composer:/home/appuser/.composer
      - ./:/var/www
    environment:
      TZ: Asia/Almaty
      PHP_IDE_CONFIG: ${PHP_IDE_CONFIG:-}
      DB_NAME: ${DB_NAME}
      DB_HOST: ${DB_HOST}
      DB_PORT: ${DB_PORT}
      DB_LOGIN: ${DB_LOGIN}
      DB_PASSWORD: ${DB_PASSWORD}
      XDEBUG_MODE: ${XDEBUG_MODE:-off}
      XDEBUG_CONFIG: "client_host=host.docker.internal"
      XDEBUG_TRIGGER: "yes"
  
  db:
    image: postgres:15-alpine
    restart: unless-stopped
    volumes:
      - .docker/data/postgres/db:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD:-dev}
      POSTGRES_USER: ${DB_USER:-dev}
      POSTGRES_DB: ${DB_NAME:-dev}
    ports:
      - "${DB_PORT:-5432}:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-dev}"]
      interval: 3s
      timeout: 3s
      retries: 10

From this example, you can see that I actively use environment variables. Their values are set in the .env file, which is added to .gitignore. Instead of it, I commit .env.example to the repository, which contains all possible environment variables with empty or fake values. Thanks to this approach, the application depends on environment variables, not on the ways to add them. And here's an example of my .env.example:

##################################
# Port forwarding
##################################
WEB_PORT=80

##################################
# xDebug settings
##################################
# Uncomment next line for xDebug usage with PhpStorm
# PHP_IDE_CONFIG=serverName=docker
# XDEBUG_MODE=develop,debug

# LINUX ZONE. Next configs are for xDebug in linux environment only.
# COMPOSE_FILE=docker-compose.yml:docker-compose.linux.yml
# Uncomment HOST_IP and set host ip in the docker network when using linux, look at docker-compose.linux.yml
# Although it usually is 172.17.0.1, your real value can be easily found with command `ip address | grep docker`,
# you'll see it like "inet 172.17.0.1/16 ..."
# HOST_IP=172.17.0.1

##################################
# Database settings
##################################
DB_HOST=db
DB_PORT=5432
DB_NAME=dev
DB_LOGIN=dev
DB_PASSWORD=dev

If you don't know why certain xDebug settings are needed - I recommend reading my example of configuring xDebug in Docker.

Peculiarities of development under Linux

If you're developing on Linux and not using Docker Desktop (which is exactly what I do), then the host.docker.internal host is not available inside containers. And to be able to use xDebug (it needs to connect to the IDE from the container independently), I always add this block to docker-compose.yml in the service with PHP:

extra_hosts:
  - host.docker.internal:${HOST_IP:-172.17.0.1}

And when I plan to work on a project not alone, I extract this block into a neighboring file, which I usually call docker-compose.linux.yml, while everything else remains in the main file. And to avoid writing the list of connected configs each time in every command (for example, docker compose -f docker-compose.yml -f docker-compose.linux.yml run --rm php php -v), I also add this environment variable to .env:

COMPOSE_FILE=docker-compose.yml:docker-compose.linux.yml

Launch

First of all, of course, we add composer.json and other project files. And the actual launch of such an environment is simple to the point of banality:

docker compose up -d

During the first launch, the container will first build. This can take more than 5 minutes depending on the machine's power and the quality of the internet connection. And when it finally starts - everything is ready for work and debugging.

docker composer run --rm --no-deps php composer require foo/bar

Conclusion

Creating an effective dev environment is not just about setting up tools, it's an evolutionary process. My approach, which I described in this article, has formed over years of working on various projects, from pet projects to large team developments.

The key idea I would like to emphasize is the balance between standardization and flexibility. On one hand, we strive for a reproducible environment that's easy to deploy on any machine. On the other hand, we need the ability to quickly adapt the configuration to the specifics of a particular project.

The use of Docker, a carefully thought-out structure of the .docker directory, flexible settings through environment variables - all this allows us to achieve this balance. We get a stable environment that is easy to customize at the same time.

I paid special attention to performance optimization (data caching, proper layer construction in Dockerfile, autoloader optimization) and convenience. These aspects are often overlooked, especially in the early stages of a project, but they are critically important for long-term success.

I hope that my experience and approach described in this article will help you not only set up environments for your projects faster but also rethink the process of organizing development itself. Remember that each project is unique, and don't be afraid to experiment and adapt these practices to your needs.

Today, I've covered the basics without delving too deep. Many topics have been touched upon here, each of which could be explored in great depth. Let me know what you find interesting, give likes on social media, and I'll publish more content on such topics. You can reach out to me on Reddit or in X. Let's make the development process more efficient and enjoyable together!

So, the first patient. Inside the trait, the fields of its descendants are used. I mean something like this:

trait Foo
{
    public function bar(): string
    {
        return $this->field . static::CONSTANT . $this->method();
    }
}

What's wrong here?

Technically, a class that uses this trait is not required to declare these field, constant and method. They may not be there. At the same time, you can even deceive the static analyzer if you add the following comment to the trait:

/**
  * @mixin SomeClass
  */

Of course, this will work only if SomeClass contains them all: the $field, the CONSTANT and the method().

The problem arises when this trait is added to another class and the developer does not know or forgets to declare all this stuff.

What is the right way?

One should use abstract methods:

trait Foo
{
    public function bar(): string
    {
        return $this->getField() . $this->getConstant() . $this->method();
    }

    abstract protected function getField(): string;
    abstract protected function getConstant(): string;
    abstract protected function method(): string;
}

Thus, we have a technical limitation at the language level: any class that includes this trait will also be obliged to declare three methods on which the main functionality of the trait depends.

Correct option 2

For adherents of the ideas "Traits are evil" and "Composition is strength":

interface BarInterface
{
    public function getField(): string;
    public function getConstant(): string;
    public function method(): string;
}

readonly final class Foo
{
    public function bar(BarInterface $bar): string
    {
        return $bar->getField() . $bar->getConstant() . $bar->method();
    }
}

Here we replace the trait with two things:

• Interface with the three methods which were abstract and protected in the trait.
• The class to which we pass the implementation of this interface in order to call these methods and use their execution results.

• those that cause a business to lose a lot of money
• and those that are the least common. 

While the first ones are immediately clear, what about the second ones? The fact is that the less often we encounter some type of error, the more difficult it is to understand what caused them.

This happened to me at work as well. One morning, the testers noticed that some requests to the backend returned a 502 (Gateway Timeout) error. This bug was a release stopper, so all the senior developers and a devops engineer took it up. At first, it was believed that Nginx returned this error, and the backend had nothing to do with it. After a while, we realized that PHP was to blame. We sinned for everything: turned off the BlackFire, changed OpCache settings, tried different patch versions in PHP, and so on. However, the error itself was not in the infrastructure, but directly in the application code.

Foreword

As an introduction, I’ll tell you that the application is based on the yii2 framework and is originally written by not the most intelligent developers. For example, the DI container was not used, instead there were components, as it was originally intended in the framework many years ago. When the project took off, specialists of a higher level came to it, and they began to write more architecturally verified code. Because of one such change, we got an error that looked like a 502 on the front-end, and for which there were no records in any logs. The first thing that came to mind: this situation with the logs occurs due to memory overflow. That is, when the php process uses more memory than it is allocated by the system. We are familiar with this situation and know how to recognize it, that is why we checked it right away. But we didn't hit this time.

In some time we turned out, that our problem was of a similar nature: the process fell off due to reaching another system limitation, not memory. In a very non-obvious place, we reached the limit on the maximum nesting of function calls. In other words, we have entered a recursion. Moreover, this recursion was implicit. That is, the function did not call itself, but another function, which in turn called the first function, and that again the second, and that again the first one...

And we came to this as follows. In the configuration, we had a component (let's call it 'foo' for clarity). The configuration of this component looked like this:

'foo' => [
    'class' => FooClass::class,
    'property1' => 'value1',
]

One of our developers added the definition of this class to the DI container:

FooClass::class => static fn() => Yii::$app->get('foo'),

What did we get as a result? When the project code accessed a component, the framework tried to create that component. Seeing the need to get a class object in the component definition, it looked for this class first in the DI container, where it found the definition Yii::$app->get('foo'), and again tried to get the component. And so on in a circle.

This is how the simplest mistake managed to fool developers with more than 10 years of experience. We just don't see it very often.

Unexpectedly long search

My salary expectations remained at the same level, but after the publication of my resume on HeadHunter, not a single company wrote to me. Not a single response. I, to put it mildly, was surprised, and began to write responses myself. At the same time, I published my resume on other job boards. Not all companies, to whom I wrote, sent at least some kind of answer, some of them refused silently. With some, I had a dialogue for a while. I went through several interviews at all stages, but I was refused everywhere.

Only one company made a kind of gift for the new year in the form of an offer 😃 I went out with them after the New Year holidays in the Russian Federation.

At the same time, I improve my English in order to calmly communicate with potential employers from Europe and America. I suppose that I could try now, but it’s too scary: after several years of lack of practice in English, my level fell somewhere to B1.

Well, until I went out to a new employer, I decided to focus on project work, freelancing, and consulting other companies. I have quite a lot of experience: I not only wrote the code, but also participated in the formation and change of the processes of the IT departments of the companies in which I worked. I watched a lot of how well or poorly certain processes work in more advanced IT companies.

Post Scriptum and the sudden twist

When I already found a job, hh.ru finally showed me a notification that only companies in Kazakhstan see my resume: after all, I honestly indicated Almaty in it. At the same time, I indicated the salary in RUB. With the ruble exchange rate, which has grown 1.5 times since the spring of 2022, this salary in terms of KZT was inadequately high, and I could not interest Kazakh companies. And the Russian ones just did not see my resume. In your opinion, was this the only problem I had, and is everything in order with hiring in IT and PHP, or has our bubble deflated? And is it a bubble at all? Let's discuss.

At the moment this has happened only once. Usually I worked on adult projects, where either such problems had already been solved, or it was a terrible legacy without resources for refactoring. So, where did I need the Builder?

Task: product feeds optimization

The project was an online store and a marketplace at the same time. A dozen commodity feeds were generated on it. These were files of various formats with a list of products, their categories and characteristics. And they were uploaded to other marketplaces or, more often, to various platforms that provide advertising and analytics services. Each feed had its own settings: what products/brands/categories/etc. should be included in it, what data should be available for products, etc. The settings were stored in the database and displayed in the UI by our marketers.

Each feed was generated independently of the others. Initially, it took up to 10 minutes for each feed and heavily loaded the system, because it read data from the database very actively. And when it was necessary to generate all the feeds, this procedure stretched for an hour and a half, during which the reading replica of the database worked at the limit.

First iteration of optimization

First of all, I've done two things:

• I've used SphinxSearch to search for products and get some data on them. The initial version of feeds was written even before the introduction of the Sphinx, and it was difficult to introduce something new into it, so hands have reached it only now.
• I've made feed generation a single process. The data could be obtained once, and based on it, the necessary feeds could be built. The feed was divided into two things: a filter that chose the suitable products, and a template that created a file from these products. We took a product and passed it through all the feeds. If the filter passed it, the feed wrote information about this product into a file. And so we did for each product.

Second iteration: The Builder

The second thing that came to my mind was to create my own QueryBuilder with top-level “queries”: withBrands(), withCategories(), withPhotoType(), etc. When it was necessary to generate several feeds at a time, a QueryBuilder instance was taken for each of them, and they were merged into one to select from the database only those products that are needed by the current set of feeds. The two goals have been achieved:

• The independence of the entities in the feed generation module from the database structure was preserved.
• Feed generation speed was significantly improved for sertan cases.

As a result the generation code itself changed only in one place: getting products from the repository changed from getProducts(): iterable to getProducts(QueryBuilder …$queries): iterable

Here are the most popular approaches:

• Find something hype on the left road
• Take something proven and reliable on the right road
• Go straight ahead and use your favorite tool

They are good because you don't have to think when using them. You just take what you want - and that's it 😃 Well, if there is a need or a desire to approach the issue more seriously - welcome under the cut, we'll figure it out.

So, if not “quickly”, how to choose then?

1. Make a list of requirements

The very first and most obvious step. But not everything is as simple as we would like. The list should be relevant right now and for the foreseeable future. That is, you need to strike a balance between two directions:

• Do not look into the distant future with the potential growth of the company to a “MAANG killer” and increase RPS from the current 0.1 to 1000.
• Do not leave behind real requirements, current ones and from the foreseeable future (say, in 1-3 years).

2. Choose several candidates that meet all the requirements

And when this is done - conduct a comparative analysis of them, using the requirements drawn up earlier. Do not forget to take into account a few more points:

1. Ease of use.
   The tool that you are going to use regularly should not interfere with your use of it, and even better, it should make this process pleasant and convenient.
2. Frequency of updates.
   Some old, reliable tools eventually stagnate and stop being updated. In this case, even if such a tool seems to be the ideal solution now, there is a rather high probability that it will have to be changed again soon, as it will either no longer meet the security requirements, or will not implement the new features that its rapidly developing competitors will have. There are young tools on the other hand. It is possible to stagnate for them when there is too small community and a few maintainers.
3. The presence of a community, integrations, plugins.
   The lack of a large community for a new cool tool and a large number of integrations that its more proven counterparts have can be a very serious obstacle in the development of your company. Not being able to quickly embed the tool into your current processes is a tangible problem. With older, slower, less user-friendly tools, you can often save yourself dozens or even hundreds of hours of work simply because your problems have already been solved by someone else. And no matter how cool a tool is, at the dawn of its development there is always one obstacle: users need to solve their problems on their own.
4. The presence of expertise in the team.
   Even if an unfamiliar tool does not look complicated, and installation and configuration guides fit on one screen, this does not mean that you will not have difficulties in a month. And since you have no expertise in working with this tool, it is not known how long it will take you to eliminate errors or optimize its work.

In the general case, the analysis should take into account only the main functionality common to all systems. I'm talking about the fact that all infrastructure tools, without exception, sooner or later become obsolete. Immediately think about how you will change this tool to some other one. Not to some specific, but to an abstract one. Caching system - to another caching system. In the case of systems for which there are no standards like PSR, for this you will have to conduct a deeper analysis yourself to identify this common functionality.

3. Weigh all the pros and cons of the chosen instruments

Even in similar situations in similar companies, the choice can be radically different, since the value of one or another point will also change. For some, the ease of use of the system is more important, for some it is the size of the community and related tools, and for some this tool will be built into such a fast-growing business that bandwidth will become the main factor for it, and not at all ease of use and speed its embedding. You can create a table with weights for each tool feature, if you want to make this comparison more visual.

Real Life Example

Now let's try to choose some real tool, which we will select according to the scheme above. The company where I work recently faced the need to change the queue server. Before the replacement, Redis was used, but it ceased to suit us. The volume of information passed through it is growing, its value is high, and we are not ready to lose it in the event of a failure. This implies the main criterion by which it does not suit us: the reliability of message delivery. We do not deal with routing messages between queues, the complex logic of their delivery, and other similar things. The growth of the traffic passed through the queues increases by a maximum of two times per year. Another criterion: the speed of launching a new message broker in production. We want to finish embedding in a month. So, some completely new tool is not suitable, because we are not ready to spend extra time on its embedding because of the lack of finished cases.

At the stage of choosing a tool, everything came down to a classic confrontation:

• RabbitMQ. A couple of our developers already had experience with it. It is also a fairly popular queue server that has a rich set of functionality and works according to the amqp standard. It is the most well documented and easier to install and maintain than other brokers that implement amqp.
• Apache Kafka - very popular among enterprise-level companies. Works according to its own standard.
• NATS was considered as one of the options for a long time, because it did not immediately become clear that it does not persist messages, which means that it loses them after it is turned off. And it was also against him that it only receives messages via UDP, which adds risks of their loss.

So, let's evaluate the two remaining competitors in terms of their capabilities and shortcomings.

RabbitMQ

• Some people on our team have already worked with it, so it has a head start.
• There is a possibility of flexible message routing, thanks to the amqp protocol. The chip is cool, but it is not taken into account in the rating, because this cannot be reused when switching to another broker. Their use will make it more difficult to switch to another instrument when the moment is right.
• Method of clustering. RabbitMQ uses database synchronization for clustering and high availability. It works quickly, clearly, but does not forgive network errors. In other words, if the broker's nodes are located on different servers, in different data centers, network problems will inevitably arise, which will lead to data desynchronization in the nodes.

  Shovel

  There is also an alternative in the form of the Shovel plugin, which uses the amqp standard under the hood and simply forwards messages from the queue of one server to the exchanger of another, while correctly handling network errors, but adding significant overhead, because this is not just a copy of raw data, but a complete processing of a message.

• Message delivery guarantees depend on the settings and only two types are supported:
  • at least once, any message will be delivered one or more times
  • at most once, any message will not be delivered more then once (but it also may be not delivered at all)
• It is possible to enable writing messages to disk so that they are not lost when the queue broker is restarted.
• Rabbit's throughput is not bad, but it seriously drops when writing messages to disk is turned on, down to several thousand messages per second. Other brokers have orders of magnitude higher throughput (from hundreds of thousands to millions per second), but we are within these numbers in the foreseeable future.

Apache Kafka

• We've heard a lot about it, but haven't seen it live.
• Implements only pub/sub, does not know how to route messages. Which, again, is not a minus, but a statement of fact.
• Ability to cluster - available out of the box, without a noticeable loss of performance and restrictions on the local network, which allows you to make readonly replicas, store different queue shards on different servers, etc. Minus: another tool is required, ZooKeeper.
• Message delivery guarantees also depend on the settings, but all three possible types are supported, including “exactly once”, a guarantee that a message will be delivered to the recipient exactly once. However, with this mode of delivery guarantees, there are difficulties when setting up Kafka clusters. Of course, the corresponding recipes are already on the Internet.
• Writing messages to disk is not disabled due to architectural features: queues in Kafka are logs where messages are added by producers and from where they are read by consumers. In other words, all messages received by Kafka are always available for reading, including those that have been processed a long time ago.
• Bandwidth - about 1 million messages per second.

When comparing the pros and cons of these two tools, it becomes clear that Kafka wins tangibly. And yet, we made a choice in favor of RabbitMQ. It's all about its very first plus: this system is already familiar to us, and it is less likely that we will encounter problems in production. At the same time, we do not plan to make a geographically distributed system, i.e. features of Rabbit clustering in our case are not a minus.

In Kafka, however, its architectural difference brings significant difficulties. First, Kafka does not actually have a queue: he has logs divided into partitions, and exactly one consumer can read from each partition. We have never worked with such a scheme, and there is a high probability of a shot in the foot when working with real data in production. We especially feel apprehensive at the thought of scaling when processing messages. You can simply add consumers to a Rabbit. And with Kafka, it is necessary to think in advance about the number of partitions and the distribution of messages over them in order to preserve the order of tasks in some cases.

Our company is growing and developing, and we do not renounce the possibility that we will change RabbitMQ to Kafka in a couple of years, if suddenly our requirements for the queue broker change. And in order for this replacement to be painless, we will not get hung up on the features of the current tool.

Conclusions

If you follow the above plan, you can choose any tool from the available options. Of course, it leaves room for risk: if you choose unequivocally the best available, but unfamiliar tool, you can stumble upon pitfalls during operation. These risks should also be taken into account when choosing a tool. I will give a plan for preparing for the choice of an infrastructure tool again:

1. Make a list of requirements, not missing the real ones and not inventing something beyond what is necessary.
2. Select several candidates and conduct their comparative analysis.
3. Evaluate winning and losing positions for different instruments, guided by current priorities.

Tell me, have you followed a similar plan in your practice? What oddities happened due to unaccounted for requirements or features of the tool? I’m waiting for you in the telegram chat, I’ll be glad to hear your stories and to chat with you!

Introduction

The problem lies precisely in the fact that it is not customary to talk about it. With an 8-hour work day, most developers sincerely believe that they must be as productive as possible for all 8 hours. Or they are sure that their superiors think so. As a result, we either really try to work much more productively than we can, or we diligently pretend that we are.

The taboo nature of this topic leads to an almost complete absence of materials about it in the public domain, which is why we have to get out of the hole we dug ourselves. And if it doesn’t work out, that burnout follows. Are you familiar with this?

1. I procrastinate and can't do anything
2. I'm angry at myself for not being able to do as much as I want, or resenting uninteresting tasks/incorrect guidance/outdated tools.
3. Performance is declining, self-flagellation is rising
4. Complete burnout

Yes, a lot of articles about burnout tell how to prevent it. But at the same time, almost nowhere is it said about procrastination, although it comes long before burnout. And the funny thing is that articles about burnout are read by those who have already fallen into it. As a rule, in the first few years of work in the profession, a couple of burnouts happen to most of us. Of course, we get a wealth of experience as a result, thanks to which it becomes easier to avoid such crises next time. But, nevertheless, rarely anyone manages to avoid them completely. And even more so - few people think of sharing their experience with younger colleagues.

And at the same time, procrastination is something that happens to absolutely all people. Sooner or later, anyway. Usually, we are closely acquainted with procrastination at school. And if at this age it is customary to blame the education system and our teachers, then in the case of a favorite job, everything turns out to be much more complicated. The person is again faced with the feeling of being unable to continue his work, while experiencing a sense of responsibility to himself and the employer, as a result of which he makes the worst possible choice: begins to blame himself.

Here, I'm late with the deadlines for the submission of the task. After all, I love this job so much, why can't I do something for its benefit?

I confess, I myself am a sinner. I still haven't been able to get rid of that reflex. And yet, it is nothing more than a reflex. Procrastination is a state in which many people fall into many times during their lives. So, it has certain mechanics. It has determined causes and remedies.

How to fight procrastination?

No way.

How does procrastination work?

It is important to understand that this is a defense mechanism. There is no need to fight it, because it's just a signal that something goes wrong. Although there can be an infinite number of local reasons for its occurrence, in general, procrastination is a signal of fatigue. You are tired and cannot continue to work. Fatigue can be any, including for reasons that are not quite obvious: physical, moral, from forbidding yourself to be yourself, etc. Of course, the first thing for you to do is to relax. Go on vacation or devote at least one or two evenings to yourself beloved instead of any “have to”.

But what to do, if after a rest the fatigue does not go away? First of all, check to see if you're really resting while you're resting, or are you continuing to build all sorts of systems in your mind (not necessarily in terms of development) and to think about your “have to”. Or maybe you switch from one job to another? In this case, have a rest. For real. And if even this does not help, try the following options.

Causes and solutions to procrastination

Too have to

Our mind is designed in such a way that we are always forced to choose between "I want" and "I have to." And for maximum efficiency, they must be alternated. If you keep postponing your desires until later, after “more important things”, after “have to”, then procrastination and burnout await you. No matter how unnecessary and stupid your desires may seem - allow them to yourself, regularly allow them to yourself. For example, work on the yii3 framework was an outlet for me for a long time. I wrote work tasks as "I have to", and wrote the framework as "I want". This also includes computer and sports games, hiking, music, movies, etc.

Overloaded with plans

How often have you put off a task until later? Maybe they changed priorities? Does it happen that some task is postponed for later again and again? Of course, it happens to everyone. Sometimes it becomes a problem. The problem is that we try to keep a very large number of tasks in our heads. It doesn't have to be big coding tasks. It could be checking email, committing to reply to someone, pending code reviews, and so on. The problem is that the more such tasks we try to remember, the more energy we spend on it. The solution is a to-do list. Personally, I approach it in two stages:

1. First, I write out all my plans. I mean, all my plans and desires. All that I am going to do in one way or another, both in the near future and later. After that, this list is edited. I remove everything that I consider unnecessary in the current situation. It's not just crossing off an item from the list, it's a decision not to move in that direction, not to spend any energy on achieving the goal. Complete rejection of the target.
2. And then I sort this list by urgency and distribute it into several categories. For example, household chores and work chores. Plus I mark some cases as urgent. The purpose of this list is to continue to do only what is on it. To remove cognitive load from trying to remember and correctly prioritize all tasks on the go. It sounds crazy, that's for sure. For me, it also looked like strange crap at first. But you should try too. This method will free you up a significant amount of resources, allowing you to work effectively for much longer than is currently possible. And I immediately answer the question about the situation when you need to do something that is not on the list: put this business on the list. Once again: don't do anything that isn't on the list, and if something still needs to be done, put it on the list.

Frequent switching of attention

People have this feature: we need time to switch to different types of tasks. In other words, if you were working and something distracted you, then it will take you up to half an hour to get back to working condition and work as efficiently as you worked before. And this is if you are in a good condition: you slept well, you are not tired, and so on. In a less productive state, this process will take even longer. Thus, a simple recommendation appears: for the duration of work, ensure the most comfortable environment for yourself, eliminate distractions: turn off notifications on your phone, ask your wife not to disturb you, send your children to kindergarten, and so on. Just imagine: if every 10 minutes notifications come to your messenger, it will unsettle you for 10 minutes. And this means that during the working day you will not start working as efficiently as you can. And, I assure you, it only seems to you that the notifications from the chat do not distract you: in fact, for a split second, your mind is distracted by the thought: “Do I need to read this message?”. And it knocks you off the rhythm.

Excessive endorphin bursts

The result of another extreme between "I want" and "I have to". When we fulfill our desires, we get a charge of endorphins directly to the brain. And if we regularly follow our wishes, then over time we get dependent on them and inevitably come to the simplest ways to get a dose of endorphins. These are food and all kinds of feeds: tiktok, instagram, TV series, reading the contents of chats, etc. And, of course, games. Especially - games with short rounds and clickers. All these things are united by one thing: each of them is an easy and affordable way to get a dose of endorphins. And the brain loves them. If you have reached this stage, the path to productivity will be associated with withdrawal symptoms. You will always want more. At least one sandwich, at least one eye to watch the series, just one quest to complete in the game ... Believe my experience 😄 At some point, I realized that I always fill every free minute with my phone. If there is very little time or no desire to do something specific, I scroll through the chats. In other cases - games and TV series. Compared to this, all other pastimes have become boring, including work. And technically, the point is that the receptors in the brain have developed an addiction to endorphins. And the only way is to reduce the dose so that the sensitivity is restored, and the world sparkles with bright colors again. At the same time, a lot of time will be freed up for other things, and the overall tone will increase.

Psychotherapist.

Today, going to a psychotherapist is not such a bummer as it was thought 10 years ago. Don't neglect this opportunity. A good psychotherapist will definitely shorten your path from procrastination to productivity, will help you to quickly and effectively find and eliminate the causes of its occurrence.

Postscript and Literature

There are other reasons for procrastination, as well as other ways to deal with it. The main thing is not to perceive it as something abnormal and try to fight it. This is just a signal from the body. If nothing above suits you, or if you want to understand the issues of procrastination and efficiency better, I recommend this cool man, a professional procrastinatologist: procrastinatology.com.
I'm not sure if he has much material in English, but at least look at the given site.

As always, I'd be glad to discuss in the Telegram chat. Feel free to supplement the article with your very own experience and ask any questions.

Have a nice day and don't burn out 😊

TL;DR: How To

My story

Now I'm one of the Yii3 core development team. I like this framework very much and I like to help it to become better. The story about how did I come into the core team is as simple as possible. Once I came to the framework telegram chat and saw Alexander Makarov, the framework maintainer, answering the questions in the chat. He was answering every question, not just "interesting" or "useful" ones. It seems that he wrote something on the topic of being written to him in a PM, if there are any questions for him personally, but I'm not sure. Frankly, I was dumbfounded. You can say that Alexander was my idol, and suddenly - here he is, in a chat room where you can chat with him just like with my friends. That moment I've understood I didn't talk to him before just because I've decided he won't want to talk to me. For the same reason I didn't participate in the life of the Yii framework.

Then I decided on an adventure. I was scared, but I have texted Alexander anyway. That time I still was thinking he is smthng more than me. But I convinced myself that, first of all, we are both people, which means that communication is not alien to us. At last, I've written smthng like that:

Hi! My name is Viktor, I'm a PHP developer. I like the Yii framework very much, and I'd like to help in developing of the new, the third version of the framework. Tell me please, how can I start?

And he thanked me for my enthusiasm and gave me links to some GitHub tickets, which I soon got to work on. Tickets were really at the level of "where to start". I don't remember what exactly it was, but it was the little things. Gradually, I got involved in this process and began to do more and more complex things. For example, I wrote the first version of the yiisoft/validator library. Not completely, just proof of concept. At that time I changed my main job and for some months I could not do OpenSource development. But the Yii core team guys took my code, finalized it and turned it into a full-fledged library. Now it has completely different architectural approaches, but for me personally it means a lot: it was my first serious contribution to the popular and, IMHO, the best framework.

My results of the OpenSource development

Of course, I got a lot of experience. I continue to happily engage in OpenSource in my free time and continue to get more and more new experiences. To single out the most striking acquisitions, I will name these points:

Deep understanding of SOLID principles and overall application and library architecture.

In commercial development, you usually don't have the opportunity to sit down and analyze various architectural solutions, write several versions and choose one of them, or even completely rework the original design with a deep refactoring. There are other values in OpenSource: while in commercial development one of the main criteria for choosing anything is the price/quality ratio, in the OpenSource the emphasis is always on quality. And now I use the experience of creating SOLID architectures, gained in OpenSource, in commercial development, where it is more important not to follow the principles to the end, but to understand where and how they should not be followed, what will be the price of their observance and violation.

Writing tests.

I had little experience writing tests before beginning the Yii3 development. Basically it were only the things I've learned myself. In YiiSoft we apply an integrated approach:

• Psalm, statical typification checker.
• PHPUnit, a framework for unit tests.
• Infection, a tool for checking unit tests quality (mutational testing).

It could mean nothing, but we do as full code coverage as possible, set Psalm level 1 and improve Infection MSI up to 100% for every package which is going to be released (see yiisoft/assets for example). It's very valuable for me that I've come to YiiSoft on start of the new evolution iteration of the framework. These tools and the way of their usage were selected by the whole team. We were covering the first packages with tests together. By the way, I've covered with tests my first package so badly that lately I was terrified. It was very difficult to maintain and evolve package with such tests. But this is the case when you learn from mistakes. Although it is these tests that have not yet been refactored at the time of this writing 😆

Experience of working in a self-managing collective

Yes, we all are equal in the team. We usually make more sense for Aleksander Makarov's (@samdark) opinion. But he doesn't shy away from the others too. If anyone have questions or objections, we will discuss it till our common solution.

We've got our cons too. For example, for a long time it was Alexander who performed all managerial work. He was our boss in fact. He made most of architectural decisions, merged PRs and made releases. He also was the one who set the team's priorities.

Once he dropped out of the framework development for a couple of months. We had to get out ourselves. I'm glad to say: we did it. Not at once, but we changed our processes to avoid Alexander in most cases. We've phoned and discussed the most pressing issues, agreed on compromises and priorities. @Samdark came back in some time too. But he is not a bus-factor for the team since then. He is still the most respected team member and the framework maintainer. But now he is doing more in terms of helping the team to improve processes and discuss decisions instead of direct managing. This is a wonderful experience: people united by one idea, on their own initiative, cooperated and are doing a common thing. And most of us are doing this thing for free. You can get a similar experience in a "teal company", I think. But there are still a few such companies, so OpenSource is more simple way to get it.

Summary

The above points are the experience that turned out to be the most vivid for me. It will be smthng else for you. But the most important thing is that everyone can find in OpenSource a lot of experience, not available on commercial development. Not to mention how valuable the line that you have experience developing a popular OpenSource tool is on your CV.

How to start writing code in an OpenSource project yourself

It doesn't matter which one of the OpenSource projects do you like the most. Its team will be glad to get your help. The good news is that it's pretty easy to start writing code for it. The necessary steps are:

1. Find out what help do they need. Find an actual issue list or ask in chat.
2. Write the corresponding code and get review for it.
3. Fix the review comments, if any.

That's all. After that hundreds/thousands/millions of people will use your code! All you need to continue is just to reiterate the above steps again.

The most difficult thing is to do the first step on this path. You should find out the way you can help. It is really pretty easy: the only thing you have to do is to ask a question in the tool community. I'm sure all the OpenSource tools have their own chats or forums for now. I.e. Yii3 has telegram chat rooms @yii3en and @yii3ru. The algorithm is simple: go into the chat, express your desire to help and ask them to submit a ticket that should be dealt with. If it's your first time, you'd rather all for smthng more simple to get into the development process before taking more complex things.

What prevents you from joining an OpenSource product

The algorithm above is really outrageously simple, its implementation is available to everyone. But why do so few people do it?

1. I have no time

You have a full-time job and a family, I guess. And you're busy for 24 hours in a day. Maybe even for 25 hours. However, the secret is simple: you can do OpenSource in your spare working time. It may seem that "spare" and "working" are incompatible things, but it is not so. The fact is that we are really productive only 2-4 hours out of the whole working day. The rest of the time is occupied by other things: code reviews, routine, bureaucracy, etc. But this is ideally, and usually all this time is occupied by procrastination. Consider: do your tasks really take as much time to complete as they do? Don't they? Then I propose an experiment: do your work for 2 hours a day with maximum immersion in it, without being distracted by anything. Prepare a clear plan of action, switch all chats and mail to silent, and go ahead. The second part of the plan is to be sure to dedicate part of your time to what brings pleasure, what you sincerely enjoy. Personally, I sometimes spend this time developing a framework 😃 Well, a significant part of the time - for sluggish work tasks that do not require much concentration. And do not forget about lunch, where you will not be doing work in any form for an hour. It is also desirable to arrange a walk or some kind of physical activity and exercises during breaks.
I bet that with this mode, your efficiency will increase, and part of the freed up time can be given to your favorite OpenSource project.

2. I'm inexperienced

So OpenSource is for you! This is an excellent place to gain experience. As a rule, there are enough tasks of very different complexity: not only to develop new architectural approaches and performance optimization, but also various simple but necessary little things: change the code style, add documentation, rename files and classes, etc. And you will help a lot if you take these things upon yourself. At the same time, you are free to take more complex issues where you need to figure out for implementation, and even ask for help from the main developers of the product. Entering OpenSource development is possible at any stage of professional development if you already know well the programming language used in the product.

3. I'm afraid I'll be laughed at

It was very strange for me to hear this reason. I have never met developers of OpenSource tools so toxic that they somehow ridicule those who want to help them. For what? The only thing that comes to mind is that your friends, having heard that you decided to make your contribution to OpenSource, out of envy and self-doubt, they may try to somehow insult you, stop you, so that in no case it turns out that you are "better than them". Throw such acquaintances if you have them: you should not go under with them. Our path is only forward!

4. I'm scared

Of course, you are! Like anyone else who is going to start something new in his life. It's ok. There is no personal development without fear. A brave person is not one who is not afraid, but the one who acts in spite of fear. Therefore, the best decision is to be afraid and do it 😊 Find new colleagues, and who knows, maybe - friends and a mission?

• No need to bother with setting up a local environment, switching PHP versions, installing additional libraries and resolving conflicts
• One text file with command line aliases is enough for any version of PHP to work on any computer. And from here
  • Ease of transferring data between machines
  • You can safely demolish the system on your main computer, restoring work with PHP will be as simple as git pull

What Aliases are

An alias is an additional or overridden command in the terminal that, when called, actually calls another command. For example, if you always write ls -la to list files in a folder, it makes sense to use the alias alias ls='ls -la'. Thus, every time you type ls in the terminal, ls -la will actually be called.
Creating an alias is a terminal command. Those, you can write alias ls='ls -la' in the terminal, and it will work. But only in the current terminal session. For this to always work, you need to run such a command in all sessions. This is done differently in different shells. I will talk about how this is done in Bash, which is the default in most linux distributions. If you are using ZShell or another one, we will assume that you are aware of how aliases are created in it.

So bash. Any bash user can create a .bashrc file in their home directory, which is always executed when the terminal starts. Ubuntu creates it by default, and by default it makes the following entry in it:

if [ -f ~/.bash_aliases ]; then
    . ~/.bash_aliases
fi

That is, it includes the .bash_aliases file in the home directory, if it exists. I write all my aliases in .bash_aliases to keep them in a separate file. And now - let's start studying its contents.

PHP

I wrote this set of aliases to work with PHP:

alias php='docker run --rm -it -u `id -u`:`id -g` --volume `pwd`:/app -w /app ghcr.io/mileschou/xdebug:8.1 php  $@'
alias php81='docker run --rm -it -u `id -u`:`id -g` --volume `pwd`:/app -w /app ghcr.io/mileschou/xdebug:8.1 php  $@'
alias php8='docker run --rm -it -u `id -u`:`id -g` --volume `pwd`:/app -w /app ghcr.io/mileschou/xdebug:8.0 php  $@'
alias php74='docker run --rm -it -u `id -u`:`id -g` --volume `pwd`:/app -w /app ghcr.io/mileschou/xdebug:7.4 php  $@'

I end up typing commands like php -a for interactive work or php vendor/bin/phpunit for running tests in the terminal, and everything works as if php is local on my machine. And when I need a different version of php for some project, I write, for example, php74 vendor/bin/psalm.

So, let's go to parse the above commands. For each version, I have written the same thing, only the version itself changes.

• docker run starts a new container based on the specified image (it is at the end of the command). Docs for the docker run. All the above options of this command are described on the same documentation page.
• --rm - this parameter says that the container should be removed after it finishes its work. If you do not specify this, for every docker run a new container will be created, after stopping it will not go anywhere, and soon you will run out of hard disk space.
• -it - this parameter is needed to work in an interactive command line session. If you do not specify it, then those php commands that are waiting for some kind of reaction from the user (for example, php -a or scripts that ask for data input) will not work.
• -u starts the container as a specific user. By default, the container runs as root, which can lead to permission issues with files that are mounted from the local machine and modified/created in the container. `id -u` and `id -g` returns the user and group id respectively, and in most cases it will be 1000. These commands are enclosed in backticks so that they are executed before the alias is called. As a result, the command in the alias will be called with the following value of the user parameter: -u 1000:1000 if your user and group id are both 1000.
• --volume `pwd`:/app - this option mounts the current path in the file system (`pwd`) to the container at /app path. In the other words, your files from the current folder will be available in the container at the path /app.
• -w /app - set the path /app as the working folder in the container.
• ghcr.io/mileschou/xdebug:8.1 - the name of the container image to run and its tag (version). I use this image instead of the official php because there is no XDebug in the official one, and sometimes you need debugging or calculating code coverage with tests. The tag is always specified after the colon, in this example it is 8.1
• php $@ is a command that runs inside the container. However, $@ is a bash variable pointing to the line after the alias. I'll show you with an example. If I type php vendor/bin/phpunit --foo --bar in the terminal, the $@ variable will be vendor/bin/phpunit --foo --bar.

PhpStorm

PhpStorm works great with containers. In order to be able to run tests, static analysis or other scripts from PhpStorm with a button, you need to add a container as an interpreter. Docs

However, the adventure doesn't end there. There is another common use case for php in the terminal, Composer.

Composer

With the Composer, everything is as similar as possible. However, the command here is much longer, because environment variables and volumes are added. They are needed for the two purposes:

• to store settings and composer cache between container launches
• and to transfer data for ssh authorization from the host machine to the container.

I have two aliases for it to be able to work with a project where the first version is hardwired. Here I use official container images.

alias composer='docker run --rm -it --tty -u 1000:1000 -e COMPOSER_HOME=/composer-data/.composer -e COMPOSER_CACHE_DIR=/composer-data/.composer/cache -e SSH_AUTH_SOCK=/ssh-auth.sock --volume `pwd`:/app --volume /home/`whoami`/.composer:/composer-data/.composer --volume /run/user/1000/keyring/ssh:/ssh-auth.sock --volume /etc/passwd:/etc/passwd:ro --volume /etc/group:/etc/group:ro composer:2 $@'
alias composer1='docker run --rm -it --tty -u 1000:1000 -e COMPOSER_HOME=/composer-data/.composer -e COMPOSER_CACHE_DIR=/composer-data/.composer/cache -e SSH_AUTH_SOCK=/ssh-auth.sock --volume `pwd`:/app --volume /home/`whoami`/.composer:/composer-data/.composer --volume /run/user/1000/keyring/ssh:/ssh-auth.sock --volume /etc/passwd:/etc/passwd:ro --volume /etc/group:/etc/group:ro composer:1 $@'

In addition to the parameters that I have already analyzed above, several more are used here. I will not repeat myself and will focus only on the new ones.

• -e - this option sets the environment variable inside the container. I have several of them:
  • COMPOSER_HOME=/composer-data/.composer - where the Composer will look for and store its data (for example, access tokens on GitHub)
  • COMPOSER_CACHE_DIR=/composer-data/.composer/cache - where the Composer will look for and store its cache. This is necessary for optimization. If you do not store the cache on the host, it will re-download all packages every time. If there is a package of the required version in the cache, the Composer will simply copy the files from the cache to the project.
  • SSH_AUTH_SOCK=/ssh-auth.sock - path to authorization socket for ssh agent
• Plus I'm mounting a few more volumes from the host. These are pairs to the above environment variables.
  • --volume /home/`whoami`/.composer:/composer-data/.composer - save composer data on the host between container launches
  • --volume /run/user/`id -u`/keyring/ssh:/ssh-auth.sock - forward an authorization socket for the ssh agent into the container
  • --volume /etc/passwd:/etc/passwd:ro and --volume /etc/group:/etc/group:ro dump user accounts from the host in read-only mode (the :ro at the end is responsible for this) into the container. It is worth noting right away that this is not safe, and it is worth doing this only if you understand what you are doing and why. Personally, I believe that the official images of the composer are trustworthy, but this is just my personal opinion. And without these volumes, authorization on the GitHub via SSH with keys from the host machine will not work.

It is worth remembering that the container contains the minimum assembly required for the composer to work. This means that sometimes you will have to append the --ignore-platform-reqs flag to the command you are calling: composer i --ignore-platform-reqs.

If you have any questions or suggestions for improving aliases - welcome to the blog chat, let's chat.

If I want to inherit the class, and there is a private method, I have to study the code to understand why it was made private and whether I can make it public.

This opinion was very unusual for me, and I decided to figure it out if there is really more problems when fields and methods are private by default.
Let's write an extra public method and see how easy is it to support it.

interface FooInterface {
  public function foo();
}

class Foo implements FooInterface {
  public function foo() {
    // do stuff
    $this->bar();
    // do stuff
  }

  public function bar() {
    // do stuff
  }
}

Let us agree that at the time of writing the code, the bar method is no longer used anywhere, and technically we do not care whether to make it public or private.

Private

If we make it private, we will encounter the voiced difficulties: before making the logic of this method public, the programmer will have to familiarize himself with the method code and find out if there are places specific to this particular class. For example, working with a state.

Public

If you make the method public by default, we will avoid the likelihood that we will need to perform the work described above in the future. Just kidding, of course, there is no escape 😄

Let's think about what other problems we can face in a few years after writing a such code. Let's imagine that we did not change this method of the year 3. And now we need to remove it or change the signature. The first question that arises: is this method used in other places of the project? Anyone of company developers could call a public method from any other place, and they all need to be found. You can say that modern IDEs solve this issue instantly, but what if the black magic of frameworks was used?

Complicating it a little more: we found several places where the bar method was used, but it is not entirely clear why, and the authors of that code no longer work in your company. What to do in this case?

Let's add another potential problem to the piggy bank. Some developer decided to slightly change the functionality of bar, but did not deeply seek for usages of this method. And they were. But they were hidden.

Conclusions

The public way does not solve the problem voiced for the private one, but adds a heap of new difficulties. Therefore, I definitely recommend that all fields, constants and methods of classes be made private if they are not used outside the class in which they are declared, and are not explicitly intended for this.

An example of private-to-public refactoring

So, in our project there is a version of the Foo class with the private bar method. At some point, it became obvious that the functionality of this method was needed in a couple of another places. In most cases you can take bar to a separate class, which can be used anywhere in the project using your favorite DI Container. The full code will look like this:

class Bar {
  public function bar() {
    // do stuff
  }
}

interface FooInterface {
  public function foo();
}

class Foo implements FooInterface {
  __construct(private Bar $bar) {}

  public function foo() {
    // do stuff
    $this->bar->bar();
    // do stuff
  }
}

In this case a public contract for the bar functionality will be concluded exactly at the moment when it became needed. Accordingly, the attitude towards it will be appropriate: as a consciously realized contract, and not "another public method, which is unlikely to be used anywhere." Because in such a project, nothing public is just done.

The Trap of Long-Running Processes

Your application grows, and you decide to optimize its performance by switching to a modern web server like RoadRunner, Swoole, or FrankenPHP. Now, PHP processes don't die after each request but are reused. And here's where the interesting part begins: data from one user randomly "leaks" into the requests of another user because the service's state persists between requests.

Or imagine you decide to process orders asynchronously via a message queue. The worker processing the queue lives for a long time and handles thousands of messages in one lifecycle iteration. If your service maintains state, each unprocessed message can affect the processing of subsequent ones, creating tangled and hard-to-debug errors.

Evolution of Usage

Even if your service is currently used in a simple context, without these trendy long-running states, its application might evolve:

• Code that was called once starts being called in a loop
• A simple HTTP request handler is moved to a console command
• Synchronous operations become asynchronous
• The need for scaling and parallel execution arises

In each of these cases, the presence of internal state becomes a source of problems and requires code refactoring.

Solution: Stateless Services

A Stateless service is a class that does not store internal state between calls to its methods. Each method works only with the data passed to it as parameters.
This approach allows abstracting away from the context in which the service is used. A stateless service can be called once, in a loop, or in a long-running application. It doesn't matter to it.

What are the alternatives? Services with state, or stateful. Let's consider an example I often see in various projects.

Example of a Stateful Service

class OrderProcessor
{
    private PaymentGateway $paymentGateway;
    private float $taxRate;
    private ?User $currentUser = null;
    
    public function __construct(PaymentGateway $paymentGateway, float $taxRate)
    {
        $this->paymentGateway = $paymentGateway;
        $this->taxRate = $taxRate;
    }

    public function setUser(User $user): void
    {
        $this->currentUser = $user;
    }

    public function processOrder(array $items): void
    {
        $total = $this->calculateTotal($items);
        $this->paymentGateway->charge($this->currentUser, $total);
    }

    private function calculateTotal(array $items): float
    {
        $subtotal = array_sum(array_map(
            fn($item) => $item['price'] * $item['quantity'],
            $items
        ));
        
        return $subtotal * (1 + $this->taxRate);
    }
}

In this example, it's essential to set the correct user as the service's state. And the result of the processOrder() method depends entirely on it. If, for some reason, the setUser() method was not called, it will attempt to charge money from the wrong person. What else could go wrong? Anything. The main reason is the human factor: you can be sure that sooner or later, one of the project's programmers will fail to ensure the correct user is set in the service, leading to a serious error. Here's what could happen technically:

• The method was forgotten to be called
• After setting the correct user, another user was set (e.g., during the processing of an event chain between the setUser() and processOrder() calls)
• After setting the correct user, the service instance was replaced

Example of a Stateless Implementation

To get rid of the state in the example above, simply remove the user field and the corresponding method, and add the user itself as a parameter to the method that actually depends on it:

class OrderProcessor
{
    private PaymentGateway $paymentGateway;
    private float $taxRate;
    
    public function __construct(PaymentGateway $paymentGateway, float $taxRate)
    {
        $this->paymentGateway = $paymentGateway;
        $this->taxRate = $taxRate;
    }
    
    public function processOrder(User $user, array $items): void
    {
        $total = $this->calculateTotal($items);
        $this->paymentGateway->charge($user, $total);
    }

    private function calculateTotal(array $items): float
    {
        $subtotal = array_sum(array_map(
            fn($item) => $item['price'] * $item['quantity'],
            $items
        ));
        
        return $subtotal * (1 + $this->taxRate);
    }
}

Advantages of This Approach

1. Predictability:

   • Method behavior depends only on input parameters
   • The same input always yields the same result (in this example, we always call paymentGateway->charge() with the same arguments as a result)
   • No implicit dependencies between calls

2. Ease of Testing:

   • No need to worry about initial state
   • Tests become simpler and clearer
   • Methods can be tested in isolation

3. Thread Safety:

   • Can be safely used in a multi-threaded environment
   • No problems with scaling
   • Absence of race conditions

Understanding Different Data Types in Services

Not everything stored in class properties is harmful state. Let's break down three fundamentally different types of data:

1. Configuration

These are immutable values that define the service's behavior:

class OrderProcessor
{
    private readonly float $taxRate;
    private readonly float $minimumOrderAmount;
    
    public function __construct(float $taxRate, float $minimumOrderAmount)
    {
        $this->taxRate = $taxRate;
        $this->minimumOrderAmount = $minimumOrderAmount;
    }
}

Configuration settings are acceptable in class properties because they:

• Do not change during the object's lifetime
• Define the service's base behavior
• Are part of the application's configuration
• Do not depend on the execution context

2. Dependencies

These are other services or resources needed for operation:

class OrderProcessor
{
    public function __construct(
        private readonly OrderRepository $orderRepository,
        private readonly PaymentGateway $paymentGateway,
        private readonly LoggerInterface $logger
    ) {}
}

Dependencies can be stored in properties, as they:

• Are tools for performing operations
• Are usually stateless themselves
• Are injected via the constructor
• Do not change during operation

3. Ephemeral State

This is exactly what should be avoided - data that changes during operation:

// Anti-pattern!
class BadOrderProcessor
{
    private ?User $currentUser = null;
    
    // Avoid methods like this!
    public function setUser(User $user): void
    {
        $this->currentUser = $user;
    }
}

Design Recommendations

1. Configuration:

   • Pass via constructor
   • Make immutable (readonly)
   • Use value objects for complex configurations

2. Dependencies:

   • Inject via constructor
   • Use interfaces
   • Do not change after object creation

3. Ephemeral State:

   • Pass via method parameters
   • Avoid set* methods
   • Use DTOs to group parameters
   • Store in DB or cache if necessary

Conclusion

Designing stateless services is not just a trendy architectural decision. It's a necessity in modern PHP development, where applications must be ready for scaling, parallel execution, and operation in long-running processes.

A proper understanding of the differences between configuration, dependencies, and ephemeral state allows for the creation of clean and maintainable services that are easy to test and safe to use in any context.

Remember: a service that handles a single request today might become part of a complex asynchronous process tomorrow. By designing it stateless from the beginning, you protect yourself from numerous potential problems in the future.

There are two main approaches to entities: the so-called "rich" and "anemic" models. The rich model implies that the entity itself knows what can be done with it and how. Let's say we have such an entity as "order". In a rich domain model, its interface would look like this:

interface OrderInterface
{
    public function getId(): OrderId;
    public function getProducts(): array;
    public function getCustomer(): Customer;
    public function getStatus(): OrderStatus;
    public function create(): void;
    public function update(): void;
    public function delete(): void;
    public function moveTo(OrderStatus $status): void;
    public function removeProduct(Product $product): void
    // etc.
}

It has getters and some methods for its changing: saving to a DB, status modifying (FSM?), etc.

The logic says there will be problems with the Single Responsibility and Interface Segregation principles (from the SOLID), and code coupling of such a project will be very high. Just imagine how many actions in other subsystems need to be done to create an Order: payments, logistics, warehouse, etc. Besides, I've never seen a successful appliance of a rich model. Maybe, I just don't know how to deal with it. If you have an example of a project in which it is justifiably applied, I'll be glad to see its code.

So, let's dwell on the anemic model in more detail. It is called so because the entity has no additional responsibilities and no knowledge of anything other than its own state. That is, if we take the example above, the Order will have only getters. We can even drop them since php 8.1:

class Order
{
    public function __construct(
        public readonly OrderId $id;
        /** @var Product[] */
        public readonly array $products;
        public readonly Customer $customer;
        public readonly OrderStatus $status;
    ) {
    }
}

An entity in an anemic domain model is called DTO, Data Transfer Object.

Data Transfer Object

DTO is just a representation of some data, which travels from one place in a system to another. Ideally, a DTO is created at the entrance to the system and served at the exit from it. For example, a web controller: a user sends data, it comes to a controller in the form of a $_POST array, where we immediately form the corresponding DTO of it. To the internal services of the system we give a fulfilled DTO, not a raw data. Inside the system the data goes exclusively in the form of DTO.

There are two key features of DTO:

Nothing except data representation

DTOs, by definition, lack any logic whatsoever. It is purely a representation of the data. This approach allows DTO usage for end-to-end data transfer between different subsystems, including when this transfer is carried out over the network via API, queues, etc. Because it's just data, it's easy to be serialized and deserialized. The absence of business logic in data guarantees the absence of side effects from the transfer of an object to the next service or subsystem. It's very easy to support and change such classes.

Immutability

DTOs are inherently immutable, and this is their main advantage. What for? Just imagine that a DTO can change. Let's say we have code like this: $service->foo($dto); and we know that the foo method does not need to change the state of the DTO passed to it at all. But time passes, the code changes, and somewhere down the chain of calls, not in foo itself, something like this appeared: $dto->bar = 'baz';. How will the code that comes after the call to foo react to this? When will you notice the behavior has changed? How many hours will it take to debug? Either we can immediately make the object immutable by any of these ways:

• mark all fields readonly
• make fields private and provide access via getters
• mark class @psalm-immutable if Psalm is used in your CI

But what is the way to make changes to the data? No way. This is the point. If the business logic involves data changing, you must create a new object with this new data. Sometimes a DTO may imply such operations itself. To do so, there are with-methods in the conventions of the YiiSoft team, that return a new object of the same class with changed data. Personally I'd prefer calling a variable $instance rather than $new, but that's a minor point.

Service

The second type of classes needed in any project. In contrast to DTOs, services are stateless and implement some kind of logic. The example of services are repositories, controllers, factories, and other kinds of classes that do something. Often, services do some work on the data, that is, on the DTOs passed to them.
What mistakes should be avoided when writing a service, and what benefits will we get?

Service state

This is the only truly blunder in the design of any service. If a service store some state, there are high chances of getting unexpected side effects on the second call of the service. But if a service doesn't store any state, it can easily be reused elsewhere. Or in the same place, within the same php-process, but with other data. And this not only facilitates further development, but also makes it possible to use tools like RoadRunner and Swoole.
So, the wrong way: $service->setData($data)->foo(), the right way: $service->foo($data). If you still find it necessary to leave state in your service for some individual methods to work, it is likely that you should split this service into two.

It is worth making a remark about what the state of the class is. Its fields can contain various payloads: dependencies, settings, cache, and state.

• Dependencies are other services that allow the current one to do its job. We just follow the Dependency Inversion principle and deliver the dependencies to class through the constructor.
• Settings are values that allow the service to work. Database connection data for the repository, web address for the API client, cache prefix, etc.
• The runtime cache stores already calculated values in case these values do not change over time, and their recalculation is resource-intensive. Its usage looks like this:

  if (!isset($this->cache[$id]) {
    $this->cache[$id] = $this->build($id);
  }
  
  return $this->cache[$id];
• The state is not set globally for the entire project/module, but changes depending on the context. This is the only kind of data in the service that can change during program execution. It is on it or with its help that the service performs some work.

So good services can have dependencies, settings and runtime cache, while DTOs only have state.

Of course, there are other architectural patterns that don't fit into these two categories. But they are needed much less frequently. For example, I needed to implement the Builder only once in 10 years of work.

Dockerfile

Let's start with the Dockerfile. Installing xDebug in supported php versions has become quite trivial. All you have to do is install PECL itself, call pecl install and then enable xDebug in php settings. For an Alpine-based image (e.g. php:8.2-fpm-alpine), this command looks like this:

RUN apk add --no-cache linux-headers \
	&& apk add --update --no-cache --virtual .build-dependencies $PHPIZE_DEPS\
	&& pecl install xdebug \
	&& docker-php-ext-enable xdebug \
	&& pecl clear-cache \
	&& apk del .build-dependencies

Done, the image with xDebug has been built!

PhpStorm

Open the settings window, go to PHP -> Servers and add a new server, be sure to specify the correct mappings.

The most important parts are highlighted on the screenshot.

• Absolute path on the server: we should specify which path the project files in the container are available in. In the docker-compose.yml example above, I mounted them as a volume into the container along the path /var/www
• Name. Yes, the name of the server in this case plays a key role, although this field is usually needed just for entering a human-readable name. In order to work correctly with xDebug, it must completely match to what we wrote in the PHP_IDE_CONFIG environment variable. The config above says serverName=docker, so I also named the server docker in the PhpStorm settings. This is necessary so that PhpStorm can match local files with files on the server (in a container).

docker-compose.yml

My minimal docker-compose config usually looks like this:

version: "3.8" 

services: 
  php: 
    build: 
      dockerfile: .docker/php/Dockerfile 
      context: ./ 
    user: "${USER_ID:-1000}:${GROUP_ID:-1000}" 
    restart: unless-stopped 
    volumes: 
      - ./:/var/www 
    working_dir: /var/www 
    environment: 
      PHP_IDE_CONFIG: ${PHP_IDE_CONFIG:-serverName=docker} 
      XDEBUG_MODE: ${XDEBUG_MODE:-off}
      XDEBUG_CONFIG: "client_host=host.docker.internal"
      XDEBUG_TRIGGER: 'yes'
    extra_hosts: 
      - host.docker.internal:${HOST_IP:-172.17.0.1} 
    dns: 
      - 1.1.1.1 
      - 8.8.8.8

Setting up xDebug here is done via environment variables, thanks to Derik Rethans for such a convenient way. All possible xDebug settings and corresponding environment variables can be viewed on the dedicated page.

Changing the value of environment variables during local development is very convenient via the .env file. It may contain something like this:

# Change the name of the PHP server in the PhpStorm settings from docker to project-server
PHP_IDE_CONFIG=serverName=project-server

# Enable xDebug, because it is disabled by default
XDEBUG_MODE=develop,debug,coverage

The minus of this approach is that the debug-session will start with every request. In order not to start it, you have to either remove the XDEBUG_TRIGGER environment variable, or remove debug value from the XDEBUG_MODE environment variable. In the first case you'll still be able to start debug-sessions from your browser with get-parameters or cookies (e.g., with the Chrome extension).

The extra_hosts setting in the docker-compose.yml config deserves special attention. It adds the entries specified in this setting to the hosts of the container. In this case it means the domain host.docker.internal should be searched by 172.17.0.1 IP. The host machine is usually available exactly at this address, but there are exceptions, so the IP is also configured via an environment variable: so that it can be changed.

Finished project

I posted a simple project with the specified settings on github at https://github.com/viktorprogger/xdebug-sample. To check the specified settings work using it, clone it locally and follow these steps:

1. Set up PhpStorm as I described above
2. Create a .env file with the following content:

   XDEBUG_MODE=debug
3. Set a breakpoint in the index.php file
4. Enable xDebug connection listening in PhpStorm
5. If you are using Windows or MacOS, remove extra_hosts from docker-compose.yml
6. Run the docker-compose up -d command. We don't need to start services, but we need to create a network. The next command will not work without it.
7. Run the docker-compose run --rm php php index.php command. Before the first launch, the container image will be built, this will take a few minutes.
8. Voila, script execution is stopped at your breakpoint!