TysonAndre · GitHub

@TysonAndre

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.

Read the original on github.com ↗