[RFC] [Discussion] array_get and array_has functions

This is the link to the RFC: https://wiki.php.net/rfc/
array_get_and_array_has <
https://wiki.php.net/rfc/array_get_and_array_has>;
I'd prefer $key=null case removed. It's not that useful, not on pair
with array_has(), and one would debate what to do with the $default in
this case.

I'm not sure this needs to be stated in the RFC, but I hope they do not
throw a warning when the key does not exist, on any level.

Thanks for your comments. I would like to hear what other people think
about the null case. I find it useful but if other people think it is
unnecessary, it can be easily removed. In any case, the $default would not
be used in this case

Technically speaking, this scenario does exist; the problem here, if I’m not mistaken, is how to represent or handle it. You originally suggested using the null value for this, which, to my knowledge, is one approach. However, this dilutes the parameter’s meaning, much like it does with “int.” A common and long-established approach is to use only strings for the reference tokens (“keys”).

Since “null” is then the empty string (z-string, empty string, null string), the dot notation in your path can still express this—it would contain neither a dot nor any character—but it would be ambiguous, as it could also mean an empty key for access or just be string zero, just the default string value, e.g. never a name or reference.

JSON Pointer resolves this by prefixing each “key” with the separator; accessing the empty key is then “//” (or “..” in dot-prefix notation for illustration) and accessing the container itself is “/” (or “.” in dot-prefix notation)—the null case discussed here.

For the iterable access discussed (an iterable of reference tokens instead of a string with the dot path), this is then no longer ambiguous, since null, as originally proposed, becomes the empty array and not an array containing the empty string—problem solved. So, if one considers allowing iterables, it becomes possible to avoid the null case and use an empty iterable instead. In this context, the notation [] is probably even more meaningful than null.

I hope these thoughts help you think through the whole thing a bit more carefully. Technically speaking, after removing null, there can only be one other null case: the empty string. Switching from postfix to prefix notation can help with this and also prevents empty strings entirely; and regardless of the discussion about iterables, removing “null” boils down to the fact that if you want to support both cases: access to the holder’s value and access to the holder’s empty key must be resolved into a single case, and you must specify which case that is, since you cannot express two values for a single value, and keys or any other type of reference must be unique, otherwise they will obviously become unusable too quickly. In my opinion, it makes the most sense to resolve the null case first, since all other specification errors related to ambiguity only arise later (e.g., insufficient escaping rules, conditional access to the existence of a key based on fuzzy logic, etc.) and this provides the precision needed for the cases you want to support, whether it’s postfix or prefix notation or whatever.

In practice, it doesn’t take much effort to pass the array via a placeholder when calling the function:

$value = array_get_dot([‘’ => $array], ‘.’);

This serves as an example of the null/placeholder/null key scenario in this context and highlights where there might still be some ambiguity with postfix notation.

A third function that lists all dot paths in an array could be helpful for discussing and testing the RFC:

// The function array_get_dots() returns the array of all dot paths of the array in breadth-first order.
function array_get_dots(array $array): array { ... }

$dots = array_get_dots($array);

With a small test data set, simple property tests could be performed, which could then be used as examples in the RFC to formulate the expectations.

The function names in the two listings are for illustrative purposes only.

And yes, in my view, it makes sense to remove “null” and, furthermore, “int” from the first parameter.

Because of the dot notation as shown, the empty string as a value for the dot path should trigger a value error due to an empty dot path, as removing “null” alone does not fully resolve the ambiguity issue for the null string value.

And, no, no warning will be thrown if any part of the path does not exist,
being able to easily support not existing paths is one of the main reasons
for this RFC

Thank you for the clarification!

This is in my opinion good to clarify in the RFC as well, as it is commonly known as error handling, which includes writing what an error is and what is not an error and which diagnostics are guaranteed by the implementation (for example, no warnings/notices.)

--hakre

Hi,

I would like to open the discussion on my proposal to add two small, focused array functions for retrieving and checking nested array elements using dot notation.

This is the link to the RFC: https://wiki.php.net/rfc/array_get_and_array_has

This is the link to the proposed implementation: https://github.com/php/php-src/pull/21637

Thanks!!

Carlos

Hi Barel,

Interesting! As dot-notation isn't used anywhere else, and I don't see it discussed as part of the RFC, how are developers to prevent injections of dots in user input? With SQL, we have parameters and escaping ... but I don't see any of that here.

As an example:

$user = [ 'data' => [...], 'password' => 'secret' ];

If the path is completely user-controlled (as in the examples given), then they can access sensitive information in the array. Even if it is prefixed, ie., "data.%s" -- an attacker can simply enumerate all possible keys and subkeys.

As it stands, it appears to add a new vulnerability to PHP that will be unfamiliar with PHP developers -- unless they're using a framework that already does this sort of notation.

I wouldn’t go that far, but I’d like to start by emphasizing that the dot notation described here clearly does not provide a mechanism for escaping the dot. That’s probably a shortcoming, but if any user-supplied string key poses a security risk, then PHP arrays are also affected, and this vulnerability would be nothing new! (Rather, it would be to be expected.)

-- hakre

My point is that this is different and distinct from regular array vulnerabilities and injections.

$user['data'][$key] !== array_get($user['data'], $key, null);

In the former 'some.key' is a full key; in the latter, it would access ['some']['key'].

Further, the former could be a valid key, but there is no way to access it using the proposed RFC

— Rob

__

Hi,

I would like to open the discussion on my proposal to add two small, focused array functions for retrieving and checking nested array elements using dot notation.

This is the link to the RFC: https://wiki.php.net/rfc/array_get_and_array_has

This is the link to the proposed implementation: https://github.com/php/php-src/pull/21637

