DEV Community: Giacomo Masseroni

lazynginx: a beautiful terminal UI for Nginx management

Giacomo Masseroni — Sat, 17 Jan 2026 17:40:38 +0000

LazyNginx: A Beautiful Terminal UI for Nginx Management

Managing Nginx servers typically involves memorizing commands, juggling configuration files, and navigating complex log directories. LazyNginx simplifies this workflow with an elegant, keyboard-driven terminal interface built with Go and the Bubble Tea framework.

Repository: github.com/giacomomasseron/lazynginx

License: MIT

Requirements: Go 1.21+, Nginx

What is LazyNginx?

LazyNginx is a terminal-based user interface that streamlines common Nginx administration tasks. Rather than typing out systemctl commands or searching for log file locations, administrators can navigate through a clean, intuitive menu to perform essential operations.

The tool brings together Nginx's most frequently used functions into a single, accessible interface. It handles platform-specific differences automatically, making it equally useful on Linux, macOS, and Windows systems.

Key Features

The application covers the essential operations needed for day-to-day Nginx management:

Service Control: Start, stop, and restart Nginx services with a single keystroke. The reload function allows configuration updates without service interruption.

Configuration Management: Test configuration files for syntax errors before applying changes. View the complete nginx.conf file directly within the terminal interface.

Log Monitoring: Access the last 50 lines of both error and access logs without navigating to log directories or remembering file paths.

Status Checking: Quickly verify whether Nginx is currently running on your system.

Design and Usability

LazyNginx uses the Bubble Tea framework to create a responsive terminal UI. Navigation relies on familiar keyboard shortcuts: arrow keys or vim-style h/j/k/l movement, Enter to select, and q to quit. The interface provides clear visual feedback for each operation's success or failure.

The application automatically detects the operating system and adjusts its commands accordingly. On Linux systems with systemd, it uses systemctl. Windows installations use net start/stop commands. For other Unix-like systems, it calls nginx commands directly.

Installation and Setup

Building LazyNginx requires Go 1.21 or later and an existing Nginx installation. The process is straightforward:

git clone https://github.com/giacomomasseron/lazynginx
cd lazynginx
go mod download
go build -o lazynginx
./lazynginx

The tool searches common locations for Nginx configuration files and logs, including /etc/nginx/ on Linux, C:\nginx\ on Windows, and /usr/local/nginx/ on macOS.

Permissions and Platform Support

Certain operations like starting, stopping, and restarting services require elevated privileges. Linux and macOS users should run the application with sudo when needed. Windows users need to launch it with administrator rights.

The cross-platform design ensures consistent functionality across different operating systems, abstracting away platform-specific command differences.

Use Cases

LazyNginx proves particularly valuable in several scenarios:

Learning Environments: New administrators can explore Nginx management without memorizing commands or worrying about syntax errors.

Development Workflows: Developers frequently restarting and reconfiguring Nginx during testing benefit from the streamlined interface.

Quick Diagnostics: When troubleshooting issues, rapidly checking logs and service status through a unified interface saves time.

Remote Server Management: When SSH'd into a server, the terminal UI provides an efficient way to manage Nginx without context switching.

Laravel Pulse card for Clean Architecture UseCase

Giacomo Masseroni — Mon, 12 Jan 2026 12:08:02 +0000

When building Laravel applications with Clean Architecture principles, tracking the performance and execution of your UseCases becomes crucial for monitoring application health.

Laravel Pulse provides an excellent framework for real-time application monitoring, and with the php-clean-architecture package, you can create custom recorder cards to track UseCase execution metrics.

Understanding the Architecture

The php-clean-architecture package helps you implement Clean Architecture patterns in Laravel by providing a structured approach to UseCases.

When combined with Laravel Pulse, you can gain valuable insights into how your UseCases perform in production.

Our custom recorder will track two key events:

UseCaseStarted: Fired when a UseCase begins execution
UseCaseCompleted: Fired when a UseCase finishes execution

By measuring the time between these events, we can calculate execution duration and aggregate statistics.

The Custom Recorder

Let's examine the UseCases recorder class that makes this possible:

<?php

declare(strict_types=1);

namespace App\PulseRecorders;

