DEV Community: Demian Kostelny

Laravel & Design Patterns — Practice Series: Builder

Demian Kostelny — Thu, 10 Sep 2026 16:00:00 +0000

I was tired of seeing how many articles repeat, again and again, basic examples of using design patterns in development; examples based on shape figures/real-life objects are good for understanding when you are just starting to learn this concept of design patterns. But what about real practice? What about real examples with real code and frameworks to get a much better practical understanding and use?

And this is the reason why I decided to start writing a series of articles about full practice in the Laravel framework. Even if you’re not a PHP developer and you have some medium-level experience in web development, you can still understand what we are going to do and use it in your own development.

Builder pattern: Introduction

It was a good decision to start this series with one of the simplest patterns, named “builder,” from the creational patterns. Let’s begin with some graphical examples to remember how it works, and after that, let’s move on to writing some code for generating reports in different file formats.

Let’s begin with a definition:

The Builder design pattern is a creational pattern that separates the construction of a complex object from its representation, allowing the same construction process to create different representations. It is especially useful when an object needs to be created with many optional parts or configurations.

Real-life example

A simple real-life example of the Builder Pattern is how you order a burger at a fast-food restaurant:

Instead of giving you only fixed menu items, the restaurant lets you customize your burger.
You can add a patty, cheese, lettuce, tomato, sauces, bacon, etc., in the order you like.
The builder (the person assembling) constructs the burger step by step.
At the end, you get a fully built burger according to your specifications.

🥩 + 🧀 + 🥬 + 🍅 + 🍞 ➝ 🍔

UML Representation

Now, let’s take a quick look at the abstract UML schema to understand how we should build our classes' interactions:

Here is an explanation of how this UML schema works:

Everything begins with the interface IBuilder, which defines a typical build() method that will be used in the concrete class implementation for building the final class object
Next, what comes after this is ObjectBuilder, a class with a concrete implementation of how a class object can be built. There can be different methods, not only the concrete implementation of the build() method
TargetObject — is the final product of the object that we will get from our builder
And if we want, we can extend our builder and have a lot of OtherObject

This abstraction gives to use power for encapsulation of object creation in our builder, which makes your Laravel code cleaner, modular, and easier to extend or modify.

Let’s now take a look at a more concrete UML implementation, and after that, we are going to begin using this design pattern in the app:

I hope that this picture will give you more understanding of how the builder pattern works, and that’s what we are going to do now: we are going to use this pattern to create a report creation solution. Let’s begin.

Implementation

First, take a look at how our structure will be organized:

app/
└── Services/
    └── Report/
        ├── Builders/
        │   ├── IReportBuilder.php
        │   ├── ReportBuilder.php
        ├── Formats/
        │   ├── Formatter.php
        │   ├── PDFReport.php
        │   ├── JSONReport.php
        └── ReportService.php

Of course, if you want, you can follow DDD (Domain-Driven-Design) pattern, and then your structure will look like this:

app/
└── Domains/
    └── Report/
        ├── Builders/
        │   ├── IReportBuilder.php # Our interface
        │   ├── ReportBuilder.php
        ├── Formats/
        │   ├── Formatter.php
        │   ├── PDFReport.php
        │   ├── JSONReport.php
        └── Report.php

When we get the full picture of how our structure will look, we can start building and create a report entity in Report.php:

<?php

namespace App\Domains\Report\Entities;

class Report
{
    public function __construct(
        public string $title = '',
        public ?array $period = null,
        public array $rows = [],
        public array $totals = []
    ) {}

    public function toArray(): array
    {
        return [
            'title' => $this->title,
            'period' => $this->period,
            'rows' => $this->rows,
            'totals' => $this->totals
        ];
    }
}

Next, let’s define our interface IBuilderInterface that will be used for our report builder:

<?php

namespace App\Domains\Report\Builders;

use App\Domains\Report\Entities\Report;
use App\Domains\Report\Formats\Formatter;

interface IReportBuilder
{
    public function reset(): static;

    public function setTitle(string $title): static;

    public function setPeriod(?array $period): static;

    public function setRows(array $rows): static;

    public function addRow(array $row): static;

    public function setTotals(array $totals): static;

    public function setFormatter(Formatter $formatter): static;

    public function getReport(): Report;

    public function build();
}

Okay, now we need to define the Formatter interface that will be used for our Format classes:

<?php

namespace App\Domains\Report\Formats;

