DEV Community: Alkin Veysal

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.