DEV Community: Denis

We are deploying a PHP project on the prod using Ansible

Denis — Wed, 19 Nov 2025 20:18:29 +0000

In this article, we will get to know you at a basic level with Ansible, and deploy a project using it on a PHP server.

Getting to know Ansible

What kind of miracle tool is this?

Ansible is a tool for every YAML champion, with which you can deploy applications, configure configurations, and automate tasks via ssh.

You may have heard of it along with the phrase "Infrastructure as Code (IaC)", because most of the infrastructure is set up using it.

Basic concepts:

Playbook is yaml a file that contains a set of tasks for their sequential execution

---
- name: Update web servers
  hosts: webservers
  tasks: ...


- name: Update db servers
  hosts: databases
  tasks: ...

The example shows the scenario of updating the web server and database

In each scenario, we describe:

name - script name
hosts - the name of the host/hosts from the inventory file
tasks - a set of tasks, you can specify instructions directly or connect individual files with the task itself

For a detailed introduction, go to link

Task is yaml a file with a certain set of commands that is responsible for its area (installing packages, configuring a web server, etc.)

---
- name: Update web servers
  hosts: webservers
  tasks:
  - name: Ensure apache is at the latest version
    ansible.builtin.yum:
      name: httpd
      state: latest

  - name: Write the apache config file
    ansible.builtin.template:
      src: /srv/httpd.j2
      dest: /etc/httpd.conf

- name: Update db servers
  hosts: databases
  tasks:
  - name: Ensure postgresql is at the latest version
    ansible.builtin.yum:
      name: postgresql
      state: latest

  - name: Ensure that postgresql is started
    ansible.builtin.service:
      name: postgresql
      state: started

Here we are already clearly looking at completing tasks in the playbook

In the problem, we can describe:

name - task name
ansible.builtin. - the module and its parameters

The module in the task facilitates the execution of operations by preparing a script inside the module, and the interaction takes place by passing arguments to the module.

For more information, go to link

Vars is yaml a file that contains a set of variables that we can use in task and template files

---  
repo_url: "https://github.com/deniskorbakov/laravel-12-frankenphp-docker.git"  
path_to_remote_directory: "/var/www/laravel"

In the file, we describe the variables that we want to use in our task and template files.

- hosts: app_servers
  vars:
    app_path: "{{ path_to_remote_directory }}/22"

To use variables, we open and close the birds, and in them we specify the name of our variable.

For more information, go to link

Template is j2 a file that we can reuse in task files, for example, to copy configuration files with prepared variables

server {  
    listen 80;  
    listen [::]:80;  
    server_name {{ domain }};  
    server_tokens off;  
    root {{ path_to_remote_directory }}/public;  
    ...
}

This file contains variables that will be determined during the execution of the playbook, thereby allowing flexible configuration of various files.

For more information, go to link

Inventory is ini a file that contains a list of hosts that we can manage via Ansible

[web]
host1
host2 ansible_port=222 # defined inline, interpreted as an integer

[web:vars]
http_port=8080 # all members of 'web' will inherit these
myvar=23 # defined in a :vars section, interpreted as a string

Using these files, we describe our hosts, which in the future we will be able to specify in the playbook.

For more information, go to link

Conclusion on Ansible:

With these concepts, we can describe task scenarios in playbooks, add reusable variables and template files, and be able to perform tasks on multiple hosts.

About the PHP project

I took my own template for the project.:
https://github.com/deniskorbakov/laravel-12-frankenphp-docker

This template contains frankenphp, docker-compose environment, web sockets via centrifugo, Open Api Doc and ready authorization.

It already describes in advance the playbook for deployment on the prod

Writing a Playbook

Description of what needs to be done:

On the prod, we will need to install the necessary packages, configure nginx to proxy our project, issue certificates for the domain, deploy and configure the project itself.

Setting up inventory:

[webservers]  
144.124.249.213  

[all:vars]  
ansible_connection=ssh  
ansible_user=root

We fill in ssh access for the server on which we will deploy the project

We specify variables:

---  
repo_url: "https://github.com/deniskorbakov/laravel-12-frankenphp-docker.git"  
path_to_remote_directory: "/var/www/laravel"  
domain: "v543323.hosted-by-vdsina.com"  
url: "https://{{ domain }}"  
os_environment:  
  - key: APP_URL  
    value: "{{ url }}"  
  - key: APP_ENV  
    value: "production"  
  - key: APP_DEBUG  
    value: "false"  
  - key: OCTANE_HTTPS  
    value: "true"

We fill in the following variables:

repo_url - the url of our project in github
path_to_remote_directory - the path where our project will be located on the server
domain - specify which is linked to our server
url - generated independently from domain
os_environment - fill in the variables for env, which we will replace with the product

Creating a Playbook:

- name: Expand the environment  
  hosts: webservers  
  vars_files:  
    - ../vars/default.yml  
  tasks:  
    - name: Init Packages  
      ansible.builtin.include_tasks: ../tasks/packages/init.yml  

    - name: Setup Docker  
      ansible.builtin.include_tasks: ../tasks/docker/setup.yml  

    - name: Clone Project  
      ansible.builtin.include_tasks: ../tasks/sync/copy.yml  

    - name: Init App  
      ansible.builtin.include_tasks: ../tasks/app/init.yml  

    - name: Configure Nginx  
      ansible.builtin.include_tasks: ../tasks/system/nginx.yml  

    - name: Produce Certificates  
      ansible.builtin.include_tasks: ../tasks/system/cert.yml  

    - name: Rebuild App  
      ansible.builtin.include_tasks: ../tasks/app/rebuild.yml

Here we specify the alias of our hosts from inventory.ini to hosts, add a file with variables and specify the tasks to be performed in turn at startup

We describe Tasks:

Next, let's look at each task in order.

Init Packages

---  
- name: Install required packages  
  ansible.builtin.apt:  
    name:  
      - apt-transport-https  
      - ca-certificates  
      - curl  
      - software-properties-common  
      - gnupg  
      - make  
      - git  
      - nginx  
      - socat  
      - certbot  
      - python3-certbot-nginx  
    state: present  
    update_cache: yes

Here we install all the packages we need to work with.

Setup Docker

---  
- name: Add Docker GPG key  
  ansible.builtin.apt_key:  
    url: https://download.docker.com/linux/ubuntu/gpg  
    state: present  

- name: Add Docker repository  
  ansible.builtin.apt_repository:  
    repo: deb [arch=amd64] https://download.docker.com/linux/ubuntu {{ ansible_distribution_release }} stable  
    state: present  
    filename: docker  

- name: Install Docker  
  ansible.builtin.apt:  
    name:  
      - docker-ce  
      - docker-ce-cli  
      - containerd.io  
    state: present  
    update_cache: yes  

- name: Start and enable Docker service  
  ansible.builtin.service:  
    name: docker  
    state: started  
    enabled: yes  

- name: Add user to docker group  
  ansible.builtin.user:  
    name: "{{ ansible_user | default('ansible') }}"  
    groups: docker  
    append: yes  

- name: Install Docker Compose  
  ansible.builtin.get_url:  
    url: https://github.com/docker/compose/releases/download/v2.29.2/docker-compose-linux-x86_64  
    dest: /usr/local/bin/docker-compose  
    mode: '0755'  

- name: Create symbolic link for Docker Compose  
  ansible.builtin.file:  
    src: /usr/local/bin/docker-compose  
    dest: /usr/bin/docker-compose  
    state: link  

- name: Verify Docker Compose installation  
  ansible.builtin.command: docker-compose --version  
  register: docker_compose_version  
  changed_when: false

In this task, we install docker and docker-compose for further work.

Clone Project

---  
- name: Check if directory exists  
  ansible.builtin.stat:  
    path: "{{ path_to_remote_directory }}"  
  register: project_dir_stat  

- name: Create project dir  
  ansible.builtin.file:  
    path: "{{ path_to_remote_directory }}"  
    state: directory  
    mode: 0755  
  when: not project_dir_stat.stat.exists  