use App\Domains\Report\Entities\Report;

interface Formatter
{
    public function render(Report $report);
}

After this, let’s create our first format class — and it will be JsonReport:

<?php

namespace App\Domains\Report\Formats;

use App\Domains\Report\Formats\Formatter;
use App\Domains\Report\Entities\Report;

class JsonReport implements Formatter
{
    public function render(Report $report)
    {
        return response()
            ->json($report->toArray());
    }
}

And let’s also add another class that will be used to create a report in XML format:

<?php

namespace App\Domains\Report\Formats;

use App\Domains\Report\Entities\Report;

class XMLReport implements Formatter
{
    public function render(Report $report)
    {
        $xml = new \SimpleXMLElement('<?xml version="1.0" encoding="UTF-8"?><report></report>');

        $xml->addChild('title', $report->title);

        if ($report->period) {
            $periodNode = $xml->addChild('period');
            $periodNode->addChild('from', $report->period['from'] ?? '');
            $periodNode->addChild('to', $report->period['to'] ?? '');
        }

        $rowsNode = $xml->addChild('rows');
        foreach ($report->rows as $row) {
            $rowNode = $rowsNode->addChild('row');
            foreach ($row as $key => $val) {
                $rowNode->addChild($key, htmlspecialchars((string) $val));
            }
        }

        if (!empty($report->totals)) {
            $totalsNode = $xml->addChild('totals');
            foreach ($report->totals as $key => $val) {
                $totalsNode->addChild($key, (string) $val);
            }
        }

        return response($xml->asXML(), 200, [
            'Content-Type' => 'application/xml',
        ]);
    }
}

Amazing, and the main class that will be used to build the report following the Builder pattern — this is ReportBuilder:

<?php

namespace App\Domains\Report\Builders;

use App\Domains\Report\Builders\IReportBuilder;
use App\Domains\Report\Entities\Report;
use App\Domains\Report\Formats\Formatter;

class ReportBuilder implements IReportBuilder
{
    protected Report $report;

    protected ?Formatter $formatter = null;

    public function __construct()
    {
        $this->reset();
    }

    public function reset(): static
    {
        $this->report = new Report();
        return $this;
    }

    public function setTitle(string $title): static
    {
        $this->report->title = $title;
        return $this;
    }

    public function setPeriod(?array $period): static
    {
        $this->report->period = $period;
        return $this;
    }

    public function setRows(array $rows): static
    {
        $this->report->rows = $rows;
        return $this;
    }

    public function addRow(array $row): static
    {
        $this->report->rows[] = $row;
        return $this;
    }

    public function setTotals(array $totals): static
    {
        $this->report->totals = $totals;
        return $this;
    }

    public function setFormatter(Formatter $formatter): static
    {
        $this->formatter = $formatter;
        return $this;
    }

    public function getReport(): Report
    {
        return $this->report;
    }

    public function build()
    {
        $response = $this->formatter->render($this->report);
        $this->reset();

        return $response;
    }
}

Before we are going to test how it works in the controller, we also need to register in the container our IBuilderInterface with the ReportBuilder class in app/Providers/AppServiceProvider.php:

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Domains\Report\Builders\IReportBuilder;
use App\Domains\Report\Builders\ReportBuilder;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     */
    public function register(): void
    {
        $this->app->bind(IReportBuilder::class, ReportBuilder::class);
    }

    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        // ...
    }
}

Almost done; now we should create a new controller — ReportController:

$ php artisan make:controller ReportController

Finally, let’s use our ReportBuilder to create a JSON report:

<?php

namespace App\Http\Controllers;

use App\Domains\Report\Builders\ReportBuilder;
use App\Domains\Report\Formats\JsonReport;
use App\Domains\Report\Formats\XMLReport;
use Illuminate\Http\Request;

class ReportController extends Controller
{
    public function __construct(
        private ReportBuilder $reportBuilder
    ) {}

    public function getReport(Request $request, string $type)
    {
        $rows = [
            ['date' => '2025-08-01', 'orders' => 12, 'revenue' => 3400],
            ['date' => '2025-08-02', 'orders' => 9,  'revenue' => 2210],
        ];

        $totals = [
            'orders'  => array_sum(array_column($rows, 'orders')),
            'revenue' => array_sum(array_column($rows, 'revenue')),
        ];

        $period = ['from' => '2025-08-01', 'to' => '2025-08-02'];

        $formats = [
            'json' => JsonReport::class,
            'xml' => XMLReport::class,
        ];

        // Get selected formatter
        $formatter = app()->make($formats[$type]);

        $report = $this->reportBuilder
            ->reset()
            ->setTitle('JSON Report')
            ->setPeriod($period)
            ->setRows($rows)
            ->setTotals($totals)
            ->setFormatter($formatter)
            ->build();

        return $report;
    }
}

