Rewrite and flesh out string interpolation docs #2000

Girgias · 2022-11-12T14:04:08Z

This covers the PHP 8.2.0 deprecation of interpolation It also renames simple to basic and complex to advanced as those don't make a judgement on complexity.

iluuu1994

Only minor things, looks good to me overall.

iluuu1994 · 2022-11-13T13:13:51Z

language/types/string.xml

-    <link linkend="language.types.string.parsing.simple">simple</link> one and a
-    <link linkend="language.types.string.parsing.complex">complex</link> one.
-    The simple syntax is the most common and convenient. It provides a way to
+    <link linkend="language.types.string.parsing.simple">basic</link> one and an


The pages are still named simple and complex, should those be renamed? I'm also not sure this needs to be renamed at all.

I didn't want to change them in case other pages link to here. But I could check and change them

iluuu1994 · 2022-11-13T13:19:07Z

language/types/string.xml

+]]>
+       </screen>
+      </informalexample>
+      The <link linkend="language.types.string.parsing.complex">advanced</link>


The basic one would be fine too for the first example.

Well I was trying to have an example to demonstrate the reason why it is deprecated, so I copied the RFC example, but if you have a better example I'll take it :)

The error message only mentions {$var} because that will work for all versions of ${var}, like ${var['foo']}. That's not valid in the basic syntax (when translating 1:1), where the ' need to be omitted: $var[foo]. When only simple variables are used, $var should be fine as well.

iluuu1994 · 2022-11-13T13:21:23Z

language/types/string.xml


    <simpara>
     If a dollar sign (<literal>$</literal>) is encountered, the parser will
     greedily take as many tokens as possible to form a valid variable name.
-     Enclose the variable name in curly braces to explicitly specify the end of


This comment seems kind of useful. Maybe move it to the advanced section instead?

How would code using the advanced syntax use this? And isn't that part of the deprecation?

What this comment is saying that by enclosing the whole expression with {$...}, the parser doesn't need to guess when the expression is done (or rather stop after the first dimension) but will look for the ending } instead.

What this comment is saying that by enclosing the whole expression with {$...}, the parser doesn't need to guess when the expression is done (or rather stop after the first dimension) but will look for the ending } instead.

No, this comment is referring to the ${...} syntax. If you read the current docs that's how it's used.

This section seems clear to me as @Girgias has changed it, enclosing just the variable name in brackets (${....}) was deprecated, but still explained in the warning that comes a bit later.

iluuu1994 · 2022-11-13T13:22:32Z

language/types/string.xml

    curly braces surrounding the expression.
   </simpara>

   <sect4 xml:id="language.types.string.parsing.simple">
-    <title>Simple syntax</title>
+    <title>Basic syntax</title>

    <simpara>
     If a dollar sign (<literal>$</literal>) is encountered, the parser will
     greedily take as many tokens as possible to form a valid variable name.


I find that statement a little misleading. The syntax isn't greedy, e.g. only one array dimension is allowed. https://3v4l.org/pJF8E

Well brilliant, this is already the existing docs but might as well fix them now. Do you have better wording? I can try to come up with one otherwise.

Maybe something like:

The basic syntax only allows for single-dimensional array or property accesses.

$foods = ['apples', 'bananas', 'lettuce', 'spinach']; echo "$foods[0]\n"; // apples $foods = ['fruits' => ['apples', 'bananas'], 'vegetables' => ['lettuce', 'spinach']]; echo "$foods[fruits][0]\n"; // Warning: Array to string conversion in /in/hcu76 on line 7 // Array[0]

To use multi-dimensional array or property accesses, use the advanced syntax.

I find that statement a little misleading. The syntax isn't greedy, e.g. only one array dimension is allowed. https://3v4l.org/pJF8E

Actually this statement is only about the name of a variable, not any following dimension. So I think it's correct.

I'm not sure what that statement is really about (there are still places in the docs where it talks about "variables" but means "values", what I consider grossly wrong). However, if it is only about the identifier, the word "token" doesn't make sense.

Also, braces don't change how the variable name itself is tokenized, so it's not even correct in that context.