use App\Events\UseCaseCompleted;
use App\Events\UseCaseStarted;
use Carbon\CarbonImmutable;
use Laravel\Pulse\Facades\Pulse;
use Laravel\Pulse\Recorders\Concerns\Groups;
use Laravel\Pulse\Recorders\Concerns\Ignores;
use Laravel\Pulse\Recorders\Concerns\Sampling;

class UseCases
{
    use Groups;
    use Ignores;
    use Sampling;

    /**
     * The time the last job started processing.
     *
     * @var list<int>
     */
    protected array $lastUseCaseStartedAt = [];

    /**
     * The events to listen for.
     *
     * @var list<class-string>
     */
    public array $listen = [
        UseCaseStarted::class,
        UseCaseCompleted::class,
    ];

    /**
     * Record the request.
     */
    public function record(UseCaseStarted|UseCaseCompleted $event): void
    {
        $now = CarbonImmutable::now();

        if ($event instanceof UseCaseStarted) {
            $this->lastUseCaseStartedAt[get_class($event->useCase)] = $now->getTimestampMs();

            return;
        }

        [$timestamp, $timestampMs, $name, $lastUseCaseStartedAt] = [
            $now->getTimestamp(),
            $now->getTimestampMs(),
            get_class($event->useCase),
            tap($this->lastUseCaseStartedAt[get_class($event->useCase)], fn () => ($this->lastUseCaseStartedAt[get_class($event->useCase)] = null)),
        ];

        $duration = $timestampMs - $lastUseCaseStartedAt;

        Pulse::lazy(function () use ($timestamp, $name, $duration) {
            Pulse::record(
                type: 'use_cases',
                key: $name,
                value: $duration,
                timestamp: $timestamp,
            )
                ->count()
                ->avg();
        });
    }
}

How It Works

Event Listening

The recorder listens to two events through the $listen property. When either event is dispatched, the record() method is automatically invoked by Laravel Pulse.

Tracking Start Times

When a UseCaseStarted event is received, the recorder stores the current timestamp in milliseconds, keyed by the UseCase class name. This creates a simple in-memory registry of when each UseCase type began execution.

Calculating Duration

When a UseCaseCompleted event arrives, the recorder:

Retrieves the start timestamp for that UseCase class.
Calculates the duration by subtracting the start time from the current time.
Records the metric to Pulse with both count and average aggregations.
Cleans up the stored start timestamp.

Pulse Traits

The recorder uses three standard Pulse concerns:

Groups: Allows grouping of recorded data
Ignores: Enables filtering of certain UseCases
Sampling: Provides sampling capabilities to reduce overhead

Setting Up the Events

You'll need to create two events that your UseCases will dispatch. Here's an example structure:

<?php

namespace App\Events;

use Illuminate\Foundation\Events\Dispatchable;

class UseCaseStarted
{
    use Dispatchable;

    public function __construct(
        public object $useCase
    ) {}
}

<?php

namespace App\Events;

use Illuminate\Foundation\Events\Dispatchable;

class UseCaseCompleted
{
    use Dispatchable;

    public function __construct(
        public object $useCase
    ) {}
}

Configuring Pulse

'recorders' => [
    // ... other recorders

    \App\PulseRecorders\UseCases::class => [
        'enabled' => env('PULSE_USE_CASES_ENABLED', true),
        'sample_rate' => env('PULSE_USE_CASES_SAMPLE_RATE', 1),
        'ignore' => [
            // Add UseCase class names to ignore
        ],
    ],
],

Creating the Dashboard Card

To visualize this data, you'll want to create a custom Pulse card. Create a Livewire component that queries the recorded data:

<?php

namespace App\Livewire\Pulse;

use Laravel\Pulse\Livewire\Card;
use Livewire\Attributes\Lazy;

#[Lazy]
class UseCases extends Card
{
    use Thresholds;

    /**
     * Ordering.
     *
     * @var 'slowest'|'count'
     */
    #[Url(as: 'use-cases')]
    public string $orderBy = 'slowest';