So, we just created a flexible class to set all report data just by using special functions and following the Builder design pattern, and of course, we can easily select a format by creating separate classes that are responsible for report formats (remember about SOLID principles and try always to write your code clean).

Don’t forget also to include your report controller in routes/web.php to test how it works in the browser:

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\ReportController;


Route::get('/report/{type}', [ReportController::class, 'getReport']);

Conclusion

As we can see, it’s easy and nice to use this pattern in case if you want to create objects of some classes flexibly and easily customizable. Laravel has a lot of internal classes that use this pattern for object creation (for example, DB, Mailable, and Http).

In the next series, we are going to check other creational patterns with practical examples in Laravel. Thanks for reading!

Laravel & Design Patterns — Practice Series: Facade

Demian Kostelny — Wed, 09 Sep 2026 16:30:00 +0000

In this article, we are going to take a look at how to practically implement the most-used pattern in Laravel — the Facade pattern. So, as always, let’s begin with a definition.

Facade is a structural design pattern that provides a simplified interface to a library, a framework, or any other complex set of classes.

Just imagine that you have installed a custom mailing library into your application that requires object initialization and other function calls to send email. And instead of creating a library class object again and again, and calling all other tasks that you need for sending email, you just create a simple facade class where you will do all this stuff in one function, without the need to work with the library directly.

Introduction

For this article, we are going to install a real library just to demonstrate how you can use this pattern for such cases, so run the following command:

$ composer require league/flysystem

This is a great abstraction package for working with local or remote storage, and now let’s see a bad example without a facade implementation.

Bad example

Let’s imagine that we need to save a file in our controller to local and remote storage using this library in the controller called FileController:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use League\Flysystem\Local\LocalFilesystemAdapter;
use League\Flysystem\Filesystem;
use League\Flysystem\FileAttributes;
use Exception;

class FileController extends Controller
{
    public function createFileWithList(Request $request)
    {
        $path = __DIR__ . '/storage';
        $adapter = new LocalFilesystemAdapter($path);
        $filesystem = new Filesystem($adapter);

        // Save file into our local storage
        try {
            $filesystem->write(location: 'example.txt', contents: 'Lorem ipsum dolor sit amet.');
        } catch (Exception $e) {
            throw new Exception("Something went wrong with file upload: " . $e->getMessage());
        }

        // Get files list from storage
        $listing = $filesystem->listContents($path);

        foreach ($listing as $item) {
            $itemPath = $item->path();
            if ($item instanceof FileAttributes) {
                echo "File: $itemPath\n";
            } else if ($item instanceof DirectoryAttributes) {
                echo "Directory: $itemPath\n";
            }
        }
    }
}

As you can see here, we do a lot of different imports and create two different objects to handle file upload and file listing, and also we do “try-catch” for the write function, and make another call to foreach all files and directories from our storage. In our case, each time we want to save a file, we will need to specify the storage path, create new class objects, and again call the write() function — that’s not good.

This is the case when we should use the Facade pattern to separate the library functionality that we need into a separate class that we are going to use for such cases.

Facade pattern implementation

Now it’s time to do everything correctly. First, create a new file in app/Facades/FileFacade.php — that will be our facade class that will be used for file upload with that library:

<?php

namespace App\Domains\Facades;

use League\Flysystem\Local\LocalFilesystemAdapter;
use League\Flysystem\Filesystem;
use League\Flysystem\FileAttributes;
use Exception;

class FileFacade
{
    private $path;
    private LocalFilesystemAdapter $adapter;
    private Filesystem $filesystem;

    public function __construct()
    {
        $this->path = storage_path('app/files');
        $this->adapter = new LocalFilesystemAdapter($this->path);
        $this->filesystem = new Filesystem($this->adapter);
    }

    public function createFile($name, $content)
    {
        $this->filesystem->write(location: $name, contents: $content);
    }

