Sounds like a solved problem. And honestly, if you build it this way, your first ten test queries will look great. You’ll show it to a colleague and feel proud.

Then someone types “the bot stopped responding after I configured the webhook” and your neat three-step system retrieves chunks about webhook setup, chunks about bot response formatting, and chunks about Slack timeout handling. Every chunk ranked well on similarity. None of them contain the actual answer. The answer is hiding in the relationship between a misconfigured webhook endpoint and an error handler that quietly drops incoming messages.

Vector search located text that looks like the question. The answer slipped right through.

This is the line between tutorial RAG and production RAG.

Five Problems the Acronym Hides

I’ve been running a RAG pipeline in production, and every failure that wasn’t immediately obvious falls into one of five categories. The three-step model acknowledges none of them.

1. The classification problem.

Not every message from a user needs retrieval. Someone writes “got it, thanks” and the system launches a full embedding pass, hits the vector store, pulls back documentation chunks tangentially related to gratitude, and composes a paragraph about being happy to assist. Burned tokens, added latency, awkward interaction.

The first meaningful decision in any pipeline should be: does this input actually need retrieval? Small talk bypasses everything and jumps to generation. A single decision gate. In my system, this saves compute on about a third of all incoming messages.

2. The ambiguity problem.

“How do I configure the integration?” The product has six integrations. The system converts the query to a vector, retrieves documentation for whichever integration landed closest in embedding space, and answers with total confidence about the wrong one. The user can’t tell the answer is wrong because the system never hesitated.

This isn’t a model problem. It’s an architecture problem. Before you generate anything, check whether the retrieved documents point to one topic or several. If they point to several, the right response is a clarifying question, not a confident guess.

I solve this with graph cluster detection. When matched entities land in disconnected clusters — no path between them within four hops — the query spans multiple unrelated topics. The system asks the user to narrow it down.

3. The context overflow problem.

You retrieve 20 solid chunks. That’s about 15,000 tokens of context. You feed all of it into the prompt. The model pays attention to the top, pays attention to the bottom, and glazes over everything in between.

“Lost-in-the-middle” is well-studied at this point. Fetching fewer chunks sacrifices recall. The real fix is summarizing the retrieved context before handing it to generation. Compress 15,000 tokens of raw chunks down to 3,000 tokens of distilled summary. Now the model actually reads the whole thing.

I cache summaries keyed by content hash. Same context bundle hits the cache instead of burning another LLM call. Simple optimization, real savings on repeated questions.

4. The flat retrieval problem.

This one matters most.

Vector similarity works on textual surface. It finds chunks that sound like your query. But knowledge isn’t flat. It has topology. Causes chain into effects. Prerequisites gate actions. Alternatives fork from shared roots.

“What happens when finding X is linked to corrective action Y?” That’s a question about a relationship. No single chunk holds the answer because finding X is documented in one place and corrective action Y in another. A relationship connects them, not word overlap.

Vectors don’t traverse relationships. Graphs do.

5. The intent problem.

“What is two-factor authentication?” and “2FA broke after the update” look similar to a vector. They need completely different retrieval strategies. The first is exploration. The second is troubleshooting. Serving the same chunks for both means mediocre answers for both.

Intent classification before retrieval reshapes the search. Concept queries pull explanatory material and connected topics. Problem queries pull symptoms, root causes, and documented fixes. One knowledge base. Two very different paths through it.

What a Graph Brings to the Table

A knowledge graph stores entities and how they relate to each other. Not paragraphs. Structure.

Think of it this way: vector search says “here are documents that talk about similar things.” A graph says “here are the things connected to what you asked about, and here’s how they connect.”

The graph doesn’t replace the vector store. It sits next to it. Vectors find entry points. The graph fans out from there, pulling in related knowledge that no amount of cosine similarity would surface.

The mechanics

Three phases.

Seed selection. Vector search returns top chunks by distance. A configurable subset becomes seeds for graph traversal. The remaining chunks still contribute to context, but only seeds enter the graph.

Graph expansion. From each seed, traverse the graph a configurable number of hops. A chunk mentions entity A. Entity A is linked to entity B through RESOLVED_BY. Entity B has evidence in chunk C. Chunk C never appeared in vector results — it’s written in completely different language. But it contains the fix. Now it’s part of the context.

Reranking. Blend vector scores with graph relationship scores. A chunk with a decent embedding match but strong graph connectivity to the query entities climbs above a chunk that’s merely close in vector space.

Designing a Graph Schema for Your Domain

No universal schema exists. What you model as nodes and what you model as edges determines everything the graph can reveal that vectors cannot. This is domain design, not framework configuration.

Two examples from domains I know.

Customer support knowledge base

The domain I’ve spent the most time building in.

Entities. A single node type with a kind field distinguishing: Problem, Solution, Concept, Feature, Configuration. Problem is something that breaks. Solution is how to fix it. Concept is explanatory knowledge. Feature and Configuration model the product itself.

Relationships. The schema lives or dies here.

CAUSES — root cause to visible symptom. “Invalid webhook URL” CAUSES “Bot doesn’t respond.” User reports the symptom, graph traces back to the cause.

RESOLVED_BY — problem to fix. “Bot doesn’t respond” RESOLVED_BY “Verify the webhook endpoint is publicly accessible.” Multiple solutions per problem. The model picks the most relevant given context.

DIAGNOSED_BY — problem to diagnostic question. “Bot doesn’t respond” DIAGNOSED_BY “Does the webhook URL return 200 on a GET request?” This edge powers clarifying questions before the system commits to a full answer.

RELATED_TO — bidirectional general association. “Webhook configuration” RELATED_TO “API key setup.” Supports conceptual browsing when the user is learning, not firefighting.

EVIDENCE_FOR and MENTIONS — the bridge layer. They connect chunks (vector world) to entities (graph world). A documentation chunk is EVIDENCE_FOR a Solution, or MENTIONS a Feature. Without these edges, your two retrieval systems are blind to each other.

Intent-aware traversal. Same graph, different paths depending on what the user needs. Problem intent traces CAUSES backward and RESOLVED_BY forward. HowTo intent follows RESOLVED_BY and looks for step-by-step content. Concept intent walks RELATED_TO broadly, mapping the neighborhood of connected knowledge.

Same nodes. Same edges. Different traversal logic.

E-commerce product catalog

Different world. Different schema. Identical principle.

Entities. Product, Category, Feature, Specification, Review, Brand.

Relationships.

BELONGS_TO — Product to Category. “Running Shoe X” BELONGS_TO “Men’s Athletic Footwear.”

HAS_FEATURE — Product to Feature. “Running Shoe X” HAS_FEATURE “Carbon fiber plate.” Vector search catches the literal phrase. Graph traversal also finds every product sharing that feature node, including those describing it as “carbon-infused midsole” or “energy return plate.” Different vocabulary, same node.

COMPATIBLE_WITH — Product to Product. “Running Shoe X” COMPATIBLE_WITH “Performance Insole Y.” This fact doesn’t live in any product description. It exists only as a relationship.

COMPARED_TO — competitive links. “Which is better, X or Z?” — the graph pulls comparison context from both sides.

The shared pattern: entities are things users ask about. Relationships are connections between those things that no individual text chunk captures. The graph holds the knowledge that lives between documents.

When You Don’t Need a Graph

A graph adds complexity to indexing, storage, and querying. It pays off when your data has entities with real relationships between them, when users ask relational questions, and when ambiguity shows up often.

If your use case is searching 500 FAQ articles and surfacing the closest match, vectors handle that fine. Don’t bolt on a graph because it looks sophisticated on an architecture diagram. Add one when users ask questions that require following connections between things.

The Pipeline Is the Product

RAG is not three steps. My pipeline has sixteen stages. Each exists because a specific production failure demanded it. Classification to skip needless retrieval. Intent detection to shape the search. Vector search for semantic matching. Graph expansion for relational knowledge. Reranking to merge signals. Summarization to fit attention windows. Ambiguity detection to stop confident wrong answers. Model selection to balance cost and quality.

Nothing was designed upfront. Every stage got added because something broke and needed to stop breaking.

The acronym promises simplicity. The engineering delivers something else entirely.

Share

Thanks for reading.

Subscribe now

There is a particular kind of beauty that survives time.

Not because someone preserved it intentionally — but because it was so precisely right that people kept coming back. The proportions of the Parthenon. The color palette of a Vermeer interior. The typeface of a 1960s Swiss train schedule. These things carry a quiet authority. They don’t explain themselves. They just work.

Sanzo Wada’s color combinations are like that.

Who was Sanzo Wada?

Sanzo Wada (1883–1967) was a Japanese artist, teacher, and costume designer. He spent decades studying color — not as an abstract concept, but as a practical tool. He worked in kimono design, textile production, and theater. He was interested in how colors affect perception, mood, and meaning in everyday objects and environments.

In the 1930s, he published A Dictionary of Color Combinations — a collection of 348 curated palettes built from 159 carefully selected colors. Each combination was assembled by hand, each swatch painted precisely. The book wasn’t a theory paper or an academic study. It was a reference guide: a craftsman’s tool for people who work with color and need reliable, harmonious combinations.

The original edition was published in Japanese, but the book eventually found a second life internationally. Seigensha Art Publishing reprinted it, and over the last few years, it quietly became a cult reference among designers, illustrators, and anyone who takes color seriously.

The Dictionary: Why It Matters

What makes Wada’s dictionary different from a random collection of palettes on Dribbble or Coolors?

Intent.

Every combination in the dictionary was composed with purpose. Wada wasn’t generating combinations algorithmically. He wasn’t running HSL calculations or color-wheel rules. He was painting swatches and looking at them — testing how they feel next to each other, how they behave in different contexts, how they create balance or tension.

The result is a collection that feels timeless. The palettes are not trendy. They don’t look like “2024 web design.” They don’t look like any particular era. They look — correct. In the same way that certain musical intervals sound right regardless of genre, Wada’s combinations carry a visual harmony that transcends fashion.

Each color in the dictionary includes not only its visual swatch but detailed technical data: hex, RGB, CMYK, and L*a*b* values. Each combination is either 2, 3, or 4 colors. Some are bold and contrasting. Some are quiet and tonal. Some feel like autumn. Some feel like the interior of a 1950s jazz club. All of them feel considered.

Color as a Material

In my article Art in Everything: From Bruegel to Web Applications, I wrote about creativity being everywhere — in facade renovations, in running shoe design, in writing code. Color is one of the most fundamental materials of that creativity. It is the first thing people perceive. Before they read your headline, before they understand your layout — they feel your colors.

And yet, color is one of the most neglected aspects of web development.

We spend hours optimizing database queries, structuring middleware, writing tests. Then we pick a color palette in five minutes — usually by copying some trending combination from a design tool or just going with Tailwind’s default slate and blue. It works. But it doesn’t sing.

Wada’s dictionary offers something different: a curated, time-tested library of combinations that were assembled by someone who spent a lifetime studying how colors interact. It’s like having a sommelier’s recommendations instead of grabbing a random bottle from the shelf. The random bottle might be fine. The recommendation will be better.

And the thing is — these palettes are not limited to art or print design. They apply to anything where color matters:

• Web interfaces — landing pages, dashboards, SaaS products

• Brand identity — logos, marketing materials, social media presence

• Data visualization — charts, graphs, maps

• Presentations — slides that don’t look like default PowerPoint

• Design systems — building a consistent Tailwind or CSS custom theme

Any surface that carries color can benefit from Wada’s eye.

From a Book to the Browser

A few years ago, Matt DesLauriers (@mattdesl) digitized the color data from Wada’s dictionary and published it as a JSON dataset on GitHub under an MIT license. That dataset is a beautiful piece of work in itself — 159 colors with full hex/RGB/CMYK/L*a*b* values, and 348 combinations referencing those colors by ID.

When I found this dataset, the idea clicked almost immediately.

I wanted to build something around it. Not a static gallery. Not just another color-swatch website. I wanted to make Wada’s palettes actually usable — browsable, searchable, and most importantly, accessible programmatically. If I’m building a website and I want a good three-color palette, I should be able to ask for one and get it back as Tailwind config or CSS variables. If an AI assistant is helping me with a UI, it should be able to pull from Wada’s dictionary instead of making up random colors.

That’s how espectro.dev was born.

Espectro is a free, non-commercial web project built with Laravel, Livewire, and Tailwind CSS. It serves the full Wada dictionary as:

• A browsable site — explore all 159 colors and 348 combinations with swatches, detail pages, and search

• A public JSON API — no authentication required, rate-limited to 15 requests per minute, returning full color data in structured JSON

• An MCP server — so AI tools like Cursor and Claude can search colors, fetch palettes, and export combinations directly

The site itself is intentionally minimal. Muted tones. Serif headings. Lots of white space. I wanted it to feel like the book — quiet, respectful, focused on the colors themselves.

The Practical Part: Color Palettes for Your Tailwind Config

Here’s where it gets useful for everyday development.

Say you’re building a dashboard. You need a primary color, a secondary, and an accent. Instead of guessing or scrolling through color pickers, you can hit the API:

curl https://espectro.dev/api/combinations/42

You get back a structured JSON response with 2, 3, or 4 colors — each with hex, RGB, CMYK, and L*a*b*. Or if you want something random for inspiration:

curl https://espectro.dev/api/combinations/random

But the real power comes from the export endpoint (available via MCP). Ask for combination #42 as a Tailwind config and you get:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        'theme': {
          'primary': '#ebd999',
          'secondary': '#8b6c42',
          'accent': '#4a3728',
        }
      }
    }
  }
}

Or as CSS variables:

:root {
  --color-primary: #ebd999;
  --color-secondary: #8b6c42;
  --color-accent: #4a3728;
}

