PHPackages felixarntz/terminal-image - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [CLI & Console](/categories/cli) 4. / 5. felixarntz/terminal-image ActiveLibrary[CLI & Console](/categories/cli) felixarntz/terminal-image ========================= A PHP port of the popular JavaScript library of the same name, enabling the display of images directly in the terminal. 1.0.0(1mo ago)024↓100%MITPHPPHP >=7.4CI passing Since Mar 23Pushed 1mo agoCompare [ Source](https://github.com/felixarntz/terminal-image)[ Packagist](https://packagist.org/packages/felixarntz/terminal-image)[ Docs](https://github.com/felixarntz/terminal-image)[ RSS](/packages/felixarntz-terminal-image/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)Dependencies (6)Versions (2)Used By (0) Terminal Image (PHP) ==================== [](#terminal-image-php) A PHP port of the popular [JavaScript library of the same name](https://www.npmjs.com/package/terminal-image), enabling the display of images directly in the terminal using ANSI escape sequences. [![Terminal Image (PHP) CLI Screenshot](https://private-user-images.githubusercontent.com/3531426/567488913-5d8bfc8d-82ea-4f6c-916a-27299e69e218.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzQ0MTM2MjEsIm5iZiI6MTc3NDQxMzMyMSwicGF0aCI6Ii8zNTMxNDI2LzU2NzQ4ODkxMy01ZDhiZmM4ZC04MmVhLTRmNmMtOTE2YS0yNzI5OWU2OWUyMTgucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDMyNSUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjAzMjVUMDQzNTIxWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9M2MxYjlkMTM0NmEwODU2MDYzMDc1ZmM1ZDNkOTgzMDIwNzUzNTc1NThkYjBjMzEzY2QwMDQwNjg0MDVmYjQ5NyZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.a3iLm9hozLYzZ51UPdfKXkBNejp70FYBQrPH4L9jWjY)](https://private-user-images.githubusercontent.com/3531426/567488913-5d8bfc8d-82ea-4f6c-916a-27299e69e218.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzQ0MTM2MjEsIm5iZiI6MTc3NDQxMzMyMSwicGF0aCI6Ii8zNTMxNDI2LzU2NzQ4ODkxMy01ZDhiZmM4ZC04MmVhLTRmNmMtOTE2YS0yNzI5OWU2OWUyMTgucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDMyNSUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjAzMjVUMDQzNTIxWiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9M2MxYjlkMTM0NmEwODU2MDYzMDc1ZmM1ZDNkOTgzMDIwNzUzNTc1NThkYjBjMzEzY2QwMDQwNjg0MDVmYjQ5NyZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.a3iLm9hozLYzZ51UPdfKXkBNejp70FYBQrPH4L9jWjY)- Supports JPEG, PNG, WebP, and any other format supported by PHP's GD library. - Works in any terminal that supports colors. - Requires PHP >= 7.4 with the GD extension. Installation ------------ [](#installation) ``` composer require felixarntz/terminal-image ``` Usage ----- [](#usage) From a file path: ``` use FelixArntz\TerminalImage\TerminalImage; // excluded in the following examples echo TerminalImage::file('unicorn.jpg'); ``` From a binary string (e.g. an HTTP response body): ``` $data = file_get_contents('https://example.com/unicorn.jpg'); echo TerminalImage::buffer($data); ``` ### Scaling [](#scaling) By default, images are scaled to fit within the terminal window while preserving their aspect ratio. Set a specific width in columns; height is derived from the aspect ratio: ``` echo TerminalImage::file('unicorn.jpg', ['width' => 40]); ``` Set a specific height in rows; width is derived from the aspect ratio: ``` echo TerminalImage::file('unicorn.jpg', ['height' => 20]); ``` Use a percentage of the terminal size: ``` echo TerminalImage::file('unicorn.jpg', ['width' => '50%']); ``` Set both dimensions; the image is scaled to fit within the box: ``` echo TerminalImage::file('unicorn.jpg', ['width' => 60, 'height' => 20]); ``` Disable aspect ratio preservation to stretch to exact dimensions: ``` echo TerminalImage::file('unicorn.jpg', [ 'width' => 60, 'height' => 20, 'preserveAspectRatio' => false, ]); ``` API --- [](#api) ### `TerminalImage::file(string $filePath, array $options = []): string` [](#terminalimagefilestring-filepath-array-options---string) Renders an image from a file path as a string of ANSI escape sequences. - `$filePath` — Absolute or relative path to the image file. - `$options` — Optional associative array of options (see below). Throws `InvalidArgumentException` if the file does not exist, cannot be read, or contains invalid image data. ### `TerminalImage::buffer(string $data, array $options = []): string` [](#terminalimagebufferstring-data-array-options---string) Renders an image from a binary string as a string of ANSI escape sequences. - `$data` — Binary string of image data. - `$options` — Optional associative array of options (see below). Throws `InvalidArgumentException` if the data is not a valid image. ### Options [](#options) KeyTypeDefaultDescription`width``int` or `string`—Target width in columns, or a percentage string (e.g. `'50%'`) relative to the terminal width.`height``int` or `string`—Target height in rows, or a percentage string (e.g. `'50%'`) relative to the terminal height.`preserveAspectRatio``bool``true`Whether to preserve the aspect ratio when both `width` and `height` are provided.When neither `width` nor `height` is provided, the image is scaled to fit within the terminal dimensions. Credit ------ [](#credit) Major credit goes to [@sindresorhus](https://github.com/sindresorhus), who created the original `terminal-image` JavaScript library. License ------- [](#license) MIT ### Health Score 36 — LowBetter than 82% of packages Maintenance90 Actively maintained with recent releases Popularity10 Limited adoption so far Community6 Small or concentrated contributor base Maturity33 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 50d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/a60abe9a2c42fe5cf2117b88aac2eab186f0ea3c969f1f4a29d4a09d831153b8?d=identicon)[felixarntz](/maintainers/felixarntz) --- Top Contributors [![felixarntz](https://avatars.githubusercontent.com/u/3531426?v=4)](https://github.com/felixarntz "felixarntz (19 commits)") --- Tags ansicliimagephpterminalphpterminalimageansi ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/felixarntz-terminal-image/health.svg) ``` [![Health](https://phpackages.com/badges/felixarntz-terminal-image/health.svg)](https://phpackages.com/packages/felixarntz-terminal-image) ``` ### Alternatives [bvanhoekelen/terminal-style Return your terminal message in style! Change the text style, text color and text background color form the terminal interface with ANSI color codes. The terminal style tool support Laravel and Composer. 19784.4k2](/packages/bvanhoekelen-terminal-style)[alecrabbit/php-console-spinner Extremely flexible spinner for \[async\] php cli applications 24032.0k2](/packages/alecrabbit-php-console-spinner)[php-school/learn-you-php An introduction to PHP's core features: i/o, http, arrays, exceptions and so on. 3192.0k](/packages/php-school-learn-you-php)[alecrabbit/php-cli-snake Lightweight cli spinner with zero dependencies 29211.3k5](/packages/alecrabbit-php-cli-snake) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)