    public function getFilesList()
    {
        $listing = $this->filesystem->listContents($this->path);

        foreach ($listing as $item) {
            $itemPath = $item->path();

            if ($item instanceof FileAttributes) {
                echo "File: $itemPath\n";
            } else if ($item instanceof DirectoryAttributes) {
                echo "Directory: $itemPath\n";
            }
        }
    }
}

Pay attention that for each operation we created a separate function, so in the future we can easily reuse it in our codebase. Now it’s time to rewrite FileController in the right way by using the facade that we just created:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Domains\Facades\FileFacade;

class FileController extends Controller
{
    public function __construct(
        private FileFacade $fileFacade
    ) {}

    public function createFileWithList(Request $request)
    {
        // also we can provide values from $request for this function
        $this->fileFacade->createFile('test.txt', 'my super file');
        $this->fileFacade->getFilesList();
    }
}

Don’t forget to add an endpoint for this controller in your routes/web.php:

<?php

use App\Http\Controllers\FileController;
use Illuminate\Support\Facades\Route;

Route::get('/file/create', [FileController::class, 'createFileWithList']);

Visit this page and check the storage/app/files folder — and you will see that the file was created, which means that our implementation is working properly. We separated our controller from direct interaction with the library and also removed the dependency on the library — that’s a good approach.

Inside Laravel examples

Now that you have understood what the facade pattern is and how it can be used in development, let’s see some examples of Laravel classes that are being used frequently by developers. First example — Http facade:

<?php

namespace App\Domains\Facades;

use Illuminate\Support\Facades\Http;

class GetPostsCommand
{
    private $api = 'https://jsonplaceholder.typicode.com/';

    public function execute()
    {
        $response = Http::get($this->api.'/posts');

        return $response->getBody();
    }
}

Basically, we just did a GET HTTP request using the get() function from the Http facade, and the most interesting thing is that Laravel, in the Http class, is using the Guzzle HTTP library, and to make use of this class easier and simpler, it’s using the facade pattern.

And that’s not the only example of Laravel classes that use this pattern; all classes that are in the Illuminate\Support\Facades namespace are classes with implemented Facade pattern.

Conclusion

This was a simple but practical example of how to use Facade in your Laravel application, pretty easy and nice, which makes your code cleaner and easier for modifications.

Laravel & Design Patterns — Practice Series: Adapter

Demian Kostelny — Fri, 28 Aug 2026 16:30:00 +0000

Welcome back. This is the next article in our practical use of patterns in Laravel, and in this guide, we are going to talk about one of the most popular patterns that is used by many developers — the Adapter pattern.

Introduction

Let’s begin with the definition of Adapter:

Adapter pattern is a structural design pattern that allows objects with incompatible interfaces to work together by translating one interface into another that a client expects.

Real-world example

Imagine that you’re traveling from the US to the EU, and when you arrive at your hotel, you find out that in the EU, people use a different type of socket to use their electronic devices. And to solve this problem, you buy a socket adapter to easily charge your devices with your US plug.

Bad example (anti-pattern)

First, let’s see what a bad solution looks like without using any adapter classes and without any clean code architecture:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Stripe\StripeClient;
use Square\SquareClient;
use Square\Models\Money;
use Square\Models\CreatePaymentRequest;

