The Symfony Terminal Component

Introducing the Symfony Terminal Component

Transcript

1. Terminal Fabien Potencier
2. Terminal Fabien Potencier
3. 15 years ago... June 14, 2008 symfony 1.1 introduces "tasks"
4. Console is one of the oldest Symfony Component
5. Console is the most used/downloaded Symfony Component
6. Symfony Console > Commands Input: parses CLI arguments/options Code: your own business logic Output: prints, redirect, pipe > Low-level terminal abstractions Cursor Color Style ...
7. namespace Symfony\Component\Console; final class Color { public function __construct(string $foreground = '', string $background = '', array $options = []) bold underscore blink reverse conceal Is it a color? $color = new Color('#000', 'white', ['underscore', 'reverse']); Color Class Console 7.0
8. Introducing the Terminal Component
9. Colors
10. class Color { public function __construct( private readonly string $value, ) { } ANSI-4 16 colors ANSI-256 256 colors ANSI-24 "true colors" Just a color! $color = new Color('#000'); $color = new Color('red'); Color Class Terminal 8.0 $color = $color->tint(20); $color = $color->shade(20); $color = $color->scale(20); $color = $color->mix($anotherColor, 20); Like Saas $context = new Context( colorMode: ColorMode::Ansi8, ); Color "degradation"
11. $color = new AdaptiveColor('#0f0', '#ff0'); $context = new Context( darkMode: true, ); Color adapts depending on your terminal background Light/Dark background? Terminal 8.0 Light Dark
12. $theme = new BootstrapColorTheme(); $color = $theme['primary']; $color = $theme['bg-primary']; // dark mode supported $color = $theme['blue']; $color = $theme['blue-200']; "Semantic" colors ColorTheme > BootstrapColorTheme Terminal 8.0 "Base" colors Dark/Light colors
13. From Colors to Styles namespace Symfony\Component\Console; final class Color { public function __construct(string $foreground = '', string $background = '', array $options = [])
14. Styling, Formatting, ... /** * Formats a message within a section. * * @param string $section The section name * @param string $text The text message * @param integer $size The maximum size allowed for a line (65 by default) */ public function formatSection($section, $text, $size = null) { return sprintf(">> %-$9s %s", $section, $this->excerpt($text, $size)); } /** * Formats a message within a section. */ public function formatSection(string $section, string $message, string $style = 'info'): string { return sprintf('<%s>[%s]</%s> %s', $style, $section, $style, $message); } Console 7.0 circa 2023 Tasks 1.1 circa 2008
15. $style = new Style(); echo $style->render('Hello World!')."\n"; echo $style->foreground('#0f0')->render('Hello World!')."\n"; echo $style->background('#0f0')->render('Hello World!')."\n"; echo $style->foreground('#0f0')->background('#0f0')->render('Hello World!')."\n"; echo $style->bold()->render('Hello World!')."\n"; echo $style->italic()->render('Hello World!')."\n"; echo $style->bold()->italic()->render('Hello World!')."\n"; echo $style->link('https://symfony.com')->render('Hello World!')."\n"; $style = (new Style()) ->foreground('#0f0') ->background('#0f0') ->bold() ->italic() ; Rendering a Style Style Terminal 8.0 Colors "Options" like bold/italic Reuse styles
16. echo $style ->foreground($theme['indigo']) ->background($theme['yellow']) ->render('Hello World!')."\n" ; Inline vs Block Terminal 8.0 inline by default echo $style ->display(Style::DISPLAY_BLOCK) ->render('Hello World!') ; block display echo $style ->foreground($theme['indigo']) ->background($theme['yellow']) ->render('Hello World!')."\n" ; Style with a ColorTheme
17. echo $style ->display(Style::DISPLAY_BLOCK) ->foreground($theme['yellow-300']) ->background($theme['pink-600']) ->height(10) ->align(Position::MIDDLE) ->render('Hello World!') ; echo $style ->display(Style::DISPLAY_BLOCK) ->foreground($theme['yellow-300']) ->background($theme['pink-600']) ->width(40) ->align(Position::CENTER) ->render('Hello World!') ; Size & Alignement Terminal 8.0
18. echo $style ->display(Style::DISPLAY_BLOCK) ->foreground($theme['yellow-300']) ->background($theme['pink-600']) ->width(40) ->height(10) ->align(Position::MIDDLE | Position::CENTER) ->render('Hello World!') ; Size & Alignement Terminal 8.0
19. CSS on the console?
20. echo $style ->display(Style::DISPLAY_BLOCK) ->padding(4, 6) ->foreground($theme['yellow-300']) ->background($theme['pink-600']) ->align(Position::MIDDLE | Position::CENTER) ->render('Hello World!') ; Padding Terminal 8.0 padding(4) padding(4, 6) padding(4, 7, 2, 6)
21. echo $style ->display(Style::DISPLAY_BLOCK) ->foreground($theme['yellow-300']) ->background($theme['pink-600']) ->align(Position::MIDDLE | Position::CENTER) ->padding(4, 6) ->margin(2, 4) ->render('Hello World!') ; Margin Terminal 8.0 margin(4) margin(4, 6) margin(4, 6, 4, 6)
22. echo $style ->display(Style::DISPLAY_BLOCK) ->foreground($theme['yellow-300']) ->background($theme['pink-600']) ->align(Position::MIDDLE | Position::CENTER) ->padding(4, 6) ->margin(2, 4) ->borderStyle(BorderStyle::ROUNDED) ->render('Hello World!') ; Border Terminal 8.0
23. $borderStyle = $style ->display(Style::DISPLAY_BLOCK) ->padding(0, 1) ->marginBottom(1) ->background($theme['yellow']) ->foreground($theme['indigo']) ->borderBackground($theme['yellow']) ->borderForeground($theme['indigo']) ->align(Position::MIDDLE | Position::CENTER) ; Let's reuse the base style Terminal 8.0
24. echo $borderStyle ->borderStyle(BorderStyle::WIDE) ->render('Hello World!') ; echo $borderStyle ->borderStyle(BorderStyle::TALL) ->render('Hello World!') ; Smart Borders Terminal 8.0
25. Smart Borders Terminal 8.0 ['▁', '▁', '▁'] ['▎', ' ', '▊'] ['▔', '▔', '▔'] ['▊', '▔', '▎'] ['▊', ' ', '▎'] ['▊', '▁', '▎'] [2, 0, 1] [2, 0, 1] [2, 0, 1] [1, 1, 1] [0, 1, 3] [1, 1, 1]
26. $titleStyle = $style ->display(Style::DISPLAY_BLOCK) ->padding(0, 2) ->foreground($theme['indigo']) ->align(Position::MIDDLE | Position::CENTER) ->borderStyle(BorderStyle::WIDE) ->borderBottom(true) ; echo $titleStyle->render('Hello World!'); Be creative with borders Terminal 8.0
27. echo $titleStyle->toString(); Debugging styles Terminal 8.0
28. printf('%-10s ', 'Shade'); for ($i = 1; $i <= 9; $i++) { echo $style->foreground($theme['indigo-'.(100 * $i)])->render('▃▃'); } printf('%-10s ', 'Scale'); for ($i = -$max; $i <= $max; $i++) { echo $style->foreground($theme['indigo']->scale((int) (- $i / $max * 100)))->render('▃'); } printf('%-10s ', 'Shade'); for ($i = 0; $i <= $max; $i++) { echo $style->foreground($theme['indigo']->shade((int) (100 - $i / $max * 100)))->render('▃'); } printf('%-10s ', 'Tint'); for ($i = 0; $i <= $max; $i++) { echo $style->foreground($theme['indigo']->tint((int) (100 - $i / $max * 100)))->render('▃'); } printf('%-10s ', 'Mix'); for ($i = 0; $i <= $max; $i++) { echo $style->foreground($theme['indigo']->mix($theme['yellow'], (int) (100 - $i / $max * 100)))->render('▃'); } Terminal 8.0 foreach ($theme::BASE_SEMANTIC_COLORS as $name) { printf('%-10s ', ucfirst($name)); for ($i = 1; $i <= 9; $i++) { print($style->foreground($theme[$name.'-'.($i * 100)]) ->render('██')); } } printf('%-10s ', 'Gray'); for ($i = 1; $i <= 9; $i++) { print($style->foreground($theme['gray-'.($i * 100)]) ->render('██')); }
29. From a Style to a Stylesheet
30. $stylesheet = new DefaultStylesheet(); echo $stylesheet['span']->render('Hello World!')."\n"; echo $stylesheet['div']->render('Hello World!'); echo $stylesheet['div']->bold()->render('Hello World!'); echo $stylesheet['b']->render('Hello World!')."\n"; echo $stylesheet['div bold']->render('Hello World!'); echo $stylesheet['h1']->render('Hello World!'); echo $stylesheet['h2']->render('Hello World!'); Stylesheet Terminal 8.0
31. echo $stylesheet['p p-2 my-1 italic text-html-silver bg-html-green'] ->render('Hello World!'); Tailwind-like Terminal 8.0
32. $stylesheet['my-box'] = $stylesheet['p p-2 italic text-html-silver bg-html-green']; echo $stylesheet['my-box w-full']->render('Hello World!')."\n"; Compose styles Terminal 8.0
33. $stylesheet = new DefaultStylesheet(); foreach (ColorTheme::BASE_SEMANTIC_COLORS as $name) { echo $stylesheet['.alert-'.$name]->render('This is a '.$name.' alert box!'); } $content = $stylesheet['h1']->render('Well done!'). $stylesheet['p']->render('Lorem ipsum...'). $stylesheet['p']->marginBottom(0)->render('Lorem ipsum...') ; echo $stylesheet['.alert-success']->render($content); Default useful styles like Bootstrap alerts Terminal 8.0
34. $term = new Terminal(); $stdout = $term->stdout(); dump( $stdout->hasDarkBackground(), $stdout->getWidth(), $stdout->getHeight(), ); print "\n\n"; $context = $stdout->getContext(); dump($context); print "\n\n"; $cursor = $stdout->cursor() $cursor->moveToPosition(10, 10); // operations on the screen $screen = $stdout->screen(); $screen->enableMouse(); $screen->clear(); Terminal Terminal 8.0
35. Organizing content
36. $screen = new Columns( 'LEFT', 'RIGHT', ); echo $screen->render(); $stylesheet['.screen'] = (new Style()) ->width('terminal["width"]') ->height(20) ; $screen = (new Columns( new StyledContent('LEFT', $stylesheet['.cell w-2fr']), new StyledContent('RIGHT', $stylesheet['.cell w-1fr']), ))->style($stylesheet['.screen']); echo $screen->render(); $screen = (new Rows( $screen, $screen, ))->style($stylesheet['.screen']); echo $screen->render(); Columns and Rows Terminal 8.0 2fr 1fr $stylesheet['.cell'] = (new Style()) ->borderStyle(BorderStyle::ROUNDED) ->align(Position::CENTER) ->borderForeground('color("border-primary")') ;
37. $screen = (new Columns( (new Rows( new StyledContent('UP', $stylesheet['.cell']), new StyledContent('MIDDLE', $stylesheet['.cell']), new StyledContent(' LOW ', $stylesheet['.cell']), ))->position(Position::MIDDLE)->style($stylesheet['.cell w-1fr']), new StyledContent('CENTER', $stylesheet['.cell w-1fr']), new StyledContent(trim(str_repeat("RIGHT\n", 15)), $stylesheet['.cell w-1fr']), ))->position(Position::BOTTOM)->style($stylesheet['.screen']); echo $screen->render(); Columns and Rows Terminal 8.0
38. From Static to Interactive with Widgets
39. interface WidgetInterface extends RenderInterface { public function init(Stylesheet $stylesheet, LoggerInterface $logger): void; public function update(MessageInterface $message): ?MessageInterface; } interface RenderInterface { public function render(): string; } WidgetInterface Terminal 8.0 ExitMessage KeyMessage MouseMessage TickMessage WindowSizeMessage
40. class HelloWorldWidget implements WidgetInterface { public function init(Stylesheet $stylesheet, LoggerInterface $logger): void { } public function update(MessageInterface $message): ?MessageInterface { if ($message instanceof KeyMessage && 'q' === (string) $message->key) { return new ExitMessage(); } return null; } public function render(): string { return 'Hello World!'; } } $term = new Terminal(); $stylesheet = new DefaultStylesheet(); $app = new Application($term, $stylesheet, new HelloWorldWidget()); $app->run(); HelloWorldWidget Terminal 8.0 Render Update the state Infinite loop
41. A Pager Terminal 8.0 Supported keys up and down page up and down go to top go to bottom
42. public function __construct(string $content) { $this->viewport = new ViewportWidget(); $this->viewport->setContent($content, substr_count($content, "\n")); } public function init(Stylesheet $stylesheet, LoggerInterface $logger): void { $this->stylesheet = $stylesheet; $this->viewport->init($stylesheet, $logger); } public function update(MessageInterface $message): ?MessageInterface { $this->viewport->update($message); return null; } public function render(): string { return $this->stylesheet['span p-1 border-double'] ->render($this->viewport->render()); } A Pager Terminal 8.0 Update the Viewport Propagate init() Render the Viewport Rely on another widget
43. $screen->enableMouse(); try { $app->run(); } finally { $screen->disableMouse(); } Mouse support Terminal 8.0 if ($message instanceof WindowSizeMessage) { $this->viewport->width($message->width); $this->viewport->height($message->height); } Window resizing support
44. Demo Time? Terminal
45. A component with many sub-parts Multi-year effort - release gradually 7.1 -> 8.0 Progressively use it internally in Console Help from the community needed Terminal
46. First Pull request: Empty "shell" Terminal 8.0 Second one: Color sub-namespace
48. https://symfony.com/sponsor Sponsor Symfony Thank you!