bakame/period-visualizer

A Visualizer for League Period.

0.3.1 2018-12-21 11:10 UTC

README

Author Build Status Total Downloads Latest Stable Version Software License

This package contains a visualizer for League Period.

It is heavily inspired from the work of @thecrypticace on the following PR Visualization Helper.

<?php

use Bakame\Period\Visualizer\Viewer;
use Bakame\Period\Visualizer\ConsoleOutput;
use League\Period\Period;
use League\Period\Sequence;

$view = new Viewer(new ConsoleOutput());
echo $view->sequence(new Sequence(
    new Period('2018-01-01', '2018-02-01'),
    new Period('2018-01-15', '2018-02-01')
));

results:

 A    [========]
 B         [===]

System Requirements

You need:

  • PHP >= 7.1.3 but the latest stable version of PHP is recommended

Installation

$ composer require bakame/period-visualizer

Usage

Basic Usage

Viewing a Sequence collection.

<?php

use Bakame\Period\Visualizer\Viewer;
use Bakame\Period\Visualizer\ConsoleOutput;
use League\Period\Period;
use League\Period\Sequence;

$view = new Viewer(new ConsoleOutput());
echo $view->sequence(new Sequence(
    new Period('2018-01-01', '2018-02-01'),
    new Period('2018-01-01', '2018-01-15')
));

results:

 A    [========]
 B    [===]     

Viewing a Sequence gaps.

$view = new Viewer(new ConsoleOutput());
echo $view->gaps(new Sequence(
    new Period('2018-01-01', '2018-03-01'),
    new Period('2018-05-01', '2018-08-01')
));

results:

 A       [=]       
 B            [===]
 GAPS      [==]  

Viewing a Sequence intersections.

$view = new Viewer(new ConsoleOutput());
echo $view->intersections(new Sequence(
    new Period('2018-01-01 08:00:00', '2018-01-01 12:00:00'),
    new Period('2018-01-01 10:00:00', '2018-01-01 14:00:00')
));

results:

 A                [=====]   
 B                   [=====]
 INTERSECTIONS       [==] 

Viewing a Period difference.

$view = new Viewer(new ConsoleOutput());
echo $view->diff
    new Period('2018-01-01 08:00:00', '2018-01-01 12:00:00'),
    new Period('2018-01-01 10:00:00', '2018-01-01 14:00:00')
);

results:

 A       [=====]   
 B          [=====]
 DIFF    [==]  [==]

Advance Usage

Customize the line labels

The Bakame\Period\Visualizer\Viewer class can be further formatter by providing a object to improve line index generation. By default the class is instantiated with the letter index strategy which starts incrementing the labes from the 'A' index. You can choose between the following strategies to modify the default behaviour

Letter strategy

<?php

use Bakame\Period\Visualizer\Viewer;
use Bakame\Period\Visualizer\ConsoleOutput;
use Bakame\Period\Visualizer\Label\LetterType;
use League\Period\Period;
use League\Period\Sequence;

$view = new Viewer(new ConsoleOutput(), new LetterType('aa'));
echo $view->sequence(new Sequence(
    new Period('2018-01-01', '2018-02-01'),
    new Period('2018-01-01', '2018-01-15')
));

results:

 aa    [========]
 ab    [===]     

Integer strategy

<?php

use Bakame\Period\Visualizer\Viewer;
use Bakame\Period\Visualizer\ConsoleOutput;
use Bakame\Period\Visualizer\Label\IntegerType;
use League\Period\Period;
use League\Period\Sequence;

$view = new Viewer(new ConsoleOutput(), new IntegerType(42));
echo $view->sequence(new Sequence(
    new Period('2018-01-01', '2018-02-01'),
    new Period('2018-01-01', '2018-01-15')
));

results:

 42    [========]
 43    [===]     

Roman Number strategy

<?php

use Bakame\Period\Visualizer\Viewer;
use Bakame\Period\Visualizer\ConsoleOutput;
use Bakame\Period\Visualizer\Label\IntegerType;
use Bakame\Period\Visualizer\Label\RomanType;
use League\Period\Period;
use League\Period\Sequence;

$labelGenerator = new RomanType(new IntegerType(5), RomanType::LOWER);

$view = new Viewer(new ConsoleOutput(), $labelGenerator);
echo $view->sequence(new Sequence(
    new Period('2018-01-01', '2018-02-01'),
    new Period('2018-01-01', '2018-01-15')
));

results:

 v     [========]
 vi    [===]     

Affix strategy

<?php

use Bakame\Period\Visualizer\Viewer;
use Bakame\Period\Visualizer\ConsoleOutput;
use Bakame\Period\Visualizer\Label\IntegerType;
use Bakame\Period\Visualizer\Label\RomanType;
use Bakame\Period\Visualizer\Label\AffixType;
use League\Period\Period;
use League\Period\Sequence;