Copy, paste, done. Your site now uses a palette that a Japanese color master composed 90 years ago. And it looks better than whatever you would have picked at 11 PM on a Friday.

This works for anything: landing pages, email templates, logo concepts, data dashboards, presentation themes. Wherever you need a cohesive set of colors that actually harmonize.

Making It an MCP Server

Here’s the part that excited me the most.

MCP — Model Context Protocol — is a standard that allows AI assistants to use external tools. If you’ve worked with Cursor or Claude, you’ve probably seen how they can call functions, search documentation, or interact with databases. MCP makes it possible to expose any service as a set of tools that an AI can invoke.

I built Espectro’s MCP server directly into the Laravel application. It exposes six tools:

ToolWhat it doessearch-colorsSearch colors by name or hex valueget-colorGet full details for a color by slugsearch-combinationsFilter combinations by palette size (2, 3, or 4)get-combinationGet a combination by ID with all color datarandom-combinationGet a random paletteexport-combinationExport as Tailwind config or CSS variables

The MCP endpoint is public at https://espectro.dev/mcp/espectro — the same rate limit applies (15 req/min per IP). Anyone can connect to it from any MCP-compatible client without installing anything.

For Laravel developers specifically, I also published a small connector package — labrodev/laravel-mcp-espectro. You run composer require and php artisan espectro:install, and it creates a .mcp.json in your project root. Cursor picks it up automatically. That’s it — no local MCP server, no configuration, no color data to bundle. The package simply points your tools to the hosted endpoint.

How I Actually Use It

I added Espectro as a connector in Claude Desktop. It took about 30 seconds: open settings, add a custom MCP server, paste the URL https://espectro.dev/mcp/espectro, save.

Now, when I’m working on a project and I need a color scheme, I don’t leave the conversation. I just say something like:

“I need a warm three-color palette for a bakery website. Check Sanzo Wada combinations and suggest something.”

Claude calls search-combinations with size 3, browses the results, and suggests specific combinations from Wada’s dictionary — with hex codes, visual descriptions, and even an exported Tailwind config if I ask for it. If I don’t like the first suggestion, I can say “something cooler, more muted” and it searches again, this time filtering by different criteria.

It’s not generating colors out of thin air. It’s pulling from a curated, historically validated source. And that’s the difference — instead of AI hallucinating a palette, it’s selecting from one of the most thoughtful color collections ever assembled.

I also use it in Cursor when I’m coding. If I’m styling a component and I need an accent color that works with my existing palette, I can ask Cursor to check Wada’s dictionary. It calls search-colors, finds matching options, and I pick one without leaving my editor.

This is what I meant in my article about AI and experience — AI amplifies your architecture. If you feed it good sources, you get good results. Wada’s dictionary is an exceptionally good source.

A Note on Public Domain and Credits

Sanzo Wada passed away in 1967. Under Japanese copyright law, his works entered the public domain 50 years after his death — in 2017. The color data used in Espectro comes from Matt DesLauriers’ open-source digitization (MIT license) of the original published work.

Espectro is a free, non-commercial project. It does not assert any rights over the color data. No cookies, no tracking, no personal data collection on the API or MCP. It exists to make Wada’s work accessible and useful in the modern web development context.

If you enjoy working with these colors, I’d encourage you to buy the physical book — it’s available on Amazon and it’s a beautiful object to have on your desk. There’s something irreplaceable about seeing those swatches printed on paper, exactly as Wada intended.

Final Thought

There is a particular kind of beauty that survives time.

Sanzo Wada spent decades learning what that beauty looks like in color. He encoded it into 348 combinations. Now, almost a century later, those combinations can flow from a book through a JSON file through an MCP server into your Tailwind config — and from there, onto someone’s screen.

The river is the same. The waters are ever newer.

Espectro is open and free at espectro.dev. Color data credits: mattdesl/dictionary-of-colour-combinations (MIT). Developed by Petro Lashyn.

Recently, I faced a task that made me pause and reflect on one of my larger projects.

But very quickly, it became clear that I wasn’t just reflecting on the project itself — I was reflecting on my approach to building software in general.

Over the years, I’ve worked in many roles: PHP developer, Laravel developer, software architect, DevOps, frontend developer, full-stack developer. Sometimes all of them at once. Sometimes by choice, sometimes because the project demanded it.

When I didn’t know something, I figured it out. At first with Stack Overflow, experiments, patterns, and trial and error. Later with frameworks, best practices, and philosophies. SOLID, DRY, KISS. Object-oriented programming, abstractions, factories, contracts, interfaces. Mixing Laravel with ideas from Symfony. Falling back to simple MVC when it made sense.

I’ve worked on single-page applications across different generations: early Angular, then Vue, then Vue 3 with a completely different paradigm. React, TypeScript, Tailwind, Inertia. Domain-driven design. Layered architectures. Large projects with many models and tables, APIs, dashboards for different actors, background jobs, console scripts, and integrations — all sharing the same core.

I didn’t build unicorns.

I didn’t work in Big Tech.

But for more than 15 years, I’ve worked on real projects — SaaS, CRM, ERP, small pet projects, experimental ones — and many of them are still running today.

Why I started reflecting more consciously now

The real trigger for this reflection was AI.

I’ve recently started using AI as a serious resource in my development process — not as a toy, but as a tool to speed up work, explore solutions, refactor code, and challenge my own decisions.

AI has an interesting side effect: it forces you to be explicit.

If your architecture is blurry, AI amplifies the blur.

If responsibilities are mixed, AI happily generates more mixed logic.

If boundaries are unclear, everything starts leaking everywhere.

That’s when I realized: this is a good moment to consciously draw boundaries, simplify decisions, and reflect on what actually matters in my daily work as a developer.

After compressing all that experience, I ended up with just three simple statements.

1. Keep it simple, Smart

This sounds obvious, but it’s still the most important thing.

KISS really works.

Not “simple” in a dumb way — but simple in a smart, intentional way. So literally, Keep It Simple, Stupid Smart.

When you come back to a piece of code after a year — to add a feature, debug a strange 500 error, or adapt to new business logic — simplicity becomes priceless. If the code is straightforward, you immediately understand what’s going on. You don’t need to re-learn layers of abstractions or trace hidden flows.

Simple code is easier to maintain.

Simple code is easier to debug.

Simple code is easier for others to work with.

And future you is also “someone else”.

2. Separate concerns and make the structure explicit

Simplicity does not mean chaos.

It’s extremely important to separate concerns and build a clear structure — whether it’s a Laravel project, a package, or a Vue SPA.

How you do this is up to you: frameworks, patterns, naming, folder structure. That part is personal. But once you choose a structure, it must be logical and predictable.

You should clearly understand:

• where responsibilities live,

• how data flows through the system,

• how actors move through the application.

The system should be decomposed into layers that can live independently: application layer, domain or service layer, view or view-model layer. These layers should communicate through well-defined boundaries and be replaceable.

You should always have a clear picture in your head of how the flow moves through these layers and what exactly happens in each of them.

3. Have a single source of truth

This principle connects everything above.

A single source of truth works beautifully — and it’s closely related to both separation of concerns and simplicity.

For example, when you perform mutating operations on a model — creating records, updating fields, deleting data, changing state — there should be one clearly defined place where this logic lives.

Not spread across controllers, services, jobs, and helpers.

Not duplicated in slightly different forms.

The same applies to reading data, orchestration, business rules, and configuration. Each concern should have its own source of truth.

When you work this way:

• behavior becomes predictable,

• systems become easier to reason about,

• changes become safer.

You always know where to look.

You always know what to change.

Final note

None of these thoughts are new or revolutionary.

But they are the things that, based on my experience, really matter for my work today. They help me stay productive, calm, and confident when working on real projects — especially now, when AI is part of the development process.

This is simply what works for me.

Glad to hear your reflections! And thanks for an attention!

Image credit: https://unsplash.com/@jontyson

In engineering, we solve problems all the time. Some problems are straightforward. Something is broken, we fix it. Something is slow, we optimize it. But many problems are not like that.

We often face situations where:

• improving one thing makes another thing worse

• every option looks reasonable, but none feels right

• any decision comes with a clear downside

Examples are familiar:

• make the system more flexible, and it becomes harder to understand

• add safety checks, and performance drops

• simplify logic, and future changes become harder

These are not bugs.

These are engineering dilemmas.

At this point, the solution depends not only on what we do, but on how we think about the problem. Different approaches lead to very different results.

One of those approaches is TRIZ.

What is TRIZ (and what it is not)

TRIZ stands for Theory of Inventive Problem Solving.

It was developed by studying a large number of engineering inventions and patents and looking for patterns in how difficult problems were solved.

Despite the name, TRIZ is not abstract theory.

It is a practical, engineering-focused way to analyze problems.

A common misunderstanding:

TRIZ is often associated with the Russian language because the original materials were written in Russian. But TRIZ itself is not “about Russian engineering” or culture. It is a universal approach, based on patterns found across many industries and countries.

TRIZ is not:

• brainstorming

• intuition-based creativity

• a list of clever tricks

TRIZ is about structured thinking.

In simple terms, TRIZ says:

Many hard problems are hard because of contradictions inside the system.

If we understand those contradictions, we can find better solutions.

The basic TRIZ cycle: problem → dilemma → contradiction → solution

TRIZ often works as a cycle.

Problem

Something needs to be improved.

Dilemma

Improving one thing makes another thing worse.

Contradiction

We clearly describe what exactly conflicts with what.

Solution

We change the system so the conflict no longer exists in the same way.

The key step here is moving from dilemma to contradiction.

A dilemma is vague: “this or that”.

A contradiction is precise: “when I improve X, Y becomes worse”.

Once the contradiction is clear, the solution space becomes wider.

Real-world examples using the TRIZ cycle

Example 1: Fast but safe transportation

Problem: move people faster

Dilemma: higher speed increases danger

Contradiction: speed improves efficiency but reduces safety

A compromise would be “not too fast”.

A TRIZ-style solution changes the system:

• separate traffic flows

• add safety systems that activate only in dangerous situations

• automate parts of control

High-speed trains are not a compromise.

They are a resolution of the contradiction.

Example 2: Simple devices with many functions

Problem: one device should do many things

Dilemma: more functions mean more complexity

Contradiction: functionality increases value but reduces simplicity

Instead of adding more buttons:

• functions are hidden behind modes

• software replaces hardware controls

• interfaces change depending on context

The device stays simple at the moment of use.

Example 3: Software development

Problem: ship features quickly

Dilemma: fast changes reduce stability

Contradiction: speed improves delivery but increases risk

TRIZ-style solutions include:

• automated testing

• feature flags

• staging environments

Speed and stability are no longer in direct conflict.

The system is changed so they coexist.

TRIZ in real companies and practice

TRIZ is not a niche idea.

Elements of TRIZ thinking have been used by:

• Samsung (systematic innovation programs)

• Intel (engineering problem analysis)

• Toyota (process improvement and contradictions in manufacturing)

Many modern engineering practices reflect TRIZ ideas, even if they are not labeled as such.

People often use TRIZ principles without knowing the name.

Conclusion: applying TRIZ beyond engineering

At its core, TRIZ is about how we frame problems.

Instead of asking:

• “Which option is better?”

We ask:

• “Why do these things conflict?”

• “Can the system be changed so they don’t?”

This way of thinking works not only in engineering.

It applies to:

• work processes

• business decisions

• team organization

Anywhere trade-offs appear, contradictions exist.

TRIZ does not promise perfect answers.

It offers something more valuable:

a disciplined way to think before accepting limits.

And often, that is enough to find a better path.

Thanks for your attention!

Subscribe now

Image credit: https://unsplash.com/@thisisengineering

In this article I would like to share playbook how to install, configure and set up a process for auto-renewal (it’s actual because normal Let’s Encrypt certificate lifetime is 90 days).

But we jump deep in practical manual parts, let’s just do a quick refresher what is SSL and what is Let’s Encrypt.

What is SSL an why it’s important?

When people say SSL, they usually mean TLS (Transport Layer Security). It’s the technology that makes the connection between your browser and a server encrypted and verified. In practice, that means:

• The server proves it’s really the site you wanted to reach (using a certificate and private key).

• The browser checks that certificate against a trusted authority (Certificate Authority).

• Once trust is established, all traffic is scrambled with encryption so nobody in between can read or change it.

So passwords, forms, payments, API calls — everything stays safe from eavesdropping or tampering. In 2025, you can’t run a serious site without it: browsers warn users, Google ranks HTTPS sites higher, and security compliance flat-out requires it.

What is Let’s Encrypt and why it’s free

Let’s Encrypt is a Certificate Authority (CA) — the trusted third party that hands out SSL/TLS certificates. Normally, companies like RapidSSL or DigiCert sell you a certificate for money every year. Let’s Encrypt flipped the model: it’s a non-profit, backed by Mozilla, EFF, and others, that gives certificates away for free.

Why? Because encrypted web traffic should be the default, not a luxury. Their funding comes from sponsors and donations, not from charging website owners.

And the really cool part here is automation: instead of filling out forms, emailing back and forth, and paying invoices, you run a simple tool (certbot), and within seconds your server gets a valid certificate. It also renews automatically, so you don’t wake up one morning with a broken “expired cert” warning.

Personally, dealing with SSL certificates was always a headache. You had to contact the client, explain what you needed, ask for credentials to log in to the issuer’s site and fill out forms. Or sometimes you’d just wait for the client to send you the freshly issued certificate — often in some unexpected format, and almost always with a file or two missing. Sounds familiar, doesn’t it?

So Let’s Encrypt not only save costs for you and for your clients, but also make the process of handling the certificates drastically simpler. And in the guide below, you’ll see how effortless it really is.

Let’s Encrypt installation and configuration guide

Below is the step-by-step instruction how to install and configure Let’s Encrypt certificates on your Ubuntu + Nginx server (probably the most common combination of server setup).

