[rfc] str_mask function

در تاریخ جمعه ۱۸ سپتامبر ۲۰۲۶، ۲۲:۲۳ Pratik Bhujel <
prateekbhujelpb@gmail.com> نوشت:

Hi Sepehr,

I have a few concerns with the current semantics before this becomes
another permanent global API.

The RFC motivates str_mask() primarily around sensitive data and privacy,
but the proposed behavior is fail-open:

str_mask('AB', '*', 3) === 'AB'

An incorrect offset therefore returns the original sensitive value
unchanged.

If masking is being presented as the reason for introducing the function,
why is an invalid masking range considered successful rather than
exceptional? Silently leaking the input seems like a particularly
surprising contract for an API whose stated purpose is hiding data.

There is a similar issue with $mask_char.

The signature accepts string, but the RFC specifies that only the first
byte is used. So:

str_mask($value, '●', ...)

does not mask using the character that was passed. It takes one byte from
a multibyte UTF-8 sequence and can produce invalid UTF-8.

I understand that str_mask() is intended to be byte-oriented, but then
accepting an arbitrary string and silently truncating it to one byte feels
like the wrong API. Why not require exactly one byte and throw ValueError
otherwise?

My larger concern, though, is whether the primitive itself earns a place
in core.

The RFC's email example still needs strpos() and strlen() to determine
where the semantic part to hide actually is. Credit cards, emails, phone
numbers, tokens and identifiers all have different disclosure rules. PHP
cannot determine those rules; the caller still has to do that work.

Once the caller already knows the offset and length, the remaining
operation is essentially replacement of a substring with a repeated byte.

So I think there are three questions that need stronger answers:

1. What recurring capability does str_mask() provide that cannot already
   be expressed clearly with existing string primitives?

2. Do we have evidence from real-world codebases that this pattern occurs
   frequently enough to justify another global function rather than a small
   userland abstraction?

3. The RFC states that the implementation is "significantly faster". Could
   you include reproducible benchmarks against an equivalent
   substr_replace()/str_repeat() implementation, including short strings
   representative of the examples in the RFC?

For operations on strings this small, C being faster in isolation does not
necessarily establish that the difference is meaningful enough to justify
expanding the standard library.

I would also avoid describing this as providing privacy or GDPR
compliance. Whether exposing part of an identifier is appropriate is
contextual, and a generic byte-level replacement operation cannot provide
that guarantee.

I think these questions should be resolved before discussing the
implementation itself.

Best regards,
Pratik Bhujel

Hi Pratik,

Thanks for the feedback! I've updated the RFC document to reflect the
fail-closed error handling design and edge-case behavior we discussed.

Regarding grapheme_mask(), I haven't designed or implemented it yet, but
I will definitely incorporate these principles once I start working on it
in ext/intl.

Also, to ensure this on it in ext/intl.

Also, to ensure this to include real-world usage analysis/benchmarks (e.g.
log masking, sensitive data display in popular frameworks) in the proposal?
I'd love to hear your thoughts on this or any specific cases you have in
mind.

Best regards,
Sepehr

در تاریخ جمعه ۱۸ سپتامبر ۲۰۲۶، ۲۳:۱۲ Osama Aldemeery aldemeery@gmail.com
نوشت:

‪On Fri, Sep 18, 2026 at 9:27 PM ‫سپهر محمودی‬‎ sepehrphpr@gmail.com
wrote:‬

Hi everyone,

I'm officially starting my work on the ext/intl and standard string
functions, and I'm very excited to share my first major proposal for PHP
8.7!

I have successfully set up my local development environment and compiler
on my machine, and everything is up and running smoothly.

As part of this, I would like to propose a new native function called
str_mask().

Proposal Overview

The str_mask() function is designed to securely mask portions of a
string using a specified mask character. This is extremely useful for
handling sensitive user data like credit card numbers, phone numbers, and
tokens.

Signature:
str_mask(string $string, string $mask_char = '*', int $offset = 0, ?int
$length = null): string

Examples

1. Masking a credit card (positive offset & length):
   $credit_card = '1234567890123456';
   $masked_card = str_mask($credit_card, '*', 4, 8);
   // Output: 1234********3456

2. Masking a phone number (negative offset to count from the end):
   $phone_number = '+989123456789';
   $masked_phone = str_mask($phone_number, 'X', -4);
   // Output: +9891234XXXX

You can find all the details, implementation plans, and RFC discussions
here:
https://wiki.php.net/rfc/str_mask

Looking forward to hearing your feedback and thoughts!

Best regards,
Sepehr Mahmoudi

Hi,

Unless I am missing something...this looks identical to the existing
substr_replace. It has the same signature with just a different name
and without array being part of the params/return types.

Your examples could be rewritten as:

$credit_card = '1234567890123456';
$masked_card = substr_replace($credit_card, str_repeat('*', 8), 4, 8);

$phone_number = '+989123456789';
$masked_phone = substr_replace($phone_number, str_repeat('X', 4), -4);

Regards,
Osama

Hi Osama,

Thank you for the feedback!

While it is true that masking can be composed using substr_replace($str, str_repeat($mask, $len), $offset, $len), there are three key motivations
behind proposing str_mask():

1. Ergonomics & Clarity: Masking sensitive information (PII, credit cards,
   emails, tokens) is one of the most common everyday tasks in modern web
   security and logging. Writing substr_replace(..., str_repeat(...), ...)
   is verbose and prone to off-by-one errors. A dedicated function makes the
   intent clear.

2. Fail-Closed Security & Strict Validation: Data masking often deals with
   sensitive credentials. substr_replace() has legacy and lenient behaviors
   regarding out-of-bounds offsets. In contrast, str_mask() is designed with
   a strict fail-closed approach (throwing ValueError on invalid boundaries
   or empty mask characters) to ensure sensitive data is never silently
   exposed due to silent clipping.

3. Performance & Memory: The substr_replace + str_repeat combination
   performs two separate string allocations (one temporary string created by
   str_repeat and the final string created by substr_replace).
   str_mask() computes the masked string directly in C in a single
   allocation pass, making it more memory- and CPU-efficient.

Best regards,
Sepehr

Not useful.
Easily implemented in user-space.
Performance would never be an issue for a function typically used on small strings a few times per request.

In the multi-million-line web application I work on this probably would not be used even once.

Greetings, Casper
This. I don’t see any reason why this should added. Its use-case is quite a niche, which can be easily solved by calling substr_replace together with str_repeat.

If you want to go on with your idea, the string parameter of this function should have the SensitiveParameter attribute or else it may end up in a backtrace.

Regards,
Jordi

در تاریخ شنبه ۱۹ سپتامبر ۲۰۲۶، ۰۲:۱۳ Casper Langemeijer langemeijer@php.net
نوشت:

8On Fri, Sep 18, 2026, at 20:26, سپهر محمودی wrote:

As part of this, I would like to propose a new native function called
str_mask().

Not useful.
Easily implemented in user-space.
Performance would never be an issue for a function typically used on small
strings a few times per request.
In the multi-million-line web application I work on this probably would
not be used even once.

Please stop this. Your mails read like AI slop, and your proposals are of
very poor quality. I suspect that there are more than a few thousand humans
reading this list, and you are wasting their time.

Please don't see this as a personal attack. It's the work that is not good
enough, not you as a person.

Greetings, Casper

Hi Casper,

My responses to your questions are summarized in the benchmark tests, which
I am currently conducting. I prefer to avoid any further discussion
regarding AI to keep our focus strictly on the technical merits of the
proposal.

Best regards,
Sepehr