    /**
     * Render the component.
     */
    public function render(): Renderable
    {
        [$useCases, $time, $runAt] = $this->remember(
            fn () => $this->aggregate(
                'use_cases',
                ['avg', 'count'],
                match ($this->orderBy) {
                    'count' => 'count',
                    default => 'avg',
                },
            )->map(function ($row) {
                return (object) [
                    'use_case' => $row->key,
                    'count' => $row->count,
                    'avg' => $row->avg,
                ];
            }),
            $this->orderBy,
        );

        return View::make('pulse.use-cases', [
            'time' => $time,
            'runAt' => $runAt,
            'useCases' => $useCases,
            'config' => [
                'threshold' => Config::get('pulse.recorders.'.SlowRequestsRecorder::class.'.threshold'),
                'sample_rate' => Config::get('pulse.recorders.'.SlowRequestsRecorder::class.'.sample_rate'),
            ],
        ]);
    }
}

Benefits of This Approach

This recorder provides several advantages for Clean Architecture applications:

Performance Monitoring: Track how long each UseCase takes to execute
Usage Patterns: See which UseCases are called most frequently
Bottleneck Identification: Quickly identify slow UseCases that need optimization
Production Insights: Get real-time visibility into your application's business logic layer

PHPDocs for Laravel relationships

Giacomo Masseroni — Fri, 24 Oct 2025 16:29:41 +0000

Context
Laravel Relationships
- HasOne
- BelongsTo
- HasMany
- HasManyThrough
- BelongsToMany
- MorphTo
- MorphOne
- MorphMany
- MorphToMany

Context

The context: you have a Laravel 10/11/12 project, and you want to use PHPStan.

You use a PHPStan level 6 (or higher), because it's cool! (and you're right about that).

You execute the PHPStan command, and this is one of the error you get:

------ -----------------------------------------------------------------------------------------------------------------------------
  Line   Models\Base\Comment.php
 ------ -----------------------------------------------------------------------------------------------------------------------------
  82     Method App\Models\Base\Comment::commentable() return type with generic class Illuminate\Database\Eloquent\Relations\MorphTo
         does not specify its types: TRelatedModel, TDeclaringModel
         🪪  missingType.generics
 ------ -----------------------------------------------------------------------------------------------------------------------------

What happened?
You have a model defined like this:

public function commentable(): MorphTo  
{  
    return $this->morphTo(__FUNCTION__, 'commentable_type', 'commentable_id');  
}

Without PHPDoc, PHPStan is unable to check your code to verify if everything is correct.

How can you fix this?

Add this PHPDoc to the function:

/**  
 * @return MorphTo<Model, $this>  
 */
 public function commentable(): MorphTo  
 {  
     return $this->morphTo(__FUNCTION__, 'commentable_type', 'commentable_id');  
 }

Following are all PHPDocs you need to add to Laravel relationships to pass PHPStan level > 6 check.

Laravel Relationships

HasOne

/**  
 * @return HasOne<PostFollowingPost, $this>  
 */
public function postFollowingPostsAsFollowing(): HasOne
{  
    return $this->hasOne(PostFollowingPost::class, 'following_id', 'id');  
}

BelongsTo

/**  
 * @return BelongsTo<Post, $this>  
 */
public function post(): BelongsTo  
{  
    return $this->belongsTo(Post::class, 'id_post');  
}

HasMany

/**  
 * @return HasMany<PostFollowingPost, $this>  
 */
public function postFollowingPostsAsFollowing(): HasMany  
{  
    return $this->hasMany(PostFollowingPost::class, 'following_id', 'id');  
}

HasOneThrough

/**  
 * @return HasOneThrough<Post, Pivot, $this>
 */
public function posts(): HasOneThrough
{  
    return $this->hasOneThrough(Post::class, Pivot::class, 'post_id', 'id');  
}

HasManyThrough

/**  
 * @return HasManyThrough<Post, Pivot, $this> 
 */
public function posts(): HasManyThrough
{  
    return $this->hasManyThrough(Post::class, Pivot::class, 'post_id', 'id');  
}

BelongsToMany

/**  
 * @return BelongsToMany<Post, $this>
 */
public function posts(): BelongsToMany
{  
    return $this->belongsToMany(Post::class, 'post_id', 'id');  
}

MorphTo