- name: Git clone  
  block:  
    - name: Clone repository  
      ansible.builtin.git:  
        repo: "{{ repo_url }}"  
        dest: "{{ path_to_remote_directory }}"  
        version: "{{ branch | default('main') }}"  
      register: clone_result  
      retries: 3  
      delay: 5  
      until: clone_result is succeeded  
      when: not project_dir_stat.stat.exists

Here we create a directory for the project, if it has not yet been created, and clone our project, which we specified in the variables file.

Init App

---  
- name: Create Storage Public Dir  
  ansible.builtin.file:  
    path: "{{ path_to_remote_directory }}/storage/app/public"  
    state: directory  
    mode: 0755  

- name: Copy env.example  
  ansible.builtin.copy:  
    src: "{{ path_to_remote_directory }}/.env.example"  
    dest: "{{ path_to_remote_directory }}/.env"  
    remote_src: yes  

- name: Set vars in ENV  
  lineinfile:  
    path: "{{ path_to_remote_directory }}/.env"  
    state: present  
    regexp: "^{{ item.key }}="  
    line: "{{ item.key }}={{ item.value}}"  
  with_items: "{{ os_environment }}"  
  become: yes  

- name: Init Project  
  ansible.builtin.command:  
    cmd: make init-prod  
    chdir: "{{ path_to_remote_directory }}"  
  register: command_result  
  failed_when: "'FAILED' in command_result.stderr"

Here we create a public directory, copy env.example to env and replace certain variables that we explicitly specify in the file with variables for ansible and run make init-prod to initialize the project on the prod

Configure Nginx

---  
- name: Delete default dir  
  ansible.builtin.file:  
    state: absent  
    path: /var/www/html  

- name: Copy config  
  ansible.builtin.template:  
    src: ../templates/nginx_conf.j2  
    dest: "/etc/nginx/sites-enabled/{{ domain }}"  

- name: Reload Nginx  
  ansible.builtin.systemd:  
    state: reloaded  
    name: nginx

In this task, delete the default directory, copy the config for nginx, and restart the nginx process.

Produce Certificates

---  
- name: Obtain SSL certificate with certbot  
  ansible.builtin.command: |  
    certbot \  
    --force-renewal \  
    --nginx \  
    --noninteractive \  
    --agree-tos \  
    --cert-name {{ domain }} \  
    -d {{ domain }} \  
    -m test@gmail.com \  
    --verbose  
  args:  
    creates: "/etc/letsencrypt/live/{{ domain }}/cert.pem"  
  become: yes  
  register: certbot_result

Here we already issue certificates for our domain through certbot

Rebuild App

---  
- name: Pause for 2 min  
  ansible.builtin.pause:  
    minutes: 2  

- name: Restart app  
  ansible.builtin.command:  
    cmd: make restart  
    chdir: "{{ path_to_remote_directory }}"  
  become: yes  
  register: restart_result  

- name: Pause for 2 min  
  ansible.builtin.pause:  
    minutes: 2  

- name: Update project  
  ansible.builtin.command:  
    cmd: make update-project  
    chdir: "{{ path_to_remote_directory }}"  
  become: yes  
  register: update_result

In this task, we are restarting our containers and updating these projects so that everything works for sure!

The result of the work done:

Now you and I have written your first playbook and got acquainted with the wonderful tool Ansible for YAML champions

I'm waiting for comments under the post about what can be improved or how you would write this playbook ;)

Bottom line

Today, we learned a little about Ansible, studied its basic concepts, wrote a Playbook with you, and deployed the project on the prod

Thank you for reading this article.

How to create a TUI utility on GO

Denis — Mon, 06 Oct 2025 06:46:41 +0000

Here is the translated text with all formatting preserved:

In this article, I will explain how to create a console TUI utility in Go using ready-made components, show examples of interfaces, and build an application using Goreleaser.

In other words, we will go through the entire cycle of creating an application up to its release.

Everything described in this article is collected in this repository:

https://github.com/deniskorbakov

Background

I really like TUI; with it, terminal utilities come to life with new colors, and the pleasure of using these programs increases significantly.

Recently, with the team at https://жыбийрыр.рф/, we participated in a hackathon where we created a utility (Go + Ansible) for automated deployment and building of all possible applications on a server (a dystopian task).

For this solution, we also used TUI components for the utility, which helped us stand out among the participants and ultimately win.

What we will use to create the utility

1) Cobra - https://github.com/spf13/cobra

2) Fang - https://github.com/charmbracelet/fang

3) Huh - https://github.com/charmbracelet/huh

Cobra

This library is used for creating console applications in Go.

It provides a necessary set of tools for building utilities:

A convenient API for creating commands and defining logic
Support for flags
Suggestions for incorrect command input, etc.

Fang

This library enhances the description of the utility, making it more informative and vibrant, and integrates seamlessly with Cobra.

By adding Fang, you get the following interface:

Huh

This library provides a set of ready-made TUI components and fits perfectly into the color palette of Fang.

Here are the components you can get by using this library:

Creating the Utility

Clone the template:

git clone https://github.com/deniskorbakov/skeleton-cli-go.git

Navigate to the project folder:

cd skeleton-cli-go

Build our application:

make build

Run the template utility:

./cli

Application Architecture

cmd/cli - contains a directory with the name of our application, which includes the main file that initializes cobra.

package main  

import "github.com/deniskorbakov/skeleton-cli-go/internal/command"  

func main() {  
    command.Run()  
}

configs/constname - contains constants that describe (name, short, and long descriptions of commands).

example.go

package constname  

const (  
    // UseExampleCmd Name example command    
    UseExampleCmd = `example`  

    // ShortExampleCmd Short description example command
    ShortExampleCmd = `Example test command`  
    ...
)

root.go

package constname  

const (  
    // UseRootCmd App name and default name command    
    UseRootCmd = `cli`  

    // LongRootCmd Long description root command    
    LongRootCmd = `cli is a example util`  
    ...
)

internal/command - contains the application’s commands.

example.go

package command  

import (  
    "github.com/deniskorbakov/skeleton-cli-go/configs/constname"  
    "github.com/deniskorbakov/skeleton-cli-go/internal/component/form"  
    "github.com/deniskorbakov/skeleton-cli-go/internal/component/output"  
    "github.com/spf13/cobra"  
)  

// exampleCmd Command for build pipeline 
var exampleCmd = &cobra.Command{  
    Use:   constname.UseExampleCmd,  
    Short: constname.ShortExampleCmd,  
    Long:  constname.LongExampleCmd,  
    RunE: func(cmd *cobra.Command, args []string) error {  
       fields, err := form.Run()  
       if err != nil {  
          return err  
       }  

       output.Green("Success green output: ", fields.ExampleInput)  
       output.Red("This command will be run successfully")  

       return nil  
    },  
}

Here is an example of a command that we will need to add to root.go.

root.go

package command  

import (  
    "context"  
    "os"  
    "github.com/charmbracelet/fang"  
    "github.com/deniskorbakov/skeleton-cli-go/configs/constname"  
    "github.com/deniskorbakov/skeleton-cli-go/internal/component/output"  
    "github.com/deniskorbakov/skeleton-cli-go/internal/version"  
    "github.com/spf13/cobra"  
)  

// Run Start app with cobra cmd
func Run() {  
    cmd := &cobra.Command{  
       Use:     constname.UseRootCmd,  
       Long:    constname.LongRootCmd,  
       Example: constname.ExampleRootCmd,  
    }  

    // Disable default options cmd  
    cmd.Root().CompletionOptions.DisableDefaultCmd = true  

    // Add all command in your app  
    cmd.AddCommand(  
       exampleCmd,  
    )  

    if err := fang.Execute(  
       context.Background(),  
       cmd,  
       fang.WithVersion(version.Get()),  
    ); err != nil {  
       output.Red("The app is broken")  
       os.Exit(1)  
    }  
}

