DEV Community: Alkin Veysal

Poka-Yoke in PHP: Guarding Business Operations Before They Run

Alkin Veysal — Thu, 22 Oct 2026 07:20:47 +0000

In manufacturing, Poka-Yoke is a way of designing a process so that common mistakes are prevented or detected before they cause harm. An asymmetric fixture that accepts a component in only one orientation is a familiar example.

I work with software in operational environments, and I kept returning to a related question: what does mistake-proofing look like at the boundary of a PHP business operation?

Not every mistake needs a new library. Most of the time, an ordinary if statement is the right answer. But when an operation depends on several independent conditions, it can become useful to make those checks explicit, collect the reasons for rejection, and keep the action itself behind a single guard.

That experiment became Novora Poka-Yoke, a small, framework-independent PHP 8.4+ package.

The problem is not just validation

Consider a shipping operation. Before dispatching, we may need to know that payment has been confirmed, a shipping address exists, and sufficient stock is available.

We can write these conditions inline. There is nothing inherently wrong with that. But a sequence of early returns often tells the user only about the first missing condition, while the same requirements can end up scattered across controllers, command handlers, and services.

For some workflows, I wanted an explicit boundary:

Evaluate application-defined preconditions.
Collect understandable, machine-readable reasons if any fail.
Invoke the operation callback only when every check passes.

The important distinction is that this is operation precondition checking, not a general data-validation framework, a state machine, or a transaction manager.

A minimal API

Install the stable package with Composer:

composer require "novora/poka-yoke:^1.0"

A rule implements one method and returns either null (allowed) or a Violation:

<?php

declare(strict_types=1);

use Novora\PokaYoke\Rule;
use Novora\PokaYoke\Violation;

final class PaymentConfirmed implements Rule
{
    public function check(mixed $context): ?Violation
    {
        if (!$context instanceof Order) {
            throw new InvalidArgumentException('Expected an Order.');
        }

        return $context->isPaid()
            ? null
            : new Violation('payment.not_confirmed', 'Payment must be confirmed.');
    }
}

Order is a placeholder for an entity or DTO from your application; the package does not define an Order class.

We can combine multiple rules without hiding which ones ran:

use Novora\PokaYoke\Guard;

$guard = new Guard();

$result = $guard->check($order, [
    new PaymentConfirmed(),
    new ShippingAddressPresent(),
    new InventoryAvailable(),
]);

if (!$result->allowed()) {
    foreach ($result->violations as $violation) {
        // Application decides how to present or translate the message.
        echo $violation->code . ': ' . $violation->message . PHP_EOL;
    }
}

The two additional rule classes above are application-defined examples too. By default, check() collects violations in rule order. For cases where evaluating later rules would be unnecessary, it supports stopOnFirstViolation: true.

Put the action behind the guard

A separate check followed by an action is useful for displaying diagnostics, but the package also offers a compact operation boundary:

use Novora\PokaYoke\Guard;
use Novora\PokaYoke\OperationBlocked;

try {
    $shipmentId = (new Guard())->execute(
        $order,
        [new PaymentConfirmed(), new ShippingAddressPresent(), new InventoryAvailable()],
        fn () => $shippingService->dispatch($order),
    );
} catch (OperationBlocked $exception) {
    foreach ($exception->result->violations as $violation) {
        // Map stable codes to your API, logs, or UI.
    }
}

The callback is not invoked if any rule rejects the operation. execute() returns the callback's value if all rules pass. Exceptions thrown by a rule or the callback are not swallowed.

One design decision here is deliberate: a rule expresses why the operation cannot proceed, while the application remains responsible for domain decisions and persistence.

Where this pattern is useful

The same narrow concept appears in quite different applications:

Shipping: payment, address, and stock checks before dispatch.
Manufacturing: verifying a scanned part and a completed quality step before recording the next operation. Real machinery safety must remain in dedicated safety systems.
Bookings: checking consent and requested capacity before submitting a booking.

These are not promises of safe concurrent inventory or seat allocation. They are examples of where explicit preconditions make intent easier to understand.

The repository includes a runnable order example and a discussion of practical scenarios and alternatives.

What Poka-Yoke cannot guarantee here

This is the part I consider especially important.

A successful precondition check does not guarantee the state will still be valid when the callback commits its changes. Inventory, account balance, or booking capacity can change concurrently. The library does not provide database transactions, row locking, idempotency, distributed coordination, or rollback.

If correctness depends on the check and write being atomic, the application must enforce that with suitable database constraints, transactions, locks, or other domain-specific mechanisms. Likewise, rule implementations should avoid side effects, but the library cannot prevent user-supplied PHP code from mutating state.

For data shape and field constraints, an established validator is probably a better choice. For state transitions, a workflow or state-machine component is usually a better abstraction. And for one or two straightforward preconditions, plain PHP conditionals may be simpler.

Testing the contract

The initial v1.0.0 release was validated with 15 PHPUnit tests (27 assertions), PHPStan level 8, Composer validation, and CI on PHP 8.4 and PHP 8.5. I also installed the published package from Packagist in a separate PHP project and exercised its API.

Tests cover failing preconditions, the order of violations, fail-fast checking, invalid rule values, propagation of exceptions, falsy contexts, and the guarantee that a rejected operation does not invoke its callback.

Those checks establish the package's documented behavior. They are not proof that every consuming application's business rules are correct.

A modest conclusion

I do not think Poka-Yoke in PHP requires a large framework. Sometimes it is simply a useful design habit: make the conditions for a consequential operation explicit, and stop before the side effect when those conditions are not met.

Novora Poka-Yoke packages one small expression of that idea. It might be useful when you want structured rejection reasons and a consistent execution boundary; it is not intended to replace a validator, workflow engine, or carefully designed domain model.

If you have solved similar problems differently, I would be interested to learn what worked for you.

Project links: GitHub · Packagist · v1.0.0 release

Bulk Editing in EasyAdmin 5: A Review-and-Confirm Workflow for Doctrine Entities

Alkin Veysal — Thu, 22 Oct 2026 05:14:28 +0000

EasyAdmin is one of the reasons building administrative interfaces with Symfony can be pleasantly straightforward. It gives us CRUD pages, filters, forms, actions, and a lot of useful defaults without making every project reinvent its back office.

But there is a small workflow I have needed in real applications: select several records and change only a few explicitly chosen fields.

Imagine an administrator managing a product catalogue. Twenty products need to move from draft to published. Their titles, prices, categories, and other attributes must remain untouched. Opening twenty edit forms is tedious. A custom one-off batch action works, but each additional field or entity often means another controller method and another form.

I wanted to explore whether that common workflow could be packaged as a focused EasyAdmin extension. The result is Novora EasyAdmin Bulk Edit Bundle, with its latest published release, v1.1.3.

This post is about the decisions behind it, how to wire it into an EasyAdmin 5 CRUD controller, and—just as importantly—what the bundle does not attempt to solve.

The difference between a batch action and bulk editing

EasyAdmin already supports batch actions. You can select multiple rows and invoke a custom action. That is an excellent extension point; the bundle uses it rather than replacing EasyAdmin's index UI.

What a generic bulk edit workflow needs on top of that is a little more involved:

Collect the selected records from the batch action.
Let the administrator choose which fields to change, and supply their new values.
Validate those values with Symfony Forms.
Display the proposed changes before anything is written.
Check permissions again when the final confirmation arrives.
Apply the changes through Doctrine ORM within a transaction.

The second point is easy to underestimate. A bulk edit form must distinguish “leave this field unchanged” from “set this field to null, false, an empty string, or zero.” Those values can be perfectly valid updates.

For that reason, the form gives each editable field its own opt-in checkbox. The new value matters only when the checkbox is selected. Unchecked fields are omitted from the change set entirely.

A deliberately small scope

The bundle targets PHP 8.4+, Symfony 7.4/8.x, EasyAdmin 5.x, and Doctrine ORM 3.x. Version 1.x keeps its supported operation intentionally narrow: up to 100 selected entity identifiers, with explicit handlers for scalar values (string, int, float, bool, or null).

It is not an automatic editor for every Doctrine property. Arbitrary associations, collections, object-valued form data, and asynchronous processing are out of scope.

That constraint is a feature of the design rather than a claim that those cases are unimportant. I would rather maintain a modest public API with understandable behavior than guess how every application's domain model should be mutated.

Installation

The package is listed on Packagist. For a project meeting its requirements:

composer require novora/easyadmin-bulk-edit-bundle:^1.1.3

// config/bundles.php
return [
    // Your existing bundles...
    Novora\EasyAdminBulkEditBundle\NovoraEasyAdminBulkEditBundle::class => ['all' => true],
];

This assumes an existing, correctly configured EasyAdmin application with Symfony sessions, Twig, Doctrine, and CSRF protection. The registration snippet is for applications where the bundle is not already present in config/bundles.php; do not add it twice.

Connecting a CRUD controller

The following example assumes a Product entity with a setStatus(string $status) method and an application voter that understands the EDIT permission. Those are application-specific examples, not classes supplied by the bundle.

First, register an EasyAdmin batch action. BulkEditAction::new() uses EasyAdmin’s normal batch-action mechanism and skips its generic preliminary confirmation for this action only; the bundle still provides its own review and final confirmation:

use EasyCorp\Bundle\EasyAdminBundle\Config\Actions;
use Novora\EasyAdminBulkEditBundle\BulkEditAction;

public function configureActions(Actions $actions): Actions
{
    return $actions->addBatchAction(
        BulkEditAction::new('bulkEdit', 'Bulk edit')
    );
}

Then add the two custom CRUD actions. With EasyAdmin 5, the #[AdminRoute] attributes matter: they make these custom routes discoverable in its routing system.

<?php

declare(strict_types=1);

namespace App\Controller\Admin;

use App\Entity\Product;
use EasyCorp\Bundle\EasyAdminBundle\Attribute\AdminRoute;
use EasyCorp\Bundle\EasyAdminBundle\Config\Action;
use EasyCorp\Bundle\EasyAdminBundle\Config\Actions;
use EasyCorp\Bundle\EasyAdminBundle\Context\AdminContext;
use EasyCorp\Bundle\EasyAdminBundle\Controller\AbstractCrudController;
use EasyCorp\Bundle\EasyAdminBundle\Dto\BatchActionDto;
use EasyCorp\Bundle\EasyAdminBundle\Router\AdminUrlGenerator;
use Novora\EasyAdminBulkEditBundle\BulkEditAction;
use Novora\EasyAdminBulkEditBundle\BulkEditField;
use Novora\EasyAdminBulkEditBundle\Workflow\BulkEditWorkflow;
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

final class ProductCrudController extends AbstractCrudController
{
    public static function getEntityFqcn(): string
    {
        return Product::class;
    }

    public function configureActions(Actions $actions): Actions
    {
        return $actions->addBatchAction(
            BulkEditAction::new('bulkEdit', 'Bulk edit')
        );
    }

    #[AdminRoute('/bulk-edit', name: 'bulk_edit', options: ['methods' => ['POST']])]
    public function bulkEdit(
        AdminContext $context,
        BatchActionDto $batchActionDto,
        BulkEditWorkflow $workflow,
        AdminUrlGenerator $urls,
    ): Response {
        $this->denyAccessUnlessGranted('ROLE_PRODUCT_EDITOR');

        return $workflow->start(
            $batchActionDto,
            $context->getEntity()->getFqcn(),
            $urls->setController(self::class)
                ->setAction('bulkEditConfirm')
                ->generateUrl(),
        );
    }