In this example let’s charge a certificate for domain labrodev.com.

Install Certbot and the Nginx plugin

sudo apt update
sudo apt install -y certbot python3-certbot-nginx

Make sure Nginx has a matching server block

Certbot’s Nginx plugin needs to find your vhost by server_name. Minimal HTTP block:

# /etc/nginx/sites-available/labrodev.com
server {
    listen 80;
    listen [::]:80;
    server_name labrodev.com www.labrodev.com;

    root /var/www/labrodev;  # your path
    index index.html index.htm index.php;
}

Before issuing a new certificate for your domain, make sure you have an Nginx config in sites-available (and symlinked in sites-enabled) with a server_name that exactly matches the domain you’re requesting the certificate for.

If it’s not enabled yet (no symlink in sites-enabled), enable it before moving for next step:

sudo ln -s /etc/nginx/sites-available/labrodev.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Issue certificate

sudo certbot --nginx -d labrodev.com -d www.labrodev.com

What happens here:

• Certbot serves an HTTP‑01 challenge via Nginx.

• On success, it writes certs under /etc/letsencrypt/live/labrodev.com/.

• It modifies your Nginx server block to add ssl_certificate and ssl_certificate_key, and (if you accept) an HTTP→HTTPS redirect.

So after the certificate is issued, your vhost for this domain with such server name will have automatically added record for ssl_certificate and ssl_certificate_key:

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name labrodev.com www.labrodev.com;

    ssl_certificate /etc/letsencrypt/live/labrodev.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/labrodev.com/privkey.pem;

    root /var/www/labrodev;
    index index.html index.htm index.php;
}

Configure auto-renewal process

Let’s verify the systemd timer exists.

Certbot (APT) installs a timer that runs renew checks twice daily:

systemctl list-timers | grep certbot
systemctl status certbot.timer

Dry‑run renewal

This command will simulate renewal (with —dry-run option) of certificates:

sudo certbot renew --dry-run

You should see something like “Congratulations, all simulated renewals succeeded!” message.

Reload Nginx automatically after real renewals

Create a post‑renew hook that syntax‑checks and reloads Nginx only when certs actually renew:

sudo tee /etc/letsencrypt/renewal-hooks/post/reload-nginx.sh >/dev/null <<'EOF'
#!/bin/bash
# Only runs after a successful *real* renewal event.
# Validate config before reloading to avoid downtime.
if /usr/sbin/nginx -t; then
  systemctl reload nginx
fi
EOF
sudo chmod +x /etc/letsencrypt/renewal-hooks/post/reload-nginx.sh

Simulate the end-to-end flow

I like to confirm the entire chain (renew → nginx test → reload) in one go:

sudo certbot renew --dry-run && sudo nginx -t && sudo systemctl reload nginx

Dry‑run won’t actually change certs, but you’ll see the path is healthy and your reload command works.

Double check the setup

There are some proof commands that feel you secure about whole setup and which you actually can use from time to time to check the state of certificates. Below there are some of these useful commands.

When does auto‑renew run next / when did it last run?

systemctl list-timers | grep certbot
systemctl status certbot.timer
journalctl -u certbot --since "3 days ago"

What version am I running / which binary?

certbot --version
which certbot

List all installed certificates and their expiry

sudo certbot certificates

Check the expiry of a specific PEM

sudo openssl x509 -enddate -noout -in /etc/letsencrypt/live/labrodev.com/fullchain.pem
# notAfter=Nov 17 11:05:44 2025 GMT

What about wildcard certificates?

A wildcard certificate is one that covers all subdomains under a given domain. For example, a cert for *.labrodev.com would automatically secure dev.labrodev.com, test.labrodev.com, api.labrodev.com, and so on — without you needing to issue separate certs for each one. This is handy if your product spins up subdomains dynamically (e.g. customer1.yourapp.com, customer2.yourapp.com), since managing dozens or hundreds of individual certificates would be a nightmare.

Let’s Encrypt can issue wildcard certificates, but there’s a catch: you need to prove ownership via DNS-01 validation (adding TXT records in your DNS). That adds complexity, because it means touching DNS settings rather than just letting Certbot hook into Nginx.

Personally, my approach is simpler: I just treat each subdomain I use as a separate domain with its own Nginx vhost and Let’s Encrypt certificate. So labrodev.com, dev.labrodev.com, and test.labrodev.com each have their own config and their own cert. It works perfectly fine if you only have a handful of subdomains.

Of course, if your platform generates subdomains on the fly dynamically, that’s when a wildcard makes sense — but that’s a bigger topic for another day and not for this article.

Conclusion

So nearly in ~10 minutes you can:

• Install Let’s Encrypt on Ubuntu,

• Issue trusted certs via the Nginx plugin,

• Enable hands‑off auto‑renewal,

• And wire a post‑renew hook so Nginx picks up fresh certs automatically.

Short‑lived certs + automated renewals are exactly how SSL should work in 2025: secure by default, zero manual babysitting, and no licensing friction. It’s simple, robust, and free.

I hope you enjoy this article!

Have a luck with this and keep your domains secure!

If you like it or find useful, you may share it with your audience.

Share

If you like Labro:Dev blog and topics we cover here, we will glad to see your in our subscribers list. Let’s connect!

Subscribe now

Preview image credit: https://unsplash.com/@franckinjapan

Why we need composer packages?

Composer is the de facto package manager for PHP, making it easy to share and reuse code across projects. By creating a reusable Composer package, you can modularize your code and avoid “reinventing the wheel” in future projects. It’s also satisfying and fun to open-source your work – not only do you benefit from reusability, but other developers can discover and use your package, potentially improving it with feedback or contributions. In the vast PHP ecosystem, thousands of packages on Packagist (the main Composer repository) exemplify how sharing solutions benefits the community. In short, building a package encourages better code organization, and publishing it publicly gives others the opportunity to learn from or build upon your work.

What inside this article?

In this article, we’ll walk through how to build a simple PHP package and publish it on Packagist, using a real example: a “Postal Formatter” library that we’ve built to use in different projects. This package provides a handy utility to format European postal codes according to each country’s official standards. We’ll cover the journey of creating the package, setting it up for Composer, pushing it to GitHub, releasing it via Packagist, and even highlight a neat PHP 8.1 feature (Enums) used in the package. By the end, you should have a clear roadmap for creating and sharing your own PHP library.

Bring it to the world!

So let’s start with the publishing process.

After writing your PHP library, how do you make it installable via Composer for anyone in the world? The answer is Packagist.org – the central repository for Composer packages.

The process is quite straightforward described below and can’t be represented as to-do guide with some steps:

1. Prepare a GitHub Repository: Create a new public repository on GitHub for your package code. At minimum, your repo should contain a composer.json file at its root with the package’s metadata (name, description, author, PHP version requirement, etc.). This file is essential – Packagist will read it to get your package info . For example, your composer.json should declare a unique package name in the format "vendor/package" (e.g., "labrodev/postal-formatter") and the minimum PHP version, among other details. You should also include a README with usage instructions and a License file (more on these later).

2. Implement Your Package Code: Develop your library code under the repository. Follow PSR-4 autoloading by organizing classes into directories matching your namespace (configured in composer.json). For instance, if your package’s namespace is Labrodev\PostalFormatter, the source files might live under a src/ directory. Ensure your code is committed and pushed to the GitHub repo.

3. Add a Version Tag: Before submitting to Packagist, tag a release version in your Git repository. This step assigns a version number to your code. Using semantic versioning is recommended (e.g., v1.0.0 for your first release). You can create a tag via command line:

   git tag -a v1.0.0 -m "Initial release"
   git push origin v1.0.0

   Packagist automatically detects versions from Git tags. In fact, new versions of your package are fetched from the tags you create in your VCS repository, so it’s best to omit a fixed version in composer.json and just rely on Git tags like 1.0.0 or v1.0.0 . This way, each Git tag (v1.0.1, v1.1.0, etc.) will appear as a version that users can require via Composer.

4. Submit to Packagist: Create an account on Packagist.org (you can sign in with GitHub for convenience). Once logged in, click the “Submit” button on Packagist’s top menu. In the submission form, provide the public Git repository URL of your package (for example, the GitHub URL). Packagist will import your repository – reading the composer.json to gather package details automatically . After submitting, your package will have its own Packagist page, and developers can install it via Composer.

5. Enable Auto-Updates (Optional but Recommended): By default, Packagist will periodically check your repo for new tags. To get immediate updates on new releases, you can hook up Packagist to your GitHub. If you logged in via GitHub and authorized Packagist, it can set up a service hook so that every time you push a new tag, Packagist notices right away . This ensures your users can fetch the latest version as soon as you release it.

Once these steps are done, your library is live on Packagist! For example, if your package is named vendor/package, anyone can run composer require vendor/package to pull it into their project . In our case, we used labrodev/postal-formatter as the package name, so developers can install it with a simple command:

composer require labrodev/postal-formatter

Next, let’s dive into the Postal-Formatter package itself as a case study of how a simple Composer package is structured and what it contains.

Case Study: Inside the Postal-Formatter Package

Postal-Formatter is a small PHP library that formats European postal codes in a consistent way. Imagine you have postal/zip codes from various countries – this tool will clean them up and output them in the official format for that country. For example, if given a UK code "sw1a1aa", the library will output "SW1A 1AA" with the proper capitalization and spacing; if given a Czech Republic code "12345", it will output "123 45" with the standard space in the middle . It supports over 45 country formats (essentially most of Europe) and normalizes input by removing any extraneous characters and uppercasing letters . In short, it’s a handy utility if you’re dealing with international postal addresses and want to ensure the codes are uniformly formatted.

Features and Usage

To summarize what our tiny package offers, here are its key features (as described in the README):

• Cleans and standardizes postal code input (trims whitespace, removes non-alphanumeric characters, and uppercases letters) .

• Supports 45+ European country codes, each with country-specific formatting rules (ISO 3166-1 alpha-2 country codes are used for identifying countries) .

• Auto-formats codes per country standard – e.g., "12345" becomes "123 45" for Czech Republic (CZ), "LV1234" becomes "LV-1234" for Latvia, or "sw1a1aa" becomes "SW1A 1AA" for Great Britain (GB) .

• Provides a simple static interface for formatting (a single PostalFormatter::format() method handles everything).

• Written for strict typing in PHP 8.1+ (uses declare(strict_types=1) and typed class properties/methods), ensuring type safety.

• Includes a test suite (PHPUnit) and static analysis (PHPStan) configuration, which means the code is verified for correctness and adherence to best practices.

Using the package is straightforward. We just call the static format method. For example:

use Labrodev\PostalFormatter\Utilities\PostalFormatter;

echo PostalFormatter::format(' 12345 ');          
// Outputs: 12345  (default normalization)

echo PostalFormatter::format('12345', 'CZ'); 
// Outputs: 123 45 (Czech format)

echo PostalFormatter::format('sw1a1aa', 'GB'); 
// Outputs: SW1A 1AA (UK format)

echo PostalFormatter::format('1050', 'LV');  
// Outputs: LV-1050 (Latvia format)

Under the hood, the formatter will throw an exception if you provide an unsupported country code (to avoid silently failing or mis-formatting). For instance, PostalFormatter::format('12345', 'XX') would throw an InvalidCountryCode exception, because “XX” is not a valid ISO country code in its list.

Project Structure and Notable Files

One goal of this case study is to illustrate how a simple Composer package is organized. The Postal-Formatter repository follows common best practices for PHP libraries:

• composer.json: This file defines the package metadata. It includes the package name (labrodev/postal-formatter), a description, keywords, the minimum PHP version (8.1), autoload information (PSR-4 mapping of the namespace to the src/ directory), and any dependencies. It also lists development requirements like PHPUnit and PHPStan, and even defines convenient Composer scripts (e.g., "test" to run the test suite, "analyse" to run PHPStan) to streamline development. This file is crucial, as Packagist reads it to register your package and Composer uses it to resolve dependencies.

• README.md: A comprehensive README is provided, which serves as the documentation for the package. It typically explains the package’s purpose, features, installation instructions, usage examples, and any other important notes. In Postal-Formatter’s README, for example, you’ll find the list of features and code examples we discussed above, plus sections on running tests and static analysis. A good README is important for any open-source package – it’s the first thing developers will read on GitHub or Packagist to understand how to use your library.

• CHANGELOG.md (or CHANGES.md): It’s a good practice to include a changelog file listing the changes in each version of your package. This helps users see what’s new or fixed when you tag a new release. In our package, a CHANGES.md file outlines updates across versions (e.g., new country formats added, bug fixes, etc.). Maintaining this is especially useful as your package evolves.

• LICENSE: An open-source license file (in this case, MIT License) is included, allowing others to know the terms under which they can use and distribute the package. MIT is a permissive license, encouraging wide usage. Make sure to choose a license for your package – lack of a clear license can deter potential users or contributors.

• src/ Directory: This contains the PHP source code for the library, organized by namespace. For Postal-Formatter:

  • Utilities/PostalFormatter.php – the main utility class with the format() method. It handles cleaning the input and delegating to country-specific formatting if a country code is provided.

  • Enums/CountryCode.php – an Enum defining supported country codes (like CZ, GB, FR, etc.) with each enum case encapsulating the logic to format a postal code for that country. We’ll discuss this Enum in detail in the next section.

  • Exceptions/InvalidCountryCode.php – a custom exception class thrown when an unknown country code is used. This is a simple class extending PHP’s Exception, providing a static make($code) method to create a standardized error message.

• tests/ Directory: Contains unit tests (using PHPUnit) to verify the package’s behavior. For instance, Postal-Formatter has tests ensuring that PostalFormatter::format() returns expected outputs for a variety of inputs and country codes. There’s also a test to ensure an invalid country code triggers the appropriate exception. Automated tests give confidence that the package works as intended and that future changes won’t break existing functionality.

