Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Proposal: Add
println(string $data = ''): int
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.
- Loading branch information