Add debug command (#1)

README.md

@@ -2,9 +2,9 @@
 
 Binarized flags are not intuitive to understand, using concepts like
 [bitwise operators](http://php.net/manual/en/language.operators.bitwise.php),
-[bitmask](https://en.wikipedia.org/wiki/Mask_(computing)) or [Bit field](https://en.wikipedia.org/wiki/Bit_field).
+[bitmask](https://en.wikipedia.org/wiki/Mask_(computing)) or [bit field](https://en.wikipedia.org/wiki/Bit_field).
 Moreover, theses flags are not easy to debug; find flags that hide behind integer bitfield is very annoying.
-This lib propose a fluent API to handle bitfield and improve developer experience with tools for debugging them.
+This library propose a fluent API to handle bitfield and improve developer experience with tools for debugging them.
 
 [![Build Status](https://travis-ci.org/maidmaid/flag.svg?branch=master)](https://travis-ci.org/maidmaid/flag) 
 [![Latest Stable Version](https://poser.pugx.org/maidmaid/flag/v/stable)](https://packagist.org/packages/maidmaid/flag)
@@ -98,8 +98,8 @@ $flag = Flag::create(null, 'E_')
 As in [``Request::METHOD_*`` case](https://github.com/symfony/symfony/blob/8872833c5d6a46ea27a4483e650617361660d946/src/Symfony/Component/HttpFoundation/Request.php#L49-L58), values flags are not integer but string. For example, ``METHOD_GET`` has ``GET`` string as value. This string values are internally binarized.
 
 ```php
-use Maidmaid\Flag\Flag;
 use Symfony\Component\HttpFoundation\Request;
+use Maidmaid\Flag\Flag;
 
 $flag = Flag::create(Request::class, 'METHOD_')
     ->add(Request::METHOD_GET)  // logs '[debug] bitfield changed Request::METHOD_* [bin: 10] [dec: 2] [METHOD_*: GET]'
@@ -125,3 +125,16 @@ $flag = (new Flag())
     ->add(32) // logs '[debug] bitfield changed [bin: 101000] [dec: 40] [flags: 8 | 32]'
 ;
 ```
+
+## Debug
+
+If you add ``symfony/console`` suggested package, you can debug your flags with ``debug:flag`` command.
+Run ``php bin/flag --help`` for details.
+
+<p align="center">
+ <img src="doc/debug_command.png" width="600">
+</p>
+
+## License
+
+Flag is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

bin/flag

@@ -0,0 +1,15 @@
+#!/usr/bin/env php
+<?php
+
+use Maidmaid\Flag\Command\DebugCommand;
+use Symfony\Component\Console\Application;
+
+require file_exists(__DIR__.'/../vendor/autoload.php')
+    ? __DIR__.'/../vendor/autoload.php'
+    : __DIR__.'/../../../autoload.php'
+;
+
+$app = new Application();
+$app->add(new DebugCommand());
+$app->setDefaultCommand('debug:flag', true);
+$app->run();

bin/flag-example.php

@@ -0,0 +1,152 @@
+<?php
+
+namespace Maidmaid\Flag\Demo;
+
+require __DIR__.'/../vendor/autoload.php';
+
+use Symfony\Component\Console\Logger\ConsoleLogger;
+use Symfony\Component\Console\Output\ConsoleOutput;
+use Maidmaid\Flag\Flag;
+
+$logger = new ConsoleLogger(new ConsoleOutput(ConsoleOutput::VERBOSITY_DEBUG));
+
+echo "\nOverview\n";
+class Yaml
+{
+    const DUMP_OBJECT = 1;
+    const PARSE_EXCEPTION_ON_INVALID_TYPE = 2;
+    const PARSE_OBJECT = 4;
+    const PARSE_OBJECT_FOR_MAP = 8;
+    const DUMP_EXCEPTION_ON_INVALID_TYPE = 16;
+    const PARSE_DATETIME = 32;
+    const DUMP_OBJECT_AS_MAP = 64;
+    const DUMP_MULTI_LINE_LITERAL_BLOCK = 128;
+    const PARSE_CONSTANT = 256;
+}
+$flag = Flag::create(Yaml::class);
+$flag->setLogger($logger);
+$flag
+    ->add(Yaml::DUMP_OBJECT)
+    ->add(Yaml::PARSE_DATETIME)
+    ->remove(Yaml::DUMP_OBJECT)
+;
+var_dump(
+    $flag->has(Yaml::DUMP_OBJECT),
+    $flag->has(Yaml::PARSE_DATETIME),
+    $flag->get()
+);
+$flag->set(100);
+foreach ($flag as $k => $v) {
+    echo "$k => $v ";
+}
+
+echo "\n\nExample\n";
+class Color
+{
+    const RED = 1;
+    const GREEN = 2;
+    const YELLOW = 3;
+    public $flag;
+
+    public function __construct($logger)
+    {
+        $this->flag = Flag::create(self::class);
+        $this->flag->setLogger($logger);
+    }
+}
+(new Color($logger))->flag
+    ->add(Color::RED)
+    ->add(Color::GREEN)
+    ->remove(Color::GREEN)
+;
+
+echo "\nPrefix\n";
+class Caster
+{
+    const EXCLUDE_VERBOSE = 1;
+    const EXCLUDE_VIRTUAL = 2;
+    const EXCLUDE_DYNAMIC = 4;
+    const EXCLUDE_PUBLIC = 8;
+    const EXCLUDE_PROTECTED = 16;
+    const EXCLUDE_PRIVATE = 32;
+    const EXCLUDE_NULL = 64;
+    const EXCLUDE_EMPTY = 128;
+    const EXCLUDE_NOT_IMPORTANT = 256;
+    const EXCLUDE_STRICT = 512;
+}
+$flag = Flag::create(Caster::class, 'EXCLUDE_');
+$flag->setLogger($logger);
+$flag
+    ->add(Caster::EXCLUDE_EMPTY)
+    ->add(Caster::EXCLUDE_PRIVATE)
+    ->add(Caster::EXCLUDE_NOT_IMPORTANT)
+    ->remove(Caster::EXCLUDE_NOT_IMPORTANT)
+;
+
+echo "\nHierarchical\n";
+class Output
+{
+    const VERBOSITY_QUIET = 16;
+    const VERBOSITY_NORMAL = 32;
+    const VERBOSITY_VERBOSE = 64;
+    const VERBOSITY_VERY_VERBOSE = 128;
+    const VERBOSITY_DEBUG = 256;
+}
+$flag = Flag::create(Output::class, 'VERBOSITY_', true);
+$flag->setLogger($logger);
+$flag
+    ->add(Output::VERBOSITY_VERBOSE)
+    ->add(Output::VERBOSITY_DEBUG)
+    ->remove(Output::VERBOSITY_DEBUG)
+;
+
+echo "\nGlobal space\n";
+$flag = Flag::create(null, 'E_');
+$flag->setLogger($logger);
+$flag
+    ->add(E_ALL)
+    ->set(0)
+    ->add(E_USER_ERROR)
+    ->add(E_USER_DEPRECATED)
+    ->remove(E_USER_DEPRECATED)
+;
+
+echo "\nBinarizedFlag\n";
+class Request
+{
+    const METHOD_HEAD = 'HEAD';
+    const METHOD_GET = 'GET';
+    const METHOD_POST = 'POST';
+    const METHOD_PUT = 'PUT';
+    const METHOD_PATCH = 'PATCH';
+    const METHOD_DELETE = 'DELETE';
+    const METHOD_PURGE = 'PURGE';
+    const METHOD_OPTIONS = 'OPTIONS';
+    const METHOD_TRACE = 'TRACE';
+    const METHOD_CONNECT = 'CONNECT';
+}
+$flag = Flag::create(Request::class, 'METHOD_');
+$flag->setLogger($logger);
+$flag
+    ->add(Request::METHOD_GET)
+    ->add(Request::METHOD_POST)
+    ->add(Request::METHOD_PUT)
+    ->remove(Request::METHOD_PUT)
+;
+
+echo "\nStandalone\n";
+$flag = new Flag();
+$flag->setLogger($logger);
+$flag
+    ->add(8)
+    ->add(32)
+    ->remove(32)
+;
+echo "\n";
+$flag = Flag::create();
+$flag->setLogger($logger);
+$flag
+    ->add('a')
+    ->add('b')
+    ->remove('b')
+;

composer.json

@@ -26,11 +26,18 @@
         "psr/log": "^1.0"
     },
     "require-dev": {
-        "phpunit/phpunit": "^5.7"
+        "phpunit/phpunit": "^5.7",
+        "symfony/console": "^3.1"
     },
+    "suggest": {
+        "symfony/console": "For debugging flags using the debug:flag command"
+    },
+    "bin": [
+        "bin/flag"
+    ],
     "autoload": {
         "psr-4": {
             "Maidmaid\\Flag\\": "src/Flag"
         }
     }
-}
+}

src/Flag/AbstractFlag.php

@@ -48,7 +48,7 @@ public function __construct($from = false, $prefix = '', $bitfield = 0)
      * @param string|null|bool $from         Class from where the searching flags is made; define to null to
      *                                       search flags in global space; define to false for standalone use
      * @param string           $prefix       Prefix flags from the search flags is made
-     * @param bool             $hierarchical Defines hierarchical flags
+     * @param bool             $hierarchical Defines flags as hierarchical
      * @param int              $bitfield     Sets bitfield value
      *
      * @return AbstractFlag

src/Flag/Command/DebugCommand.php

@@ -0,0 +1,118 @@
+<?php
+
+/*
+ * This file is part of the maidmaid/flag package.
+ *
+ * (c) Dany Maillard <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Maidmaid\Flag\Command;
+
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Helper\Table;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+use Maidmaid\Flag\Flag;
+
+class DebugCommand extends Command
+{
+    private $legends = array();
+    private $max;
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function configure()
+    {
+        $this
+            ->setName('debug:flag')
+            ->addArgument('bitfield', InputArgument::OPTIONAL, '', 0)
+            ->addOption('from', 'f', InputOption::VALUE_REQUIRED, 'Class where searching flags is made')
+            ->addOption('prefix', 'p', InputOption::VALUE_REQUIRED, 'Prefix flags that filter search result')
+            ->addOption('hierarchical', 'l', InputOption::VALUE_NONE, 'Defines flags as hierarchical')
+            ->setHelp(<<<EOF
+Examples of <info>%command.name%</info> command:
+
+  <info>php %command.full_name% --prefix E_</info>
+  <info>php %command.full_name% --prefix E_ 8</info>
+  <info>php %command.full_name% --from Symfony\\\\Component\\\\Console\\\\Output\\\\Output --prefix VERBOSITY_ --hierarchical 64</info>
+
+EOF
+            )
+        ;
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output)
+    {
+        $bitfield = (int) $input->getArgument('bitfield');
+        $from = $input->getOption('from');
+        $prefix = $input->getOption('prefix') ? $input->getOption('prefix') : '';
+        $hierarchical = $input->getOption('hierarchical');
+
+        $flag = Flag::create($from, $prefix, $hierarchical, $bitfield);
+
+        $flags = array();
+        $flagged = array();
+        $iterator = $flag->getIterator(false);
+        $iterator->ksort();
+        foreach ($iterator as $v => $f) {
+            // Check if it's a top flag
+            if (((int) ($r = log($v, 2))) == $r) {
+                $flags[$r] = $f;
+                $flagged[$r] = $flag->has($v) ? '<bg=green;fg=black;options=bold>1</>' : 0;
+            }
+        }
+        $this->max = max(array_keys($flags));
+
+        $headers = array();
+        $bitfield = array();
+        for ($i = $this->max; $i >= 0; --$i) {
+            $headers[] = $i;
+            $bitfield[] = isset($flagged[$i]) ? $flagged[$i] : 0;
+        }
+
+        $i = -1;
+        foreach ($flags as $x => $flag) {
+            $this->legend($this->max - $x, ++$i, $flag, $flagged[$x]);
+        }
+
+        $rows = $this->legends;
+        array_unshift($rows, $bitfield);
+
+        $table = new Table($output);
+        $table->setColumnWidths(array_fill(0, count($headers), 2));
+        $table->setHeaders($headers);
+        $table->setRows($rows);
+        $table->setStyle('compact');
+
+        $output->writeln('');
+        $table->render();
+    }
+
+    private function legend($x, $y, $name, $highlight = false)
+    {
+        $format = $highlight ? '<info>%s</info>' : '%s';
+
+        while (!isset($this->legends[$y])) {
+            $this->legends[] = array_fill(0, $this->max + 1, '');
+        }
+
+        $this->legends[$y][$x] = sprintf($format, '└─');
+        $this->legends[$y][$this->max + 1] = sprintf($format, $name);
+
+        // h
+        for ($i = $x + 1; $i <= $this->max; ++$i) {
+            $this->legends[$y][$i] = sprintf($format, '──');
+        }
+
+        // v
+        for ($i = $y - 1; $i >= 0; --$i) {
+            $this->legends[$i][$x] = sprintf($format, '│');
+        }
+    }
+}

src/Flag/FlagInterface.php

@@ -53,7 +53,7 @@ public function get();
     /**
      * Adds a flag.
      *
-     * @param int $flag Bitfield to add
+     * @param int|string $flag Flag value to add
      *
      * @return $this
      */

tests/Flag/AbstractFlagTest.php

@@ -8,6 +8,7 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+
 namespace Maidmaid\Flag\Tests;
 
 use PHPUnit\Framework\TestCase;