By structuring the project in this way, we ensure that it’s easy to navigate and maintain. When others browse your repository or install the package, they can quickly find the documentation (README), see how to run tests, and understand how the code is organized. These are hallmarks of a well-crafted Composer package.

Quality Assurance: Static Analysis and Testing

As mentioned, our example package emphasizes code quality by including static analysis and testing tools:

• PHPUnit Tests: Having a suite of tests is crucial for any package. In Postal-Formatter, the tests cover various country formats (e.g., formatting a Polish postal code should insert a dash after the first two digits, formatting a UK code should insert a space in the right spot, etc.) and edge cases (like handling already formatted input or throwing exceptions on bad input). To run the tests, one can simply execute composer test (thanks to the script in composer.json), which runs PHPUnit. All tests passing means our formatter works for all supported countries as expected.

• PHPStan Static Analysis: The package also includes a PHPStan configuration (phpstan.neon.dist) and a Composer script composer analyse to run static analysis. PHPStan goes through the code to catch potential bugs or type errors without even running the code. By running static analysis, we ensure that our code has no obvious mistakes, that we’re not calling undefined methods, passing wrong types, etc. Using PHPStan at level max (or a high level) enforces strict, bug-free code. The inclusion of "declare(strict_types=1)" at the top of PHP files further ensures that type declarations are honored, preventing unintended type juggling. Embracing these tools (tests and static analysis) means the package is more robust and trustworthy for users. It’s great to highlight this in your package’s README (Postal-Formatter’s README explicitly notes it includes PHPUnit and PHPStan support ).

Overall, by investing in testing and static analysis, even a small utility library maintains high quality. When you build your own package, consider doing the same – it pays off in fewer bugs and easier maintenance.

Using PHP 8.1 Enums in Postal-Formatter

One particularly interesting aspect of the Postal-Formatter package is its usage of PHP 8.1 Enums. Enums (enumerations) are a feature introduced in PHP 8.1 that allow you to define a set of constant values in a type-safe way . Unlike traditional constants or configuration arrays, Enums give you a class-like structure where each possible value is a discrete case of the enum type, and you can even attach methods to it.

In Postal-Formatter, the CountryCode enum plays a central role. It defines cases for each supported country (like case CZ = 'CZ';, case GB = 'GB';, etc., with the two-letter codes as values). This enum also includes a method formatPostalCode(string $raw): string which contains the logic to format a cleaned postal code for that specific country. Internally, it uses a match expression to apply the correct pattern. For example:

• For countries like Czech Republic (CZ) or Slovakia (SK) that use a 3+2 digit format, the enum’s formatPostalCode returns substr($code,0,3) . ' ' . substr($code,3) (adding a space after the third digit) if the input is 5 digits long.

• For the UK (GB), it uses a regular expression to split the code into the outward and inward parts (e.g., "SW1A1AA" -> "SW1A 1AA").

• For Latvia (LV), it prepends "LV-" if the code is 4 digits.

• And so on for other countries (some use a dash, some have prefixes like AD or MC).

The PostalFormatter::format() function utilizes this enum by attempting to convert the country code string to a CountryCode enum case:

$country = CountryCode::tryFrom($countryCode) 
    ?? throw InvalidCountryCode::make($countryCode);
return $country->formatPostalCode($cleaned);

If tryFrom fails (meaning the provided code isn’t one of the enum cases), it throws our earlier mentioned InvalidCountryCode exception. Otherwise, it calls the enum’s formatting method for that country.

Why Use an Enum for Country Codes?

Enums in PHP 8.1 are a perfect fit when you have a limited, predefined set of values — like country codes. In the case of postal formatting, each country has its own unique rules, so it makes sense to encapsulate those rules alongside the country identifiers themselves.

By using an enum (CountryCode), we get type safety by design: only supported country codes can be used, and any invalid input is caught early. When a user passes a string like "CZ" or "PL", we convert it using CountryCode::tryFrom(), which ensures the value maps to a valid case — otherwise, an exception is thrown. This avoids the pitfalls of dealing with unchecked strings throughout the codebase.

Another major advantage is that each enum case can contain logic. In this package, we’ve attached a formatPostalCode() method directly to the CountryCode enum. That means each country case knows how to format its postal code — no need for a giant switch in a separate service or a hardcoded array of closures. It’s clean, localized, and easy to extend. Want to support a new country? Just add a new case and its formatting logic. Done.

This approach also makes the code much easier to navigate and maintain. You don’t have to look across multiple files or layers to understand how formatting works — it’s all bundled logically with the enum case itself.

In short, using an enum here improves:

• Clarity – the code is more readable and expressive

• Safety – only valid country codes are accepted

• Extensibility – adding new rules is straightforward

• Modernity – this is idiomatic PHP 8.1+, using language features as they were meant to be used

For a utility package like Postal-Formatter, this results in a tidy, robust, and maintainable solution.

Conclusion

Building a Composer package in PHP is both rewarding and educational. We started with the motivation – creating reusable code and sharing it with others – and walked through the practical steps of publishing a package on Packagist (from setting up your composer.json to tagging releases and submitting to Packagist). Then we explored the Postal-Formatter package as a concrete example of a simple yet useful library. Along the way, we saw how important it is to structure your package well (with proper documentation, autoloading, and licensing) and to uphold code quality via tests and static analysis.

Finally, we highlighted the use of PHP 8.1 enums in the package, which showcases how embracing new language features can lead to cleaner and more robust solutions. Enums helped ensure only valid country codes are handled and neatly packaged each country’s formatting logic.

If you’re a PHP developer, I encourage you to try creating your own small Composer package. Think of a common problem or utility in your projects, abstract it into a reusable library, and follow the steps to publish it. Not only will it streamline your future development, but you’ll also get the thrill of contributing to the open-source ecosystem. And if you’re curious about the Postal-Formatter package, check it out on GitHub or Packagist – feel free to use it, suggest improvements, or learn from its code. Happy coding, and enjoy your journey into building PHP packages!

Sources:

• Official Packagist documentation on submitting packages and versioning

• Labrodev Postal-Formatter package on Packagist (README and details)

Picture credits:

Unsplash, @curology

Thanks for you attention! Subscribe for Labrodev blog to have more interesting articles around web/php/laravel/vue.js development and more.

Subscribe now

You may also share a post if you found it interesting!

Share

Imagine this: your Laravel app doing its thing, not even knowing there’s a Python service running alongside it. Meanwhile, a lean FastAPI container beside it serves AI model, handles async tasks, or just answers a quick /ping to prove it’s alive. Let’s build that today—in under 10 minutes.

Why FastAPI + Docker

• Separation of concerns.

  We keep our Laravel code in PHP, and all Python-specific logic (whether it’s ML inference, data transformation, or simple utilities) in a standalone service. No more composer vs. pip drama.

• Blazing performance & auto-docs.

  FastAPI (powered by Uvicorn) delivers near–Node.js speeds, full async support, and instantly generates OpenAPI/Swagger docs—so we spend less time wiring and more time coding.

• Portable everywhere.

  Docker wraps the entire environment—Python version, dependencies, configuration—into a single image. It runs the same on your laptop, in CI, or on Kubernetes. Zero surprises.

What we’ll build in this tutorial

As base we will observe Labrodev’s Fast API Skeleton.

It gives us as example:

• A single POST /bmi endpoint to calculate Body Mass Index (BMI)

• Docker support via a straightforward Dockerfile

• A Makefile for common build/run/stop/logs/restart commands

• Instructions for local dev and testing

Project structure

fast-api-skeleton/
├── app/
│   ├── main.py        # FastAPI application
│   └── schemas.py     # Pydantic models
├── Dockerfile         # Container build instructions
├── Makefile           # Docker lifecycle commands
├── requirements.txt   # Python dependencies
└── README.md          # Project documentation

Requirements

• Python 3.9+

• Docker (for containerized deployment)

• (Optional) curl or any HTTP client for testing

Running locally

Install dependencies:

pip install --no-cache-dir -r requirements.txt

Start the FastAPI server:

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Running with Docker

Build the Docker image:

docker build -t fast-api-skeleton-app .

Run the container:

docker run -d --name fast-api-skeleton -p 8000:80 fast-api-skeleton-app

View logs:

docker logs -f fast-api-skeleton

Stop and remove container:

make stop
make rm

You may check the Makefile to see other command aliases:

build:      # Build the Docker image.
	docker build -t fast-api-skeleton-app .

run:        # Run the container (detached).
	docker run -d --name fast-api-skeleton -p 8000:80 fast-api-skeleton-app

stop:       # Stop the running container.
	docker stop fast-api-skeleton

rm:         # Remove the stopped container.
	docker rm fast-api-skeleton

logs:       # Follow container logs.
	docker logs -f fast-api-skeleton

restart:    # Rebuild and restart the container.
	make stop
	make rm
	make build
	make run

Test example

So after successful installation and run up container, let’s try the functionality.
Example in Skeleton is Tiny API with POST endpoint /bmi. The goal of this endpoint is to calculate Body Mass Index based on incoming parameters: name, weight, height.

Let’s look inside app/main.py:

# app/main.py
from fastapi import FastAPI, HTTPException
from .schemas import InputData

app = FastAPI()

@app.post("/bmi")
def calculate_bmi(input_data: InputData):
    # unpack
    w = input_data.weight
    h = input_data.height

    # safety check (Pydantic gt=0 already covers this)
    if h <= 0:
        raise HTTPException(status_code=400, detail="Height must be > 0")

    # BMI formula
    bmi = w / (h * h)
    bmi_rounded = round(bmi, 1)

    return {
        "name": input_data.name,
        "bmi": bmi_rounded,
        "category": interpret_bmi(bmi)
    }

def interpret_bmi(bmi: float) -> str:
    if bmi < 18.5:
        return "Underweight"
    elif bmi < 25.0:
        return "Normal weight"
    elif bmi < 30.0:
        return "Overweight"
    else:
        return "Obesity"

We could see here in main.py that there is definition of post method with endoiunt /bmi and logic inside it which contains calculation and interpretation of results. Incoming parameters are described in InputData class which is imported and defined in schemas.py.

And our request schema in app/schemas.py:

# app/schemas.py
from pydantic import BaseModel

class InputData(BaseModel):
    name:   str
    weight: float
    height: float

It’s quite straightforward to see that in class InputData we describe our BODY parameters and data types of that parameters.

With this in place, a POST to /bmi with:

{
  "name": "Alice",
  "weight": 70.0,
  "height": 1.75
}

Returns:

{
  "name": "Alice",
  "bmi": 22.9,
  "category": "Normal weight"
}

This skeleton lets you quickly stand up tiny endpoints that send your input straight to an ML model and return just the results you need. You can then call these endpoints from anywhere in your system—your Laravel app, background jobs, or other services—for seamless, Python-powered inference.

Conclusion

We’ve seen how to spin up a tiny, Docker-ready FastAPI service in minutes—complete with a real /bmi endpoint, auto-generated docs, and a Makefile workflow. That BMI calculator is just a stand-in: we can easily swap in a TensorFlow or PyTorch model by:

1. Saving our trained model (e.g. models/my_model.pkl).

2. Mounting or copying it into the container.

3. Adding a new endpoint that loads the model and returns results from asking the model

4. Defining matching Pydantic schemas in app/schemas.py.

From our Laravel application, we simply make an HTTP call—no messy PHP bindings required. In this setup, FastAPI becomes the bridge between our business logic (Laravel) and any AI model we’ve built. Tiny, focused, and lightning-fast. 🎉

Let’s give our Laravel projects that Python-powered sidekick!

Thanks for reading! Subscribe to Labrodev substack and let’s keep in touch!

Petro from Labrodev.

Picture used in preview credits:
Unsplash, @rocua18

In fact, every website is bombarded with dozens of unwanted requests every day. These automated “vulnerability scanners” will casually check if you left a secret key under the doormat – be it a database dump, an old admin panel, or a default password. As one security researcher put it, “the wolf has been at your door since the day you put that server online.” 😨

So, how do we deal with this constant nuisance (and potential danger) of brute-force and bot attacks? Enter Fail2Ban – the unsung hero and bouncer of the server world.

What is Fail2Ban and How Does It Help?

Fail2Ban is a lightweight, open-source intrusion prevention framework (written in Python) that protects your server from these automated attacks. Think of it as an automated bouncer for your server: it monitors your log files for suspicious patterns (failed logins, 404 errors from bots scanning for exploits, etc.) and automatically bans the offending IPs by adding a rule to your firewall. For example, Fail2Ban will watch something like /var/log/auth.log for repeated SSH login failures and then block that IP address for a while. This dramatically cuts down the noise from bots hammering your services.

Out of the box, Fail2Ban comes with filters (rules) for many common services – SSH, FTP, web servers (Apache/Nginx), mail servers, etc. – and it’s easily configurable to watch any log file you want. The default configuration alone can stop a lot of bad behavior right away. For instance, the moment some bot throws five wrong passwords at your SSH, Fail2Ban can ban them for 10 minutes or longer (default bantime is 10 minutes, but you can adjust it). The same goes for other protocols: too many FTP login failures, or too many 404 errors on your website, and that IP gets the boot. Essentially, Fail2Ban reduces malicious login attempts by blocking the source IP addresses automatically. It’s like having a security guard who gives any suspicious intruder a time-out.

Importantly, Fail2Ban isn’t a silver bullet – it won’t stop a distributed attack (where each attempt comes from a different IP), and it doesn’t fix weak passwords or outdated software. But for the price of a quick install, it adds a very effective layer of defense. It’s also pretty opinionated software (in a good way): it assumes that if an IP is misbehaving, you’re better off not hearing from it again for a while. And honestly, I agree. 😉