$labelGenerator = new AffixType(new RomanType(new IntegerType(5), RomanType::LOWER));
$labelGenerator = $labelGenerator->withSuffix('.');

$view = new Viewer(new ConsoleOutput(), $labelGenerator);
echo $view->sequence(new Sequence(
    new Period('2018-01-01', '2018-02-01'),
    new Period('2018-01-01', '2018-01-15')
));

results:

 v.     [========]
 vi.    [===]     

Reverse strategy

<?php

use Bakame\Period\Visualizer\Viewer;
use Bakame\Period\Visualizer\ConsoleOutput;
use Bakame\Period\Visualizer\Label\IntegerType;
use Bakame\Period\Visualizer\Label\RomanType;
use Bakame\Period\Visualizer\Label\AffixType;
use Bakame\Period\Visualizer\Label\ReverseType;
use League\Period\Period;
use League\Period\Sequence;

$labelGenerator = new AffixType(new RomanType(new IntegerType(5), RomanType::LOWER));
$labelGenerator = new ReverserType($labelGenerator->withSuffix('.'));

$view = new Viewer(new ConsoleOutput(), $labelGenerator);
echo $view->sequence(new Sequence(
    new Period('2018-01-01', '2018-02-01'),
    new Period('2018-01-01', '2018-01-15')
));

results:

 vi.   [========]
 v.    [===]     

Custom strategy

You can create your own strategy by implementing the Bakame\Period\Visualizer\Label\LabelGenerator interface like shown below:

use Bakame\Period\Visualizer\Viewer;
use Bakame\Period\Visualizer\ConsoleOutput;
use Bakame\Period\Visualizer\Label\AffixType;
use Bakame\Period\Visualizer\Label\LabelGenerator;
use League\Period\Period;
use League\Period\Sequence;

$samelabel = new class implements LabelGenerator {
    public function getLabels(Sequence $sequence): array
    {
        return array_fill(0, count($sequence), 'foobar');
    }
};

$labelGenerator = (new AffixType($samelabel))->withSuffix('.');

$view = new Viewer($output, $labelGenerator);
echo $view->sequence(new Sequence(
    new Period('2018-01-01', '2018-02-01'),
    new Period('2018-01-01', '2018-01-15')
));

results:

 foobar.    [========]
 foobar.    [===]     

Customize the output

If what you want to display can not be rendered using the Viewer class you can fallback to using the ConsoleOutput class directly.

<?php

use Bakame\Period\Visualizer\ConsoleOutput;
use League\Period\Period;

$view = new ConsoleOutput();
echo $view->display([
    ['first', new Period('2018-01-01 08:00:00', '2018-01-01 12:00:00')],
    ['last', new Period('2018-01-01 10:00:00', '2018-01-01 14:00:00')],
]);

results:

 first    [=====]   
 last        [=====]

The ConsoleOutput::display or ConsoleOutput::render methods excepts a tuple as its unique argument where:

  • the first value of the tuple represents the label name
  • the second and last value represents a Period or Sequence object.

The ConsoleOutput class can be further customize by providing a ConsoleConfig object with further configuration to apply to the output.

<?php

use Bakame\Period\Visualizer\ConsoleConfig;
use Bakame\Period\Visualizer\ConsoleOutput;
use League\Period\Period;

$config = (new ConsoleConfig())
    ->withHead('🍅')
    ->withTail('🎾')
    ->withBody('💩')
    ->withSpace('+')
    ->withWidth(30)
    ->withColors('yellow', 'red')
;

$output = new ConsoleOutput($config);
echo $output->display([
    ['first', new Period('2018-01-01 08:00:00', '2018-01-01 12:00:00')],
    ['last', new Period('2018-01-01 10:00:00', '2018-01-01 14:00:00')],
]);

results:

 first    🎾💩💩💩💩💩💩💩💩💩💩💩💩💩💩💩💩💩💩🍅++++++++++
 last     ++++++++++🎾💩💩💩💩💩💩💩💩💩💩💩💩💩💩💩💩💩💩🍅

On a POSIX compliant console the first line will be yellow and the second red

Result on a POSIX compliant console

ALL CONFIGURATION OBJECTS ARE IMMUTABLE SO MODIFYING THEIR PROPERTIES RETURNS A NEW INSTANCE

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Contributions are welcome and will be fully credited. Please see CONTRIBUTING for details.

Testing

The library has a :

  • a PHPUnit test suite
  • a coding style compliance test suite using PHP CS Fixer.
  • a code analysis compliance test suite using PHPStan.

To run the tests, run the following command from the project folder.

$ composer test

Security

If you discover any security related issues, please email nyamsprod@gmail.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.