Girgias · 2022-11-14T15:04:45Z

I spent some more time again, can you please have another look @iluuu1994 @cmb69 ?

cmb69

Thank you for the PR!

I'm not convinced that this is a major improvement (but certainly causes quite some work for translators). Wouldn't it be better to have a precise description (like https://github.com/php/php-langspec/blob/master/spec/09-lexical-structure.md#string-literals)?

cmb69 · 2022-11-14T15:55:29Z

language/types/string.xml

+    <warning>
+     <para>
+      The basic syntax does not permit access to an array entry which has a key
+      containing a minus (<literal>-</literal>) sign.


I don't think it makes much sense to point out that minus is not allowed, since AFAIK only valid identifier characters are allowed anyway.

There are proably others yes, but when I was creating my example I used the array key string-key which when I tried to interpolate didn't work. So I changed the - to an _, however refering to that key is possible via the normal semantics.

language/types/string.xml

cmb69 · 2022-11-14T16:01:46Z

language/types/string.xml

-// Won't work, outputs: C:\folder\{fantastic}.txt
-echo "C:\folder\{$great}.txt"
-// Works, outputs: C:\folder\fantastic.txt
-echo "C:\\folder\\{$great}.txt"


This was a fix for https://bugs.php.net/81635. Not sure if we should just drop that.

Ah, okay I'll readd it then

Girgias · 2022-11-14T16:26:34Z

Thank you for the PR!

I'm not convinced that this is a major improvement (but certainly causes quite some work for translators). Wouldn't it be better to have a precise description (like https://github.com/php/php-langspec/blob/master/spec/09-lexical-structure.md#string-literals)?

Having a more precise description would be best, but even that page has a dead link to what it refers to as "simple expression", and we would need to define what a name is somewhere.

Which might be a good idea to have a section on basic language components, because the amount of pages where we redeclare what a label is in PHP is too many.

But this is indeed probably the best course, I'll have another go at it.

Girgias · 2022-11-22T14:06:18Z

So I've given a go at trying to write a formal definition and removing the clunky descriptions and non-examples.

cmb69 · 2022-11-24T13:41:37Z

language/types/string.xml

@@ -683,92 +683,167 @@ EOT;
  </sect3>

  <sect3 xml:id="language.types.string.parsing">
-   <title>Variable parsing</title>
+   <title>Variable substitution</title>


I think using "substition" instead of "parsing" is an improvement (but there are 3 occurrences of "parsing" left on that page), but I think "variable substitution" is still not correct; at least with the advanced syntax, it is possible to interpolate the results of evaluating expressions. Speaking of "expression substitution/interpolation" would be too general, though. Not sure what to do here.

I'm using string interpolation now

cmb69 · 2022-11-24T13:46:18Z

language/types/string.xml

    </simpara>

    <simpara>
-     Any scalar variable, array element or object property with a
+     Any scalar variable, array element or object property
+     (<modifier>static</modifier> or not) with a


language/types/string.xml

cmb69 · 2022-11-24T13:50:12Z

language/types/string.xml

-     This isn't called complex because the syntax is complex, but because it
-     allows for the use of complex expressions.
+     The advanced syntax permits the interpolation of
+     <emphasis>variables</emphasis> with arbitrary access expressions.


Not sure about "access expressions". Do we define that term somewhere? If not, it might be sensible to do that. Or maybe use "accessors"?

Girgias · 2023-07-26T16:06:02Z

Note to self: related to #2078

jimwins · 2024-09-29T02:25:51Z

The conflict is just in an example that should be easy to resolve. Otherwise, this is the last PHP 8.2 documentation issue still open on the tracker.

This covers the PHP 8.2.0 deprecation of interpolation It also renames simple to basic and complex to advanced as those don't make a judgement on complexity

Also fix token descriptions

jimwins

LGTM.

Girgias requested a review from iluuu1994 November 12, 2022 14:04

Girgias mentioned this pull request Nov 12, 2022

PHP 8.2 documentation tracker #1803

Closed

Girgias added this to the PHP 8.2 milestone Nov 12, 2022

iluuu1994 approved these changes Nov 13, 2022

View reviewed changes

Girgias force-pushed the string-interpolation-deprecated branch from 33370e5 to a08df37 Compare November 14, 2022 15:03

cmb69 reviewed Nov 14, 2022

View reviewed changes

Girgias force-pushed the string-interpolation-deprecated branch from a08df37 to 5b7bcad Compare November 22, 2022 14:02

cmb69 reviewed Nov 24, 2022

View reviewed changes

Girgias force-pushed the string-interpolation-deprecated branch 2 times, most recently from 3676194 to 57ef188 Compare November 30, 2022 15:47

Girgias mentioned this pull request May 10, 2023

Using ${var} in strings is deprecated, use {$var} #2465

Closed

Girgias mentioned this pull request Aug 30, 2023

Update string.xml to remove old string interpolation #2712

Merged

Girgias mentioned this pull request Sep 22, 2023

Undefined constant fallback deprecated; mentioned as E_NOTICE (in language.types.string) #2779

Closed

takaram mentioned this pull request Feb 13, 2024

Replace deprecated ${var} string interpolations with {$var} #3179

Merged

Girgias added 6 commits October 1, 2024 20:05

Rewrite and flesh out string interpolation docs

87a591b

This covers the PHP 8.2.0 deprecation of interpolation It also renames simple to basic and complex to advanced as those don't make a judgement on complexity

Remove variable variable examples, add more examples, review comments

bccb1c8

Change ID for basic/advanced string interpolation

a4a6944

Also fix token descriptions

Define the formal syntax and remove clunky wording

ad8f8de

Re-add example for bug 81635 fix

8b6020e

Minor nits and review comments

f6d7af4

Girgias force-pushed the string-interpolation-deprecated branch from 57ef188 to f6d7af4 Compare October 1, 2024 19:08

Girgias requested a review from jimwins October 1, 2024 19:09

jimwins approved these changes Oct 1, 2024

View reviewed changes

Girgias merged commit b012e0d into php:master Oct 2, 2024
2 checks passed

Girgias deleted the string-interpolation-deprecated branch October 2, 2024 15:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rewrite and flesh out string interpolation docs #2000

Rewrite and flesh out string interpolation docs #2000

Girgias commented Nov 12, 2022

iluuu1994 left a comment

iluuu1994 Nov 13, 2022

Girgias Nov 13, 2022

iluuu1994 Nov 13, 2022

Girgias Nov 13, 2022

iluuu1994 Nov 13, 2022 •

edited

Loading

iluuu1994 Nov 13, 2022

Girgias Nov 13, 2022

iluuu1994 Nov 13, 2022 •

edited

Loading

Girgias Nov 14, 2022

jimwins Sep 29, 2024

iluuu1994 Nov 13, 2022

Girgias Nov 13, 2022

iluuu1994 Nov 13, 2022

Girgias Nov 14, 2022

cmb69 Nov 14, 2022

iluuu1994 Nov 14, 2022

Girgias commented Nov 14, 2022

cmb69 left a comment

cmb69 Nov 14, 2022

Girgias Nov 14, 2022

cmb69 Nov 14, 2022

Girgias Nov 14, 2022

Girgias commented Nov 14, 2022

Girgias commented Nov 22, 2022

cmb69 Nov 24, 2022

Girgias Nov 30, 2022

cmb69 Nov 24, 2022

cmb69 Nov 24, 2022

Girgias commented Jul 26, 2023

jimwins commented Sep 29, 2024

jimwins left a comment

Rewrite and flesh out string interpolation docs #2000

Rewrite and flesh out string interpolation docs #2000

Conversation

Girgias commented Nov 12, 2022

iluuu1994 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

iluuu1994 Nov 13, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

iluuu1994 Nov 13, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Girgias commented Nov 14, 2022

cmb69 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Girgias commented Nov 14, 2022

Girgias commented Nov 22, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Girgias commented Jul 26, 2023

jimwins commented Sep 29, 2024

jimwins left a comment

Choose a reason for hiding this comment

iluuu1994 Nov 13, 2022 •

edited

Loading

iluuu1994 Nov 13, 2022 •

edited

Loading