Installing Fail2Ban on Ubuntu 24.04

Installing Fail2Ban on Ubuntu is straightforward since it’s available in the official package repository. Here we’ll focus on Ubuntu 24.04 (or any recent Ubuntu release). Just pop open your terminal and run:

sudo apt update && sudo apt upgrade -y
sudo apt install fail2ban -y 

That's it! The Fail2Ban service will start automatically after installation. You can verify it's running by asking it to ping itself:

sudo fail2ban-client ping

If everything is OK, it should respond with PONG. 🟢

A note on firewalls: Fail2Ban works by adding rules to your firewall (iptables under the hood). On Ubuntu, many people also use UFW (Uncomplicated Firewall). If UFW is active or if you plan to use it, make sure you have an SSH allow rule before enabling UFW, or you might lock yourself out when Fail2Ban bans something. For example:

sudo ufw allow OpenSSH    
sudo ufw enable           

Fail2Ban will happily work with UFW as the backend (it supports iptables, UFW, firewalld, etc., automatically). If you’re not using UFW, Fail2Ban will just use iptables directly. In any case, after installation, Fail2Ban is up and ready to ban bad actors.

Basic Configuration and Enabling the SSH Jail

Fail2Ban’s default settings are decent, but it’s worth doing a bit of configuration to tailor it to your needs. Configuration is typically done in the file /etc/fail2ban/jail.conf or, better, in a separate jail.local file (to override defaults without getting overwritten on updates). The quick way is to copy the default config to a .local file:

sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local

Now open /etc/fail2ban/jail.local in your favorite editor (e.g. sudo nano /etc/fail2ban/jail.local). You’ll see a bunch of sections for different “jails.” A jail in Fail2Ban parlance is basically a set of rules for a particular service or pattern (e.g., an SSH jail that watches auth log for SSH failures).

Let’s make sure the SSH jail is enabled and tweaked:

[sshd]
enabled = true        # Make sure this is true to activate the SSH jail
port    = ssh         # or specify the port if you changed it from 22
logpath = /var/log/auth.log
maxretry = 5          # max failed attempts before ban (default 5)
findtime = 10m        # time window for maxretry (default 10 minutes)
bantime  = 1h         # ban duration (e.g. 1 hour; default was 10m)

In the snippet above, we enable the [sshd] jail. We keep maxretry at 5 (meaning 5 failed login attempts within the findtime window will trigger a ban) – you can lower this if you want to be stricter. We’ve increased bantime to 1 hour in this example, instead of the default 10 minutes, because a 10-minute ban is sometimes not much of a deterrent. You could even set bantime = 1d for a full day, or bantime = -1 for a permanent ban of that IP (though permanent bans might eventually fill up your firewall rules if many accumulate).

Feel free to adjust these values. For instance, if you rarely ever log in to SSH with a password (as you should be using keys!), you might set maxretry to 3 or even 1 just to ban first-time offenders immediately. The idea is to find a balance – you want to silence the noise of incessant bot attacks without accidentally locking yourself out or banning legitimate users. (Tip: The ignoreip setting under the [DEFAULT] section can whitelist IPs you never want to ban – e.g. your home/office IP range – so you don’t ban yourself by mistake.)

When you’re done editing, save the file and restart Fail2Ban to apply changes:

sudo systemctl restart fail2ban

Fail2Ban will now be actively monitoring your SSH logs and banning any IPs that violate the rules. ✅

Adding a Custom Rule (Blocking Specific Bot Patterns)

One of the great things about Fail2Ban is its flexibility. Beyond the pre-packaged jails, you can create your own rules to match patterns specific to your environment. Remember those bots looking for .env files or other juicy targets? We can make Fail2Ban ban them too!

For example, suppose you want to ban any IP that tries to access a hidden file like .env on your web server (because legit users would never do that). We can set up a custom jail for that. Let’s check it below.

Create a filter definition

It’s basically a regex pattern to catch the bad behavior. Filters are stored in /etc/fail2ban/filter.d/. Let’s create one for “env file access attempts”:

sudo nano /etc/fail2ban/filter.d/custom-env.conf

Inside this file, define a filter under a [Definition] header. For an Nginx access log, a simple filter to match a .env request might look like:

[Definition]
failregex = ^<HOST> -.* \"GET \/\.env
ignoreregex =

Let’s break that down:

• <HOST> is a placeholder that Fail2Ban uses to identify the attacker’s IP from the log line.

• The regex here is looking for lines where an IP (that’s the <HOST> at the start of an Nginx log line) requests “GET /.env”. We put a backslash before .env because the dot is a special char in regex. This pattern is simplistic (it assumes the request is a GET and doesn’t fully anchor the line), but it should catch most cases. You can refine regex as needed (check your actual log format!). The ignoreregex is empty, meaning we’re not defining any pattern to ignore.

Define the jail using this filter

So now open your jail local config (/etc/fail2ban/jail.local or you can create a new file under jail.d/ for cleanliness) and add a section for this new jail. For example:

[nginx-env-scan]
enabled  = true
filter   = custom-env    # refers to the custom-env.conf filter we just created
action   = iptables-multiport[name=NoEnv, port=\"http,https\"]  
logpath  = /var/log/nginx/access.log
maxretry = 1
findtime = 1m
bantime  = 1d

Here, we named the jail "nginx-env-scan" (name it whatever makes sense to you). We enable it and point it to use the custom-env filter. The action line tells Fail2Ban how to ban (this uses the standard iptables action for blocking on one or multiple ports – in this case, we block the host on both HTTP and HTTPS ports). We set maxretry = 1 and a short findtime of 1 minute, meaning a single match is enough to ban the IP for a day. This is a bit aggressive, but for something like .env access attempts, it’s probably safe – there are virtually no legitimate reasons for a public user to request that file. (If you were doing this for, say, an /admin URL that could have legit visitors, you’d use a higher threshold like 3 retries in 5 minutes, etc.)

Restart the service

Let’s restart the server to load the new filter and jail:

sudo systemctl restart fail2ban

Now Fail2Ban will watch your Nginx access logs and any IP that tries to GET a .env file will be banned on the spot. 🎉 Similarly, you could craft rules for other common bot targets – e.g. wp-login.php (if you’re not running WordPress, no one should be hitting that), or blocking excessive 404 errors in a short time (indicating someone scanning for lots of files). There are community-contributed filters for common CMS exploits and bad bots, or you can write your own as we just did.

Pragmatic tip: Don’t go too overboard with hundreds of custom rules for every little thing – focus on the high-signal patterns (like obvious exploit scans) so you don’t accidentally ban real users. The goal is to reduce malicious traffic, not to create a self-inflicted denial of service. 😉

Monitoring Fail2Ban: Status, Logs, and Unbanning

Once Fail2Ban is running, you’ll want to occasionally check in on what it’s doing. The primary command-line tool is fail2ban-client, which lets you interact with the Fail2Ban daemon.

Let’s check some useful commands below.

Overall status

We may see a summary of jails and overall bans:

sudo fail2ban-client status

Jail status

We may get details about a specific jail, including currently banned IPs:

sudo fail2ban-client status sshd

This command will show you how many IPs have been banned by the SSH jail and list them. For instance, you might see output indicating X total bans and a list of IP addresses that are currently banned for SSH. Similarly, you can check nginx-env-scan or any other jail by name.

Logs

Fail2Ban logs its actions to /var/log/fail2ban.log. It’s often informative to tail this log to see which IPs are getting banned and why. For example:

sudo tail -f /var/log/fail2ban.log

We will see entries whenever a ban or unban happens, e.g., “Ban xxx.x.xxx.xx on sshd” etc.

Unbanning an IP

Occasionally, we might need to manually unban someone (maybe you banned yourself during testing – it happens and be careful with that axe, Eugene careful with this tool on your live server!). To unban an IP:

sudo fail2ban-client set sshd unbanip xxx.x.xxx.xx

Replace xxx.x.xxx.xx with the IP you want to free from jail. This command tells Fail2Ban to remove that IP from the jail’s ban list, which in turn removes the firewall rule. After unbanning, that IP can connect again (assuming it fixes its behavior).

Banning an IP manually

It is also possible to proactively ban an IP (outside the automatic triggers) using a similar command:

sudo fail2ban-client set sshd banip xxx.x.xxx.xx

Everything you do with fail2ban-client is also doable by editing config or directly manipulating firewall rules, but the tool provides a nice interface and ensures Fail2Ban’s internal state stays in sync.

Conclusion: High Impact, Low Effort Security

If you’ve made it this far, you’ve seen that Fail2Ban offers a big security win for very little effort. In about 5 minutes, you installed it and enabled a jail or two, and your server gained the ability to automatically smack down many brute-force and bot-driven attacks. It’s not fancy, and it’s certainly not a replacement for good practices (you should still use SSH keys or 2FA, strong unique passwords, keep your software updated, etc.). But Fail2Ban addresses a very common class of threats in a way that’s both simple and effective. It’s basically set-and-forget: install, configure once, and let it quietly do its job in the background.

Personally, I consider Fail2Ban a must-have on any server that faces the wild internet. It’s like having an invisible force field that won’t stop a targeted ninja attack, but will definitely fend off the annoying background noise of the internet’s riff-raff. And that means you (and your server) can sleep a little more soundly at night. 😴👍

So go ahead – give your server that bouncer it deserves. In the eternal words of the security community: “configure Fail2Ban today, and thank yourself later.” Stay safe out there!

Thanks for reading! Subscribe to Labrodev substack and let’s keep in touch!

Picture used in preview credits:
Unsplash, Towfiqu barbhuiya

"Ever-newer waters flow on those who step into the same rivers," said Heraclitus long ago. In this statement, "waters" can be interpreted as the endless and ceaseless generations of people, while "rivers" symbolize the universal essence that unites all who have lived, live now, and will live on Earth. One of the key components of this universal essence is humanity’s ability to create and interpret creativity.

A reader of Meditations by Marcus Aurelius is likely to find more thoughts resonating with contemporary times than in the New York Times bestsellers of 2024. The paintings of Pieter Bruegel the Elder evoke emotions no less than those of Banksy. Here and now, in the present, we have Banksy, Stromae, Billie Eilish, and the films of David Lynch—none of which existed in Bruegel's time. The Flemish school of painting, to which Bruegel belonged, did not exist in the days of Marcus Aurelius. And in Heraclitus’s lifetime, neither Aurelius nor the Roman Empire had yet emerged. This means that the variety of creative expressions known to humanity accumulates over time, while the universal capacity to understand and interpret creativity not only remains but also expands.

Yet art has always hidden itself not only in great books and wealthy museums. It is no longer solely "high" or elitist. It can be found everywhere—in the design of tableware on store shelves, in SpaceX spacecraft and Japanese automobiles, in the kit design of Manchester City for the 2024/25 season, in the latest models of Hoka running shoes. It exists in well-executed work—whatever that work may be—in facade renovations, in floral arrangements, in writing code, or in cleaning public restrooms (a nod to Perfect Days). It is present in Chinese souvenirs sold at Istanbul’s Grand Bazaar and in authentic embroidered shirts at the Kosiv market. It is in the things people craft with their hands—whether a knitted sweater, a built house, a restored chair, or a necklace of agate. It is in the photographs filling Google and Meta data centers.

Creativity manifests itself in poetry, paintings, music, and the reflections of modern minds. Of course, not everything deserves a place in a museum or to be immortalized on a vinyl record. But even Duchamp’s urinal once found its place in world culture. Every act of creation has the right to be named and manifested—just as it has the right to be ignored or remain unexpressed.

In the visions of a possible happy future painted by futurists, a common theme emerges: humanity will dedicate most of its time to creativity, education, and science rather than to securing comfortable survival and an illusion of safety. There is an undeniable understanding that the ability and opportunity to create—without being distracted by financial pyramids, war, or mortgage payments—will be one of the greatest privileges of the future human.

In his seminal book Concerning the Spiritual in Art, Wassily Kandinsky wrote:
"To harmonize the whole—that is the task of art."
The whole world is a single entity, and everything around us is subject to harmonization. The further we go, the more complex it becomes, because the number of elements increases. Yet it is within this mosaic that the true imprint of humanity is found.

And artificial intelligence will not take away humanity’s ability to create and interpret creativity. Because, as it seems, this is a gift granted to humans by the very force that once, through an act of creation, made them in its own image.

And here are some beautiful paintings which I’ve enjoyed in my recent trip to Vienna.

1. Pieter Bruegel the Elder - The Hunters in the Snow (1565)

   Kunsthistorisches Museum

2. Egon Schiele - Self-portrait with stripped shirt (1910)

   Leopold Museum

3. Max Pechstein - Young Lady with Feather Hat (1910)

   Leopold Museum

And the beautiful quote from Egon Schiele:

In this article, we’ll explore how traits work in Laravel, how they can be used to add shared functionality to Eloquent models, and dive into an example with a custom Numberable package—a trait-based package for generating unique, consistent document numbers for models. We’ll also touch on how to separate a trait into a standalone Laravel package, making it reusable across projects.

What Are Traits and Why Use Them?

Traits in PHP are a mechanism for code reuse, allowing classes to inherit methods from multiple sources. In Laravel, traits are often used to add reusable methods or functionalities to Eloquent models. Instead of creating a complex inheritance hierarchy, you can simply import a trait, making your model gain additional behaviors or features without impacting the rest of the application.

Example Uses of Traits:

• Automatic Timestamps: Custom traits can automatically set timestamps for specific actions.

• Soft Deletes: Laravel’s SoftDeletes trait allows models to be marked as deleted without removing them from the database.

• Custom Attributes: Traits can add calculated or formatted attributes for models.

Traits are an excellent choice for sharing functionality across different models, especially when you need consistency and reusability. They allow us to keep our models lean and focused on their primary business logic.

Building the Numberable Trait: An Example

Our Numberable package demonstrates how traits can add reusable functionality to Eloquent models. This package provides a trait, ModelHasNumber, which automatically assigns a unique document number to each model when it’s created.

The generated number format can be customized, making this package ideal for any application that needs consistent, flexible document numbering. Here’s a brief overview of how the ModelHasNumber trait works.

// Labrodev\Numberable\ModelHasNumber.php

namespace Labrodev\Numberable;

use Illuminate\Support\Str;
use Carbon\Carbon;

trait ModelHasNumber
{
    public static function bootModelHasNumber(): void
    {
        static::created(function ($model) {
            if (!$model->isModelHasNumberTraitValueGenerated()) {
                if (isset($model->id)) {
                    $model->{$model->modelHasNumberTraitColumn()} = $model->generateNumberByTraitModelHasNumber($model->id);
                    $model->withoutEvents(function () use ($model) {
                        $model->save();
                    });
                }
            }
        });
    }

    protected function modelHasNumberTraitColumn(): string
    {
        return 'number';
    }

    private function isModelHasNumberTraitValueGenerated(): bool
    {
        $name = $this->modelHasNumberTraitColumn();
        return isset($this->attributes[$name]) && $this->attributes[$name] !== null;
    }

    protected function generateNumberByTraitModelHasNumber(int $modelId): string
    {
        $currentYear = Carbon::now()->year;
        $predictionNumber = $this->predictionNumberForTraitModelHasNumber();
        $paddingLength = strlen((string) $predictionNumber);

        return $currentYear . Str::padLeft((string) $modelId, $paddingLength, '0');
    }

    protected function predictionNumberForTraitModelHasNumber(): int
    {
        return 10000;
    }
}

How ModelHasNumber Works

• Automatic Number Generation: The trait attaches a listener to the created event of the model. Upon creation, it checks if the number attribute is already set, and if not, it generates a new document number.

• Year-Based Numbering: The number generated includes the current year as a prefix, followed by a padded model ID. This format is useful for document numbers, invoice numbers, or order IDs.

• Customizable Logic: You can override the generateNumberByTraitModelHasNumber method within a model to provide a custom document number format. This allows you to adapt the numbering system for specific requirements.

Example Number Format: If the current year is 2024, the model ID is 45, and the prediction number is 10000, the document number generated would be 202400045. This ensures a consistent document number length.

Customizing the Trait in Models

Laravel makes it easy to override trait methods within a model. If a model requires a custom numbering format, you can simply override the generateNumberByTraitModelHasNumber method to create a unique numbering scheme without modifying the base trait.

use Labrodev\Numberable\ModelHasNumber;

class Order extends Model
{
    use ModelHasNumber;

    protected function generateNumberByTraitModelHasNumber(int $modelId): string
    {
        // Custom numbering logic for Order model
        $prefix = 'ORD';
        return $prefix . Carbon::now()->year . str_pad((string) $modelId, 6, '0', STR_PAD_LEFT);
    }
}

In this example, the Order model will have a custom numbering format, such as ORD2024000045, combining a prefix with the year and a padded ID.

Packaging the Trait as a Laravel Package

Creating a standalone package for the ModelHasNumber trait allows it to be reused across multiple projects. Here’s how to set up this package in a few steps:

1. Create the Package Structure: Inside your packages directory, create a folder for your package, for example, Labrodev/Numberable, with a src folder containing the ModelHasNumber.php trait.

2. Set Up composer.json: In the root of the package folder, create a composer.json file to define the package’s dependencies and metadata:

{
    "name": "labrodev/numberable",
    "description": "A Laravel package for automatic document numbering",
    "type": "library",
    "require": {
        "php": ">=8.1",
        "illuminate/contracts": "^10.0",
        "nesbot/carbon": "^2.72",
        "ramsey/uuid": "^4.7"
    },
    "require-dev": {},
    "autoload": {
        "psr-4": {
            "Labrodev\\Numberable\\": "src/"
        }
    },
    "scripts": {
        "post-autoload-dump": "@composer run prepare",
        "clear": "@php vendor/bin/testbench package:purge-skeleton --ansi",
        "prepare": "@php vendor/bin/testbench package:discover --ansi",
        "build": [
            "@composer run prepare",
            "@php vendor/bin/testbench workbench:build --ansi"
        ],
        "start": [
            "Composer\\Config::disableProcessTimeout",
            "@composer run build",
            "@php vendor/bin/testbench serve"
        ]
    },
    "config": {
        "sort-packages": true
    },
    "minimum-stability": "dev",
    "prefer-stable": true
}

Conclusion

Traits are a fantastic way to add modular functionality to Eloquent models, making it easy to reuse logic across different models. The Numberable package is a practical example of how traits can encapsulate specific functionality, in this case, document number generation. By converting it into a standalone package, we’ve made it possible to reuse this functionality across Laravel projects with ease.

Traits are especially useful when combined with Laravel’s event-driven model lifecycle, allowing us to automate processes like assigning unique numbers to models. With a little customization, traits like ModelHasNumber can serve a variety of business needs, keeping your Laravel codebase clean, consistent, and highly maintainable.

For the full implementation, check out our laravel-numberable package on GitHub.

Thanks for reading!

Subscribe to our Substack to get more tips and tutorials on Laravel development and best practices delivered straight to your inbox.

Preview photo credit:

https://unsplash.com/@francesco_ungaro

They can also be really useful in APIs, where they can serve as unique resource identifiers. As well as in Dashboards or Back end interfaces where we could use them as route parameters instead of plain old IDs.

In this article, we’ll describe how to implement UUID generation for Eloquent models in Laravel using a reusable trait.

Step 1: Add UUID column in table in database

First, you need to add a UUID column to your table in the database (if your table is already has uuid column, skip this step). You can do this by creating a new migration or modifying an existing one. Here's an example of Laravel migration how to add a UUID column to a table:

public function up()
{
    Schema::table('example_table', function (Blueprint $table) {
        $table->uuid('uuid')->unique()->nullable();
    });
}

public function down()
{
    Schema::table('example_table', function (Blueprint $table) {
        $table->dropColumn('uuid');
    });
}

Step 2: Create the Trait

Let’s create a trait that automatically generates and assigns a UUID when a new Eloquent model is created.

<?php

declare(strict_types=1);

namespace Labrodev\Uuidable;

use Illuminate\Support\Str;

trait ModelHasUuid
{
    /**
     * Boot the trait and add the creating event listener.
     *
     * @return void
     */
    public static function bootModelHasUuid(): void
    {
        static::creating(function ($model) {
            /** @var static|self $model */
            if (empty($model->{$model->fetchUuidColumn()})) {
                $model->{$model->fetchUuidColumn()} = Str::uuid();
            }
        });
    }

    /**
     * Get the name of the UUID column.
     *
     * @return string
     */
    protected function fetchUuidColumn(): string
    {
        return 'uuid';
    }
}

This trait hooks into the creating event of the model and assigns a UUID if the UUID column is empty. The fetchUuidColumn method specifies the column name used for storing the UUID. If your column is named differently, you can override this method in your model.

When we use the bootModelHasUuid static function, it seamlessly integrates with Laravel Eloquent's booting mechanism. Laravel automatically calls the boot method on all traits used by a model, allowing the bootModelHasUuid method to contribute its functionality to the model's primary boot method. This ensures that the UUID assignment logic is consistently applied whenever a new model instance is created.

Step 3: Using the Trait in a Model

To use the ModelHasUuid trait, include it in your Eloquent model like this:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Labrodev\Uuidable\ModelHasUuid;

class ExampleModel extends Model
{
    use ModelHasUuid;
}

Step 4: Customizing the UUID Column Name

If your UUID column is named something other than uuid, you can override the fetchUuidColumn method in your model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Labrodev\Uuidable\ModelHasUuid;

class ExampleModel extends Model
{
    use ModelHasUuid;

    /**
     * Override method to specify a custom column name.
     *
     * @return string
     */
    protected function fetchUuidColumn(): string
    {
        return 'custom_uuid_column';
    }
}

Conclusion

By following these steps, you can implement UUID generation for Eloquent models in Laravel, providing a reliable and unique identifier for your records. This approach is encapsulated in a reusable trait, making it easy to apply to any model within your application. For the full implementation, check out our laravel-uuidable package on GitHub.

Thanks for reading!

Subscribe to our Substack to get more tips and tutorials on Laravel development and best practices delivered straight to your inbox.

Preview photo credit:

https://unsplash.com/@afgprogrammer

I want to cover a straightforward topic about using SSH key authentication to access your remote server as a preventive measure against unauthorized access in your environment. This article doesn't contain any big insights, and I'm not a cybersecurity professional, so this is not an article to cover the depths of securing remote servers (nor does it dig deep into discussing the insecure nature of SSH in general).

I'm just a software developer who operates a bunch of remote servers (mostly Ubuntu, VPS). These servers host many projects—test, live, commercial, educational, and demo—with numerous .env files. These are things you always want to keep private for yourself, your clients, and your colleagues.

Here are some first-hand measures that can at least reduce potential risks in case someone discovers your login/password and connects to your server through SSH.

And now, let's talk about SSH brute force attacks.

If you check the access logs of some of your servers that host indexed websites or are exposed to public domains through DNS, you might find numerous attempts to log in to your server from random IP addresses (often from unexpected geo-locations).

You're lucky that none of these attempts succeeded and were disconnected due to authentication failures (incorrect login/password combinations). However, statistically, one pair could match one day, and that's a problem. It's even easier if your login is named "root," isn't it?

So here you may find in your server access logs:

11:40:50.181
Dec 22 12:40:50 your-server sshd[4922]: Disconnected from authenticating user root xxx.xxx.xx.xxx port 41112 [preauth]
 
11:41:38.002
Dec 22 12:41:38 your-server sshd[5050]: pam_unix(sshd:auth): authentication failure; logname= uid=0 euid=0 tty=ssh ruser= rhost=xxx.xxx.xx.xx user=root
 
11:41:39.751
Dec 22 12:41:39 your-server sshd[5050]: Failed password for root from xxx.xxx.xx.xx port 49826 ssh2
 
11:41:39.904
Dec 22 12:41:39 your-server sshd[5052]: pam_unix(sshd:auth): authentication failure; logname= uid=0 euid=0 tty=ssh ruser= rhost=xxx.xxx.xx.xx  user=root
 
11:41:39.940
Dec 22 12:41:39 your-server sshd[5050]: Received disconnect from xxx.xxx.xx.xx port 49826:11: Bye Bye [preauth]
 
11:41:39.940
Dec 22 12:41:39 your-server sshd[5050]: Disconnected from authenticating user root xxx.xxx.xx.xx port 49826 [preauth]
 
11:41:41.593
Dec 22 12:41:41 your-server sshd[5052]: Failed password for root from 179.95.180.141 port 53538 ssh2
 
11:41:41.787
Dec 22 12:41:41 your-server sshd[5052]: Received disconnect from xxx.xxx.xx.xx port 53538:11: Bye Bye [preauth]
 
11:41:41.787
Dec 22 12:41:41 your-server sshd[5052]: Disconnected from authenticating user root xxx.xxx.xx.xx port 53538 [preauth]

11:41:47.612
Dec 22 12:41:47 your-server sshd[5058]: Invalid user wyg from xxx.xxx.xx.xx port 52864

As you can see, there are different attempts from random IP addresses (imagine any random IP address instead of xxx.xxx.xx.xx) to connect to your server through SSH. This is how SSH brute force attacks look.

Understanding SSH Brute force attacks

A brute force attack is a method used by attackers to gain unauthorized access to accounts by systematically trying all possible password combinations. This approach can be incredibly effective if passwords are weak or not protected by additional security measures.

Many brute force attacks are automated using bots. Attackers deploy these bots across the internet to scan for servers with open SSH ports. Once a potential target is found, the bots use a list of commonly used usernames and passwords to attempt to log in. This method allows attackers to try thousands of combinations in a short period, increasing their chances of success.

Solution

To defend your server from these attacks, obvious solution is to replace SSH login/password authentication with SSH key authentication.

SSH keys provide a more secure alternative to password authentication, eliminating the chance for bots to quickly find the correct login/password combination.

Let’s go through step-by-step explanation how to make this twist.

Disclaimer: My local environment is Ubuntu (so keep in mind if you are using another operation system, which handle ssh key generation not in the same way as in Ubuntu, just find additionally how to do it with your setup).

Step 1: Generate SSH key-pair on your local

1. Open your terminal and input

ssh-keygen

2. Follow the prompts

• You will be asked where to save the key. Press Enter to accept the default location (/home/user/.ssh/id_rsa).

• Enter a passphrase for additional security, or press Enter to leave it empty.

You will receive as output something like this:

Your identification has been saved in /home/user/.ssh/id_rsa
Your public key has been saved in /home/user/.ssh/id_rsa.pub
The key fingerprint is:
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (some real data here)
The key's randomart image is:
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (some real data here)

Step 2: Copy generated public ssh key on your server

1. Input in terminal

ssh-copy-id your-server-username@your-server-ip

• Replace your-server-username with your actual username on the server (which is configured to login on server through ssh)

• Replace your-server-ip with the server's IP address or host name

2. Enter Your Password

You will be prompted to enter your password for the server.

As output of this command you may receive something like this as output:

Number of key(s) added: 1

Now try logging into the machine, with:   "ssh 'your-server-username@your-server-ip'"
and check to make sure that only the key(s) you wanted were added.

And after these steps, you will be able to log in through SSH key authentication from your local machine to your remote server without needing to enter a password anymore.

3. Ensure that new SSH key authentication works correctly

Input in your console

ssh your-server-username@your-server-ip

Important

And only if you are able to log in to your server through this command, you may move forward to the second part of the process and disable login/password authentication in the server configuration (let’s explore this in step 4 below). It's important because if you will disable password authentication on your server, but your ssh-key authentication doesn’t work for some reasons, then you will loose access to your own server.

Careful with that axe, Eugene!

Step 3: Disable Password Authentication

1. Log in into your remote server

ssh your-server-username@your-server-ip

2. Open the SSH Configuration File

sudo nano /etc/ssh/sshd_config

3. Find and Edit PasswordAuthentication Directive

Change the line #PasswordAuthentication yes to:

PasswordAuthentication no

Press Ctrl + X, then Y, and Enter to save and exit.

4. Restart the SSH Service

sudo systemctl restart sshd

Step 4: Confirm changes

1. Once again try to log in to your remote server from local with ssh-key

ssh your-server-username@your-server-ip

You should successfully log in.

2. Try to login/password authentication

ssh your-server-username@your-server-ip -o PubkeyAuthentication=no

And you should see an error indicating that password authentication is not allowed which is our expected behavior.

Step 5: Backup your SSH private key

Ensure your private SSH key (home/user/.ssh/id_rsa) is backed up securely (the path to id_rsa is provided here as an example and may vary based on your setup). Keep it in a secure location, not only on your local computer, as it’s a crucial part of SSH key authentication. If you lose your key, you may have trouble logging into your remote server.

Conclusion

In this article, we’ve highlighted the problem of SSH brute force attacks - how they are done, how to identify if your server is struggling with them, and what the solution is.

The solution is obvious and straightforward - use SSH key authentication instead of login/password authentication.

You may find here a step-by-step guide on how to implement this solution.

Enjoy your enhanced security and don’t give bots a chance to find the back door into your servers.

Thank you for your attention!

Picture in preview credit:

Unsplash, FlyD

Static analysis tool in PHP is a game-changer for code quality and readability. These tools are like having an extra pair of eyes that meticulously scan your code, pointing out any errors, typos, or even potential issues that could turn into bigger problems down the line. This is super handy because, let's face it, mistakes happen more often than we'd like to admit.

PHPStan is one of the most popular and free static analysis tools. So in this post, I just want to briefly provide a step-by-step guide on how to use PHPStan in a Laravel project. I'm hoping this will be particularly useful for those who are new to this topic.

1. Install PHP Stan

composer require phpstan/phpstan --dev

2. Install Larastan

composer require nunomaduro/larastan --dev

Larastan is specifically designed for Laravel projects. It's essentially an extension of PHPStan. By using Larastan in your Laravel projects, you're essentially adding an extra layer of quality control. It helps ensure that your code is not just error-free, but also adheres to good coding practices specific to Laravel. It provides the static analysis tool with an understanding of most of Laravel's beautiful magic.

3. Install Laravel IDE Helper

composer require --dev barryvdh/laravel-ide-helper

Laravel IDE Helper Generator for Laravel is package to generate PHPDocs, mostly for Laravel models.

PHPDocs play a significant role in describing code to static analysis tools. Therefore, it's highly beneficial to leverage this package and ensure your models are thoroughly documented with essential PHPDocs.

It also generates helper files that enable your IDE to provide accurate autocompletion. Generation is done based on the files in your project, so they are always up-to-date.

4. Configure Laravel IDE Helper

Let’s publish configuration file of package to project config directory.

php artisan vendor:publish --provider="Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider" --tag=config

After this command, you may find ide-helper.php file in config folder.

Changing any of configuration there is optionally, but I want to ended up with one thing there:

'model_locations' => [
    'app',
 ],

You may adjust locations of your models. For example, if some of your models are located in your core package in vendor, you may just provide exact location here, like this:

'model_locations' => [
    'app',
    'vendor/labrodev/filter-components/src/Models'
],

5. Generate Laravel IDE Helper files

Generate ide-helper file

php artisan ide-helper:generate 

This command is used to generate a file that provides correct PHPDoc annotations for all Facade classes. This helps integrated development environments (IDEs) understand the Laravel Facades better, thereby improving auto-completion and code analysis (and static analysis) features.

As a result, you may find generated file _ide_helper.php in root of your project.

Add \Eloquent mixin

php artisan ide-helper:eloquent

This command adds docblock mixin to /vendor/laravel/framework/src/Illuminate/Database/Eloquent/Model.php:

@mixin \Eloquent

This annotation tells the IDE that the methods from the Eloquent class are available in the model, even though they're not explicitly defined there. This enables the IDE to offer code completion, function lookup, and other helpful insights for Eloquent methods when you're working on your models. And again, it helps to better understanding of code and static analysis.

Generate PHPDocs for models

There is a 2 ways of adding PHPDocs in your model.

• to add PHPDocs to each Model class directly

• to generate separate files with PHPDocs for each Model class with mixin alias and to put only this alias to each Model file.

From my perspective, the second approach is much better because it avoids overloading models with lengthy PHPDoc blocks that don't add any functional value. Instead, everything necessary for static analysis is kept in one separate, specific file.

To generate PHPDocs in a separate file and add only mixins to the Model classes, we need to use the --write-mixin option in the command. Conversely, to write PHPDocs directly into Model classes, use the --write option.

More information specifically related to this command you may find here.

php artisan ide-helper:models --write-mixin

As result you may find generated file _ide_helper_models.php with all PHPDocs related to each model.

And you may check your Model classes, there you may find mixin with alias to _ide_helper_models classes. Something like this:

/**
 * @mixin IdeHelperYourModel
 */

Generare PHPStorm meta information

It’s optionally and could give benefits mostly for your IDE environment if IDE is PHP Storm.

php artisan ide-helper:meta

As result, you may find .phpstorm.meta.php file at the root of your project.

6. Create PHPStan configuration file

Let’s create phpstan.neon file in root of your project. And adjust configuration of PHPStan.

includes:
    - ./vendor/nunomaduro/larastan/extension.neon
parameters:
    level: 9
    paths:
        - app
    scanFiles:
        - _ide_helper.php
        - _ide_helper_models.php
        - .phpstorm.meta.php
    checkGenericClassInNonGenericObjectType: false

Let’s break up what’s going on in this configuration file.

• includes: specifies that the Larastan configuration will include settings from the extension.neon file found in the Larastan package. This file typically contains Larastan-specific configurations and is essential for integrating Larastan's static analysis capabilities into your project.

• level: 9: This sets the strictness level of the analysis. In PHPStan (and Larastan by extension), the levels range from 0 (most lenient) to 9 (most strict). A higher level means the tool will perform a more thorough analysis, catching more potential issues.

• paths: this tells Larastan to analyze the files in the app directory of your Laravel project. It's where most of your application's core logic resides, so it's crucial for static analysis.

• scanFiles: files are added to the scan list to ensure that Larastan understands your IDE helpers and any custom meta-information provided by PHPStorm (or other IDEs). It helps in making the analysis more accurate, especially for Laravel-specific features and helpers.

• checkGenericClassInNonGenericObjectType: this option, when set to false, instructs Larastan to not report errors related to the usage of generic classes in non-generic object types.

7. Define composer command to run PHP Stan analysis

Let’s go to composer.json and adjust “scripts” part to define command for running PHP Stan from composer.

"scripts": {
    "phpstan": "vendor/bin/phpstan analyse"
},

So now we may use this command in console to run PHP Stan:

composer phpstan 

Now, you may enjoy results of static analysis and investigate reports with errors provided by PHP Stan.

Wish you happy coding and green reports in PHP Stan.

Thanks you for attention.

Recently, I've faced an issue that my JavaScript library, which my clients use on their site, doesn't work because there is a conflict of global variables, as another JavaScript code uses the same global variable as mine.

Of course, this is a common problem, especially when multiple scripts are included on a web page. It’s well-known that JavaScript is very flexible with its global namespace, which means any variable declared without var, let, or const (or declared with var in the global scope) becomes a global variable. If two different scripts declare the same global variable, they will conflict with each other. If some of external JavaScript libraries are using a variable with the same name in the global scope, one script's variable will overwrite the variable from the other script. This can cause unexpected behavior or errors, as one of the libraries might not work as intended with the overwritten variable.

My code doesn't work in this scenario because it loads into the DOM after another library that uses the same naming convention. To resolve this issue, the first step is to rename my variable, verify if it's necessary in the global scope, or consider encapsulating it within namespaces, among other solutions.

The problem is that my library consists of minified JS code, which essentially contains an entire single-page application from Vue.js 3. Therefore, my conflicting global variable is a shorter name of something else, which acquired its naming during the mangling process that occurs during code compilation and minification.

Let’s breakdown what is mangling. In the context of JavaScript minification, the "mangling" process is a specific step that involves renaming variables and function names to shorter ones. It helps to reduce the overall length of code and size of code file. It’s a part of minification. So, for example, variable named userInput might be renamed to a.

Solution

Directly and brutally renaming a conflicting variable in a minified JS file is not a good idea, as it will probably cause additional problems and errors in the code. So, I found another solution - it's related to instructing the code compiler not to use certain names during the mangling process. In other words, to set up a directive that prevents certain names from being used as shortened versions of normal variables.

I compile my code with Vite, so my solution is related to adjust build settings in vite.config.js.

By default, Vite uses Esbuild web bundler for minifing code. I didn’t find easy options in Esbuild to fix my issue, so I switched from Esbuild to Terser - beautiful javascript mangler and compressor.

First of all, we need to install terser in our project:

npm install terser

My conflicting variable is called ‘dc’. So we need to configure directive in build part to not use this variable in naming shorten variables in classes during compilation.

So let’s modify our vite.config.js.

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [vue()],
  resolve: {
   // some other code
  },
  // Build configuration
  build: {
    minify: 'terser', // here we set up terser instead default esbuild
    terserOptions: { 
     mangle: {
      reserved: ['dc'] // here we set up variable we want to exclude //from naming
     }
    },
    rollupOptions: {
      // some other code
    },
  },
});

