This is the PHP worker for the command-line Composer demo. More...
Go to the source code of this file.
Functions | |
| demoCleanup (string $directory) | |
| This removes the downloads and drops the database owned by this demo run. | |
| demoConnection (?string $database=null, ?string $driver=null) | |
| This opens an administrative or test-database connection for the selected backend. Connection settings come from DRIVER, HOST, PORT, USER, PASSWORD, and ADMIN_DATABASE. PostgreSQL administration connects to the existing "postgres" database by default; loaded data always goes into a separate temporary database. | |
| demoCreateDatabase (PDO $admin, string $directory) | |
| This creates a uniquely named database and records it for cleanup. | |
| demoDownload (string $url, string $destination) | |
| This downloads one HTTPS resource directly to a file. | |
| demoDriver () | |
| This validates the selected database driver. | |
| demoEnvironment (string $name, string $default) | |
| This reads a demo setting from the environment. | |
| demoExtract (string $archive, string $destination) | |
| This extracts the archive's single GeoJSON file into a controlled local filename. | |
| demoInstall (string $directory) | |
| This builds the temporary Composer application and loads its autoloader. | |
| demoLatency (array $values) | |
| This formats the timing statistics for one group of lookup calls. | |
| demoPrintMetrics () | |
| This prints the collected durations, data sizes, memory measurements, and test coverage. | |
| demoRemoveDownloads (string $directory) | |
| This removes the compressed boundary archive and the extracted GeoJSON. | |
| demoResetMemoryPeak () | |
| This starts a new peak-memory measurement, when the PHP version supports it. | |
| demoRun (string $directory) | |
| This performs the complete Composer installation, data load, system test, and metrics run. | |
| demoTiming (string $label, $start) | |
| This records the elapsed time for one completed phase. | |
Variables | |
| $demoMetrics | |
| These are the measurements collected by the worker. | |
| const | DEMO_PACKAGE |
| This is the package installed into the temporary Composer application. | |
| const | DEMO_RELEASE_API |
| This GitHub endpoint identifies the latest published Timezone Boundary Builder release. | |
| if(realpath($_SERVER['SCRIPT_FILENAME'] ?? '') !==__FILE__) if(PHP_SAPI !=='cli'||$argc !==3||!in_array( $argv[1],[ 'run', 'cleanup'], true)||!is_dir( $argv[2])) if(function_exists('pcntl_async_signals')) | try |
| This is the worker entrypoint. | |
© Copyright 2023-2026, Little Green Viper Software Development LLC
LICENSE:
MIT License
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Little Green Viper Software Development LLC
Call demo/run.sh to run the demo. The shell creates a temporary working directory, and calls this file in either "run" or "cleanup" mode. In "run" mode, we install the released package through Composer, load the latest boundary data, check the resulting database, run location tests, and display metrics. The lookup classes come from the temporary Composer application, so this is a test of the installed package.
The separate "cleanup" invocation lets the shell remove the database and downloads, even if the loader's PHP process runs out of memory. The shell removes the remaining working directory after database cleanup succeeds.
Definition in file demo.php.
| demoCleanup | ( | string | $directory | ) |
The database name comes from database.json, and must match the generated demo naming pattern. We delete large files before connecting to the database server, so they are removed even when the server is unavailable. If dropping the database fails, its cleanup record remains for recovery. The shell removes the working directory only on success.
| RuntimeException | if a cleanup record is unexpected, or a file cannot be removed. |
| PDOException | if database cleanup fails. |
| $directory | The working directory owned by this demo run. |
Definition at line 285 of file demo.php.
References $directory, $start, demoCleanup(), and demoRemoveDownloads().
Referenced by demoCleanup().
| demoConnection | ( | ?string | $database = null, |
| ?string | $driver = null ) |
| RuntimeException | if the configured port is invalid. |
| PDOException | if the connection fails. |
| $database | Test database, or NULL for the administrative database. |
| $driver | Recorded cleanup driver, or NULL for the environment setting. |
Definition at line 191 of file demo.php.
References $database, $driver, $port, demoConnection(), demoDriver(), and demoEnvironment().
Referenced by demoConnection().
| demoCreateDatabase | ( | PDO | $admin, |
| string | $directory ) |
CREATE does not use IF NOT EXISTS, so a name collision cannot adopt an existing database. Where pcntl is available, interruption signals are blocked until the cleanup record has been written. If the record cannot be written, we drop the new database before reporting the failure.
| RuntimeException | if the cleanup record cannot be written. |
| PDOException | if database creation or rollback fails. |
| $admin | An administrative connection with CREATE and DROP permissions. |
| $directory | The working directory in which database.json is saved. |
Definition at line 326 of file demo.php.
References $admin, $directory, $driver, $name, $quote, and demoCreateDatabase().
Referenced by demoCreateDatabase().
| demoDownload | ( | string | $url, |
| string | $destination ) |
Redirects must also use HTTPS. We stream the response to disk, so the large boundary archive is never read into a single PHP string. A partial download remains in the working directory for the shell's cleanup to remove.
| RuntimeException | if the destination cannot be opened, or the transfer fails. |
| $url | The HTTPS resource to download. |
| $destination | The local filename to create in the demo's working directory. |
Definition at line 220 of file demo.php.
References demoDownload().
Referenced by demoDownload().
| demoDriver | ( | ) |
| RuntimeException | if another driver is requested. |
Definition at line 174 of file demo.php.
References $driver, demoDriver(), and demoEnvironment().
Referenced by demoConnection(), demoDriver(), and demoInstall().
| demoEnvironment | ( | string | $name, |
| string | $default ) |
The "LGV_TZ_DEMO_" prefix is added to the provided name. An explicitly set empty value is retained, which is useful for a MySQL user with an empty password.
| $name | The setting name, without the LGV_TZ_DEMO_ prefix. |
| $default | The value to use when the setting is absent. |
Definition at line 161 of file demo.php.
References $name, and demoEnvironment().
Referenced by demoConnection(), demoDriver(), demoEnvironment(), and demoInstall().
| demoExtract | ( | string | $archive, |
| string | $destination ) |
The ZIP may contain other files, but must contain exactly one .json or .geojson entry. We stream that entry into our own destination, instead of using paths from the archive. The extracted size must match the ZIP entry's size.
| RuntimeException | if the archive cannot be read, its contents are unexpected, or extraction fails. |
| $archive | The downloaded boundary ZIP file. |
| $destination | The local GeoJSON filename to create. |
Definition at line 235 of file demo.php.
References demoExtract().
Referenced by demoExtract().
| demoInstall | ( | string | $directory | ) |
We download and verify Composer, write the application's composer.json, and install the published lookup package and its optional JSON parser. Composer's home and cache are placed in the working directory, as well. Installation does not execute package scripts or plugins, and does not change the user's installed Composer.
| RuntimeException | if checksum verification or Composer installation fails. |
| $directory | The demo's temporary application directory. |
Definition at line 251 of file demo.php.
References $directory, demoDriver(), demoEnvironment(), and demoInstall().
Referenced by demoInstall().
| demoLatency | ( | array | $values | ) |
We report the arithmetic mean, the median, the nearest-rank 95th percentile, and the slowest call.
| $values | Individual lookup durations, in milliseconds. |
Definition at line 91 of file demo.php.
References demoLatency().
Referenced by demoLatency().
| demoPrintMetrics | ( | ) |
Lookup timings cover calls to the package API, using an existing connection. They exclude downloading, loading, and reference-geometry calculations. PHP memory measurements describe this worker, and do not include the database server or the separate Composer process. Large-polygon audit counters show which geometry was actually evaluated.
Definition at line 109 of file demo.php.
References $demoMetrics, $seconds, and demoPrintMetrics().
Referenced by demoPrintMetrics().
| demoRemoveDownloads | ( | string | $directory | ) |
We call this as soon as loading finishes, and again during cleanup. Already-removed files are harmless.
| RuntimeException | if a remaining boundary file cannot be removed. |
| $directory | The working directory containing the downloaded files. |
Definition at line 264 of file demo.php.
References $directory, and demoRemoveDownloads().
Referenced by demoCleanup(), and demoRemoveDownloads().
| demoResetMemoryPeak | ( | ) |
PHP 8.2 and later can reset the peak between phases and lookup calls. Earlier versions leave the lifetime peak intact; the report labels those measurements accordingly.
Definition at line 79 of file demo.php.
References demoResetMemoryPeak(), and if.
Referenced by demoResetMemoryPeak().
| demoRun | ( | string | $directory | ) |
We first check PHP and the database server, then install the package and obtain the latest boundary release. The package performs the actual load while a listener retains independent source geometry for storage and lookup checks. The large files are deleted after loading, and the reference geometry is freed before lookup measurements.
The known locations come from the installed package. Generated tests sample the largest polygons, including points on both sides of boundaries. Coverage must show that those polygons were actually decoded by the API. The parent shell handles database and directory cleanup after this function returns or the worker fails.
| RuntimeException | if setup, download, loading, or test preparation cannot complete. |
| $directory | The private working directory created by run.sh. |
Definition at line 363 of file demo.php.
References $demoMetrics, $directory, and demoRun().
Referenced by demoRun().
| demoTiming | ( | string | $label, |
| $start ) |
| $label | The label displayed in the metrics report. |
| $start | The phase's starting hrtime(true) value, in nanoseconds. |
Definition at line 65 of file demo.php.
References $demoMetrics, $start, and demoTiming().
Referenced by demoTiming().
| $demoMetrics |
"started" contains a monotonic timestamp in nanoseconds. "timings" contains phase durations in seconds. The lookup arrays contain individual call durations in milliseconds. Fields ending in "bytes" describe data sizes or PHP memory usage. "largest" contains only the small description records needed for the final report.
We retain measurements from completed phases, so a failed run can still print the information available so far.
Definition at line 58 of file demo.php.
Referenced by demoPrintMetrics(), demoRun(), and demoTiming().
| if(realpath( $_SERVER[ 'SCRIPT_FILENAME'] ?? '') !==__FILE__) if(PHP_SAPI !=='cli'|| $argc !==3||!in_array($argv[1], ['run', 'cleanup'], true)||!is_dir($argv[2])) if (function_exists( 'pcntl_async_signals')) try |
run.sh supplies the mode and working directory. An invalid invocation exits with 2. A caught worker error exits with 1, after printing any collected metrics. The shell preserves the worker's exit status unless cleanup fails.
Definition at line 575 of file demo.php.
Referenced by updaterFailure().
1.18.0 