<?php
/**
* CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
* Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
*
* Licensed under The MIT License
* For full copyright and license information, please see the LICENSE.txt
* Redistributions of files must retain the above copyright notice.
*
* @copyright Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
* @link https://cakephp.org CakePHP Project
* @since 3.1.0
* @license https://opensource.org/licenses/mit-license.php MIT License
*/
namespace Cake\Shell\Helper;
use Cake\Console\Helper;
use RuntimeException;
/**
* Create a progress bar using a supplied callback.
*
* ## Usage
*
* The ProgressHelper can be accessed from shells using the helper() method
*
* ```
* $this->helper('Progress')->output(['callback' => function ($progress) {
* // Do work
* $progress->increment();
* });
* ```
*/
class ProgressHelper extends Helper
{
/**
* The current progress.
*
* @var int|float
*/
protected $_progress = 0;
/**
* The total number of 'items' to progress through.
*
* @var int
*/
protected $_total = 0;
/**
* The width of the bar.
*
* @var int
*/
protected $_width = 0;
/**
* Output a progress bar.
*
* Takes a number of options to customize the behavior:
*
* - `total` The total number of items in the progress bar. Defaults
* to 100.
* - `width` The width of the progress bar. Defaults to 80.
* - `callback` The callback that will be called in a loop to advance the progress bar.
*
* @param array $args The arguments/options to use when outputing the progress bar.
* @return void
*/
public function output($args)
{
$args += ['callback' => null];
if (isset($args[0])) {
$args['callback'] = $args[0];
}
if (!$args['callback'] || !is_callable($args['callback'])) {
throw new RuntimeException('Callback option must be a callable.');
}
$this->init($args);
$callback = $args['callback'];
$this->_io->out('', 0);
while ($this->_progress < $this->_total) {
$callback($this);
$this->draw();
}
$this->_io->out('');
}
/**
* Initialize the progress bar for use.
*
* - `total` The total number of items in the progress bar. Defaults
* to 100.
* - `width` The width of the progress bar. Defaults to 80.
*
* @param array $args The initialization data.
* @return $this
*/
public function init(array $args = [])
{
$args += ['total' => 100, 'width' => 80];
$this->_progress = 0;
$this->_width = $args['width'];
$this->_total = $args['total'];
return $this;
}
/**
* Increment the progress bar.
*
* @param int|float $num The amount of progress to advance by.
* @return $this
*/
public function increment($num = 1)
{
$this->_progress = min(max(0, $this->_progress + $num), $this->_total);
return $this;
}
/**
* Render the progress bar based on the current state.
*
* @return $this
*/
public function draw()
{
$numberLen = strlen(' 100%');
$complete = round($this->_progress / $this->_total, 2);
$barLen = ($this->_width - $numberLen) * ($this->_progress / $this->_total);
$bar = '';
if ($barLen > 1) {
$bar = str_repeat('=', $barLen - 1) . '>';
}
$pad = ceil($this->_width - $numberLen - $barLen);
if ($pad > 0) {
$bar .= str_repeat(' ', $pad);
}
$percent = ($complete * 100) . '%';
$bar .= str_pad($percent, $numberLen, ' ', STR_PAD_LEFT);
$this->_io->overwrite($bar, 0);
return $this;
}
}