This file contains the logic for describing the main command, configuring the utility, listing added commands, and initializing Cobra.

internal/component - contains the application’s components.

internal/component/form/form.go

package form  

import "github.com/charmbracelet/huh"  

// Run Main function that runs an interactive form
func Run() (*Fields, error) {  
    fields := &Fields{}  

    err := huh.NewForm(  
       huh.NewGroup(  
          huh.NewInput().  
             Title("Example Title").  
             Description("Example description input").  
             Value(&fields.ExampleInput),  
       ),  
    ).WithShowHelp(true).Run()  
    if err != nil {  
       return nil, err  
    }  

    return fields, nil  
}

Here we create a form using huh.

internal/component/form/fields.go

package form  

// Fields struct for huh form
type Fields struct {  
    ExampleInput string  
}

This structure contains the fields we specify when creating the form.

In your application, you can remove this implementation if you consider it unnecessary and use any other output.

internal/component/output/output.go

package output  

import (  
    "fmt"  

    "github.com/charmbracelet/lipgloss/v2")  

var (  
    green = lipgloss.Color("#04B575")  
    red   = lipgloss.Color("#D4634C")  
)  

func output(colorText string) {  
    fmt.Println(colorText)  
}  

func Green(str ...string) {  
    output(lipgloss.NewStyle().Foreground(green).Render(str...))  
}  

func Red(str ...string) {  
    output(lipgloss.NewStyle().Foreground(red).Render(str...))  
}

This component is used for outputting text to the console.

You can also easily extend this component by adding your own colors using lipgloss.

internal/version - contains the logic for parsing the application version.

internal/version/version.go

package version  

import (  
    "regexp"  
    "runtime/debug")  

var (  
    regexVersion = `^v?(\d+\.\d+\.\d+)`  
    emptyVersion = "none version"  
)  

// Get return version from debug main version
func Get() string {  
    if info, ok := debug.ReadBuildInfo(); ok {  
       version := info.Main.Version  

       re := regexp.MustCompile(regexVersion)  
       if matches := re.FindStringSubmatch(version); len(matches) > 1 {  
          return matches[1]  
       }  
       return emptyVersion  
    } else {  
       return emptyVersion  
    }  
}

We retrieve the specified version during the application build and use a regular expression to get the version value; if it’s not found, we indicate that the version was not found.

Changing the utility name and its description

Currently, our project’s utility is called cli - let’s replace it with the name of your utility.

Change the path to your application to the name of your utility: cmd/cli -> cmd/your_name_cli.

In the .goreleaser.yaml file, you need to change the name cli to the name of your utility:

version: 2  

env:  
  - GO111MODULE=on  
project_name: your_name_cli

Also, replace the application name in the Makefile:

build:  
    go mod vendor    
    go build -ldflags "-w -s" -o your_name_cli cmd/your_name_cli/main.go

Change the application description in the root command - configs/constname/root.go.

Goreleaser

This is a tool for automating the process of creating releases for projects across different distributions and OS.

The project already includes a .goreleaser.yaml file and a configured GitHub Action.

You only need to add a secret to the repository named GO_RELEASER, which will contain your personal GitHub token.

Conclusion

In this article, I showed you how to create your own TUI utility in Go using a template.

GitHub - I’d be happy if you follow me.

Thank you for reading this article!

Emoji php - emoticons in your project

Denis — Mon, 15 Sep 2025 13:17:52 +0000

Background

There is a need to use emoticons, as implemented in Tg:

Grouping emoticons by type
A collection of emoticons for displaying a list
Correct storage of emoticons in the database
Emoji search (search by tags, name, etc.)

When searching the Internet, I realized that there is no such library in PHP that would solve the problems I needed and decided to write my own library.

Emoji PHP - Link to GitHub: https://github.com/deniskorbakov/emoji-php

What is the problem

Lack of a ready-made tool for this task
Where to get actual emoticons from
Storing Unicode emoticons in the database
Search for emoticons in different languages

I managed to solve all these problems, not in the best way, but I'm quite satisfied with it.

Therefore, if you have something to add, I am waiting for your comments under the post.

Next, let's look at how it was possible to solve everything.

Problem solving

1) Lack of a ready-made tool for this task

To do this, I had to write my own library, below I will show you what it can offer you in terms of functionality.

Simple implementation

In order to install the package, you need PHP (version 8.4 or higher) and composer.

composer require deniskorbakov/emoji-php

After installation, you can work with the class for emoticons.

use DenisKorbakov\EmojiPhp\Emojis;

new Emojis();

Support for 25 languages

To use the support for different languages, I added 25 languages to the project, which provided the repository from the second point, in order to get multilingual grouping and search by emoticons.

A list with a grouping

In order to get a list of emoticons grouped by type, you need to call the following method:

use DenisKorbakov\EmojiPhp\Emojis;
use DenisKorbakov\EmojiPhp\Locale;

new Emojis()->list(Locale::EN);
// return ['smileys & emotion' => ['😀' => ':grinning_face:', ...]]

Depending on the specified Locale, you will get a grouping by the selected language.

The group will contain Unicode (smiley face) and a Short Code, which we will insert into the text or we can use a smiley face in the text, and using the method below we will replace it when saving data to the database.

Replacement of Emoticons and Short Code in the text

In order to replace Unicode in the text with Short Code and vice versa, we use the following methods:

Here we are replacing Unicode with Short Code.

use DenisKorbakov\EmojiPhp\Emojis;

$text = 'Hello, world! 🌍️'

new Emojis()->toCode($text);
// return 'Hello, world! :globe_showing_europe_africa:'

Here we are replacing the Short Code with Unicode

use DenisKorbakov\EmojiPhp\Emojis;

$text = 'Hello :waving_hand:';

new Emojis()->toEmoji($text);
// return 'Hello 👋'

Keyword search

To search by keywords, we use the following method:

use DenisKorbakov\EmojiPhp\Emojis;
use DenisKorbakov\EmojiPhp\Locale;

$searchText = 'shoe'

new Emojis()->search(Locale::EN, $searchText);
// return ['👞' => ':mans_shoe:', ...]

In this method, we specify the language we want to use to perform the search and the text we are looking for.

The result is obtained by the usual coincidence of words in the tags of the searched word.

In the future, I want to improve the search, as it is not perfect, but it is quite suitable for searching by matching keywords.

2) Where to get actual emoticons from

The source of the current emoticons, I chose this repository

It already has:

Support for more than 25 languages
CLDR Short Codes
Collection of relevant emoticons

3) Storing Unicode emoticons in the database

Emoticons can be stored in the database by changing the encoding to utf8mb4

I read somewhere that Discord does not store the Unicode of the smiley face and a certain Short Code in the database, and then converts it to Unicode.

After studying the topic, I realized that it is possible to use standardized Short Codes according to the CLDR specification.

CLDR (Common Locale Data Repository) is an extensive repository of local data that is used by software around the world to correctly display and work with emojis, ensuring their consistency and correct meaning in different language environments

In the second paragraph, I specified a repository that already contains the CLDR Short Code for emoticons.

With this solution, we were able to solve the problem of saving emoticons in the database without changing the encoding of the database itself.

4) Search for emoticons in different languages

For my library, I wanted to implement a keyword search in both Russian and English.

Also, because I chose to make this solution an open library, it was also worth thinking about other languages.

The second point specifies a repository that supports more than 25 languages, and therefore this process took a little time.

Unfortunately, at this stage I had to upload all 25 languages to the project, which increases the package size, in the future I want to solve this problem by adding a command to add and remove languages.

Conclusion

I told you about the problem I faced, showed you solutions to various nuances, and showed you the functionality of the library I created for this purpose.

I will also be glad to see suggestions for future features or bug reports in the issue.

GitHub - I will be glad to receive your subscription to me

Thank you for reading this article.

Misha - console SSH client

Denis — Sat, 06 Sep 2025 11:38:56 +0000

Background

