show last fatal error on phpunit shutdown

in acdadce (do not hide errors in phpunit test-suite, 2020-04-11)
error reporting has been defined more for development, but still some
hard to track errors don't show. there is need to cover those fatals
running php 5.3, also within the pipelines container in use.

when php encounters a fatal error, it may exit silently with an exit
status of 255. so the exit status 255 is the only trail of the fatal error,
which is cumbersome as more concrete error information like the message and
the location of the error is wanted.

this behaviour depends on php runtime configuration and is not specifically
an issue with phpunit. however as it is especially cumbersome when those
fatal errors happen with phpunit, make them more visible there first.

for real, this can be because PHP_BINARY is not reflected by composer
(and we're not fully understanding why the environment variable gets
changed to `/usr/bin/php` even if exported and probably the symfony
console php-executable-finder does the rest).

and then this is more an issue in older PHP versions (e.g. before 7.0 and
also before 8.0) but still can be if errors are suppressed with the `@`
error suppression operator (educated guess).

in concrete an issue when running the phpunit test-suite with php 5.3
within the pipelines container.

regardless, and as php 5.3+ is supported, when php (phpunit) exits due
to a fatal error, verbosely show the last fatal, un-reported (didn't went
through this error capturing error handler) error on shutdown by
outputting *shutdown-with-fatal* termindated by a newline on standard
error, followed by a quick-made php-sapi error logging mimicking output
(PHP 8.0+ for line index style [linux]), again terminated by a newline.

active during development (e.g. `vendor/bin/phpunit` execution via
`vendor/autoload.php` bootstrap).

This is specifically important during the phpunit run as otherwise with
php 5.3 those hard to track php errors won't show, e.g. within the
related pipeline container. which would mean that runtime errors that
happen with lower php versions were not verbose/visible.

show the last php error on shutdown if of fatal severity (E_ERROR).

NOTE: we do see an issue with:

          $ php5.3 -f "$(which composer)" -- which-php

      as well but are not able to address it. this fix levitates the
      problem, in container the php executable pathname is only for php
      as the specific 5.3 version and locally with 5.3, composer executes
      phpunit with the default version (e.g. 7.4 set up via the debian
      alternatives system).

refs: acdadce

CHANGELOG.md

@@ -12,6 +12,8 @@ The format is based on [Keep a Changelog] and Pipelines adheres to
 - `--show` and `--show-pipelines`: Annotate steps with manual triggers
   with `*M`
 ### Change
+- Verbose last error report on Phpunit test-suite shutdown if fatal,
+  improves [0.0.32](#0032---2020-04-11)
 - `--show-pipelines`: Show unnamed steps as `no-name` (like `--show`)
 ### Fix
 - Fix internal file descriptor system paths mapping flaws, since

composer.json

@@ -26,6 +26,7 @@
     },
     "files": [
       "test/phpunit_class_aliases.php"
+    , "test/phpunit_exit_report_fatals.php"
     ]
   },
   "require": {

test/phpunit_exit_report_fatals.php

@@ -0,0 +1,27 @@
+<?php
+
+/* this file is part of pipelines */
+
+call_user_func(function () {
+    $lastReported = null;
+
+    set_error_handler(function ($errno, $errstr, $errfile = null, $errline = null) use (&$lastReported) {
+        $lastReported = array(
+            'type' => $errno,
+            'message' => $errstr,
+            'file' => $errfile,
+            'line' => $errline,
+        );
+
+        return false;
+    });
+
+    register_shutdown_function(function () use (&$lastReported) {
+        /* catch fatal error and report it if it was not yet reported */
+        $data = error_get_last();
+        if (is_array($data) && E_ERROR === $data['type'] && $lastReported !== $data) {
+            fwrite(STDERR, "*shutdown-with-fatal*\n");
+            fprintf(STDERR, "PHP Fatal error:  %s in %s:%d\n", $data['message'], $data['file'], $data['line']);
+        }
+    });
+});