class BadCheckoutController extends Controller
{
    public function store(Request $request)
    {
        // We get a lot of data from $request without any processing, which can create
        // a lot of issues in the future for transactions processing
        $gateway = $request->string('gateway');
        $amount  = (float) $request->input('amount');
        $currency = $request->input('currency', 'USD');
        $pm = $request->string('payment_method');

        // Another bad practice - is to use conditions for creating new class objects with hardcoded actions
        if ($gateway === 'stripe') {
            $stripe = new StripeClient(config('services.stripe.secret'));

            $intent = $stripe->paymentIntents->create([
                'amount' => (int) round($amount),
                'currency' => strtolower($currency),
                'payment_method' => $pm,
                'confirm' => true,
                'description' => $request->input('description', 'Order #'.now()->timestamp),
            ]);


            if ($intent->status !== 'succeeded') {
                return back()->withErrors(['payment' => 'Stripe failed: '.$intent->status]);
            }

            // All this business logic in controller will create another issues
            return redirect()->route('thankyou')->with('tx', $intent->id);
        } elseif ($gateway === 'square') {
            $square = new SquareClient([
                'accessToken' => config('services.square.access_token'),
                'environment' => config('services.square.environment', 'sandbox'),
            ]);

            $paymentsApi = $square->getPaymentsApi();

            $money = new Money();
            $money->setAmount((int) ($amount * 100.0));
            $money->setCurrency(strtoupper($currency));

            $requestObj = new CreatePaymentRequest(
                sourceId: $pm,
                idempotencyKey: (string) rand(),
                amountMoney: $money
            );

            try {
                $response = $paymentsApi->createPayment($requestObj);
                if ($response->isSuccess()) {
                    $payment = $response->getResult()->getPayment();
                    if ($payment->getStatus() !== 'COMPLETED') {
                        return back()->withErrors(['payment' => 'Square not completed: '.$payment->getStatus()]);
                    }
                    return redirect()->route('thankyou')->with('tx', $payment->getId());
                }

                $errs = collect($response->getErrors() ?? [])->map(fn($e) => $e->getDetail() ?: 'error')->implode('; ');
                return back()->withErrors(['payment' => 'Square failed: '.$errs]);
            } catch (\Throwable $e) {
                return back()->withErrors(['payment' => 'Square error: '.$e->getMessage()]);
            }

            return back()->withErrors(['payment' => 'Unknown gateway']);
        }
    }
}

Looks horrible 0.0 Now it’s time to separate all logic properly with best practices, and to solve it — we are going to use the Adapter pattern.

Adapter pattern implementation

First of all, we need to define an interface that will be used by our adapter classes to properly handle different payment systems with the same function:

<?php

namespace App\Domains\Payment;

interface PaymentGateawayInterface
{
    public function charge(
        int $amount,
        string $currency,
        string $source,
        string $description = ''       
    );
}

Also, don’t forget to install the payment library with Composer into the Laravel project:

$ composer require stripe/stripe-php

After dependencies are installed, we also need to define a class where we are going to store transaction results

<?php

namespace App\Domains\Payment;

class ChargeResult
{
    public function __construct(
        public bool $success,
        public string $transactionId,
        public string $message,
    ) {}
}

Now that the main components are defined, it’s time to create our first adapter to handle Stripe transactions:

<?php

namespace App\Domains\Payment;

use Stripe\StripeClient;
use Exception;

class StripeGateawayAdapter implements PaymentGateawayInterface
{
    // We use dependency injection to properly handle
    // object creation from the framework side
    public function __construct(
        private StripeClient $client
    ) {}

    public function charge(
        int $amount,
        string $currency,
        string $source,
        string $description = ''
    ) {
        try {
            $response = $this->client->paymentIntents->create([
                'amount' => $amount,
                'currency' => $currency,
                'payment_method' => $source,
                'confirm' => true,
                'description' => $description
            ]);

            return new ChargeResult(
                success: $response->status === 'succeeded',
                transactionId: $response->id,
                message: $response->status
            );
        } catch( Exception $e ) {
            return new ChargeResult(
                success: false,
                transactionId: null,
                message: $e->getMessage()
            );
        }
    }
}

But that's not the only adapter class that we need to create; we will also create an adapter to handle Square payment system transactions:

<?php

namespace App\Domains\Payment;

use Exception;
use Square\Payments\Requests\CreatePaymentRequest;
use Square\Legacy\Models\Money;
use Square\SquareClient;
use Illuminate\Support\Str;

class SquareGateawayAdapter implements PaymentGateawayInterface
{
    public function __construct(
        private SquareClient $client
    ) {}

    public function charge(
        int $amount,
        string $currency,
        string $source,
        string $description = ''
    ) {
        $money = new Money();
        $money->setAmount($amount);
        $money->setCurrency(strtoupper($currency));

        $request = new CreatePaymentRequest([
            'idempotencyKey' => Str::uuid()->toString(),
            'sourceId' => $source,
            'amountMoney' => $money
        ]);

        if ($description !== '') {
            $request->setNote($description);
        }

        try {
            $response = $this->client->payments->create(
                $request
            );

            if ( $response->getPayment() ) {
                // ... return success here
            }
        } catch ( Exception $e ) {
            return new ChargeResult(
                success: false,
                transactionId: null,
                message: $e->getMessage(),
            );
        }
    }
}

That looks much better now with using adapters; our code is now cleaner, readable, and we follow SOLID principles with OOP. And of course, if we are using any interface in the Laravel framework, we also need to bind it properly in the AppServiceProvider.php:

<?php