Thanks!!

Carlos

Hi Barel,

Interesting! As dot-notation isn't used anywhere else, and I don't see it discussed as part of the RFC, how are developers to prevent injections of dots in user input? With SQL, we have parameters and escaping ... but I don't see any of that here.

As an example:

$user = [ 'data' => [...], 'password' => 'secret' ];

If the path is completely user-controlled (as in the examples given), then they can access sensitive information in the array. Even if it is prefixed, ie., "data.%s" -- an attacker can simply enumerate all possible keys and subkeys.

As it stands, it appears to add a new vulnerability to PHP that will be unfamiliar with PHP developers -- unless they're using a framework that already does this sort of notation.

— Rob

Thanks Rob. Probably user input is not the best use case for these functions, I just used it in the examples because it is simple.

And quite dangerous. I’d recommend using realistic examples that showcase the work instead of simple examples that scream “hack me” to anyone who’s written PHP more than a few years.

In any case, if your program allows unrestricted array access using a user defined path, the vulnerability already exists, these functions just make it easier to implement the access.

That’s the rub, right? Array access simply cannot have a user-defined array path today. This feature allows that but as of this reply, the RFC does not disclose the danger of such a thing despite using it in the examples. It’s either irresponsible or naïve.

If you did not have them and wanted the same functionality you would use a custom implementation (like the one provided by Laravel) and you would have the same vulnerability

Cheers

Carlos

Different frameworks and implementations assign different semantics. I’ve seen dots (such as in laravel), slashes, double back-slashes, etc. over the years. I think dots is a fine choice, but it is worth pointing out that, currently, array keys are binary-safe. These simple looking functions completely ignore that. Even if you escape the dots, now you have two variables: $escaped_key (for use in these functions) and $unescaped_key.

I see that wildcards are also being considered in the future. Maybe, instead of adding two thin utility functions to global space, it would be better to create an QueryableArray class … kinda like Linq in C# … to handle this type of stuff? Otherwise, this becomes a slippery slope of assigning semantics to random byte sequences.

If you’re going to add query semantics to arrays, do it properly.

— Rob

Hi,

I would like to open the discussion on my proposal to add two small,
focused array functions for retrieving and checking nested array elements
using dot notation.

This is the link to the RFC:
https://wiki.php.net/rfc/array_get_and_array_has

This is the link to the proposed implementation:
https://github.com/php/php-src/pull/21637

Thanks!!

Thank you very much! That’s very interesting, so I have to ask right away:
Is there a specific reason to limit this to strings, integers, and null for
arrays, rather than also allowing arrays or iterables?

This reminds me of JSON Pointers (RFC 6901), which can usually be easily
mapped as an iterable with string keys, which can then be accessed via the
holder variable, similar to the foreach example you already describe in
your RFC.

If these two functions supported passing an array/iterable with the
traversal keys as a second parameter, this would be advantageous, since the
JSON pointer would then not need to be recoded into dot notation, but only
(if not already done) sliced and passed as an array as the second parameter.

That's why I'm asking.

Interestingly, JSON Pointer solves the “null problem” by prefixing the
zero or more reference tokens (keys) with a slash ‘/’, and it supports all
seven types of JSON values without limiting itself to just JSON arrays or
objects. This is just food for thought: array_... are clearly array
functions, so this “restriction” is likely intentional. In PHP, however, I
can also imagine iterables that resemble what you’ve already described in
your RFC, and from there it’s not far to the holder object we see in JSON
and JSON Pointer. So please don’t confuse my “request” regarding
arrays/iterables with the first parameter; it’s simply about passing the
key as a keys, which is a small improvement over dot notation.

With arrays in PHP, users will likely prefer the non-standard, more custom
dot notation, and that’s perfectly fine. I saw many people asking for this
in the early days of Stack Overflow, and if Symfony/Laravel have it as
well, that’s just another strong indication of such a preference.

Thanks again for your RFC

--hakre

P.S. Work on the RFC documentation for JSON Path finally began in 2020,
and it was published in February 2024. The standard has its roots in PHP
and JavaScript, and perhaps it’s time for PHP to expand its standard
library with such features at the same pace we did with JSON. Your RFC
seems well-suited for this purpose. Thanks again.

Thanks for your comments. Someone else already suggested allowing arrays
for the $key parameter and I am considering it, I think it will probably be
a good addition

Yes, I agree, and I suggest we also consider iterable as part of this discussion.

Thank you Carlos as well for your work on these functions.

--hakre

After the discussion here and after speaking to other developers, I
have decided to drop the dot notation entirely from this RFC and only
leave the option to use an array path. Using dot (or similar) notations
can be easily achieved using a simple explode or more complex code if
we need to do more complex setups like escaping. The main goal of the
RFC has always been being able to handle dynamic paths. The
implementation has also been updated and is now much simpler

Cheers

Carlos

"4) Using dot or similar notations "

This should be bullet point 3, not no 4.

I agree with Tim that an invalid path segment should error in some way, rather than just using the default. If a non-int/string path segment is encountered, it 100% of the time means the developer screwed up in some way so they should know to fix it.

One of the most common uses for structure-unclear arrays I run into is (bad) APIs that have a value that is either a primitive or an array of primitives. Can you include an example showing how these functions would help in that situation?

Eg, this JSON:

{ "state": "IL" }
vs
{"state": ["IL", "CA", "NY"] }

Presumably you also have some real-world cases in mind that you've run into. Can you include versions of those in the examples to get a better sense of what usage would look like in practice?

To Tim's naming point, perhaps array_has_path() / array_get_path()? (Or maybe path first, not sure.)

--Larry Garfield