Let's break it down:

1. build: This section of the configuration is specific to the build process of Vite project. The settings within this block are applied when you build your project for production.

2. minify: 'terser', This line tells Vite to use the terser plugin for minification.

3. terserOptions: This part allows to specify custom options that will be passed to terser during the minification process

4. mangle: This is a specific option within terser.

5. reserved: ['dc'] Under the mangle option, this array reserved lists identifiers that should not be mangled. In this case, it's specifying that terser should not rename any variables or functions named dc during the minification process.

So after changing my vite.config.js, I’ve re-built the script and not found any more ‘dc’ variable there.

Conclusion

My example is related to Vite + Terser. However, it's just an example, so if you are using other tools to build your applications, libraries, and scripts, you may employ a similar strategy to handle such conflicts.

By instructing the compiler not to use specific names during the mangling process, you effectively prevent it from creating name clashes with other variables or libraries. This method is much safer and more reliable than manually renaming variables in the already minified code, which could indeed lead to further errors and issues. Your solution shows an understanding of how to handle potential conflicts in a controlled and systematic way.

Thanks for you attention and happy coding!

P.S. Subscribe for more interesting and useful posts about web development (especially if you are curious in Laravel and Vue.js).

I've encountered situations where a Single Page Application needs to be utilized as an embedded widget for integration into external websites.

Let's assume that, as a default requirement, this widget should be versatile enough to be seamlessly integrated into any website, without imposing any specific conditions. This task presents several challenges. On one hand, the embedded widget must remain isolated and self-contained to achieve the desired visual aesthetics and workflow. On the other hand, it must ensure that it does not interfere with the styling of the parent site or disrupt any of the external site's functions.

In this article, I aim to provide a comprehensive, step-by-step guide on transforming a Single Page Application constructed with Vue.js 3 into a fully functional embedded widget.

In this particular context, an embedded widget refers to a compiled .js script that is incorporated into an external web page. It is specifically designated with a <custom tag> that serves as the entry point in the Document Object Model (DOM) for the widget elements, and this is where the SPA content will be rendered.

Let's jump into this concept with a practical example. Our objective is to create a countdown widget for tracking the time remaining until a specific date or event, for example start of the New Year or the end of discount campaigns or Black Friday time remaining counter. To implement this on an external website, it might appear as follows:

<html> 

<head> 

<script src="https://customdomain.com/countdown-widget.js"></script> 

</head> 

<body> 

<countdown-widget date="2024-01-01 00:00:00" title="Time until the New Year:"></countdown-widget> 

</body>
</html>

Let’s assume that we could use some attributes to put from the external part into the widget so we could use them in our internal logic behind the widget blackbox.

Important thing is that the content of our embedded widget will be covered by the Shadow Root. Consequently, all styles will be encapsulated inside the widget and isolated from the external site. This is a very secure way to keep the widget stable on one hand and ensure that it will not affect the external site's styles.

The Shadow Root is a crucial aspect of web development, providing a means to encapsulate and isolate the styles, structure, and functionality of a web component from the rest of the document. It acts as a container for a component's content, creating a shadow DOM subtree that shields the component's internals from external styles and scripts. By utilizing Shadow Root, developers can prevent unintended interference with or from the host document, fostering modularity and maintaining a clear separation between different components on a webpage. This encapsulation is particularly valuable for creating custom elements and widgets, offering a secure and well-defined environment for their implementation and interaction within a broader web context.

Our technology stack for this project includes:

• Vue.js 3

• Tailwind CSS

• Shadow Root

• Vite

• Custom Element API

Step-by-step guide from scratch

Vue.js 3 installation by Vite.

Let’s create initial Vue.js 3 application by Vite.

Vite is a build tool for modern web development that focuses on providing a fast development server with instant server start and optimized build times.

To get started with Vue.js 3, we'll need to follow a few steps. Before we begin, make sure we have Node.js and npm (Node Package Manager) installed on our system. It can be downloaded from the official website: Node.js.