namespace App\Providers;

use App\Domains\Payment\PaymentGateawayInterface;
use App\Domains\Payment\SquareGateawayAdapter;
use App\Domains\Payment\StripeGateawayAdapter;
use Illuminate\Support\ServiceProvider;
use App\Domains\Report\Builders\IReportBuilder;
use App\Domains\Report\Builders\ReportBuilder;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     */
    public function register(): void
    {
        $this->app->bind(PaymentGateawayInterface::class, StripeGateawayAdapter::class);
        $this->app->bind(PaymentGateawayInterface::class, SquareGateawayAdapter::class);
    }

    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        //
    }
}

Amazing, now we can easily use it in our controllers:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Domains\Payment\StripeGateawayAdapter;
use App\Domains\Payment\SquareGateawayAdapter;
use App\Domains\Payment\PaymentGateawayInterface;
use Stripe\StripeClient;
use Square\SquareClient;


class CheckoutController extends Controller
{
    private PaymentGateawayInterface $gateway;

    public function __construct()
    {
        // We will have config for all payments
        $driver = config('payments.driver', 'stripe');

        // Dynamically switch gateaway payment based on config
        // we can also move this code to service file
        $this->gateway = match ($driver) {
            'stripe' => new StripeGateawayAdapter(
                new StripeClient(config('services.stripe.secret'))
            ),
            'square' => new SquareGateawayAdapter(
                new SquareClient([
                    'accessToken' => config('services.square.access_token'),
                    'environment' => config('services.square.environment'),
                ])
            ),
            default => throw new \RuntimeException("Unknown payment driver [$driver]"),
        };
    }

    public function store(Request $request)
    {
        $result = $this->gateway->charge(
            (int) ($request->input('amount') * 100),
            $request->input('currency', 'USD'),
            $request->input('payment_method'),
            'Order #' . now()->timestamp
        );

        if (! $result->success) {
            return back()->withErrors(['payment' => $result->message]);
        }

        return redirect()
            ->route('thankyou')
            ->with('tx', $result->transactionId);
    }
}

Conclusion

Now our code is much cleaner and readable, and of course, we follow SOLID principles. Remember, in cases when you have any external library or classes that are not compatible with your interface, you can use the Adapter pattern to easily implement them into your code and separate all logic properly. Thanks for reading!

Laravel & Design Patterns - Practice Series: Proxy

Demian Kostelny — Mon, 24 Aug 2026 16:00:00 +0000

Welcome back, and this is the third article of the patterns series. We are going to implement a practical structural design pattern — Proxy. So, let’s begin with the theoretical part.

Introduction

First, let’s see what the definition of the Proxy pattern can tell us:

Proxy is a structural design pattern that lets you provide a substitute or placeholder for another object. A proxy controls access to the original object, allowing you to perform something either before or after the request gets through to the original object.

And let’s check the UML schema to visualize how it’s working:

Example of a problem

Imagine that you have a database with a lot of different financial data, and in your application, you make a lot of the same requests to receive data that consumes a large amount of resources. In this case, it will be good to implement caching for some requests that fetch data that is rarely changed.

Implementation

To solve this, we can implement some kind of class that will always be requested before proceeding to the original class that we need — you can imagine that like a guard that does a check. Let’s continue our example, and let’s imagine that we want to have a Redis caching for posts in our application, and instead of always making requests to the database — we can cache this data for 12 hours and retrieve it — and to handle this, we are going to use the Proxy pattern as was mentioned before. So first, let’s create our simple Post model that will be used in the service class later:

<?php

namespace App\Models\Post;

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
  protected $fillable = ['title', 'content'];
}

Next, we need to have an actual service to retrieve posts from the database:

<?php

namespace App\Services;

use App\Models\Post;
use Illuminate\Support\Collection;

class PostService
{
  public function find(int $id): ?Post
  {
    return Post::find($id);
  }

  public function latest(int $limit = 10): Collection
  {
    return Post::latest()->limit($limit)->get();
  }
}

And finally — PostCache class — that will be our Proxy for caching or getting actual data from the database if we don’t have cached data:

<?php

namespace App\Cache;

use App\Services\PostService;
use App\Models\Post;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Collection;

class PostCache
{
  public function __construct(
    private PostService $service
  ) {}

  public function find(int $id): ?Post
  {
    // As you can see, when there is no cached post
    // we request again actual data from service
    return Cache::remember(
      "posts:{$id}",
      now()->addMinutes(10),
      fn () => $this->service->find($id)
    );
  }

