totten/pogo

Run PHP scripts with inline dependencies

v0.5.0 2022-11-05 02:29 UTC

Requires

• php: >=7.1.8
• civicrm/composer-downloads-plugin: ~3.0
• lesser-evil/shell-verbosity-is-evil: ~1.0
• symfony/console: ~4.0
• symfony/filesystem: ~4.0
• symfony/yaml: ~4.0

Requires (Dev)

• phpunit/phpunit: ~5.0

MIT

• Tim Otten

README

Pogo allows you to write small PHP scripts which use PHP libraries (courtesy of composer/packagist)... but it doesn't require you setup a special-purpose folder, project, or repository. To use a dependency, simply add a small pragma into your script. For example:

#!require symfony/yaml: ~4.4

This makes it easier to use PHP libraries for glue-scripts, throw-away scripts, quick experiments, etc.

Example

Let's pick a small task that requires a few libraries -- suppose we want to generate a pretty PDF from a source-code file (*.php, *.json, etc). We'll need a pretty-printer (scrivo/highlight.php) and a PDF generator (dompdf/dompdf).

Skimming the README for each library, one finds a few introductory snippets. I took these, added the #!require pragmas, and improvised a little on the $html variable. This becomes a small script, code2pdf.php:

<?php
$code = file_get_contents('php://stdin');

#!require scrivo/highlight.php: ~9.15
$hl = new \Highlight\Highlighter();
$hl->setAutodetectLanguages(['php', 'css', 'yaml', 'json', 'js']);
$highlighted = $hl->highlightAuto($code);
$html = sprintf('<link rel="stylesheet" href="file://%s"/>', \HighlightUtilities\getStyleSheetPath('sunburst.css'));
$html .= sprintf("<pre><code class=\"hljs %s\">%s</code></pre>", $highlighted->language, $highlighted->value);

#!require dompdf/dompdf: ~0.8.3
$dompdf = new \Dompdf\Dompdf();
$dompdf->loadHtml($html);
$dompdf->setPaper('A4', 'landscape');
$dompdf->render();
$dompdf->stream();

To run this script in the CLI, just use:

pogo code2pdf.php

Of course, this script expects some content as input (e.g. myfile.yml) and produces a PDF as output (e.g. myfile.pdf), so a more realistic command would be

cat myfile.yml | pogo code2pdf.php > myfile.pdf

That's it!

More examples

The examples folder has several examples of using other libraries and frameworks, such as ReactPHP, Symfony Console, Clippy, and Robo. Each example is an executable program.

Motivation

Most of my day-to-day work is in PHP, JS, and bash. From time-to-time, one needs a bit of glue-code for one-offs, and I find myself avoiding PHP for that task... because using a library in PHP still requires bits of administrativa. pogo is an experiment to reduce that administrativa. Just create a .php file and run it.

Documentation

• Installation: System requirements and install steps
• Composer integration: How pogo works with composer
• Execution: Ways to invoke scripts via pogo
• Compile to PHAR: How to create a phar using pogo
• FAQ: Frequently asked questions
• Pragmas: List of all supported pragmas
• Todo: Misc things that should be done

Related

• Clippy: A variant of symfony/console optimized for scripting.