I had a desire to learn go and write some kind of open-source project on it, initially there were no ideas and problems that I could solve in my head.

At work, I often had to connect to several different machines during the working day - access to them lay in different chats, files, etc.

This situation was very annoying for me, that I had to spend a lot of time trying to find the right access points, somewhere there was a connection by password, somewhere by key, and because of this, this process could take even more time.

I did not want to use desktop ssh clients due to the habit of working over ssh through the terminal.

And eventually I realized that I wanted to create my own console ssh client, a short search led me to the fact that console ssh clients are not so popular and not very beautiful - so I started creating Mikhail

Description of Michael

Misha is a console SSH client that will grow into a full-fledged utility for convenient interaction with a remote computer via SSH in the future.

Installation:

# macOS or Linux  
brew install --cask misha

What can Misha do:

1) Knows how to make connections

Create connections - video link

Update connections - link to video

Delete connections - link to video

2) Can connect to a created connection

Connection process - video link

Future features:

1) SCP operations

I want to make a tool kit for ssh out of this utility, so I want to add a future feature for convenient SCP interaction - since I often have to drag something from the server or to the server and constantly Google which arguments scp accepts, it also takes time.

2) Project configuration

I also want to implement a configuration utility where we can set the connection shell theme, the visual theme of the application, the location of various files, and so on.

Bottom line

In this article, I shared with you my project, which I think someone might like and solve the same problem as mine.

I would really appreciate it if you put a star on the repository and also try this utility in practice, because I want to know people's opinions.

I will also be glad to see suggestions for future features or bug reports in the issue.

GitHub - I will be glad to receive your subscription to me

Thank you for reading this article.

Connecting the Centrifugo in laravel

Denis — Fri, 05 Sep 2025 14:46:33 +0000

In this article, we will look at the integration of the Centrifugo real-time server with the Laravel framework, the basic settings and nuances of operation.

This article will be more about the implementation on the framework itself than the description of Centrifugo.

You can also find an example of interaction in this template, which was described in an article about frankenphp+laravel

Centrifugo is a real–time server that supports various transports for connecting clients, including WebSocket, HTTP streaming, Server-Sent Events (SSE), and others. It uses the publish-subscribe pattern for messaging

It acts as an intermediary (proxy) between your backend and clients (web, mobile applications). Its main task is to deliver messages from the server to clients and between clients instantly.

What he can do:

One-way mailing (Push notifications): The server can send a message to all subscribed clients or specific users.
Two-way communication (Pub/Sub): Clients can subscribe to channels (topics) and publish messages in them that all other subscribers will receive (if they have rights).
Scaling: Easily runs in a cluster (via Redis or Tarantool) to handle the load of millions of connections.
Reliability: Restores lost connections and delivers messages that were sent while the client was offline (persistent channels).
Checking access rights: Connection and publication requests always go through your backend for authorization, which ensures security.

Key Philosophy:

Centrifugo does not replace your backend and database. It takes care of the most difficult and resource—intensive part - maintaining millions of constant connections and efficiently sending messages, while the application logic remains on your server.

You can find the documentation here

Deploying the Centrifugo:

We will install it via docker

dockerfile example:

FROM centrifugo/centrifugo:v6 as Base  

FROM base AS dev  

COPY .docker/centrifugo/config-test.json /centrifugo/config.json  

CMD ["centrifugo", "-c",  "config.json"]  

FROM base AS prod  

COPY .docker/centrifugo/config.json /centrifugo/config.json  

CMD ["centrifugo", "-c",  "config.json"]

In this example, we are lifting the container with our service and adding a config with settings.

we use multistaging by separating the configs:

we store the test config in the repository
the second one is on the server or in env github/gitlab

this separation is necessary because it contains the encryption keys and the password from the admin panel.

example of a test configuration:

{
  "token_hmac_secret_key": "your-secret-here",
  "admin_password": "strong-password",
  "admin_secret": "admin-secret",
  "api_key": "your-api-key",

  "channels": [
{
"name": "news",
"publish": true, // Allow clients to publish
      "subscribe": true, // Allow clients to subscribe
      "history_size": 100, // Store the last 100 messages
      "history_ttl": "5m" // Keep the history for 5 minutes
    },
    {
"name": "user:$user", // Personal channel (by user)
      "subscribe": true,
      "publish": false // Only the server can publish
    },
    {
"name": "chat:room-#rooms", // Channel with rooms
      "presence": true, // Enable presence tracking
      "join_leave": true // Send input/output events
}
]
}

to generate your config, you must go into the container and enter the command - centrifugo genconfig

or you can take an example from documentation

token_hmac_secret_key: Mandatory secret for signing clients' JWT tokens.

admin_password / admin_secret: The password for entering the admin panel and the secret for the admin API.

api_key: The key for calling the Server API (for publishing from the backend).

engine: Select an engine for data storage (memory, redis, tarantool). The default value is memory.

presence: Enables global channel presence tracking.

history_meta_ttl: How long to store the meta information of the message history.

namespaces: A more advanced alternative to channels for grouping channel settings.

Next, we add the service to docker compose (your description of the services may vary):

dev - stage:

services:
    centrifugo:  
      build:  
        dockerfile: .docker/centrifugo/Dockerfile  
        target: dev  
      container_name: centrifugo.${APP_NAMESPACE}  
      ports:  
        - '8089:8000'  
      networks:  
        - app  
      ulimits:  
        nofile:  
          soft: 65535  
          hard: 65535

prod:

services:
    centrifugo:  
      build:  
        dockerfile: .docker/centrifugo/Dockerfile  
        target: prod  
      container_name: centrifugo.${APP_NAMESPACE}  
      ports:  
        - '8089:8000'  
      networks:  
        - app  
      ulimits:  
        nofile:  
          soft: 65535  
          hard: 65535

This service operates on the internal 8000 port, so we open the port available to you for external access.

Next, we launch our docker compose and start adding variables to env and installing the sdk library for Laravel.

Installing the sdk that is listed in the dock - at this stage it is officially recommended to install this repository

Follow the installation instructions from the README file

After installation, we check that we have correctly specified the variables in env

BROADCAST_DRIVER=centrifugo  
BROADCAST_CONNECTION=centrifugo

CENTRIFUGO_TOKEN_HMAC_SECRET_KEY="your_secret_key"  
CENTRIFUGO_API_KEY="your_api_key"

CENTRIFUGO_URL=http://centrifugo:8000

BROADCAST_DRIVER & BROADCAST_CONNECTION - the driver and connection that we generated based on the README library

CENTRIFUGO_TOKEN_HMAC_SECRET_KEY - token from the config token_hmac_secret_key

CENTRIFUGO_API_KEY - token from the config api_key

CENTRIFUGO_URL - specify our service and its internal port

Now we can start writing events.

you can find out how events and broadcast work from documentation

An example of using the Centrifugo:

1) An example of sending an event via cron

In this example, we will send the current date to the public channel every 5 seconds.

Example command:

<?php  

declare(strict_types=1);  

namespace App\Console\Commands;  

use App\Events\ExampleEvent;  
use Illuminate\Console\Command;  
use Symfony\Component\Console\Attribute\AsCommand;  

#[AsCommand('example:run')]  
class ExampleCommand extends Command  
{  
    public function handle(): void  
    {  
        ExampleEvent::dispatch();  
    }  
}

Here we trigger an event to send a date.

Example of sending directly via the sdk:

<?php  

declare(strict_types=1);  

namespace App\Console\Commands;  

use Symfony\Component\Console\Attribute\AsCommand;  
use denis660\Centrifugo\Centrifugo;  
use Illuminate\Console\Command;  

#[AsCommand('centrifugo:run')]  
class CentrifugoCommand extends Command  
{  
    public function handle(Centrifugo $centrifugo): void  
    {  
        $centrifugo->publish('example', ['time' => now()]);  
    }  
}

We register the Centrifugo class through the command argument and call the publish method