    #[AdminRoute('/bulk-edit-confirm', name: 'bulk_edit_confirm', options: ['methods' => ['GET', 'POST']])]
    public function bulkEditConfirm(
        Request $request,
        AdminContext $context,
        BulkEditWorkflow $workflow,
        AdminUrlGenerator $urls,
    ): Response {
        $this->denyAccessUnlessGranted('ROLE_PRODUCT_EDITOR');

        return $workflow->confirm(
            $request,
            $context->getEntity()->getFqcn(),
            [
                'status' => [
                    'type' => ChoiceType::class,
                    'options' => [
                        'choices' => [
                            'Published' => 'published',
                            'Draft' => 'draft',
                        ],
                    ],
                ],
            ],
            [
                'status' => new BulkEditField(
                    'status',
                    static function (Product $product, string $status): void {
                        $product->setStatus($status);
                    },
                ),
            ],
            fn (Product $product): bool => $this->isGranted('EDIT', $product),
            $urls->setController(self::class)
                ->setAction(Action::INDEX)
                ->unset('bulk_selection')
                ->generateUrl(),
        );
    }
}

There are several intentionally explicit decisions in this example.

The trusted entity class comes from AdminContext. The initial batch POST includes an entity class name, but client-supplied class names must not decide which repository is modified.

The form definition and its field handler are both defined by the application. The bundle does not derive method names from HTTP field names, and checks that configured form fields match their allowed handlers before proceeding.

Authorization happens at two levels. The controller checks access to each action. The callback checks each entity during execution. Your own EasyAdmin permissions and voters must still be configured correctly. Checking permissions only when the review screen is first opened would be insufficient—roles and record ownership can change before confirmation.

For the complete integration details, see the v1.1.3 integration guide.

A small UX detail that matters

The first iteration taught me that a correct workflow can still feel awkward. EasyAdmin may show its standard batch-action confirmation dialog before the administrator even sees the edit form. Since this bundle already has a separate review and final confirmation, that extra dialog makes the experience confusing.

BulkEditAction::new() skips that preliminary dialog only for bulk editing, while leaving other batch actions' confirmations intact. I deliberately avoided disabling confirmation for the entire CRUD controller: a different batch action may delete data or perform another irreversible operation.

The edit screen also separates two decisions: should this field be changed? and what should its new value be? For example, updating an active boolean to false must not be confused with leaving the field unchanged. The current interface has English and Bulgarian translations, and the review shows boolean values as readable Yes/No equivalents. After a successful commit, it creates a localized Symfony success flash message; how it appears depends on the host application's EasyAdmin layout.

What happens between selection and confirmation?

The interaction is deliberately split into stages:

EasyAdmin index
    |
    | select rows + invoke batch action
    v
Validate action, entity class and batch CSRF
    |
    v
Store selected IDs in the server-side session
    |
    v
Edit form: check fields and enter new values
    |
    | Symfony Form validation
    v
Review page: show selected count and proposed values
    |
    | separate CSRF-protected confirmation
    v
Recheck entity permissions, update through Doctrine, commit

The server-side selection is associated with a random token, expires after 15 minutes, and is consumed when confirmation is attempted. The review values are also stored server-side; the confirmation form does not need to trust a new list of entity identifiers or mutable hidden form fields.

The review page is not a preview of every entity's old and new values, nor does it execute domain code speculatively. It displays the requested field/value changes and the number of selected records. Calling that a full “dry run” would be misleading, and the review does not detect changes made by another administrator in the meantime.

Why use Doctrine entities instead of one DQL UPDATE?

A single database-level UPDATE can be tempting:

UPDATE product SET status = 'published' WHERE id IN (...);

But a raw update is not equivalent to loading entities and calling their methods. In an application that relies on entity methods, Doctrine change tracking, and ORM lifecycle behavior, skipping the normal entity path may change application semantics.

The bundle instead loads the selected objects, authorizes each one, calls the explicitly configured field handlers, and flushes through Doctrine ORM in a transaction.

There is a trade-off: that is more work than a single SQL statement. Capping the operation at 100 selected IDs keeps the first version's expectations reasonably clear. Database transactions also have limits: rolling back the database will not undo an email, an HTTP request, or another external side effect triggered during the operation.

What about concurrent changes?

This deserves an explicit answer, particularly for administrative interfaces.

A transaction does not automatically prevent lost updates. Imagine someone edits a product after the bulk edit selection was made but before confirmation. Whether that conflict matters—and how it should be resolved—depends on the application. For critical data, consider optimistic versioning, appropriate row locks, or other domain-specific concurrency controls.

Similarly, a one-use token in a Symfony session is not a distributed exactly-once guarantee. Some session handlers serialize requests for a session; others may behave differently depending on configuration, infrastructure and deployment. If a bulk action causes financial, irreversible or externally visible side effects, use a shared idempotency or locking mechanism designed for that requirement.

The bundle documents these boundaries instead of presenting CSRF tokens and session state as universal concurrency protection.

Testing the behavior, not just the helpers

I found the most useful tests were the ones that exercised the real request flow, rather than only testing small service methods in isolation.

The project includes a Symfony integration fixture with EasyAdmin routing, Twig, forms, Doctrine, and SQLite. It checks that the batch action reaches the correct controller, the edit form renders, invalid form data does not write to the database, the review step does not write anything, and the final confirmation performs the update.

The tests also cover invalid or mismatched batch selections, forged CSRF tokens, attempts to repeat a consumed confirmation, and an access-denial scenario after the review step.

For v1.1.3, the project passed 27 PHPUnit tests (90 assertions) and PHPStan level 8, with CI jobs for PHP 8.4 (minimum and latest permitted dependencies) and PHP 8.5 (latest permitted dependencies). Those checks are useful evidence of behavior—but they are not a substitute for testing your own policies and production database configuration.

Lessons from making it reusable

A reusable Symfony bundle does not have to make every decision for the application. In fact, I think it is healthier when it does not.

For this project, I wanted the library to own the repeatable infrastructure—selection handoff, edit/review screens, form validation, and transactional orchestration—while the application retains control of entity permissions, allowed fields, setters, and domain rules.

The scope remains modest. It will not replace every custom administrative workflow, and I do not think it should. I hope it saves someone from implementing the same careful multi-record edit flow repeatedly.

If you work with EasyAdmin and have encountered a similar case, I would be interested to hear where this approach fits—and where it does not.

Links

Thanks for reading.

When Counting Overlapping Bookings Is Not Enough: Capacity-Aware Availability in PHP

Alkin Veysal — Wed, 21 Oct 2026 10:18:08 +0000

Imagine you're building a scheduling feature for a loading dock, a shared workspace, or a storage area.

The resource has a maximum capacity. A reservation occupies some of it for a period of time. You need to answer a deceptively simple question:

Can I reserve 2 units for 45 minutes, and if so, when can I start?

At first, this looks like a database query that counts overlapping reservations. I initially thought of it in similar terms. But once capacity changes throughout the day and bookings consume different amounts, counting overlaps no longer gives the right answer.

That was the starting point for CapacityAvailability, a small PHP library I recently released as version 1.0.0.

This article is about the problem and the reasoning behind the solution—not an argument that every scheduling application needs another dependency.

The trap: overlap is not concurrency

Suppose a resource has capacity 3 and already has these bookings:

Booking	Time	Units
A	09:00–09:30	1
B	09:30–10:00	1
C	10:00–10:30	1

A proposed reservation would use 2 units from 09:00 to 10:30.

All three existing bookings intersect that proposed interval. A naive approach might sum their units, get 3, and reject the request.

But the existing bookings never run simultaneously. At every instant, only one unit is occupied. Two units remain free throughout the entire 90-minute interval. The request fits.

Now add another booking for 2 units from 09:45 to 10:15. The answer changes: during part of the interval, all 3 units are occupied.

What matters is usage at each point in time, not how many reservations touch the requested interval.

And there's another complication: the resource itself might have capacity 2 before 10:00 and capacity 3 afterwards.

Model time explicitly

I chose a small model:

A capacity interval declares the total available units during [start, end).
A reservation consumes a positive number of units during [start, end).
A query specifies the required units and the duration for which those units must remain available.

The [start, end) notation matters. The start is inclusive; the end is exclusive. A booking ending exactly at 10:00 does not conflict with another beginning at 10:00.

Capacity declarations are absolute, not additive: if a pool has capacity 3, that's a level of 3, not another 3 units to add to an overlapping declaration. Overlapping capacity declarations are rejected. Any period without declared capacity has capacity zero.

This model also makes a deliberate trade-off: the units are interchangeable. It answers whether 2 places are available, not which exact two places to allocate. Scheduling individual machines with different capabilities is a different problem.

Sweep-line: look only where the state changes

The underlying approach is a sweep-line algorithm.

Instead of examining every second or minute, we collect the moments at which something changes:

When capacity begins, add its units.
When capacity ends, subtract its units.
When a reservation begins, increase occupied units.
When a reservation ends, decrease occupied units.
Sort the event times and apply all changes at the same instant together.

Between two consecutive event times, capacity and usage are constant.

For example:

Period	Capacity	Occupied	Free
09:00–09:30	2	0	2
09:30–10:00	2	1	1
10:00–10:30	3	1	2
10:30–11:00	3	0	3

If we need 2 units for 45 minutes, the period from 09:00 to 09:30 is too short. The contiguous availability from 10:00 to 11:00 is long enough.

The result is not a predefined array of quarter-hour slots. It's a continuous window with enough remaining capacity for the entire requested duration.

For C capacity intervals and R reservations, the calculation uses O((C + R) log(C + R)) time and O(C + R) additional memory, dominated by sorting the event boundaries.

Trying it in PHP

Install the package:

composer require alkin/capacity-availability:^1.0

Here's the same example using the public API:

<?php

declare(strict_types=1);

use Alkin\CapacityAvailability\AvailabilityCalculator;
use Alkin\CapacityAvailability\CapacityInterval;
use Alkin\CapacityAvailability\Reservation;

$at = static fn (string $time): DateTimeImmutable =>
    new DateTimeImmutable("2026-10-22 {$time}:00+00:00");

$capacity = [
    new CapacityInterval($at('09:00'), $at('10:00'), 2),
    new CapacityInterval($at('10:00'), $at('11:00'), 3),
];

$reservations = [
    new Reservation($at('09:30'), $at('10:30'), 1),
];

$calculator = new AvailabilityCalculator();

$windows = $calculator->availableWindows(
    capacity: $capacity,
    reservations: $reservations,
    from: $at('09:00'),
    until: $at('11:00'),
    requiredUnits: 2,
    durationSeconds: 45 * 60,
);

foreach ($windows as $window) {
    printf(
        "%s–%s; latest start: %s\n",
        $window->start->format('H:i'),
        $window->end->format('H:i'),
        $window->latestStart->format('H:i'),
    );
}

Output:

10:00–11:00; latest start: 10:15

That last field is worth highlighting: 10:15 is a valid starting time. A 45-minute booking starting at 10:15 ends at 11:00, exactly at the exclusive boundary.

If your UI only offers 15-minute slots, it can choose to display 10:00 and 10:15. But the calculation itself shouldn't impose that grid.

The library also exposes canBook() for an exact interval and timeline() for inspecting capacity, occupancy, and free units.

The important distinction: available is not reserved

So far, we've solved a deterministic calculation. We have not solved concurrent booking.

Imagine two requests arriving at the same time. Each reads the database and sees two free places. Each wants two places. Both call canBook(), both get true, and both insert their booking.