Once we have Node.js and npm installed, we can proceed with creating a Vue.js 3 application.

Step 1: Install Vite

Let’s open terminal or command prompt and run the following command to install the Vue CLI globally:

npm install vite

Step 2: Create Vite

Let’s create a Vite instance using the following command:

npm install -g create-vite

In promt let’s choose project folder, Vue as framework and Javascript as language variant.

✔ Project name: … vuejs-embedded-widget

✔ Select a framework: › Vue

✔ Select a variant: › JavaScript

Step 3: Navigate to the Project Directory

Now let’s change our working directory to the newly created project:

cd vuejs-embedded-widget

Step 4: Run npm install

Let’s make initial of project packages from package.json:

npm install

Step 5: Run application to test the installation

npm run dev

We may see in promt something like that:

  VITE v5.0.7  ready in 331 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

After running the development server, we will be able to check our initial installation of Vue.js 3 at http://localhost:5173 (or any other available port provided by the command).

Configuring Tailwind CSS in Vue.js 3

To install Tailwind CSS in our project, we will follow these steps. We already have a project set up, so we can integrate Tailwind CSS as follows:

Step 1: Install Tailwind CSS and its Dependencies

npm install -D tailwindcss postcss autoprefixer

Step 2: Create Tailwind Configuration Files

npx tailwindcss init -p

We may see in promt:

Created Tailwind CSS config file: tailwind.config.js
Created PostCSS config file: postcss.config.js

So as a result of this command will be created 2 important files in root of our project:

• Tailwind CSS config file: tailwind.config.js

• PostCSS config file: postcss.config.js

tailwindcss.config.js we will configure in further chapters as it eventually turns to be important for customization to solve the issue with responsive design for our embedded widget.

postcss.config.js we will update in next step.

Step 3: Configure tailwind.config.js

Let’s adjust tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./index.html",
    "./src/**/*.{vue,js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Step 4: Configure postcss.config.js

Let’s open the postcss.config.js file and configure it to use Tailwind CSS and autoprefixer. Let’s update the file to look like this:

module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  }
}

Step 4: Create CSS File

Now we need to create a new CSS file, for example, src/assets/styles/main.css, and import Tailwind CSS styles:

/* src/assets/styles/main.css */

@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';

Step 5: Import CSS

Let’s import the CSS file we just created into our main application file - src/main.js:

// src/main.js

import Vue from 'vue';
import App from './App.vue';
import './assets/styles/main.css';

Vue.config.productionTip = false;

new Vue({
  render: h => h(App),
}).$mount('#app');

That's it! We've successfully installed Tailwind CSS in our project.

By the way, if you are new to Tailwind CSS, you can find more detailed information about this framework, including use cases, implementation, and installation, in the official Tailwind CSS documentation for additional details and customization options.

Develop our Vue.js 3 Single Page Application

Let's now develop our functionality (Countdown till a given date/time) before jumping into the main topic of this article: transforming a simple Vue.js 3 app into an embedded widget script.

Step 1: Create a component for Countdown

Let’s create a component src/components/Countdown.vue and put there a logic.

<template>
    <div class="text-center mt-2" :style="{ color: textColor }">
        
        <div v-if="countdownDateIsInvalid === true">
            :date property is invalid. Should be dateString in correct format.
        </div>

        <!-- Display a message when the countdown has expired -->
        <div v-if="countdownExpired && end !== null" class="text-2xl">
            <p>{{ end }}</p>
        </div>
        <!-- Display the countdown when it's still active -->
        <div v-else>
            <p class="text-4xl font-bold">
                {{ title }}
            </p>
            <!-- Display the countdown in days, hours, minutes, and seconds -->
            <p class="text-3xl font-bold mt-2">
                <span>{{ countdown.days }} days </span>
                <span>{{ countdown.hours }} hours </span>
                <span>{{ countdown.minutes }} minutes </span>
                <span>{{ countdown.seconds }} seconds </span>
            </p>
        </div>
    </div>
</template>

<script setup>
    // Import required functions from Vue
    import { ref, defineProps } from 'vue';

    // Define props for the component
    const props = defineProps({
        date: {
            type: String,
            required: true
        },
        title: {
            type: String,
            required: true
        },
        end: {
            type: String,
            required: true
        },
        color: {
            type: String,
            required: true
        }
    });

    // Calculate the timestamp for the countdown end date
    const countdownDate = ref(new Date(props.date).getTime());

    const countdownDateIsInvalid = isNaN(countdownDate.value);

    // Initialize the countdown values
    const countdown = ref({
        days: 0,
        hours: 0,
        minutes: 0,
        seconds: 0
    });

    // Track whether the countdown has expired
    const countdownExpired = ref(false);

    // Determine the text color based on the provided prop or default to black
    const textColor = props.color || 'black';

    // Update the countdown values every second
    // setInterval schedules repeated execution every delayed value (1000 ms = 1 second)
    setInterval(() => {
        // Get the current timestamp
        const now = new Date().getTime();

        // Calculate the remaining time in milliseconds
        const distance = countdownDate.value - now;

        // Check if the countdown has expired
        if (distance <= 0) {
            countdownExpired.value = true;
            return;
        }

        // Calculate days, hours, minutes, and seconds
        countdown.value.days = Math.floor(distance / (1000 * 60 * 60 * 24));
        countdown.value.hours = Math.floor((distance % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
        countdown.value.minutes = Math.floor((distance % (1000 * 60 * 60)) / (1000 * 60));
        countdown.value.seconds = Math.floor((distance % (1000 * 60)) / 1000);
    }, 1000);

</script>

Step 2: Add component to App.vue

Let’s add component to App.vue with necessary properties needed to our Countdown widget.

<template>
  <CountDown 
      :date="props.date"
      :title="props.title"
      :end="props.end" 
      :color="props.color" />
</template>

<script setup>
  import CountDown from "@/components/CountDown.vue";

  // Import required functions from Vue
  import {  defineProps } from 'vue';

  // Define props for the component
  const props = defineProps({
      date: {
          type: String,
          required: true
      },
      title: {
          type: String,
          required: true
      },
      end: {
          type: String,
          required: false,
          defaut: 'Countdown is end.'
      },
      color: {
          type: String,
          required: false,
          default: '#FF0000'
      }
  });
</script>

Now, our SPA is ready and provided countdown logic.

Step 3: Run the application to check results

Let’s run application to check results and test our countdown logic. Run in console a command to serve application in development mode:

npm run serve

If you give development host in browser, it will look like:

Turn SPA to Embedded Widget

Here we are in the main part of this topic. Now let’s convert an SPA to an embedded widget so that we have a compiled .js script ready to be implemented on external sites.

The significant magic point here is to use Custom Elements API.

The Custom Elements API is a part of the web platform and is related to JavaScript, HTML, and web development in general. It is a standard web API that is not specific to any particular JavaScript framework or library, including Vue.js.

The Custom Elements API is a browser feature that allows developers to define and use their own custom HTML elements with encapsulated behavior. It enables you to create reusable components and extend the set of available HTML elements, making it easier to build modular and maintainable web applications.

Let’s create a bootstrap.js file in our /src folder. In this file, there will be logic to mount our app into the expected DOM element (which is the target argument). This element will be from a widget tag on the external site (<countdown-widget> in our case).

Step 1: Create bootstrap.js

import { createApp } from 'vue';
import App from './App.vue';

// Function to bootstrap and mount the Vue.js application
export function bootstrap(target, attributes) {

    // Create a new Vue application instance
    // second argument is object of attributes that will be 
    // converted to properites in App.vue
    const app = createApp(App, attributes)
    
     // Mount the Vue application onto the specified target element
    app.mount(target);
}

Step 2: Make custom element in main.js

Let’s then use our bootstrap function in main.js and use Custom Element API to turn to embedded widget.

// Import the bootstrap function from the 'bootstrap.js' file
import { bootstrap } from './bootstrap.js';

// Define a custom element 'countdown-widget' using the Custom Elements API
customElements.define('countdown-widget', class extends HTMLElement {
 
  async connectedCallback() {

    // Create a shadow DOM for encapsulatio
    const shadowRoot = this.attachShadow({ mode: 'open' });

    // Fetch <countdown-widget> attributes 
    // to pass as properties for App.vue

    const attributes = {
      'date': this.getAttribute('date'),
      'title': this.getAttribute('title'),
      'end': this.getAttribute('end'),
      'color': this.getAttribute('color')
    }
    
    // Bootstrap the Vue.js application within the shadow DOM
    bootstrap(shadowRoot, attributes);
  }
});

Step 3: Configure vite.config.js

Let’s configure vite.config.js to compile necessary files: .js file for script to include in external site and .css file to apply styles inside our application to be used in Shadow Root.

import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue(),
  ],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  build: {
    rollupOptions: {
      input: {
        widget: fileURLToPath(new URL('./src/main.js', import.meta.url)),
        style: './src/assets/styles/main.css'
      },
      output: {
        inlineDynamicImports: false,
        entryFileNames: '[name].js',      
        chunkFileNames: '[name].js',      
        assetFileNames: '[name].[ext]'
    },
  }
})

Step 4: Adjust package.json

Let’s check package.json file. Check if there is a property:

  "type": "module",

If yes, then let’s change it to:

  "type": "commonjs",

Step 5: Compile widget files

Let’s compile widget files (.js and .css) which will be outputed in /dist folder.

npx vite dist

In folder /dist we may find 2 files:

• widget.js

• style.css

In promt we may see:

  VITE v5.0.7  ready in 209 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

If we go to http://localhost:5173/widget.js, we can see the compiled, minified JavaScript code.

But let's transition from development mode to a configured host and production build so that we can thoroughly test the entire solution and deploy it on an external site. Consequently, we require a stable production build for our widget, ensuring that widget.js is accessible through a dedicated host.

Step 6: Configure virtual host

Let’s configure virtual host (in this example, it will be Nginx).

Find more here how to deal with it if you are new in Nginx.

This file will be somewhere in /etc/nginx/sites-available:

                                                                                        server {
     listen 80;

     root /var/www/vuejs-embedded-widget/dist;

     server_name vuejs-embedded-widget;

     location / {
             try_files $uri $uri/ /index.html?$query_string;
     }
}

We may also need to add the "vue-js-embedded-widget" host to our local hosts list (while we are on a local server). You can find it in /etc/hosts. Add the following entry:

127.0.0.1       vuejs-embedded-widget

We also need to make symlink from /etc/nginx/sites-available/vuejs-embedded-widget.conf to /etc/nginx/sites-enabled.

sudo ln -s /etc/nginx/sites-available/your_domain /etc/nginx/sites-enabled/

Let’s restart nginx server:

sudo service nginx restart

Step 7: Make build

Let’s make a build to compile widget.js and style.css and to have them available by our virtual host:

npx vite build 

Now we are able to reach compiled widget files:

• http://vuejs-embedded-widget/widget.js

• http://vuejs-embedded-widget/style.css

Step 8: Link compiled style.css to Shadow Root

Let's include our compiled style.css directly into the App.vue template using the <link> attribute. This implies that our App.vue will be within the Shadow Root, resulting in the inclusion of style.css inside the Shadow Root.

Consequently, CSS styles from style.css will be applied to the widget's DOM content.

<template>
  <!--Link to compiled style.css-->
  <link rel="stylesheet" href="http://vuejs-embedded-widget/style.css">

  <CountDown 
      :date="props.date"
      :title="props.title"
      :end="props.end" 
      :color="props.color" />
</template>

<script setup>
  import CountDown from "@/components/CountDown.vue";

  // Import required functions from Vue
  import {  defineProps } from 'vue';

  // Define props for the component
  const props = defineProps({
      date: {
          type: String,
          required: true
      },
      title: {
          type: String,
          required: true
      },
      end: {
          type: String,
          required: false,
          defaut: 'Countdown is end.'
      },
      color: {
          type: String,
          required: false,
          default: '#FF0000'
      }
  });
</script>

Step 9: Re-compile files with new build to apply changes in App.vue

npx vite build

That’s all!

Now that we have widget.js, we can implement our Countdown widget to render on any website without dependencies on the website's tech stack.

Implement widget in external site

Let's assume that we are still on a local environment, so we will use http://vuejs-embedded-widget (as configured in the previous step). And, of course, the site where it will be implemented should also be on a local server in this case.

Step 1: Add widget.js to site <head>

<head>

<script src="http://vuejs-embedded-widget/widget.js" async></script>

</head>

Step 2: Put widget tag inside <body></body>

Let’s put <countdown-widget></countdown-widget> with necessary attributes in external site body in place where it should be rendered:

<countdown-widget 
   date="2024-06-14" 
   title="Euro 2024 will start in"
   end="Euro 2024 is started!"
   color="#FF0000">
</countdown-widget>

And now it works!

We may find inside DOM of the external site where the widget is embedded how it’s rendered with #shadow-root block:

Conclusion

This tutorial describes the concept of using Vue.js 3 SPA as an embedded widget. It provides a simple example of Countdown functionality, but it can also be applied to more complex Vue.js applications involving APIs, Axios, Store management, etc.

An important aspect is the utilization of the Shadow Root, which serves as an effective means to deliver embedded components for use in external sites without the need for an <iframe>.

I will continue this topic in the next article and use this project as a base to cover some other issues related to building embedded widgets with Vue.js. For example, I'll show how to make it mobile-friendly, as we need to define the size on the parent block where the widget is embedded, not based on the size of the screen. Additionally, I will explain how to adjust the Tailwind theme configuration to correctly reflect the size definition.

You may find repository with code covered in this article on Labro Dev Github.

Thanks for reading this article, and I hope it was helpful for you. Please subscribe to the Labro Dev Substack, where our Labro Dev team will continue to share our experiences related to web development, with a focus on Laravel and Vue.js.

Subscribe now