I Feel PreTTY is a package for formatting PHP scripts on ANSI terminals. Script output is often going by too fast to read, or has too little information to be useful. There is often no indication of how long until done. Adding colors and grouped indentation and an estimated time to completion leaves you that much more prepared for those late nights running those unnerving migrations
distributed under the MIT license.
- Automatic indent management with tier grouping
- ANSI colors (teal, yellow, white, grey, purple), bold
- Progress bar - 0% to 100%
- Estimated time to completion - minutes seconds
- Increased saliva production during sexy script readouts
- Automatically resizes with your terminal
- Simple, chainable, and object oriented API
-
Create a class that extends
PreTTYProcess
, and->install()
your custom components if you have any. This example installs the breadcrumbs component.class ExampleMigration extends PreTTYProcess { function __construct() { parent::__construct(); $this->install(new PreTTYBreadCrumbs); } function run() { //... } }
-
Count your operations as best you can up front, and tick them off as they are done. This will be used to track completion percentage and time estimates
function run() { $this->setTasks(UserQuery::create()->count()); foreach(UserQuery::create()->find() as $user) { $this->doSomethingWith($user); $this->completeTask(); } }
-
Run your tasks, indenting for subtasks and coloring as you see fit. For instance, 'done' can be green and 'error' can be red.
function doSomethingWith(User $user) { $this->say('Processing user #' . $user->getUserID(), 'blue') ->indent() ->say('Doing something'); $user->doSomething(); $this->say('Saving'); $user->save(); $this->say('done', 'green') ->outdent(); }
Have a nice serenading demo of PreTTYProcess
, just run php demo.php
to see what the PreTTYDemo
object has in store for you.
PreTTYProcess
is in itself a very basic object. What it allows is
installing components. The standard PreTTYFormatter
and the
PreTTYProgressBar
are installed by default. It then uses __call()
to send data as hooks all the installed components. Data returned
during a hook is printed. And yes, you can write your own components,
quite easily.
__construct(array $components)
If you do not provide any components
PreTTYFormatter
andPreTTYProgressBar
are installed by default. Technically the next two arguments accept aPreTTYColorCodeProvider
and a TPUTWrapper. These classes create themselves if you do not have a reason to provide them.
->say(string $text, string $color = 'grey', boolean $is_bold = false)
Available colors are teal, yellow, white, grey, and purple. They will not necessarily appear that color on a terminal since most terminals let you customize them. If your output is not indented, bold actually defaults to true.
->install(iPreTTYComponent $component)
Install a new component.
PreTTYFormatter
andPreTTYProgress
bar are installed by default.PreTTYBreadCrumbs
ships but is not installed by default. You can write and install your own components.
->runHook($hook, array $data = array())
Manually run a hook. Every component will receive the hook and the data, and either handle it or ignore it. Hooks are run in the order that components were installed.
component classname:PreTTYFormatter
This is the standard indentation/truncation formatter. But you can easily
swap it out with your own. Installed by default
->indent()
Indent the following calls of
->say()
->outdent()
de-Indent the following calls of
->say()
component classname:PreTTYProgressBar
This renders a progress bar and estimated time until completion at the
bottom of your terminal
->setTasks(integer $amount)
progress bar and time estimate is generated by comparing the amount provide here to how many times you've called
->completeTask()
->completeTasks()
The progress bar and time estimate is generated by tracking how many tasks you've marked completed with this function, to how many total tasks you set with
->setTasks()
component classname:PreTTYBreadCrumbs
The top of your terminal will track the breadcrumbs of how your process
arrived at its latest output. For instance, if every A is compared to
every B, and merged together an item at a time, then you may see this:
+Begin comparing A #123 to all Bs
+++Comparing to B #194
+++++Consolidating
+++++++Consolidating first items
PreTTYBreadCrumbs
does not provide any new methods to PreTTYProcess
when
installed.
Your components must implement the interface iPreTTYComponent
. There
are three methods you must meet:
->setWidth($v)
Tells your component the terminal width (in columns). This is called regularly at the moment. In the future it will only be called when it changes.
->setEncoder(PreTTYColorEncoder $encoder)
See the
PreTTYColorEncoder
's documentation for using colors and moving the cursor
->runHook($hook, array $data = array())
The standard hooks are below. Your object does not need to respond to every hook. The return value from a hook will be echoed.
iPreTTYComponent::HOOK_BEFORE_SAY
- no dataiPreTTYComponent::HOOK_SAY
-array('string' => PreTTYStringObject)
iPreTTYComponent::HOOK_AFTER_SAY
- no dataiPreTTYComponent::HOOK_INDENT
- no dataiPreTTYComponent::HOOK_OUTDENT
- no data
When you install a component, you are able to use your own hooks, thanks
to PreTTYProcess
's usage of __call()
. This is how ->indent()
, ->outdent()
,
->setTasks()
, and completeTask()
all work. The method name gets converted to
all caps and becomes the hook name. The arguments are used as the $data
array.
$component = new MyComponent;
$process->install($component);
// this
$process->customHook(1, 2, 3);
// is the same as
$component->runHook('CUSTOMHOOK', array(1, 2, 3));
ANSI sequences begin a format or move the cursor. If you begin a format make sure you reset the format to normal before your hook ends. The sequences just need to be embedded in your output to affect the terminal.
->encode($color, $bold = false)
This will return a string that, when echoed, turns the text the specified color and weight.
->reset()
This will return a string that, when echoed, resets the text color and weight to normal.
->moveBack($columns)
Moves the cursor right by by the specified number of columns
->moveUp($columns)
Moves the cursor up by by the specified number of columns
->setCursor($line, $column)
Moves the cursor to the specified line and column (0,0 is the upper left corner)
->saveCursor()
saves the position of the cursor so that the
->restoreCursor()
will bring it back to this location.
->restoreCursor()
moves the cursor back to where it was last saved via the method
->saveCursor()