The calculation can be completely correct while the final database state is overbooked.

That's why the library separates the pure algorithm from an optional Doctrine DBAL adapter for a particular MariaDB/InnoDB schema.

The adapter's booking path is, in simplified terms:

BEGIN TRANSACTION
    SELECT pool_id
    FROM capacity_pools
    WHERE pool_id = :pool
    FOR UPDATE

    -- Read capacity and overlapping bookings
    -- Recalculate availability while holding the pool lock
    -- Insert only when the request fits
COMMIT

The stable pool row acts as the synchronization point. Independent writers for the same pool must acquire that lock before reading the snapshot used for a write decision.

This comes with a serious condition: every code path that changes capacity or reservations for that pool must follow the same locking protocol. A cancellation, reschedule, import, or manual SQL update that bypasses it can invalidate the guarantee.

The adapter also intentionally does not provide idempotency, automatic deadlock retries, or arbitrary ORM mappings. It rejects nested transactions; its behavior was verified for the documented MariaDB setup, not every database engine or isolation configuration.

I would rather document these boundaries clearly than hide them behind a convenient-looking API.

Testing two different kinds of correctness

There were two separate questions to test:

Is the algorithm giving the correct answer?

Alongside ordinary unit tests, I used an independent reference implementation that samples every minute—or every second for smaller calendars—and compares all possible starts against the sweep-line result.

The release was checked using 300 randomized minute-resolution calendars, 80 second-resolution calendars, and 77,525 reference assertions, plus unit tests and static analysis.

Does the database adapter prevent the race?

This needed actual concurrent processes, not two sequential method calls.

In an isolated MariaDB 11.3.2 test database, I ran scenarios with independent PHP workers. The suite includes an intentionally unsafe example that demonstrates overbooking, followed by properly locked transactions.

The recorded result was 12 scenarios, 43 independent PHP processes, and 198 assertions. The unsafe test is deliberately confined to disposable test data.

Those tests are useful evidence for the documented design; they are not a promise that every application integration is automatically safe.

Why this isn't a Symfony bundle

I work primarily with Symfony, and the early experiments included a real Symfony application using DoctrineBundle. It was tempting to package everything as a Symfony bundle.

But the calculation itself doesn't need Symfony. It just takes arrays of immutable value objects and returns results.

In a Symfony application, the calculator can be registered as a normal service:

# config/services.yaml
services:
    Alkin\CapacityAvailability\AvailabilityCalculator: ~

That was enough to integrate the core using dependency injection. The optional Doctrine classes can be registered similarly when the application uses the documented persistence schema.

A bundle may make sense one day if it provides meaningful integration behavior. Adding one merely to wrap a service registration would increase maintenance without solving another problem.

Where it stops

CapacityAvailability is not a complete booking platform.

It does not handle recurring calendars, holidays, payments, user permissions, named individual resources, or multi-pool optimization. It also doesn't magically adapt its database writer to an existing application's schema.

What it does offer is a focused solution to one recurring question:

Given changing capacity and overlapping usage, when does a request fit for its entire duration?

Keeping that boundary explicit is part of the design.

The project is open source under MIT, supports PHP 8.2+, and the calculation core has no required runtime dependencies.

Source and documentation: GitHub — CapacityAvailability
Installation: Packagist — alkin/capacity-availability
Concurrency details: Transactional booking contract

If you've solved a similar scheduling or capacity problem, I'd be interested in the edge cases you ran into—especially where the simple interchangeable-capacity model stops being sufficient.

Unsaved Form Changes in Symfony — With and Without Turbo

Alkin Veysal — Mon, 19 Oct 2026 20:19:30 +0000

Not every form needs autosave. Sometimes the most useful thing an application can do is ask a simple question before someone navigates away:

You have unsaved changes. Leave this page?

It's a small detail, but a helpful one on editing screens: account settings, product details, admin forms, or anything that may take a few minutes to fill out.

I wanted a reusable way to add that behavior to a Symfony form without creating a new form type, adding server-side infrastructure, or writing another one-off JavaScript controller for each project.

That became Unsaved Form Bundle, a small open-source Symfony UX bundle built around one Stimulus controller. Version 1.0.0 is available on Packagist.

This post is about the convenience itself, how to use it, and some less obvious browser and Turbo behaviors worth understanding before relying on any unsaved-changes warning.

Why `beforeunload` alone is not quite enough

For a traditional page, the starting point is familiar:

window.addEventListener('beforeunload', (event) => {
    if (!hasUnsavedChanges) {
        return;
    }

    event.preventDefault();
    event.returnValue = '';
});

That illustrates the native browser mechanism, but it isn't a complete implementation. We still need to determine whether a form really changed, stop warning after a successful save, and avoid warnings when an ordinary submission is already in progress.

And once Turbo is involved, some navigations replace content without unloading the document at all.

For example:

Turbo Drive can visit a different page without a full browser reload.
Turbo Back/Forward restoration doesn't fire turbo:before-visit.
Turbo Frames can replace only the part of the page containing the form.
Turbo Streams can replace or remove the form without changing the URL.

Those are separate events in Turbo's documented lifecycle. A guard that listens only to beforeunload can miss them.

The goal wasn't to build a form framework. It was to make this small piece of behavior reusable.

Add it to a Symfony form

The package requires PHP 8.2+, Symfony 7.4 or 8.x, and a supported Symfony StimulusBundle integration. It works in applications with or without Symfony UX Turbo.

Install the stable 1.x release:

composer require "alkin/unsaved-form-bundle:^1.0"

In a standard Symfony UX setup, Symfony Flex registers the bundle and the Stimulus controller. It's worth checking config/bundles.php, assets/controllers.json, and the application's frontend configuration after installation.

Then add a controller to the form element:

{{ form_start(form, {
    attr: {
        'data-controller': 'alkin--unsaved-form-bundle--guard',
        'data-alkin--unsaved-form-bundle--guard-message-value':
            'You have unsaved changes. Leave this page?'
    }
}) }}
    {{ form_widget(form) }}

    <span role="status" aria-live="polite" hidden
          data-alkin--unsaved-form-bundle--guard-target="indicator">
        Unsaved changes
    </span>

    <button type="submit">Save</button>
{{ form_end(form) }}

That's the basic integration. The message and indicator are optional; the form does not need an extra controller action or a database table.

The optional indicator becomes visible while the form has unsaved changes. As with other dynamic UI messages, check that its accessibility behavior fits your own form and assistive-technology setup.

It is not limited to Symfony Forms

The controller attaches to a regular HTML <form> element too:

<form data-controller="alkin--unsaved-form-bundle--guard" method="post">
    <label>
        Title
        <input name="title" value="Example">
    </label>
    <button type="submit">Save</button>
</form>

You still need StimulusBundle and the frontend assets to be loaded. Turbo is optional.

A change is not the same as a touched field

An important design choice is to compare a form's current values with its starting values rather than remember whether an input event happened at some point.

Consider this simple sequence:

A field starts with Draft.
Someone edits it to Published.
They change it back to Draft.

The form should be considered clean again.

The controller takes a snapshot of relevant form values and compares against that baseline. It accounts for ordinary text fields, checkboxes, radio buttons, selects, textareas, and selected files. It also reacts to resets and detects changes made programmatically when it checks the form before navigation.

Sometimes a value should not affect the warning, such as a purely client-side helper field. It can be excluded:

<input name="temporary-ui-state" data-unsaved-form-ignore>

The attribute can also be placed on a wrapper around fields that should be ignored.

What happens with Turbo?

For normal Turbo Drive visits, the controller can ask for confirmation before the visit begins. For native browser navigation, it relies on the browser's beforeunload dialog.

History restoration needs different handling. Turbo explicitly does not emit turbo:before-visit for Back/Forward navigation, so that event alone cannot protect an edited form. The bundle also uses browser history information where available and keeps the original form state in page memory so a cached Turbo render does not simply turn an unsaved form into a new, apparently clean one.

Frames and Streams are another case: they can remove or replace an edited form without leaving the page. The bundle listens to their render lifecycle and asks for confirmation when the pending update would affect that form. Unrelated frame or stream updates can continue.

There's one more detail that's easy to overlook: validation failures.

A Symfony form submitted through Turbo may return an HTTP 422 response containing validation errors and re-rendered form markup. That is not a successful save. The new form should still be treated as containing unsaved edits, rather than resetting its baseline just because new HTML appeared.

These behaviors are why the controller grew beyond a short beforeunload snippet. They are also why I would not judge a navigation guard only by a couple of happy-path unit tests.

Submission and custom JavaScript

A regular form submission should not trigger an unnecessary leave-page warning simply because the browser is submitting the form.

For Turbo submissions, the controller follows Turbo's submission lifecycle. A successful response can mark the current state clean; an unsuccessful one should keep the unsaved state. For an application that saves via custom AJAX code outside that lifecycle, the controller exposes a small method, markClean(), which the application can call after the server has confirmed a successful save.

This is deliberate: the bundle does not guess that a click on a Save button means data was persisted.

It also emits an alkin--unsaved-form-bundle--guard:change event with event.detail.dirty if you want to update other UI elements when the dirty state changes.

What this does not promise

It's important to keep the scope clear.

It is a navigation warning, not a draft storage system. It does not store edits in a database or localStorage, automatically save to the server, or guarantee recovery after a tab or browser process disappears. The temporary state used during Turbo restoration lives in the page's JavaScript memory.

Browsers also control native unload dialogs. They may require prior user interaction, they choose the dialog text, and on some mobile or OS-initiated termination paths they may not show a prompt at all. This is a browser constraint, not something a Symfony bundle can override. MDN's beforeunload documentation explains the limitations.

Similarly, the history behavior depends on modern browser APIs being available. And if unrelated application code deliberately destroys a form outside the supported navigation and Turbo lifecycle, that code needs to coordinate with the guard.

Those boundaries matter more than a claim that it can "never lose changes." If an application needs guaranteed draft recovery, it should implement actual persistence or autosave separately.

Testing beyond a single browser

For the v1.0.0 release, the project includes 29 JavaScript unit tests and real-browser navigation scenarios using Playwright and Turbo 8. Its CI checks Chromium, Firefox, and WebKit, alongside PHP 8.2/8.4 checks.

The browser scenarios exercise ordinary and Turbo navigation, rejected and approved Back/Forward visits, Frames, destructive Streams, form submission, and an HTTP 422 validation response. The file-input scenario checks that declining a history navigation doesn't discard a selected file in the tested browser behavior.

That doesn't prove every browser version or integration is perfect. It does make regressions in those specific paths easier to detect.

If you're evaluating this for your own project, I would still test it against the way your application uses Turbo, especially if you have custom morphing, unusual form markup, or JavaScript that replaces parts of the DOM.

A small convenience, not another form framework

Symfony already gives us excellent form, validation, and frontend tools. I didn't want another layer around them just to display one warning.

Unsaved Form Bundle is meant to stay narrow: one opt-in Stimulus controller for a behavior that can be useful in many editing screens. It won't suit every application, and it doesn't need to.

The source, usage notes, limitations, and tests are available on GitHub. The package is on Packagist.

If you try it and run into a reproducible edge case, a small example and the browser/Turbo versions would be especially helpful. That's often more useful than a long feature wishlist.

Cover photo: Jakub Zerdzicki on Pexels, used under the Pexels License.

One Symfony Form, Two Views: Read-Only Summaries Without Duplication

Alkin Veysal — Wed, 14 Oct 2026 12:21:19 +0000

A form often has a second life.