publish - takes the name of the channel as the first argument, and the second argument is an array with the data that we want to transfer to the channel.

Now we can register the command and specify at what time it will be executed - example of working with cron in Laravel

An example of registering a team in kron:

// routes/console.php
<?php  

declare(strict_types=1);  

use App\Console\Commands\ExampleCommand;  
use Illuminate\Support\Facades\Schedule;  

Schedule::command(ExampleCommand::class)->everyFiveSeconds();

Next, we describe the event that will be executed in our team.

Example of an event:

<?php  

declare(strict_types=1);  

namespace App\Events;  

use App\Enums\ChannelName;  
use Carbon\Carbon;  
use Illuminate\Bus\Queueable;  
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;  
use Illuminate\Broadcasting\InteractsWithSockets;  
use Illuminate\Foundation\Events\Dispatchable;  
use Illuminate\Broadcasting\Channel;  

class ExampleEvent implements ShouldBroadcast  
{  
    use Dispatchable;  
    use InteractsWithSockets;  
    use Queueable;  

    public function __construct()  
    {  
    }  

    public function broadcastOn(): array  
    {  
        return [  
            new Channel(
// using enum instead of the magic value  
                ChannelName::Example->value  
            ),  
        ];  
    }  

    public function broadcastWith(): array  
    {  
        return [  
            'date' => Carbon::now()->format('Y-m-d H:i:s'),  
        ];  
    }  
}

The logic for sending events to the channel is ready

The photo below describes the authorization and subscriptions to the channel, below we can observe the responses from the channel according to the described logic - that every 5 seconds we get the current time.

I will describe about channel authorization and testing through postman below

2) An example of sending a message to a chat

In this example, we will analyze sending events for messenger messages.

Example of a controller for creating a message:

<?php  

declare(strict_types=1);  

namespace App\Http\Controllers\Api\Message;  