  public function latest(int $limit = 10): Collection
  {
    return Cache::remember(
      "posts:latest:{$limit}",
      now()->addMinutes(5),
      fn () => $this->service->latest($limit)
    );
  }

  public function forgot(int $id): void
  {
    Cache::forget("posts:{$id}");
    Cache::forget("posts:latest:*");
  }
}

And finally, let’s create a controller to use it:

<?php

namespace App\Http\Controllers;

use App\Cache\PostCache;

class PostController
{
  public function __construct(
    private PostCache $cache
  ) {}

  public function index()
  {
    $posts = $postCache->latest();
    return response()->json($posts);
  }

  public function show(int $id)
  {
    $post = $postCache->find($id);
    return response()->json($post);
  }
}

Conclusion

As you can see, it’s pretty easy to use the proxy pattern, and it’s very useful when you want to use it in caching to implement it with the cache-aside pattern with Redis or Memcached.

Self-hosted CI/CD deployments with Forgejo Runner

Demian Kostelny — Fri, 21 Aug 2026 20:00:00 +0000

Have you ever heard that you can easily set up a fully self-hosted CI/CD pipeline with a fully customized personal git instance? If your answer is no and you're interested in learning how to set it up quickly, then this article is for you. And of course, if you're a person who cares about privacy, this tutorial could help you expand your toolkit for Git.

As always, we will begin by learning all the basics about Forgejo and the base features that are provided by this open-source self-hosted Git instance (or even better, call it a GitHub analog).

Introduction: What is Forgejo and how to set up your instance fast?

Previously, I already published a starter guide on how you can quickly set up a self-hosted Forgejo instance with privacy-friendly settings. In this guide, we are going to follow the same steps, but it will be more expanded, as we will run more containers to support self-hosted CI/CD pipelines.

But first, let me answer the fundamental question: what is Forgejo? Briefly, Forgejo is a fully self-hosted Git application like Bitbucket, GitLab, or GitHub. The difference is that you control all the data and you can do whatever you want. A lot of teams use solutions like that for their internal Git system to protect code from breaches, AI, or just for privacy concerns.

Fast setup with Docker