First, someone uses it to enter or update information. Then, somewhere else in the application, someone needs to read that same information: on a confirmation screen, an internal detail page, or a review step before submitting a request.

The editable form is already there. Yet the read-only version frequently becomes another Twig template, with another list of fields, another set of labels, and sometimes another set of rules for displaying their values.

This is not a serious architectural failure. Writing a dedicated template is perfectly reasonable. But when an application contains many structured forms, a small amount of repeated presentation code can become a surprisingly persistent maintenance task.

I wanted to explore a modest alternative: what if a read-only view could reuse the information we have already given to Symfony's Form component?

That question led to FormSummaryBundle, a small open-source bundle with a deliberately limited purpose.

The duplication is easy to miss

Consider a delivery form with a carrier, status, pallet count, and a confirmation checkbox. The status field might be defined like this:

$builder->add('status', ChoiceType::class, [
    'label' => 'Status',
    'choices' => [
        'Scheduled' => 'scheduled',
        'Ready to load' => 'ready',
    ],
]);

The stored value is ready, but the label shown to the user is Ready to load.

Now imagine a separate read-only Twig template:

<dl>
    <dt>Carrier</dt>
    <dd>{{ delivery.carrier }}</dd>

    <dt>Status</dt>
    <dd>
        {% if delivery.status == 'ready' %}
            Ready to load
        {% else %}
            Scheduled
        {% endif %}
    </dd>

    <dt>Pallets</dt>
    <dd>{{ delivery.pallets }}</dd>
</dl>

There is nothing inherently wrong with this template. The problem is that part of the form's presentation contract now exists in two places.

If the status labels change, someone has to remember to update the detail view. If the form gains a field, the read-only version might need a matching change. If the application supports multiple languages, the two views must agree on translation domains and parameters. Formatting an empty value, a date, or a monetary amount introduces similar decisions.

This matters less for a single form. It matters more when you repeat the pattern across many forms and screens.

Symfony already gives us most of the ingredients

Symfony Forms are not simply a collection of HTML inputs. They hold information about field types, labels, choices, translation settings, and transformations between application data and values used for display.

When we call createView(), Symfony produces a FormView containing the information its rendering layer needs. And Symfony already exposes helpers such as field_label() and field_value(), along with an established form-theming system.

That distinction is important. FormSummaryBundle does not invent a new form model, replace Symfony's rendering system, or claim that this information was previously inaccessible.

It provides a convenience on top of those capabilities: a complete read-only representation, with common field types handled consistently, without manually mapping every field into a second template.

The entire basic API is one Twig call:

{{ form_summary(form) }}

The interesting part is not the line itself. It is how much existing form information that line can reuse.

A complete example

Here is a small form type using only standard Symfony fields.

<?php

declare(strict_types=1);

namespace App\Form;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\CheckboxType;
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
use Symfony\Component\Form\Extension\Core\Type\IntegerType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;

final class DeliveryType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('carrier', TextType::class, [
                'label' => 'Carrier',
            ])
            ->add('status', ChoiceType::class, [
                'label' => 'Status',
                'choices' => [
                    'Scheduled' => 'scheduled',
                    'Ready to load' => 'ready',
                ],
            ])
            ->add('pallets', IntegerType::class, [
                'label' => 'Pallets',
            ])
            ->add('confirmed', CheckboxType::class, [
                'label' => 'Confirmed',
                'required' => false,
            ]);
    }
}

For this demonstration, the form is populated with an array. A real application could use its normal entity, DTO, or other data structure instead.

$form = $this->createForm(DeliveryType::class, [
    'carrier' => 'Example Logistics',
    'status' => 'ready',
    'pallets' => 0,
    'confirmed' => false,
]);

return $this->render('delivery/review.html.twig', [
    'form' => $form->createView(),
]);

And the view is just:

{# templates/delivery/review.html.twig #}
{{ form_summary(form) }}

The default output is a semantic HTML description list, conceptually equivalent to:

<dl class="form-summary">
    <div class="form-summary__row">
        <dt>Carrier</dt><dd>Example Logistics</dd>
    </div>
    <div class="form-summary__row">
        <dt>Status</dt><dd>Ready to load</dd>
    </div>
    <div class="form-summary__row">
        <dt>Pallets</dt><dd>0</dd>
    </div>
    <div class="form-summary__row">
        <dt>Confirmed</dt><dd>No</dd>
    </div>
</dl>

Notice four things:

The choice label is preserved. The summary displays Ready to load, not the underlying ready value.
Zero stays zero. A pallet count of 0 is not treated as missing data.
False is meaningful. The unchecked checkbox becomes No in the default English translation.
Labels have a single source. The summary reuses the labels already configured on the form.

These are small details, but they are exactly the details that tend to diverge when we maintain separate representations by hand.

Why this is more than a loop over fields

A simple Twig loop could handle text fields quite well. Real Symfony forms, however, contain values whose display representation is not always their raw value.

Choice fields

A ChoiceType has its own mapping between submitted values and user-facing labels. A multiple-choice field may contain several selected values, grouped choices, or preferred choices. The summary uses existing choice views rather than inventing another label map.

This also applies to standard choice-derived types, including enum choices.

Dates and times

Symfony can render dates and times as single-text widgets or as compound fields containing individual components. The bundle works with those view representations. It respects the configured date pattern for supported compound dates and preserves the transformed view value for single-text fields.

It does not promise to localize every date into a new, independently chosen format. That is a responsibility worth keeping explicit.

Nested forms and collections

A form can contain a nested form or a collection of fields. The summary follows the existing FormView children and produces nested description lists. It summarizes the entries already in the form view, not collection prototypes intended for client-side additions.

Missing values

By default, an absent text value is displayed as an em dash. The caller can choose another placeholder:

{{ form_summary(form, {summary_empty: 'Not provided'}) }}

The same placeholder is used for missing components of partial compound dates and times. Values such as 0 and false remain distinct from an empty string or null.

The aim is consistency, not magic.

You do not have to summarize the whole form

Sometimes a full description list is unnecessary. Perhaps a card only needs one label/value pair, or a sentence needs the human-readable label of a selected choice.

Two smaller helpers are available:

<dl>
    {{ form_summary_row(form.carrier) }}
    {{ form_summary_row(form.status) }}
</dl>

<p>Current status: {{ form_summary_value(form.status) }}</p>

form_summary_row() renders one labeled row; form_summary_value() renders only the value.

Another useful detail: rendering a summary does not mark the original form view's fields as rendered. An application can still render editable widgets from the same view, before or after showing the summary.

That makes the approach useful for review panels alongside editable forms, without turning a read-only representation into a set of disabled inputs.

Two kinds of customization

I wanted customization to remain close to the conventions Symfony developers already know, rather than introduce another configuration language.

1. Control the value at the form level

For a field whose ordinary view value is not what we want to display, the bundle provides a summary_value option:

use Symfony\Component\Form\FormView;

$builder->add('reference', TextType::class, [
    'summary_value' => static fn (FormView $view): string =>
        'REF-'.strtoupper((string) $view->vars['value']),
]);

The callback runs when the value is summarized. It should be deterministic and free of side effects, because rendering the same summary again evaluates it again.

The default theme treats the result as text and escapes it. A custom scalar value is not a shortcut for injecting raw HTML.

2. Control the markup with a form theme

Symfony already has a mechanism for overriding how field types are rendered. The bundle adds summary-specific blocks to that mechanism.

For example, an application can provide a Twig form theme:

{# templates/form/summary.html.twig #}
{% block text_summary_value %}
    <strong>{{ value }}</strong>
{% endblock %}

And apply it to the view:

{% form_theme form 'form/summary.html.twig' %}
{{ form_summary(form) }}

Summary-specific blocks include form_summary, form_summary_row, form_summary_value, and type-specific variations such as choice_summary_value.

The default theme does not load a stylesheet or replace normal editable widget blocks. A project can style the provided classes or override the markup to fit its design system.

There is no requirement to adopt Bootstrap, Tailwind, or another UI framework.

The security boundary is worth stating clearly

A read-only summary is not an authorization mechanism.

The bundle omits types such as password, hidden, file, repeated, and button fields. This keeps tokens, file inputs, and other inappropriate controls out of the default summary.

An application can also exclude a regular field:

$builder->add('internalNote', TextType::class, [
    'summary' => false,
]);

But a field containing sensitive data may still be an ordinary TextType. No general-purpose form renderer can determine who is entitled to see that data.

The application must continue to enforce access control, select the correct data for the user, and decide what should appear on each page. Likewise, displaying a submitted form does not make its data valid: confirmation flows still need the application's normal submission and validation checks.

The default summary theme escapes text and choice labels. Custom themes remain application code, so developers should preserve escaping and avoid applying raw to untrusted data.

It is better to describe this boundary clearly than to promise safety a presentation package cannot provide.

When I would use it — and when I would not

I find this abstraction useful when a read-only screen closely follows the structure of an existing form: confirmation pages, internal inspection views, structured administrative details, or review sections in operational software.

It can also reduce routine maintenance. When a label or a choice changes in the form, the summary continues to use the form's current metadata, rather than a separately maintained mapping.

But I would not use it automatically on every detail page.

A dashboard with calculated KPIs, a domain-specific timeline, or a carefully designed customer-facing profile may deserve its own view model and template. A screen that combines data from several sources may not correspond to a form at all. Even for a simple form, five explicit lines of Twig may be more understandable than introducing a dependency.

The question is not whether the bundle can render the data. The question is whether the form's existing structure is the right structure for the read-only presentation.

If the answer is yes, reuse makes sense. If the answer is no, a dedicated template is often the cleaner design.

That trade-off is intentional.

What the bundle deliberately does not do

To keep its responsibilities narrow, FormSummaryBundle does not:

validate submissions or enforce authorization;
query entities to build a separate read model;
persist or modify data;
generate PDFs or send emails;
implement a multi-step workflow; or
automatically understand every possible custom compound field.

It renders from an already created FormView. Creating that form view may still involve normal Symfony transformations or choice loading, and a more specialized field can use summary_value or a custom summary theme block.

This is a small convenience layer, not another application framework.

Installation and compatibility

The package is published on Packagist:

composer require "alkin/form-summary-bundle:^1.0"

If your application does not register the bundle automatically, add it to config/bundles.php:

Alkin\FormSummaryBundle\FormSummaryBundle::class => ['all' => true],

There is no separate summary schema to configure. Create your Symfony form as usual, pass its FormView to Twig, and use form_summary().

Version 1.0.0 targets PHP 8.2+ and compatible Symfony 6.4, 7.4, and 8.x applications. The repository's CI matrix covers combinations of PHP 8.2–8.5 and Symfony 6.4, 7.4, 8.0, and 8.1, as well as lower supported dependency versions and installation of the exported package without development dependencies.

The test suite includes 94 PHPUnit tests with 214 assertions. Among the tested behaviors are escaping, translated choice labels, excluded fields, zero and false values, compound dates, and compatibility with editable form themes.

Tests cannot guarantee that every custom form behaves identically, but they provide a useful baseline for maintaining a small public API.

For the full option reference, supported field types, theme overrides, and known limitations, see the README.

A final thought

The most satisfying part of this project was not creating a new rendering system. It was realizing that Symfony already gives us much of what we need.

There is a place for dedicated, carefully designed templates. There is also a place for a small utility that removes a repeated task without changing how the rest of an application works.

When the form already describes the information we want to show, reusing that description can be simpler than writing it all again.

That is the entire idea behind FormSummaryBundle.

The source is available on GitHub, and the package is available on Packagist. Feedback is welcome, particularly from developers working with nested forms and custom field types. Those are often the places where a small abstraction reveals both its value and its limits.

Applying Kaizen Thinking to Symfony Debugging

Alkin Veysal — Sat, 10 Oct 2026 07:13:02 +0000

A small open-source experiment in understanding recurring log issues, documenting investigations, and reviewing improvements.

Introducing Novora KaizenBundle 1.0 — a small, Lean-inspired approach to investigating recurring application issues.

When working on a Symfony application, logs are often the first place we look when something goes wrong.

We find an exception, investigate it, make a correction, and move on.

But sometimes the same issue returns. Or we discover that a particular warning has been appearing for days without anyone noticing how frequently it occurs.

That made me interested in a simple question:

Could we make the process of identifying, investigating, and reviewing recurring problems a little more structured, without introducing another monitoring platform?

This question led to Novora KaizenBundle, a small open-source package for Symfony.

Version 1.0 is now available on Packagist.

The idea behind the bundle

In Lean thinking, Kaizen describes continuous improvement through observation, analysis, and incremental changes.

These principles are not new, and neither are the techniques used in this bundle.

Pareto analysis, Ishikawa diagrams, the 5 Whys, and PDCA have existed for a long time. Error grouping and monitoring are also well-established areas of software engineering.

The intention here is not to reinvent them or replace existing tools.

Instead, I wanted to explore how a few of these ideas might fit into an everyday Symfony troubleshooting workflow.

The result is a deliberately small application-level tool with three main steps.

1. Identify recurring patterns

Novora KaizenBundle reads existing Monolog log files and groups records using fingerprints derived from their severity, channel, and message.

It applies limited normalization to certain dynamic values, such as UUIDs and timestamps, before grouping.

The dashboard uses a Pareto-style chart to show which patterns occur most frequently within the available log sample.

This can help answer a modest but useful question:

Which recurring technical symptoms might deserve attention first?

Frequency is not the same as importance. A rarely occurring exception may have a far greater impact than a frequently logged warning.

The chart is a starting point for investigation, not an automatic priority decision.

2. Document the investigation

Once a recurring pattern looks worth examining, a developer can open an investigation.

The bundle provides a small workspace inspired by familiar Lean techniques:

Gemba: record what was actually observed.
Ishikawa: organize possible contributing causes.
5 Whys: explore the reasoning behind a problem.
PDCA: document the intended change, its implementation, observations, and follow-up actions.

These methods are aids, not mandatory rituals.

A small issue does not necessarily need a complete Ishikawa analysis or five written explanations.

One design decision I consider important is that a hypothesis cannot be marked as confirmed without supporting evidence.

The bundle does not discover root causes automatically. The developer remains responsible for determining whether the evidence is sufficient.

3. Review what happened after a change

Fixing an exception and observing that it no longer appears are two different things.

For investigations linked to a log fingerprint, the bundle allows a correction timestamp to be recorded.

It can then compare matching log-event counts over equal periods before and after that timestamp, using at most a 24-hour comparison window.

It also checks for later occurrences still present in the available sample.

This does not prove that a problem has been permanently resolved.

A quiet log might mean the correction helped. It might also mean the relevant operation was not executed again, or that older logs have already been rotated.

The bundle therefore reports the observed counts and limitations rather than automatically declaring success.

A small example

Consider this simplified, entirely synthetic log entry:

[2026-10-10T08:00:00+00:00] app.ERROR: Cache directory is not writable [] []

Suppose the same message appears repeatedly.

The dashboard can group those matching entries and make their frequency visible.

A developer may then open an investigation, check the actual filesystem permissions and process identity, and record the findings.

If the evidence supports a permission problem, the developer can document a corrective action.

After applying the correction, the developer records when it was made and reviews the matching log entries before and after that point.

If the same fingerprint appears again, there is a concrete reason to investigate further.

If it does not appear, the observation is recorded — but the case is not automatically considered resolved.

This example illustrates the intended workflow. It is not a production case study or evidence of measured time savings.

Keeping the implementation small

The bundle is built for PHP 8.2+ and Symfony 7.4 or 8.x.

It works with existing supported Monolog file formats, provides a small administrator interface, and stores investigations in local JSON files.

It does not require its own database schema, external APM server, or hosted telemetry service.

An optional correlation feature can attach execution identifiers to new HTTP, CLI, and Messenger log records, provided the host application has the appropriate Monolog integration.

Existing log entries are not retroactively correlated.

Installation is available through Composer:

composer require novora/kaizen-bundle:^1.0

The bundle must then be registered and configured in the Symfony application. The administrator routes require authentication and ROLE_ADMIN access, and the configured log and investigation directories need appropriate filesystem permissions.

The complete setup instructions are available in the README.

What version 1.0 does not do

There are important limitations worth making clear.

The bundle reads a bounded portion of a configured log file — 2 MiB by default — rather than collecting complete application history.

Its fingerprinting is heuristic. Different errors may occasionally be grouped together, while variations of the same underlying problem may form separate groups.

Its before-and-after comparison uses observed log counts, not traffic-normalized failure rates.

It does not provide distributed tracing, automatic root-cause analysis, alerting, or multi-server monitoring.

Investigation storage is local and intended for a single shared-writer environment. Display redaction is best-effort and should never be treated as permission to log credentials or personal information.

These are conscious limitations of the first version, not capabilities hidden behind a configuration option.

For many applications, an established monitoring or error-tracking platform will be the more appropriate choice.

Why release it?

There is no shortage of debugging tools, dashboards, or methodologies.

I do not expect this bundle to change that landscape.

The idea is simply to offer another small option for Symfony developers who already have application logs and would like a structured way to move from recurring technical symptoms to documented investigations.

Version 1.0 has automated tests and has been exercised in separate Symfony 7.4/PHP 8.2 and Symfony 8.1/PHP 8.4 test applications.

That verifies specific behavior and compatibility scenarios. It does not establish how much time the tool saves in real-world development teams.

I would rather learn that from actual users than make claims I cannot support.

If the bundle proves useful, it can improve incrementally. If parts of the workflow feel unnecessary, simplifying them may be more valuable than adding new features.

That, to me, is very much in the spirit of Kaizen.

Open source

Novora KaizenBundle 1.0 is available under the MIT License.

The source code, documentation, and tests are public:

GitHub: https://github.com/alkinbg/Novora-KaizenBundle

Packagist: https://packagist.org/packages/novora/kaizen-bundle

Feedback, bug reports, and focused contributions are welcome.

The goal is not to build the biggest tool — just something small enough to understand and useful enough to keep around.

Lean Software Development in Practice: Finding Muda in Four PHP Projects

Alkin Veysal — Mon, 28 Sep 2026 11:24:33 +0000

Lean has one word that I like because it is brutally simple: Muda.

Waste.

In a factory, waste is often visible. Extra movement. Waiting. Too much inventory. Producing something before it is needed.

In software, it is much better at hiding.

An unused abstraction does not block a corridor. A feature nobody asked for does not sit on a pallet. A public API that became too large does not look like inventory.

But all of them still cost something.

They have to be designed, written, tested, documented and maintained. And once other developers start depending on them, removing them becomes much harder than adding them.

That made me look at four of my own open-source PHP projects from a slightly different angle.

Three are Symfony bundles:

The fourth is a standalone CLI tool:

Doctrine Migration Guard

I have already written separate technical articles about all four projects:

This time, I do not want to explain again how the packages work.

The more interesting question is:

What did I deliberately choose not to build?

That is where the Lean part becomes interesting.

Muda is not the same as "more code"

This was the first thing I had to be careful about.

Lean software development does not mean deleting code until everything is small.

Sometimes more code is exactly what prevents a real failure.

For example, in HttpIdempotencyBundle the idempotency record is read again after acquiring the lock.

That is extra work.

It is also necessary.

Another request may have completed the operation between the first read and the moment the lock was acquired. Skipping the second read would make the code shorter, but also wrong.

The same happens in OptimisticConcurrencyBundle.

The HTTP layer checks If-Match, but Doctrine still performs its own optimistic-lock check during flush().

Two checks.

Two different race windows.

Both useful.

So the question is not:

How can this be done with fewer lines?

A better question is:

Does this complexity protect something real, or does it exist only because it might be useful one day?

That difference matters.

OptimisticConcurrencyBundle: do not build concurrency twice

Repository: github.com/alkinbg/optimistic-concurrency-bundle

Earlier article: Preventing Lost Updates in Symfony APIs with ETags and Doctrine

The bundle solves a specific problem: preventing stale clients from silently overwriting newer data.

A resource can expose an ETag:

#[EntityTag('document', scope: 'document-detail-v1')]
public function show(Document $document): JsonResponse
{
    // ...
}

and a write can require the client to send the same representation version back:

#[RequireIfMatch('document', scope: 'document-detail-v1')]
public function update(Document $document): JsonResponse
{
    // ...
}

There is an obvious temptation here.

Once you start solving concurrency, it is easy to keep going.

The bundle could maintain its own entity versions.

It could introduce its own locking mechanism.

It could control transactions.

It could call flush().

It could become "the concurrency layer".

But Doctrine already has optimistic locking through #[ORM\Version].

So the bundle does not replace it.

The HTTP layer answers:

Is the representation used by this client stale?

Doctrine answers:

Did the entity change before the database write completed?

That division is useful.

Building a second persistence-level concurrency system would not remove the need for Doctrine's protection. It would mostly add another implementation to understand and another set of failure cases to maintain.

That is a form of Muda I see quite often in software:

rebuilding something that another layer already does well.

There is another small detail in this project that I now appreciate more.

The supported public API is intentionally small.

Most implementation classes are internal, and there is an architecture test that protects that boundary.

Why care?

Because every public class is a promise.

If someone starts depending on it, changing it later becomes a backward-compatibility problem.

A large public API can easily become a kind of inventory: things you now have to keep carrying even when you no longer want them.

Sometimes the Lean choice is not removing code.

Sometimes it is simply not exposing it.

MaskedBundle: do not try to detect every secret in the universe

Repository: github.com/alkinbg/masked-bundle

Earlier article: I Made a Symfony Bundle for Masking Sensitive Data

MaskedBundle started from a practical problem.

Sensitive data can end up in logs.

Once you start thinking about automatic detection, the feature list grows very quickly.

Passwords.

API tokens.

JWTs.

Session IDs.

Private keys.

Database credentials.

Cloud access keys.

Payment data.

It is very easy to imagine a "smart" detector for all of them.

It is also very easy to create a large pile of heuristics.

The bundle takes a narrower approach.

Automatic detection is conservative and currently focuses on payment-card candidates where there is enough structure to make a reasonably confident decision.

When the application already knows a value is sensitive, it can pass it explicitly:

$masked = $sensitiveDataMasker->mask(
    'Authentication failed for token '.$token,
    sensitiveValues: [$token],
);

That design looks simple, but the reason behind it matters.

If the application already knows that $token is sensitive, the masking library does not need another complicated heuristic to rediscover that fact.

Trying to detect everything automatically would mean more regexes, more edge cases and, probably, more false confidence.

There is also another important choice in the implementation: detection work is bounded.

If a safety budget is exhausted, masking fails closed instead of continuing an expensive scan forever.

That is not "less code".

It is extra defensive code with a clear purpose.

The Muda would be adding twenty more speculative detectors just because the architecture allows it.

This is one of the traps I have started to notice more often:

A good abstraction makes new features easy.

And when new features are easy, it becomes very tempting to add them.

But "easy to add" and "worth adding" are not the same thing.

Doctrine Migration Guard: "I don't know" can be a valid result

Repository: github.com/alkinbg/doctrine-migration-guard

Earlier article: Catching Risky Doctrine Migrations Before Production

Doctrine Migration Guard is probably the clearest example of scope control in these four projects.

Its job is simple to describe:

Check Doctrine migration files for risky MySQL and MariaDB operations before they reach production.

The dangerous part is everything that could be added around that idea.

The tool could connect to the database.

It could inspect table size.

It could understand server versions.

It could discover pending migrations.

It could support PostgreSQL.

It could have a plugin system.

It could read Git history.

It could rewrite dangerous SQL.

Every one of those ideas sounds reasonable.

That does not mean they belong in version 0.1.

The first release intentionally understands a narrow migration shape.

This is straightforward:

$this->addSql(
    'ALTER TABLE users ADD nickname VARCHAR(64) DEFAULT NULL'
);

This is not:

$sql = 'ALTER TABLE users ADD nickname VARCHAR(64)';
$this->addSql($sql);

The tool does not try to guess what dynamic PHP code will do.

It reports the result as incomplete.

The same happens with SQL constructs that the current analyzer cannot classify safely.

They become UNANALYZED.

At first glance, this looks like weakness.

I think it is the opposite.

A static analyzer that understands only part of a construct and still returns green is more dangerous than one that says:

I don't know.

This is where Lean and safety meet quite nicely.

Supporting every possible migration shape would require much more parsing, much more testing and many more edge cases.

If the actual value of the first release is catching common risky migrations in CI, then building everything else before that idea proves useful is simply overproduction.

Software people often call that future-proofing.

Sometimes it really is.

Sometimes it is just work arriving too early.

HttpIdempotencyBundle: do not promise exactly-once when you cannot deliver it

Repository: github.com/alkinbg/http-idempotency-bundle

Earlier article: When HTTP Retries Become Dangerous: Idempotency in Symfony Without the Fairy Tales

Idempotency is another area where it is very easy to over-promise.

The bundle protects selected controller actions from accidental duplicate execution when clients retry HTTP requests.

Protection is explicit:

#[Idempotent]
public function createOrder(): JsonResponse
{
    // ...
}

It could have been automatic.

For example:

"Every POST, PUT and PATCH should be idempotent."

That sounds convenient.

It is also a huge assumption.

Not every endpoint has the same semantics. Automatically changing every write request would make the bundle responsible for application behavior it cannot fully understand.

So the controller has to opt in.

More importantly, the bundle does not claim exactly-once execution.

Because it cannot guarantee it.

Imagine this:

A controller calls an external payment provider.

The payment succeeds.

Before the completed idempotency record is saved, the PHP process crashes.

The side effect has already happened.

No Symfony event subscriber can travel back in time and undo that payment.

Adding more internal machinery does not change this fundamental failure window.

So the bundle handles the part it can actually control:

request identity, fingerprints, shared state, locking and response replay.

Other guarantees remain where they belong:

database constraints, transactions, provider-side idempotency, outbox patterns and domain-specific protection.

For me, this is another form of Lean thinking:

do not spend complexity trying to create a guarantee your layer cannot honestly provide.

More code would not make the promise true.

It would only make the implementation bigger.

The interesting part was not what the projects contain

After looking at the four repositories this way, something surprised me.

I expected the best examples of Muda to be dead code, duplicated methods or unnecessary classes.

Those things matter.

But the more interesting waste appears earlier.

It appears when deciding what the software should become.

In OptimisticConcurrencyBundle, the important decision was not to replace Doctrine.

In MaskedBundle, it was not to pretend every type of secret can be detected automatically.

In Doctrine Migration Guard, it was not to support every migration shape in the first release.

In HttpIdempotencyBundle, it was not to enable idempotency everywhere and not to claim exactly-once execution.

None of those decisions look impressive in an architecture diagram.

That may be exactly why they are easy to miss.

Sometimes avoiding waste does not result in a clever class.

Sometimes the result is that the class never gets written.

A small checklist before adding "just one more thing"

These are the questions I now try to ask before adding another feature, abstraction or extension point:

Is there a real use case now, or only a possible future one?
Does another layer already solve this problem?
Am I adding an abstraction before I have a second real case for it?
Am I making the public API larger than necessary?
If I cannot know something safely, is "unknown" better than a guess?
Will this feature create enough value to justify its tests, documentation and future compatibility cost?

I do not always get this right.

Building things is enjoyable. That is part of the problem.

A generic solution feels elegant.

A new extension point feels flexible.

Another supported scenario makes the README look stronger.

But every feature creates work after it is merged.

That part is much less exciting, and much easier to forget.

One final thought

Lean and software development are not a perfect translation of each other.

Code is not a production line, and forcing every programming problem into one of the classic Lean wastes would not be very useful.

But the basic idea behind Muda translates extremely well:

Effort is not the same as value.

A complicated solution can be necessary.

A simple solution can be wrong.

The goal is not minimal code.

The goal is to spend complexity where it protects something real.

That changed one question for me.

Instead of always asking:

What else should this support?

there is another question that is often more useful:

What happens if this is not built?

Sometimes the answer is:

Nothing.

And sometimes that is the best possible result.

When HTTP Retries Become Dangerous: Idempotency in Symfony Without the Fairy Tales

Alkin Veysal — Sun, 30 Aug 2026 21:12:29 +0000

Retries are one of those things that look harmless until the first time they duplicate a real business operation.

A request times out, so the client retries it.

Reasonable.

But what if the first request actually reached the server?

What if the application already created the order, reserved the stock, sent the message, or called a payment provider — and only the response was lost?

From the client's point of view, the request failed.

From the application's point of view, it may already be finished.

Send the same request again and you can get the worst kind of bug: one that is technically understandable, difficult to reproduce, and very expensive in production.

This is the problem that pushed me to build HttpIdempotencyBundle, a small Symfony bundle for explicit HTTP request idempotency.

But the interesting part is not the bundle itself.

The interesting part is everything that has to be true before we can safely say:

"This request is a retry of the same operation, so we should not execute it again."

And just as importantly, what we cannot guarantee.

A timeout does not mean the operation failed

Consider a simple endpoint:

#[Route('/orders', methods: ['POST'])]
public function createOrder(): JsonResponse
{
    $order = $this->orderService->create();

    return new JsonResponse([
        'id' => $order->getId(),
    ], 201);
}

Now imagine this sequence:

Client -> POST /orders
Server -> creates order #742
Server -> sends 201 response
Network -> connection dies
Client -> sees timeout
Client -> retries POST /orders

Nothing unusual happened.

The client did exactly what clients often do after a timeout.

The server did exactly what it was asked to do.

And yet, unless we have another mechanism in place, we may now create order #743 as well.

The key idea is simple:

transport failure and business-operation failure are not the same thing.

HTTP cannot always tell the client whether the operation happened.

Give the operation an identity

A common solution is an Idempotency-Key.

The client generates a unique value for one logical operation and sends it with every retry:

POST /orders HTTP/1.1
Content-Type: application/json
Idempotency-Key: order-7f98b773

{"sku":"ABC-42","quantity":1}

If the request must be retried, the same key is reused.

That gives the server a stable identity to work with.

At first, the implementation seems obvious:

if ($store->has($key)) {
    return $store->get($key);
}

$response = $controller();

$store->save($key, $response);

return $response;

Unfortunately, this is not enough.

There are several traps hiding inside those few lines.

A key alone is not enough

What should happen if a client accidentally reuses the same key for a different request?

First request:

Idempotency-Key: order-7f98b773

{"sku":"ABC-42","quantity":1}

Later:

Idempotency-Key: order-7f98b773

{"sku":"XYZ-99","quantity":10}

If we only store the key, the second request might receive the response from the first one.

That would be worse than simply failing.

The server must therefore know not only which key was used, but also which request that key belongs to.

This is where request fingerprinting becomes important.

Fingerprint the request, not just the key

A deterministic fingerprint can describe the concrete request.

For HttpIdempotencyBundle, the default fingerprint includes the important parts of the request, such as:

HTTP method
logical operation
path
normalized query parameters
normalized Content-Type
raw request body

The result is represented as a SHA-256 digest.

Conceptually:

POST
/orders
application/json
{"sku":"ABC-42","quantity":1}

becomes:

sha256(...)

Now there are two very different cases.

Same key, same fingerprint

This is the same logical request again.

If the first request already completed, we can replay its stored response.

Same key, different fingerprint

The key is being reused for another request.

That should not silently replay anything.

In the bundle, this becomes:

422 Unprocessable Content

This is an important detail.

Idempotency should protect us from duplicate execution, not hide application bugs.

The race condition in the obvious solution

Now we get to the part that makes idempotency a concurrency problem.

Imagine two identical requests arrive at almost the same time.

Worker A:

read -> no record

Worker B:

read -> no record

Worker A executes the controller.

Worker B executes the controller too.

Both workers followed the logic correctly.

The result is still wrong.

A cache lookup alone cannot serialize concurrent execution.

We need coordination.

Shared state and a shared lock

The bundle uses two separate pieces:

shared idempotency state
Symfony Lock

Both must really be shared across the application.

That distinction matters in production.

If you run multiple PHP workers, containers, or application nodes, a local in-memory cache or a local filesystem lock cannot coordinate all of them.

Redis is one practical option:

framework:
    cache:
        pools:
            cache.http_idempotency:
                adapter: cache.adapter.redis
                provider: '%env(REDIS_URL)%'

    lock:
        http_idempotency: '%env(REDIS_URL)%'

http_idempotency:
    cache_pool: cache.http_idempotency
    lock_factory: lock.http_idempotency.factory

Redis itself is not the requirement.

Shared visibility is the requirement.

Every application instance participating in the same operation must see the same idempotency state and the same locking mechanism.

The second read is easy to miss

There is a subtler race condition.

Suppose request A and request B both perform their first read before either one obtains the lock.

A: read -> no record
B: read -> no record

A gets the lock first.

It executes the controller, stores the completed response, and releases the lock.

B then acquires the lock.

If B trusts its old read, it still believes there is no record.

So it could execute the controller again.

The fix is small but essential:

Read the idempotency record again after acquiring the lock.

The simplified flow becomes:

read record

completed + same fingerprint
    -> replay

completed + different fingerprint
    -> 422

try to acquire lock

lock unavailable
    -> 409

lock acquired

read record again

completed + same fingerprint
    -> replay

completed + different fingerprint
    -> 422

still no record
    -> save processing marker
    -> execute controller
    -> store completed response
    -> release lock

That second read closes the race between the initial lookup and lock acquisition.

It is only one extra read.

It is also one of the most important reads in the whole implementation.

Why the lock is non-blocking

There is another design choice: should a duplicate request wait until the first request finishes?

It can.

But that also means tying up a worker while another request is running, with latency controlled by somebody else's operation.

HttpIdempotencyBundle uses non-blocking lock acquisition.

If another request is already processing the same idempotency identity, the duplicate request gets:

409 Conflict

The client can then decide whether and when to retry.

I prefer this because the behavior is explicit and request latency remains predictable.

"Same key" should not mean "same key globally"

Suppose two authenticated users both happen to send:

Idempotency-Key: request-123

They should not collide with each other.

So the real identity cannot be just the raw idempotency key.

Conceptually, the bundle derives an identity from:

scope + operation + key

The operation tells us which protected application action this belongs to.

The scope separates independent principals.

For authenticated Symfony users, the default scope includes the user identity.

Anonymous requests use a shared anonymous scope by default.

Applications that need a different definition can provide their own scope resolver.

This matters especially for endpoints where authentication happens somewhere else in the stack or where multiple logical principals share the same anonymous HTTP context.

Response replay is more complicated than serialization

Suppose the first execution returns:

HTTP/1.1 201 Created
Content-Type: application/json

{"id":742}

An identical retry should be able to receive that application result without running the controller again.

But an HTTP response contains more than application data.

Some headers belong to the original connection or original request environment.

For example:

Connection
Content-Length
Date
Server
Transfer-Encoding
Set-Cookie

Blindly storing and replaying the whole response would copy things that should be generated again.

Cookies are particularly sensitive here.

A response cookie from the original request should not accidentally become part of a cached idempotency replay.

The bundle therefore stores a controlled response snapshot rather than serializing the entire Symfony Response object.

On replay, normal Symfony response listeners still get a chance to generate fresh request-specific behavior.

This keeps the idempotency layer focused on the reusable application result.

What about application errors?

Here is another question that does not have an obvious answer at first:

If the controller runs and returns a 4xx or 5xx response, should a retry execute the controller again?

Not necessarily.

The important distinction is whether the application operation completed versus whether the idempotency infrastructure failed.

If the controller genuinely executed and returned an application response, the bundle treats that as a completed execution that can be replayed.

That avoids turning every application error into another execution attempt.

Infrastructure failures are different.

If the idempotency store or lock backend fails before the controller can safely run, the bundle fails closed:

503 Service Unavailable

If an endpoint explicitly requires idempotency protection, silently continuing without that protection would be a dangerous fallback.

A processing marker is useful after crashes

A lock protects concurrent execution while the process is alive.

But processes crash.

The application can die after marking the operation as in progress and before storing the completed response.

For that reason, the bundle also uses a processing marker with a TTL.

The marker is intentionally not eagerly removed during abnormal cleanup.

Its expiration creates a bounded recovery window.

During that period, retries do not immediately re-execute an operation whose previous execution may still have produced an external side effect.

This does not eliminate every failure mode.

It makes the failure behavior more controlled.

The part that should never be hidden: this is not exactly-once

This is the most important limitation in the whole design.

Imagine:

1. controller calls an external payment provider
2. payment succeeds
3. PHP process crashes
4. completed idempotency response is never stored

The business side effect happened.

The HTTP idempotency layer did not get the chance to record completion.

After the processing marker eventually expires, a retry may execute the operation again.

That failure window exists.

A middleware, bundle, cache, or distributed lock cannot simply wish it away.

So HTTP idempotency should not be sold as "exactly-once execution".

For important writes, it should be combined with domain-level guarantees such as:

database unique constraints
transactions
provider-level idempotency
transactional outbox patterns
durable jobs
domain-specific deduplication

For example, if a payment provider supports its own idempotency key, use it.

The HTTP idempotency layer and the provider-level guarantee solve related but different parts of the problem.

This is one reason I wanted the limitation to be prominent in the documentation rather than hidden in a footnote.

Making the choice explicit in Symfony

I also did not want the bundle to automatically change every POST, PUT, or PATCH endpoint.

Idempotency is an application decision.

It should be visible in the controller:

use Alkin\\HttpIdempotencyBundle\\Attribute\\Idempotent;

#[Route('/orders', methods: ['POST'])]
#[Idempotent]
public function createOrder(): JsonResponse
{
    // Perform the application operation.

    return new JsonResponse([
        'created' => true,
    ], 201);
}

Unmarked controllers are not touched.

That makes the behavior easy to discover during code review.

You can look at the endpoint and immediately see that retries are part of its contract.

Failure behavior should be boring

One of my goals was to make the failure model small enough to reason about.

For protected controllers, the bundle uses a few clear outcomes:

Status	Meaning
`400 Bad Request`	Missing or invalid idempotency key
`409 Conflict`	The same operation is already processing, or its lock cannot be acquired
`422 Unprocessable Content`	The key was reused for a different request fingerprint
`503 Service Unavailable`	The idempotency storage or locking infrastructure cannot safely protect the operation

The interesting thing is not the exact status code list.

It is that the implementation tries to fail explicitly rather than silently weakening the guarantee.

Why I turned this into a bundle

The original problem sounds small:

"Do not execute the same retried HTTP request twice."

But following it far enough touches:

request identity
request fingerprinting
concurrency
distributed locking
shared state
response replay
HTTP headers
authenticated scope
process crashes
failure recovery
the boundary between transport guarantees and business guarantees

That made it a useful problem to isolate into a small Symfony component.

The first stable release is now available as:

composer require alkinbg/http-idempotency-bundle

It supports:

PHP >= 8.2
Symfony 7.4 or 8.1

The public repository is here:

github.com/alkinbg/http-idempotency-bundle

And the package is on Packagist:

packagist.org/packages/alkinbg/http-idempotency-bundle

Final thought

Retries are not the enemy.

They are a normal part of distributed systems.

The dangerous part is pretending that a timeout tells us what happened on the other side.

A good idempotency mechanism gives the server enough information to recognize the same logical request, enough coordination to stop concurrent duplicate execution, and a clear enough failure model that we still understand what can go wrong.

That last part matters.

Because in distributed systems, the most useful guarantee is often not the one that sounds strongest.

It is the one whose limits you can explain.

Catching Risky Doctrine Migrations Before Production

Alkin Veysal — Fri, 28 Aug 2026 07:28:55 +0000

Database migrations are one of those things that often look harmless during code review.

A migration may contain only a few lines of SQL, the application tests are green, and everything seems ready to deploy.

But a small migration can still contain something like this:

public function up(Schema $schema): void
{
    $this->addSql('ALTER TABLE users DROP COLUMN legacy_code');
}

Or this:

public function up(Schema $schema): void
{
    $this->addSql('DELETE FROM audit_log');
}

Both are valid migrations.

They may even be intentional.

But they are also operations that deserve more attention before they reach production.

That is the problem I wanted to make easier to catch in CI.

The gap between valid and safe-looking

Doctrine Migrations does its job well: it gives us a structured way to manage database changes.

But Doctrine does not try to decide whether our SQL is risky.

And normal PHP static analysis is usually not interested in the meaning of SQL inside:

$this->addSql('...');

So a migration can be perfectly valid PHP and still contain a database change that should stop a deployment for review.

For example:

$this->addSql(
    'ALTER TABLE customers ADD external_id VARCHAR(255) NOT NULL'
);

Adding a NOT NULL column without a default may be completely reasonable in one situation and problematic in another.

The important point is not to automatically declare it "unsafe".

The important point is to notice it before deployment.

That idea became Doctrine Migration Guard.

What Doctrine Migration Guard does

Doctrine Migration Guard is a small standalone CLI tool for static analysis of Doctrine migrations targeting MySQL and MariaDB.

It does not boot Symfony.

It does not connect to your database.

It does not execute your migrations.

It parses the migration source code, looks at supported addSql() calls inside up(), and classifies recognized SQL operations by risk.

Install it as a development dependency:

composer require --dev alkinbg/doctrine-migration-guard

Then analyze your migrations:

vendor/bin/doctrine-migration-guard migrations/

You can also analyze one migration:

vendor/bin/doctrine-migration-guard \
    migrations/Version20260828090000.php

Or several files:

vendor/bin/doctrine-migration-guard \
    migrations/A.php \
    migrations/B.php

Risk levels instead of a simple yes/no

I did not want the tool to pretend that database migration safety can be reduced to a boolean.

Instead, findings have different levels:

Level	Example
`INFO`	Creating a table or adding a nullable column
`WARNING`	Normal index, foreign key operation, or data change with a top-level `WHERE`
`HIGH`	`UPDATE` without a top-level `WHERE`, rename, unique index, or some `NOT NULL` additions
`CRITICAL`	`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, or `DELETE` without a top-level `WHERE`
`UNANALYZED`	The tool cannot classify the construct reliably

The last one is especially important.

Fail closed instead of guessing

Static analysis becomes dangerous when the tool starts pretending it understands code that it actually does not understand.

Consider:

$sql = getMigrationSql();

$this->addSql($sql);

Doctrine Migration Guard cannot know what getMigrationSql() returns without executing application code.

So it does not guess.

The migration becomes INCOMPLETE.

The same principle applies to unsupported control flow and ambiguous SQL.

For example, a multi-action statement like this is intentionally not partially classified:

ALTER TABLE users
    ADD last_login_at DATETIME DEFAULT NULL,
    ADD last_seen_at DATETIME DEFAULT NULL

It would be easy to inspect the first action and produce a result.

It would also be misleading.

For the first release, I prefer a conservative answer:

I cannot analyze this reliably.

That is much more useful in CI than a false green result.

Doctrine lifecycle hooks need the same treatment

Doctrine migrations can also contain lifecycle methods such as:

public function preUp(Schema $schema): void
{
    $this->addSql('DROP TABLE old_users');
}

Version 0.1 does not analyze preUp() or postUp().

If one of these hooks is overridden, the migration becomes INCOMPLETE.

Supported SQL inside up() is still analyzed and reported, but the complete migration cannot be considered fully analyzed.

Again, the goal is not to pretend that unsupported code does not exist.

Useful exit codes for CI

The CLI uses deterministic exit codes:

0 = PASSED
1 = FAILED
2 = INCOMPLETE

FAILED means at least one HIGH or CRITICAL finding was detected.

INCOMPLETE has higher priority because some part of the input could not be analyzed reliably.

That makes it easy to add the tool to CI.

For example, to analyze migrations changed on a branch:

git diff --name-only origin/main...HEAD -- 'migrations/*.php' \
    | xargs -r vendor/bin/doctrine-migration-guard

Or, if the number of migrations is reasonable, simply scan the entire directory:

vendor/bin/doctrine-migration-guard migrations/

There is also JSON output for automation:

vendor/bin/doctrine-migration-guard \
    --format=json \
    migrations/

The JSON format currently uses schema version 1.

What it deliberately does not do

This part matters.

Doctrine Migration Guard does not know your table size, production workload, MySQL configuration, MariaDB version, execution plan, lock duration, or deployment strategy.

It also does not inspect a live database.

That means:

PASSED

does not mean:

This migration is guaranteed to be safe in production.

It means that the migration was fully analyzed under the supported static rules and no blocking finding was detected.

That is a much narrower promise, but it is one I am comfortable making.

Why I started small

It would be easy to add database connections, configuration files, suppression systems, custom plugins, Git integration, automatic fixes, PostgreSQL support, and many other features.

I intentionally did not start there.

For the first version I wanted something that is:

small, deterministic, CI-friendly, easy to understand, and conservative when it is uncertain.

The tool currently supports PHP 8.1 through PHP 8.5 and has no Symfony runtime dependency.

Symfony developers can use it, but it remains a standalone CLI tool.

Try it

The first public release is now available:

GitHub:

https://github.com/alkinbg/doctrine-migration-guard

Packagist:

https://packagist.org/packages/alkinbg/doctrine-migration-guard

Install it with:

composer require --dev alkinbg/doctrine-migration-guard

This is still an early 0.x project, so feedback is very welcome — especially real Doctrine migrations where the current rules produce an unexpected result.

For me, the interesting part is not trying to make migrations magically safe.

It is adding one more useful review step before risky database changes reach production.

Preventing lost updates in Symfony APIs with ETags and Doctrine

Alkin Veysal — Sat, 22 Aug 2026 16:38:18 +0000

There is a concurrency problem in APIs that is easy to miss.

Two clients read the same resource:

Client A -> GET /documents/42
Client B -> GET /documents/42

Both receive the same version.

Client A changes the title and saves it.

Then Client B, still working with the older representation, sends another update.

Without a concurrency check, the second request can overwrite the first one without knowing that the resource changed in the meantime.

This is the classic lost update problem.

Doctrine versioning is important, but there is another part

Doctrine supports optimistic locking with a version field:

use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class Document
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 180)]
    private string $title;

    #[ORM\Version]
    #[ORM\Column(type: 'integer')]
    private int $version;
}

Doctrine's version field already provides the persistence-level optimistic locking mechanism.

It can also be used directly as the client-side concurrency token. An API could expose the version, have the client send it back with the update, and use that value as Doctrine's expected version. That is a perfectly valid approach, and ETags are not required to prevent lost updates.

For this bundle, I wanted to keep the persistence version out of the API representation and express the same precondition using standard HTTP semantics instead.

I want the client to say:

Update this resource only if it is still the version I previously received.

HTTP already has a mechanism for exactly this: ETag and If-Match.

Using an ETag when reading the resource

I built OptimisticConcurrencyBundle to connect these HTTP semantics with Doctrine versioned entities.

A read endpoint can be marked with #[EntityTag]:

use OptimisticConcurrency\Bundle\Attribute\EntityTag;
use Symfony\Component\HttpFoundation\JsonResponse;

#[EntityTag('document', scope: 'document-detail-v1')]
public function show(Document $document): JsonResponse
{
    return new JsonResponse([
        'id' => $document->getId(),
        'title' => $document->getTitle(),
    ]);
}

The response receives a strong ETag:

HTTP/1.1 200 OK
ETag: "oc1-..."

The default validator is based on the entity identity, its Doctrine version and the optional representation scope.

The actual database ID and version are not exposed directly in the header.

Requiring the same version on update

The write endpoint uses #[RequireIfMatch]:

use Doctrine\ORM\EntityManagerInterface;
use OptimisticConcurrency\Bundle\Attribute\RequireIfMatch;
use Symfony\Component\HttpFoundation\JsonResponse;

#[RequireIfMatch('document', scope: 'document-detail-v1')]
public function update(
    Document $document,
    EntityManagerInterface $entityManager,
): JsonResponse {
    $document->rename('New title');

    $entityManager->flush();

    return new JsonResponse([
        'id' => $document->getId(),
        'title' => $document->getTitle(),
    ]);
}

The client sends back the ETag it received when reading the resource:

PATCH /documents/42
If-Match: "oc1-..."
Content-Type: application/json

If the resource still has the same version, the request continues normally.

If somebody changed it in the meantime:

HTTP/1.1 412 Precondition Failed

If the client does not send If-Match at all:

HTTP/1.1 428 Precondition Required

Malformed conditional headers are rejected with 400 Bad Request.

Why there are two checks

This was the part I cared about most when implementing the bundle.

Checking If-Match before executing the controller is useful, but it is not enough.

Imagine this sequence:

1. If-Match is checked
2. The version is correct
3. Another request updates the row
4. Our controller calls flush()

There is still a race window between steps 1 and 4.

For this reason the bundle does not try to replace Doctrine optimistic locking.

It uses both mechanisms:

HTTP If-Match check
        |
        v
controller executes
        |
        v
Doctrine #[ORM\Version] check during flush()

The HTTP check rejects a request that was already stale when it arrived.

The Doctrine version check protects the final database write if another update happens after the HTTP check.

If Doctrine detects an optimistic lock conflict during flush(), the bundle converts it to 412 Precondition Failed.

I think keeping both responsibilities separate is important.

HTTP handles the client's representation.

Doctrine remains responsible for the atomic database update.

ETags represent representations

There is another detail that is easy to overlook.

An ETag validates a representation, not simply a database row.

For a simple API, entity identity + version may be enough.

But imagine that the response also depends on:

locale;
serializer groups;
related entities;
user-specific fields;
query parameters.

If those values can change without increasing the entity version, the default ETag is no longer enough to describe the complete representation.

For that reason the bundle supports an explicit scope and a custom EntityTagProviderInterface.

I prefer making this limitation explicit instead of pretending that one Doctrine version field can describe every possible HTTP representation.

A deliberate limitation: hard deletes

There is one case I intentionally don't support: normal Doctrine hard deletes.

Doctrine's standard DELETE operation does not include the optimistic-lock version in the SQL WHERE condition.

That means an If-Match check before the controller would still leave a race window before the actual delete.

So #[RequireIfMatch] rejects HTTP DELETE requests instead of providing a concurrency guarantee that is not really there.

A versioned soft delete is different because it goes through Doctrine's version-checked UPDATE path.

A practical Symfony UX Turbo example

This problem is not limited to JSON APIs.

I ran into the same kind of situation in a Symfony application using UX Turbo.

Imagine an operator opens a reservation page while the entity is at version 12.

Another operator opens the same reservation and changes its status. Doctrine updates the entity and its version becomes 13.

The first browser still has the old page open.

Browser A                        Browser B

GET reservation v12             GET reservation v12
                                 |
                                 change status
                                 |
                                 POST
                                 |
                                 reservation -> v13

old Turbo form still open
|
POST old state

Without a concurrency check, the old form can submit data based on version 12 even though version 13 already exists.

The important part is that Turbo does not change the concurrency problem. It makes navigation and form submissions nicer, but the server still receives an HTTP request that may have been created from stale state.

So the same idea can be used.

When the page is rendered, the current validator is associated with the form. On submission, a small Stimulus integration can send it as:

If-Match: "oc1-..."

If the reservation has not changed, the request continues normally.

If another operator changed it first, the server responds:

HTTP/1.1 412 Precondition Failed

Instead of silently overwriting the newer data, the UI can then tell the user that the reservation changed and should be refreshed.

For me this is one of the useful properties of using HTTP preconditions for concurrency: the same contract works for an API client and for an interactive Symfony application using Turbo.

Turbo improves the interaction.

If-Match tells the server which version that interaction was based on.

Doctrine still protects the final database write.

Installation

The bundle can be installed with Composer:

composer require alkinbg/optimistic-concurrency-bundle

It currently supports:

PHP 8.2+
Symfony 7.4 LTS and 8.1+
Doctrine ORM 3.4.4+

No bundle configuration is required.

The project is MIT licensed:

https://github.com/alkinbg/optimistic-concurrency-bundle

https://packagist.org/packages/alkinbg/optimistic-concurrency-bundle

If you build Symfony APIs and have dealt with lost updates differently, I'd be interested to hear how you handle it.

I made a Symfony bundle for masking sensitive data

Alkin Veysal — Sat, 22 Aug 2026 10:14:31 +0000

I recently released a small open-source Symfony bundle called MaskedBundle.

The reason for building it was quite simple: logs are useful, but sometimes they can contain values that should not be there.

I wanted something I could reuse in Symfony projects to mask sensitive values before they reach logs or other diagnostic output.

Basic usage

Installation:

composer require alkinbg/masked-bundle

For example:

use Masked\Bundle\SensitiveDataMasker;

final class PaymentService
{
    public function __construct(
        private readonly SensitiveDataMasker $masker,
    ) {
    }

    public function example(): string
    {
        return $this->masker->mask(
            'Card: 4111111111111111',
        );
    }
}

The result:

Card: ████████████████

At the moment automatic detection focuses on payment card numbers.

I deliberately don't try to automatically detect every possible token, password or secret. There are too many formats and guessing can easily produce false positives.

Instead, values known by the application can be passed explicitly:

$token = 'secret-access-token';

$masked = $sensitiveDataMasker->mask(
    'Authentication failed for token ' . $token,
    sensitiveValues: [$token],
);

Result:

Authentication failed for token ███████████████████

Both approaches can be used together.

Arrays and logs

There is also a StructuredDataMasker for arrays:

$masked = $structuredDataMasker->mask([
    'customer' => [
        'card' => '4111111111111111',
    ],
]);

The bundle also has optional Monolog integration, so messages and context can be masked before they are written to the log.

I kept the Monolog part optional because the masking services can also be useful on their own.

One thing I cared about

Because this code handles sensitive data, I didn't want unusual input to result in partially checked data being returned.

There are limits for things like very large arrays and explicit-value searches. If a detection budget is exceeded, the masking operation prefers to fail closed.

It adds some complexity internally, but I think it is the safer behaviour for this kind of library.

That's it

MaskedBundle currently requires PHP 8.4.1+ and Symfony 8.1+.

It is MIT licensed:

https://github.com/alkinbg/masked-bundle

https://packagist.org/packages/alkinbg/masked-bundle

If you use Symfony and have any feedback, I'd be happy to hear it.

DEV Community: Alkin Veysal

Poka-Yoke in PHP: Guarding Business Operations Before They Run

The problem is not just validation

A minimal API

Put the action behind the guard

Where this pattern is useful

What Poka-Yoke cannot guarantee here

Testing the contract

A modest conclusion

Bulk Editing in EasyAdmin 5: A Review-and-Confirm Workflow for Doctrine Entities

The difference between a batch action and bulk editing

A deliberately small scope

Installation

Connecting a CRUD controller

A small UX detail that matters

What happens between selection and confirmation?

Why use Doctrine entities instead of one DQL UPDATE?

What about concurrent changes?

Testing the behavior, not just the helpers

Lessons from making it reusable

When Counting Overlapping Bookings Is Not Enough: Capacity-Aware Availability in PHP

The trap: overlap is not concurrency

Model time explicitly

Sweep-line: look only where the state changes

Trying it in PHP

The important distinction: available is not reserved

Testing two different kinds of correctness

Why this isn't a Symfony bundle

Where it stops

Unsaved Form Changes in Symfony — With and Without Turbo

Why beforeunload alone is not quite enough

Add it to a Symfony form

It is not limited to Symfony Forms

A change is not the same as a touched field

What happens with Turbo?

Submission and custom JavaScript

What this does not promise

Testing beyond a single browser

A small convenience, not another form framework

One Symfony Form, Two Views: Read-Only Summaries Without Duplication

The duplication is easy to miss

Symfony already gives us most of the ingredients

A complete example

Why this is more than a loop over fields

Choice fields

Dates and times

Nested forms and collections

Missing values

You do not have to summarize the whole form

Two kinds of customization

1. Control the value at the form level

2. Control the markup with a form theme

The security boundary is worth stating clearly

When I would use it — and when I would not

What the bundle deliberately does not do

Installation and compatibility

A final thought

Applying Kaizen Thinking to Symfony Debugging

The idea behind the bundle

1. Identify recurring patterns

2. Document the investigation

3. Review what happened after a change

A small example

Keeping the implementation small

What version 1.0 does not do

Why release it?

Open source

Lean Software Development in Practice: Finding Muda in Four PHP Projects

Muda is not the same as "more code"

OptimisticConcurrencyBundle: do not build concurrency twice

MaskedBundle: do not try to detect every secret in the universe

Doctrine Migration Guard: "I don't know" can be a valid result

HttpIdempotencyBundle: do not promise exactly-once when you cannot deliver it

The interesting part was not what the projects contain

A small checklist before adding "just one more thing"

One final thought

When HTTP Retries Become Dangerous: Idempotency in Symfony Without the Fairy Tales

A timeout does not mean the operation failed

Give the operation an identity

A key alone is not enough

Why `beforeunload` alone is not quite enough