final readonly class MessageController  
{  
    public function __construct(  
        private MessageService $messageService,  
    ) {  
    }  

    public function store(int $chatId, StoreDTO $storeDTO): array  
    {  
        $chat = Chat::query()->findOrFail($chatId);  
        Gate::authorize('show', $chat);  

        return $this->messageService->store($chat, $storeDTO);  
    }

In the controller, we search for a chat from the database and check if we have access, then we return a response from the service.

An example of a message service:

<?php  

declare(strict_types=1);  

namespace App\Services\Message;

final readonly class MessageService  
{    
    public function store(Chat $chat, StoreDTO $storeDTO): array  
    {  
        $message = Message::query()  
            ->create([  
                'chat_id' => $chat->id,  
                'user_id' => auth()->id(),  
                'message' => $storeDTO->message,  
            ]);  

        MessageCreated::dispatch($message);  

        return ShowDTO::from($message)->toArray();  
    }

Here we create chat messages, call a reply to create messages, and return data about the created message.

Example of an event for a created message:

<?php  

declare(strict_types=1);  

namespace App\Events\Message;  

use App\DTO\Event\Message\CreateDTO;  
use App\Enums\Channel\ChannelName;  
use App\Enums\Event\MessageEventName;  
use App\Models\Message;  
use Illuminate\Broadcasting\Channel;  
use Illuminate\Broadcasting\InteractsWithSockets;  
use Illuminate\Contracts\Broadcasting\ShouldBroadcast;  
use Illuminate\Foundation\Events\Dispatchable;  
use Illuminate\Queue\SerializesModels;  

final class MessageCreated implements ShouldBroadcast  
{  
    use Dispatchable;  
    use InteractsWithSockets;  
    use SerializesModels;  

    public function __construct(  
        private readonly Message $message  
    ) {  
    }  

    public function broadcastAs(): string  
    {
//enum for the event name
        return MessageEventName::MessageCreated->value;  
    }  

    public function broadcastOn(): Channel  
    {  
        return new Channel(
//enum through which we create the chat channel name.11  
            ChannelName::Chat->byId($this->message->chat_id)  
        );  
    }  

    public function broadcastWith(): array  
    {  
        return CreateDTO::from($this->message)->toArray();  
    }  
}

In this event, we accept the message model and output the array to the channel.

It is also mandatory to use a public channel and not register channel authorization, I will explain why below.

An example that we will receive when sending a message:

When sending an event, it was received by all chat participants.

Nuances that are worth clarifying:

Centrifugo does not integrate with Laravel's channel authorization mechanism out of the box. Instead, it uses its own, more flexible authorization mechanism based on JWT tokens that are generated by your backend - that is, the code below will not work.

use App\Models\User;

Broadcast::channel('orders.{orderId}', function (User $user, int $orderId) {
    return $user->id === Order::findOrNew($orderId)->user_id;
});

Private channels in Centrifugo are implemented not through the Laravel mechanism, but by sending a request to your backend (subscription process) or pre-generating a token with access rights.

We also cannot send through events to all users of the channel except the sender himself, based on the conclusion above - the code below will not work

use App\Events\OrderShipmentStatusUpdated;

broadcast(new OrderShipmentStatusUpdated($update))->toOthers();

If you want to implement this logic, you will have to write it yourself.

If we do not want to implement this logic, we will have to process the event skipping at the sender on the client.

WS testing

You can do this using the sdk for the client - examples or using Postman or its analogues - example from the documentation

For testing via Postman, specify the parameter in the url cf_ws_frame_ping_pong=true

The link will look like this:

ws://localhost:8089/connection/websocket?cf_ws_frame_ping_pong=true

Next, we will describe the interaction using json.

Example of authorization in the Centrifugo:

{"id": 1, "connect": { "token": "your_auth_token"}}

id - record identifier

connect - the type of action that we specify when connecting to the Centrifugo

token - a token for user authorization (in the example below I will show an example of creating an authorization token)

Example of channel subscription:

Here we subscribe to the public channel public-channel

{"id": 2, "subscribe": {"channel": "public-channel"}}

To subscribe to a private channel, you must specify another channel authorization token.

{"id": 2, "subscribe": {"channel": "private-channel", "token": "your_channel_token"}}

id - record identifier

subscribe - the type of action specified when subscribing to the channel in the Centrifugo

channel - the key that contains the name of the channel we want to subscribe to

token - a token for user authorization (in the example below I will show an example of creating an authorization token)

In the end, you should get the following

Next, we need to click the Connect button

After we connect, we need to send our instructions by clicking on the send button

After all the steps, we should see the given answers.

After sending the events, he authorizes the user and subscribes to the channel.

In case of errors, you can safely find their description by error code here

Conclusion about the Centrifugo

As a result, we have that the sdk gives us event support - we send event data to the specified channel - and all the rest of the logic falls on the centrifugo.

We will need to write the authorization methods for our backend application and the centrifugo ourselves - it can support authorization both through sessions and through a token.

Example of creating a token for authorization in the Centrifugo:

Example of an authorization controller:

<?php  

declare(strict_types=1);  

namespace App\Http\Controllers\Api;  

final readonly class AuthController  
{  
    public function __construct(  
        private AuthService $authService  
    ) {  
    }  

    public function WSAuth(): array  
    {  
        $user = User::query()->findOrFail(auth()->id());  

        return $this->authService->WSAuth($user);  
    }

Example of the AuthService Service:

<?php  

declare(strict_types=1);  

namespace App\Services\Auth;  

final readonly class AuthService  
{  
    public function __construct(  
        private Centrifugo $centrifugo,  
    ) {  
    }  

    public function WSAuth(User $user): array  
    {  
        $token = $this->centrifugo->generateConnectionToken((string) $user->id);  

        return new TokenDTO($token)->toArray();  
    }

Here we use the Centrifugo class, which provides us with the sdk and calls the generateConnectionToken method from it, which accepts the string UserId, at the end I output the token itself.

After that, we can process this handle for the client and use the generated token for authorization in the Centrifugo

Private channels:

Based on the fact that we cannot use private laravel channels, we must protect them in another way.

To do this, Centrifugo provides an API to authorize the client to a private channel through a token - we will generate a token in our backend application.

An example of creating a token for authorization in a private channel:

public function generatePrivateToken(User $user): array {  
    $token = $this->centrifugo  
        ->generatePrivateChannelToken(  
            (string) $user->id,  
            'your_private_channel'  
        );  

    return new TokenDTO($token)->toArray();  
}

By analogy with user authorization in the Centrifugo, we can generate a token for a private channel.

Also, Centrifugo is able to subscribe an authorized user to channels and unsubscribe (it works for both public and private channels), which allows us to manage the process more flexibly.

Example of channel subscription

I'll show you an example of a user subscribing to all their chats.

Example of a controller:


<?php  

declare(strict_types=1);  

namespace App\Http\Controllers\Api\WS;  

final readonly class WSController  
{  
    public function __construct(  
        private WSService $wsService,  
    ) {  
    }  

    public function subscribe(): Response  
    {  
        $user = auth()->user();  

        $this->wsService->subscribe($user);  

        return response()->noContent();  
    }  
}

Here we get an authorized user and call "WSService"

Example of the WSService service:

<?php  

declare(strict_types=1);  

namespace App\Services\WS;  

final readonly class WSService  
{  
    public function __construct(  
        private Centrifugo $centrifugo,  
        private ChannelService $channelService,  
    ) {  
    }  

    public function subscribe(User $currentUser): void  
    {  
        $chatChannels = $this->channelService->chats($currentUser);  

        foreach ($chatChannels as $channel) {  
            $this->centrifugo->subscribe(  
                $channel->name,  
                (string) $currentUser->id  
            );  
        }
    }  
}

From the ChannelService we get his current chats in the already in the loop we subscribe each chat to the user using the subscribe method

Example of unsubscribing from a channel

Here in the example, we will unsubscribe when each participant's group is removed from the Centrifugo

public function unsubscribe(Chat $group, Collection $members): void  
{  
    $members->each(function (User $member) use ($group): void {  
        $this->centrifugo->unsubscribe(  
            ChannelName::Chat->byId($group->id),  
            (string) $member->id  
        );  
    });  
}

The result:

We have set up and deployed Centrifugo in a laravel project, shown you examples of how to work with it, and also added it to the template so that you can easily use it and start your wonderful projects.

GitHub - I will be glad to receive your subscription to me in github

Thank you for reading this article.

Peck is a utility for your PHP projects

Denis — Wed, 27 Aug 2025 14:32:30 +0000

Peck is a powerful CLI tool designed to identify wording or writing errors in your codebase: file names, class names, method names, property names, documents, and more.

It often happens that we can incorrectly name a class name, variable name, or file name. It is not always possible to notice this due to various factors, and then there may be typos in the project, which can lead to code complexity and confusion in reading.

Therefore, such a tool will be able to solve this problem, as it can be easily implemented into your pipline, which will allow you to transfer the spell-checking process to a machine, making your life easier.

The installation process

To install the package, you will need php 8.2 and higher, as well as GNU Aspell

GNU Aspell is a free spell—checking program designed to replace Ispell and serve as a standard spell-checking tool in the GNU operating system

Adding this utility to our Dockerfile with php:

RUN apt-get update \  
    && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \  
    git \  
    unzip \  
    librabbitmq-dev \  
    libpq-dev \  
    aspell  \  
    aspell-en \  
    supervisor

And already aspell and aspell-en have been added to the necessary packages

aspell-en - contains spelling checker files for English

Install the package via composer:

composer require peckphp/peck --dev

Initialize the configuration for the package:

./vendor/bin/peck --init

After Initialization, the file peck.json:

{
    "preset": "laravel",
    "ignore": {
        "words": [
            "config",
            "namespace"
        ],
        "paths": [
            "app/MyFolder",
            "app/MyFile.php"
        ]
    }
}

The example provided by the developers

Description of the configuration keys:

words - specify the words that will not be used for spell checking

paths - specify the paths where folders or files will be ignored

in my project, I had to add more words to ignore:

{  
  "preset": "laravel",  
  "ignore": {  
    "words": [  
      "php",  
      "dto",  
      "sha",  
      "centrifugo",  
      "js",  
      "postcss",  
      "phpcs",  
      "makefile",  
      "cors",  
      "filesystems",  
      "websocket",  
      "favicon"  
    ],  
    "paths": [  
      "/public/vendor",  
      "/public/fonts",  
      "/public/js",  
      "/lang/vendor"  
    ]  
  }  
}

We can also move our config to another location and explicitly specify it using the command with the --config flag, where its argument will be the path to the file.

Example:

./vendor/bin/peck --config relative/path/to/peck.json

Now we can run the verification package:

./vendor/bin/peck

I found an error in the file name in the project.:

Misspelling  ./documentation/code_standart.md: 'standart'  

Did you mean: standard, standout, standards, stander

Also, for convenience, add this command to the composer scripts:

...
{
    "scripts": {
        "word-check": "@php vendor/bin/peck",
    }
}

And you can already call this check with the command - composer word-check

Bottom line

Although this package does not have a stable release, you can still try to install it in your projects and check for the correctness of expressions in your code base.

It's up to you to use it or not, the most important thing is to improve the quality of the codebase using the tools that you consider necessary.

I also implemented this tool in my project - laravel + frankenphp template

GitHub - I will be glad to receive your subscription to me in github

Thank you for reading this article.

Creating our own package in php

Denis — Sat, 09 Aug 2025 17:43:56 +0000

This article is intended for those who have never done package projects in bare PHP for their needs before.

I want to share with you my experience, which I encountered, and provide a template that I wrote for packages/projects.:

https://github.com/deniskorbakov/skeleton-php-docker

I will be very glad to receive an asterisk on GitHub and feedback after reading the article!

How to build a project

Project structure

Classic construction of projects written in php

Example

,── src # Directory of your package              
,── Dir1 # Directory for internal logic
│   └── PackageClass.php # A class for external use
,── tests # Directory for tests
│   ├─ Fixtures
│   ├─ Unit

This format is followed in almost all projects — these are key directories. However, you can create additional folders to bring the logic of individual parts of the application into your layers.

Folder names can be any, but it's better to follow generally accepted practices to make it easier for other developers to navigate your code.

Example of possible directories:

scripts/ — scripts for assembly, deployment, or other tasks.
assets/ — static files (styles, scripts, images).
.docker/ — Docker configuration (Dockerfile, Docker Compose).
public/ is the entry point for the web server (if the package includes a web interface).
config/— application configuration files.

Composer

Basic composer structure

You can read more about the setup here.

Key parameters when creating a package:

name/description/keywords:

Example

"name": "deniskorbakov/skeleton-php-docker",  
"description": "A skeleton php libs with docker",  
"keywords": ["php", "skeleton", "package", "docker"],

name' is the package name in thevendor/package` format.
description — a brief description of the functionality.
`keywords' — tags for searching in Packagist.

require:

Example

"require": {  
    "php": ">=8.2"  
},

Specifies the minimum PHP version and dependencies, without which the package does not work.

require-dev:

Example

"require-dev": {  
    "pestphp/pest": "^3.8",  
    "phpstan/phpstan": "^2.1",  
    "rector/rector": "*",  
    "squizlabs/php_codesniffer": "^3.13",  
    "slevomat/coding-standard": "^8.20",  
    "orchestra/testbench": "^10.4"  
},

Dependencies for development (testing, static analysis).

autoload

Example

"autoload": {  
    "psr-4": {  
        "DenisKorbakov\\SkeletonPhpDocker\\": "src/"  
    }  
},

Configure auto-upload for your package.

Useful commands and scripts

Commands:

composer validate — validating the validity of `composer.json'.
`composer outdated' — search for outdated dependencies.

Example scripts:

Example

"scripts": {  
    "tests": "pest --stop-on-failure --colors",  
    "tests-coverage": "pest --coverage --min=90",  
    "tests-mutation": "pest --mutate",  
    "lint": [  
        "@phpstan",  
        "@cs",  
        "@rector"  
    ],  
    "phpstan": "phpstan analyse --memory-limit=2G",  
    "rector": "rector",  
    "cs": "phpcs"  
},

Usage: `composer tests' — running tests.

Static analyzers and linters

Why are they needed

Each of us wants to stick to good quality from the code, but endless reviews pointing out the same formatting errors can annoy people with each other, and at least linters have become the solution to this problem.

Linter is a tool for automatic code analysis for compliance with design standards.

Static analyzers help to find errors before running the code, improving its reliability.

Static Analyzer is a tool that checks code for errors, vulnerabilities, and antipatterns without executing it.

Implementing these tools in older projects can be difficult, so sometimes it's wise to apply them only to modified files.

PHPstan

One of the most popular analyzers for PHP. Its main advantage is strictness levels (from 0 to 9). The higher the level, the more thorough the check.

Useful plugins:

cognitive-complexity — evaluates the complexity of the code.

Code complexity is a metric that shows how difficult the code is to understand and maintain.

PHP_CodeSniffer (PHPCS)

Checks the code for compliance with the standards (PSR-12, PSR-2). You can set up your own rules.

Rector

A tool for automatic refactoring. For example, it can update the syntax from PHP 7.4 to 8.2.

Testing

You should never trust yourself, much less your code

Tests help to make sure that the code is working as expected.

Pest

I chose Pest instead of PHPUnit because of the more concise syntax. However, it has a disadvantage: syntax highlighting only works with the official plugin.

GitHub Actions

Templates for issue

It is also a very good practice to make templates for which the clients of your application package will be able to compile a bug report or ask about its work.

Since it is possible to specify the inputs that they should fill in.:

Package version
Dependency version
A checkbox to confirm familiarization with other issues

There may be many examples, but the most important thing is that there will be no answers from you that the user has provided you with the necessary information to help him

At the output, we will get this form in the issue:

An example is a photo

Release on pakagist

Description of the process

Go to Packagist.
Provide a link to the repository.
Wait for moderation.

The package will be automatically updated when you push it to main. For instant updates, use Packagist Update.

An example is a photo

Output

I have described the key points of creating the package. I hope this article will help those who have not done this before.

Project Template - you can also improve it by sending PR to it.

GitHub - I will be glad to receive your subscription to me and in github

Thank you for reading this article.

Laravel + Franken PHP template

Denis — Sun, 06 Jul 2025 16:11:01 +0000

php

Hello everyone, my name is Denis, and I'm a PHP developer.

I participate in hackathons with the team жыбийрыр — and we faced an issue: we didn’t have a ready-made template to work with, forcing us to rewrite the same code repeatedly.

This article will cover how I created this template, the challenges I encountered, and my general desire to share the work I’ve done.

I want to note that this solution is not ideal, and I welcome constructive criticism in the comments.

Template repository

My GitHub

What’s included in the ready-made template:

Configured multi-threaded FrankenPHP server
Docker environment setup + multi-stage for local and production
Admin panel
API documentation for the project
System monitoring
Basic authentication logic (email verification)
WebSocket server
Configured pipeline (GitHub Actions)

Why FrankenPHP was chosen:

I wanted to experiment with a multi-threaded server, so the choice was between RoadRunner and FrankenPHP.

FrankenPHP was selected over RoadRunner because it’s easier to deploy and performs comparably in many benchmarks.

Tech stack:

Laravel 12
FrankenPHP
Docker/Docker Compose
Redis
PostgreSQL
Laravel Reverb (WebSocket server)
Horizon (queue management wrapper)
PhpStan / PhpCodeSniffer / Rector (static analyzers)
Filament (admin panel)
Beszel (lightweight monitoring)
Scribe (API documentation)
Traefik

Let’s start with the configured server + Docker:

The server is set up using Laravel Octane + FrankenPHP.

Laravel Octane is a provider for running applications on RR, Swoole, and FrankenPHP.

It also has excellent documentation for each server, including deployment guides.

Here’s the resulting Dockerfile:

FROM dunglas/frankenphp:1.4 AS base

RUN apt-get update \
    && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
    git \
    unzip \
    librabbitmq-dev \
    libpq-dev \
    supervisor

RUN install-php-extensions \
    gd \
    pcntl \
    opcache \
    pdo \
    pdo_pgsql \
    pgsql \
    redis \
    zip

WORKDIR /app

COPY --from=composer:2.8 /usr/bin/composer /usr/local/bin/composer

COPY --from=node:23 /usr/local/lib/node_modules /usr/local/lib/node_modules
COPY --from=node:23 /usr/local/bin/node /usr/local/bin/node

RUN ln -s /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm

FROM base AS dev

COPY ./.docker/supervisor/supervisord.dev.conf /etc/supervisor/conf.d/supervisord.conf

CMD ["/usr/bin/supervisord", "-n", "-c", "/etc/supervisor/conf.d/supervisord.conf"]

FROM base AS prod

COPY ./.docker/supervisor/supervisord.prod.conf /etc/supervisor/conf.d/supervisord.conf

CMD ["/usr/bin/supervisord", "-n", "-c", "/etc/supervisor/conf.d/supervisord.conf"]

This Dockerfile is compact, but it can be expanded in the future using multi-stage builds for both local development and production.

The server, queues, WebSocket, and cron tasks are managed via Supervisor.

Supervisor config:

[supervisord]
user=root
nodaemon=true
logfile=/dev/stdout
logfile_maxbytes=0
pidfile=/var/run/supervisord.pid

[program:octane]
command=php /app/artisan octane:frankenphp --watch
autostart=true
autorestart=true
stdout_events_enabled=true
stderr_events_enabled=true
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

[program:horizon]
command=php /app/artisan horizon
autostart=true
autorestart=true
stdout_events_enabled=true
stderr_events_enabled=true
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

[program:schedule]
command=php /app/artisan schedule:run
autostart=true
autorestart=true
stdout_events_enabled=true
stderr_events_enabled=true
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

[program:reverb]
command=php /app/artisan reverb:start
autostart=true
autorestart=true
stdout_events_enabled=true
stderr_events_enabled=true
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

Locally, Traefik is used as a reverse proxy to handle port forwarding.

Example:

  traefik:
    image: traefik:v2.10
    container_name: traefik.${APP_NAMESPACE}
    command:
      - --api.insecure=true
      - --providers.docker=true
      - --entrypoints.web.address=:80
    ports:
      - "80:80"
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    networks:
      - app
  php:
    build:
      context: .
      dockerfile: .docker/php/Dockerfile
      target: dev
    volumes:
      - .:/app
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.${APP_NAMESPACE}.rule=Host(`${APP_HOST:-localhost}`)"
      - "traefik.http.services${APP_NAMESPACE}.loadbalancer.server.port=${APP_PORT:-8000}"

Two key nuances to highlight:

Hot reload mode for the server
Alpine images

About Hot Reload:

FrankenPHP can operate in two modes:

Production mode – The server maintains state and requires a restart to reflect changes (resource-efficient).
Development mode – The server detects changes and updates automatically (slower, suitable for local development).

In development mode, Node.js must be installed in the container since file watching relies on a JS library.

About Alpine images:

The documentation clearly explains why they should be avoided:

The static binaries we provide, as well as the Alpine Linux variant of the official Docker images, use the musl libc library.

PHP is known to perform significantly slower with this library compared to the traditional GNU libc, especially when compiled in ZTS mode (thread-safe mode), which is required for FrankenPHP.

Additionally, some bugs only appear when using musl.

Admin Panel:

We use Filament for projects because of its clear documentation, sleek interface, and rapid admin panel development capabilities.

However, it’s not ideal for large-scale projects due to performance issues.

API Documentation:

A crucial tool for us, as we often needed to showcase endpoints to stakeholders and reduce unnecessary questions from frontend developers about request structures.

The best solution for Laravel currently is Scribe.

Advantages of this library:

Auto-generates endpoints
Auto-generates query/URL/body params
Fine-grained config customization
Theme customization
Explicit parameter specification
Attribute support

Auto-generation works best with Laravel’s built-in Request and Resource classes.

Since the template uses DTOs from Spatie’s Laravel-Data, manual parameter descriptions are necessary.

Monitoring:

Initially, I considered the popular stack: Grafana, Loki, Prometheus, and Promtail.

But I realized it would be overkill for our needs.

Instead, I opted for a simpler yet functional solution: Beszel.

It was perfect for me—a clean interface and easy setup.

Basic Authentication:

A recurring headache was rewriting authentication for each hackathon and integrating it with the frontend.

So, I decided to include authentication + email verification in the template.

A role system was also added, including a "developer" role for accessing system services like the Horizon dashboard.

Example auth service:

<?php

declare(strict_types=1);

namespace App\Services\Controllers;

use Illuminate\Validation\ValidationException;
use Illuminate\Support\Facades\Hash;
use App\DTO\User\UserAuthShowDTO;
use App\DTO\Auth\AuthRegisterDTO;
use App\DTO\Auth\AuthLoginDTO;
use App\Models\User;

final class AuthService
{
    /** @return array<string, mixed> */
    public function register(AuthRegisterDTO $authRegisterDTO): array
    {
        $user = User::query()->create([
            'name'     => $authRegisterDTO->name,
            'role'     => $authRegisterDTO->role,
            'email'    => $authRegisterDTO->email,
            'password' => Hash::make($authRegisterDTO->password),
        ]);

        return UserAuthShowDTO::from($user)->toArray();
    }

    /**
     * @return array<string, mixed>
     * @throws ValidationException
     */
    public function login(AuthLoginDTO $authLoginDTO): array
    {
        $user = User::query()->where('email', $authLoginDTO->email)->firstOrFail();

        if (! Hash::check($authLoginDTO->password, $user->password)) {
            throw ValidationException::withMessages(['bad credentials']);
        }

        return UserAuthShowDTO::from($user)->toArray();
    }
}

WebSocket Server:

In our last hackathon, we needed WebSockets for real-time race data transmission.

So, I added it to the template to save time in the future.

Currently, the best options for WebSocket servers are:

Centrifugo
Laravel Reverb

The best PHP solution for WebSockets is Centrifugo—highly performant and great for large projects.

However, I struggled to set it up quickly during the hackathon.

Instead, I included Laravel Reverb in the template—a decent choice for smaller services. It can later be scaled using queues for better performance.

GitHub Actions:

Configuring pipelines was straightforward, given the abundance of online examples. Here’s what I ended up with:

name: DEPLOY AND BUILD
on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]

jobs:
  coding-standard:
    name: Coding Standard
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
          coverage: none

      - name: Get composer cache directory
        id: composer-cache
        run: |
          echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT

      - name: Cache composer dependencies
        uses: actions/cache@v4
        with:
          path: ${{ steps.composer-cache.outputs.dir }}
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
          restore-keys: |
            ${{ runner.os }}-composer-

      - name: Install dependencies
        run: composer install --no-progress --no-suggest --prefer-dist --no-interaction --ignore-platform-reqs

      - name: Check coding style
        run: composer cs-check

      - name: Check code rector
        run: composer cs-rector

      - name: Perform a static analysis of the code base
        run: ./vendor/bin/phpstan analyse --memory-limit=2G

      - name: Test
        run: php artisan test
  deploy:
    runs-on: [ ubuntu-latest ]
    environment: deniskorbakov
    needs: coding-standard
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4.2.2
      - name: Push to server
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SERVER_IP }}
          username: ${{ secrets.SERVER_USERNAME }}
          password: ${{ secrets.SERVER_PASSWORD }}
          script: |
            cd ${{ secrets.PROJECT_PATH }}
            make update-project

One job checks code quality using static analyzers, and another deploys if changes are merged into main.

I moved all necessary commands into a Makefile to avoid overly long configs and to abstract deployment logic.

Makefile:

include .env

# a set of commands for updating a project in production
update-project: pull composer-install db-migrate build-front rm-images build-prod doc-generate restart

# a set of commands to initialize a project locally
init: build composer-install build-front key-generate storage-link db-migrate seed doc-generate restart build-wait

# a set of commands for initializing a project on production
init-prod: build-prod composer-install build-front key-generate storage-link db-migrate seed doc-generate restart build-prod

build:
    @echo "Building containers"
    @docker compose --env-file .env up -d --build
build-wait:
    @echo "Building containers"
    @docker compose --env-file .env up -d --build --wait
up:
    @echo "Starting containers"
    @docker compose --env-file .env up -d --remove-orphans
build-prod:
    @echo "Building containers"
    @docker compose -f docker-compose.yml -f docker-compose.prod.yml --env-file .env up -d --wait --build
up-prod:
    @echo "Starting containers"
    @docker compose -f docker-compose.yml -f docker-compose.prod.yml --env-file .env up -d --wait --remove-orphans
exec:
    @docker exec -it $$(docker ps -q -f name=php.${APP_NAMESPACE}) /bin/bash
code-check:
    @echo "Perform a static analysis of the code base"
    @DOCKER_CLI_HINTS=false docker exec -it $$(docker ps -q -f name=php.${APP_NAMESPACE}) vendor/bin/phpstan analyse --memory-limit=2G
    @echo "Perform a code rector"
    @DOCKER_CLI_HINTS=false docker exec -it $$(docker ps -q -f name=php.${APP_NAMESPACE}) composer cs-rector
    @echo "Perform a code style check"
    @DOCKER_CLI_HINTS=false docker exec -it $$(docker ps -q -f name=php.${APP_NAMESPACE}) composer cs-check
rector-fix:
    @echo "Fix code with rector"
    @DOCKER_CLI_HINTS=false docker exec -it $$(docker ps -q -f name=php.${APP_NAMESPACE}) composer cs-rector-fix
code-baseline:
    @echo "Perform phpstan generate-baseline"
    @DOCKER_CLI_HINTS=false docker exec -it $$(docker ps -q -f name=php.${APP_NAMESPACE}) vendor/bin/phpstan analyse --generate-baseline --memory-limit=2G
composer-install:
    @echo "Running composer install"
    @docker exec -i $$(docker ps -q -f name=php.${APP_NAMESPACE}) composer install --ignore-platform-reqs
db-migrate:
    @echo "Running database migrations"
    @docker exec -i $$(docker ps -q -f name=php.${APP_NAMESPACE}) php artisan migrate --force
build-front:
    @echo "Building admin frontend for production"
    @docker exec -i $$(docker ps -q -f name=php.${APP_NAMESPACE}) npm i
    @docker exec -i $$(docker ps -q -f name=php.${APP_NAMESPACE}) npm run build
pull:
    @echo "Updating project from git and rebuild"
    @git pull
rm-images:
    @echo "Delete extra images"
    @docker system prune -f
key-generate:
    @echo "Key generate"
    @docker exec -i $$(docker ps -q -f name=php.${APP_NAMESPACE}) php artisan key:generate
storage-link:
    @echo "Storage Link"
    @docker exec -i $$(docker ps -q -f name=php.${APP_NAMESPACE}) php artisan storage:link
seed:
    @echo "Db Seed"
    @docker exec -i $$(docker ps -q -f name=php.${APP_NAMESPACE}) php artisan db:seed
doc-generate:
    @echo "Key generate"
    @docker exec -i $$(docker ps -q -f name=php.${APP_NAMESPACE}) php artisan scribe:generate
restart:
    @echo "restart container"
    @docker restart php.${APP_NAMESPACE}

Conclusion:

That’s it! This article covered the key points. If you’d like a deeper dive into any topic, let me know in the comments.

For a detailed look, check out the repository.

Thanks to everyone who read this post. This is my first publication on Habr, so go easy on me—I tried to focus on the most interesting aspects.