Of course, you can set up Forgejo without Docker or Podman, but it will be much harder than using a solution with containers. We are going to begin by creating a new Docker Compose file (also don't forget to create a separate folder for your instance):

version: "3.8"

networks:
  forgejo:
    external: false

services:
  db:
    image: postgres:16-alpine
    container_name: forgejo_db
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./postgres:/var/lib/postgresql/data
    networks:
      - forgejo

  forgejo:
    image: codeberg.org/forgejo/forgejo:16
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=${POSTGRES_DB}
      - FORGEJO__database__USER=${POSTGRES_USER}
      - FORGEJO__database__PASSWD=${POSTGRES_PASSWORD}
      - FORGEJO__actions__ENABLED=true # this is important to enable CI/CD
    volumes:
      - ./forgejo:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "2222:22"
    depends_on:
      - db
    networks:
      - forgejo

  # And yes, we are going to run docker-in-docker (what a surprise!)
  docker-in-docker:
    image: docker:dind
    container_name: forgejo_dind
    privileged: true
    restart: unless-stopped
    command: ["dockerd", "-H", "tcp://0.0.0.0:2375", "--tls=false"]
    healthcheck:
      test: ["CMD", "docker", "-H", "tcp://127.0.0.1:2375", "info"]
      interval: 2s
      timeout: 5s
      retries: 15
    networks:
      - forgejo

  runner:
    image: data.forgejo.org/forgejo/runner:13
    container_name: forgejo_runner
    restart: unless-stopped
    depends_on:
      docker-in-docker:
        condition: service_healthy
      forgejo:
        condition: service_started
    environment:
      DOCKER_HOST: tcp://docker-in-docker:2375
    user: "1001:1001"
    volumes:
      - ./runner-data:/data
    networks:
      - forgejo
    command: forgejo-runner daemon --config /data/runner-config.yml

volumes:
  forgejo_db_data:_db_data:

I know what you're thinking after you saw that there will be a docker-in-docker container and you already are calling DevOps police, but let me explain this part briefly. Forgejo runner (container that will run CI/CD) can't run Docker commands inside its own container for the workflows, and to solve this problem, there are two possible solutions.

First solution: we can create a new Docker instance inside Docker so it can be used by the Forgejo runner as we just did.

Second solution: nest a host's UNIX socket and use it to run Docker commands.

For our case, it will be easier and better to use the docker-in-docker solution, as we are already running a Forgejo instance with Docker.

Installation and configuring all configs

After the docker-compose.yaml is created, the next step will be to create a .env file in the same folder where docker compose and paste the following variables:

POSTGRES_DB=forgejo_db
POSTGRES_USER=forgejo_db
POSTGRES_PASSWORD=forgejo_pass_123

Don't forget to generate a strong password in case you're going to host this in your homelab or VPS server. Don't run all containers at once; first, you need to start only the database and forgejo containers:

$ docker compose up -d db forgejo

If there are no errors in the container logs, then you can continue and move into the installation step. Open https://localhost:3000, and you should see the following page:

All installations can be easily completed via this page if you don't want to do configuration via a configuration file. Also, you can fill in additional settings if you need, for example, an SMTP server for your git instance. If no need that, then scroll down and open the "Administrator account settings":

Just fill in your administrator account credentials and save them, and after that, just click on "Install Forgejo" to start the installation process. It can take a few seconds; after that, you should see the dashboard page:

Great, now get back into your terminal and run the following command to create a Forgejo runner config:

$ mkdir -p runner-data/.cache
$ docker run --rm data.forgejo.org/forgejo/runner:13 \
  forgejo-runner generate-config > runner-data/runner-config.yml

Okay, now you'll need to open again Forgejo UI and register the runner - click on the avatar in the top right corner -> Site administration -> Actions -> Runners -> Create new runner.

Just type the runner name and create. Copy the UUID and token - you will need this for runner configuration:

Open your editor and open the following file: runner-data/runner-config.yml, and find the "server" variable and just paste the runner configuration inside the "connections" variable:

container:
  network: "host" # edit this variable too

server:
  connections:
      forgejo:
        url: http://forgejo:3000/ # Important, type here forgejo, not localhost
        uuid: cfb0f9aa-afff-40d3-aad2-077e9db72584
        token: edccd714edb2c15ca43edf6e851f64cee0c495d7

It's time to start all containers; just run the following command:

$ docker compose up -d
$ docker compose logs -f runner # run this to check logs of forgejo runner container

If everything is okay, you should see the following message inside the Forgejo runner container:

time="2026-08-20T06:13:51Z" level=info msg="[poller] launched"

Creating the first workflow

We are going to create a pretty simple deployment workflow just to see that it will be triggered after we push some changes into repositories that we host inside our Forgejo instance. But before you run your first deployment, we need to have something we can deploy, and first we need a new repository.

Just open the dashboard and click on the plus button and "New repository":

Like on GitHub, you type all the information and settings here:

And after that, just follow the steps to clone the repository into your local machine:

After the repository is cloned, open it in the IDE and create the following folders and file with the workflow .forgejo/workflows/demo.yml:

on: [push]
jobs:
  test:
    runs-on: docker
    steps:
      - uses: https://code.forgejo.org/actions/checkout@v4
      - run: echo "Forgejo + Actions is alive"

In short, this workflow will be triggered only when we push new changes into the repository, and it will just log a "Forgejo + Actions is alive" message in the action logs. And don't forget to commit your changes:

$ git add .
$ git commit -m "first commit"
$ git remote add origin http://localhost:3000/runneruser/myrepo.git # don't forget to type your repo URL here
$ git push -u origin main

It will ask for credentials from your Forgejo account; just type your admin account credentials:

Go back to the repository page and open the "Actions" tab; you should see that the action was triggered:

You can also check progress logs for each step:

And if everything went well, you will see green checkmarks in all steps:

Congratulations! You just created your first workflow and fully self-hosted CI/CD with custom deployments; now it's time to discuss what we should do next and other capabilities in Forgejo.

What's next?

So now you got full understanding of how you can do this, and the next question is - what should I do next? Just like on GitHub, you can use similar workflow schemas to create your deployment workflows that will be executed via the Forgejo runner and a Docker-in-Docker container. If you don't have any experience with this topic, I really recommend trying to set up a custom CI/CD deployment for a simple Node.js application inside an EC2 instance.

More about Forgejo, workflows, CI/CD, and self-hosting, I'm going to explain and show in the next article series - for now, thank you for reading this guide.