/**  
 * @return MorphTo<Model, $this>  
 */
 public function commentable(): MorphTo  
 {  
     return $this->morphTo(__FUNCTION__, 'commentable_type', 'commentable_id');  
 }

MorphOne

/**  
 * @return MorphOne<Post, $this>  
 */
public function post(): MorphOne
{  
    return $this->morphOne(Post::class, 'postable');  
}

MorphMany

/**  
 * @return MorphMany<Post, $this>
 */
public function posts(): MorphMany
{  
    return $this->morphMany(Post::class, 'postable');  
}

MorphToMany

/**  
* @return MorphToMany<Post, $this>  
*/
public function posts(): MorphToMany
{  
    return $this->morphToMany(Post::class, 'name');  
}

I developed a package to generate Laravel Models from an existing database.

The package generates code PHPStan level max compliant:

https://github.com/giacomomasseron/laravel-models-generator

Clean Architecture in a Laravel project

Giacomo Masseroni — Mon, 13 Oct 2025 14:21:25 +0000

What is The Clean Architecture structure?

“Clean Architecture” is a project structure first mentioned by Robert C. Martin (Uncle Bob).

At first glance, this is the diagram of the structure:

The structure is divided in layers, where each layer does have a precise function, separated from the others.
The simplest and more important rule of this structure is:

An inner circle must never know anything about the circles around it.

To learn more about the benefits of this structure, and see the levels in detail, you can read the article on Uncle Bob's blog.

What we want to do today, is apply this structure in a Laravel project that uses the MVC (Model-View-Controller) design pattern.

Let’s go through every level.

Entities

TL;DR: this layer contains "Enterprise Business Rules”.

This is the layer that should change less during the development of the project.
Why?
Because the objects inside this layer contain the enterprise wide business rules, and usually they are defined at the start of the project (or at the start of a new feature).

In a Laravel project there is no Entity concept: we have to create it.
We can create a folder inside the app folder, called “Entities”.

Use Cases

TL;DR: this layer contains the actions your project performs.

Good examples of use cases are:

Login
Register
ConfirmOrder

A use case should be a single, very specific action. It shouldn’t do anything more than its name suggests.

If you structure your project with use cases, you get an unexpected and very powerful benefit: you are creating your project’s documentation.
If an external developer looks at your use cases list, it understands exactly what your project is about.

In a Laravel project there is no UseCase concept: we have to create it.
We can create a folder inside the app folder, called “UseCases”.

Interface adapters

TL;DR: this layer contains all MVC elements.

This is the most controversial and ambiguous layer.
Many classes could be inside it, it’s the developer choice.

For start, the best decision in a Laravel project is to put inside it:

Models
Views
Controllers

At the end of the day, how should I develop?

In a Laravel controller, you can just call an UseCase.
In an UseCase, you can just call classes in the Entity layer.

An example of Laravel controller:

namespace App\Http\Controllers;

use App\UseCases\LoginUseCase;
use Illuminate\Http\Request;

public class AuthController extends Controller
{
    public function login(Request $request)
    {
        LoginUseCase::run($request);
    }
}

What if I have to update a database model in an UseCase?

Since a model is in the Interface Adapters layer, an UseCase must not depend on a lower layer.

So we add the Repository pattern to abstract the Database and to create coupling only between UseCase and Repository.

In a Laravel project there is no Repository concept: we have to create it.
We can create a folder inside the app folder, called “Repositories”.

An example of UseCase:

namespace App\UseCases;

use App\Repositories\UserRepository;

class LoginUseCase
{
    public static function run(...$arguments): mixed
    {
        return UserRepository::login($arguments);
    }
}

Our Laravel project structure will be:

app
    Http
    Entities
    Models
    Providers
    Repositories
    UseCases

Best practices

Always work with interfaces.

You should create interfaces for every layer, in order to keep your code more stable and maintainable.

EntityInterface
UseCaseInterface
RepositoryInterface
ArchitectureControllerInterfacer

Now what?

There are a lot of improvements you can do. These are some examples:

Use Laravel validation rules for validating parameters passed to use case;
Work with dependency injection and substitute the static run function with a not static run function;

I developed a PHP package on Github to use it.