What this does
--------------
This function behaves similarly to this userland code
```
function println(string $data = ''): int {
return printf("%s\n", $data);
}
```
Similarly to `printf("%s\n", $data);`.
- `println` is NOT a keyword. (e.g. functions named println can continue to be
declared outside of the global namespace)
- It returns the number of bytes that were successfully written to standard
output. In the unlikely event that there was an error writing,
this and printf return a smaller number.
- This deliberately always prints the unix newline (`\n`)
**instead of PHP_EOL**.
I would find it very unexpected if println were to behave
differently based on the web server was running it,
e.g. if you moved a website's backend from/to a linux server
to/from a windows server, responses generated by `println` would
suddenly be different.
Additionally, https://www.php-fig.org/psr/psr-2/ recommends that all php
source files contain unix line endings.
If those files contain inline html/text snippets mixed with php+println(),
it would be inconsistent to have `\r\n` in the lines printed by
println() and `\n` anywhere else.
This is same choice of line ending as var_dump, debug_zval_dump,
and var_export use for dumping output.
Otherwise, `println("myArray=" . var_export($myArray, true));`
would be a mix of multiple line ending choices.
Many new languages have elected to always use only the unix newlines,
e.g. https://golang.org/pkg/fmt/#Println and
https://doc.rust-lang.org/std/macro.println.html
Overall, editors do a much better job of detecting newline choices and
displaying different newline choices than they did decades ago.
My opinion is that this anything generating files targeting a specific OS's
line endings should continue to use PHP_EOL or continue to base
the newline choice on the OS of the user requesting the output.
This newline choice differs from the implementation PR for a similar proposal
made 2 years ago https://externals.io/message/104545 ,
for which an RFC was never written.
Differently from printf's argument list, echo, and print,
the argument $data is type checked based on the file's `strict_types` setting.
This is consistent with handling of $data in
`fwrite($stream, string $data): int` or the way format strings($format)
of `printf` are checked.
`println((string)$value)` should be used when strict_types=1 but you are uncertain
of the type.
Reasons to add this
-------------------
1. This is useful for self-contained scripts and a useful helper function to
have overall. E.g. phpt tests of php itself print multiple lines for the
`--EXPECT--` section, and var_dump can be overused even for known strings
because `var_dump(some_function())`
is shorter than `echo some_function() . "\n";`
2. Even if codebases add userland helper equivalents that do exactly this,
If you are new to a codebase, or contribute to multiple
codebases, it is inconvenient to use `xyz_println`,
`ABCUtils::println()`, `echo X, "\n"`, etc., and remember if those different
functions actually use the line endings you think they do.
Additionally, the prefixing is much more verbose.
3. In tutorials or language references that teach a developer
how to use php functionality, it is often preferable to use
functions that append a newline when multiple snippets would be evaluated
together to keep examples simple.
`println("Hello $name");` would be useful to have for introducing PHP
to a new developer before `echo "Hello $name\n";`
(requires explaining escaping first)
or `var_dump("Hello $name");` (that debug representation is rarely useful
for `string(11) "Hello world"`)
E.g. `var_dump` is frequently used instead of
`var_export`, `echo`, or `print` in the manual even for printing strings
with no control characters such as
https://www.php.net/manual/en/function.json-encode.php#example-3972
TODO: Write an rfc document, gather existing counterarguments for/against
naming choices and newline choices, gather examples of other languages that put
a println equivalent in the standard library and their choices.