diff --git a/.actrc b/.actrc new file mode 100644 index 0000000..99e6b7e --- /dev/null +++ b/.actrc @@ -0,0 +1,3 @@ +# Configuration file for nektos/act. +# See https://github.com/nektos/act#configuration +-P ubuntu-latest=shivammathur/node:latest diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..84f918e --- /dev/null +++ b/.editorconfig @@ -0,0 +1,26 @@ +# This file is for unifying the coding style for different editors and IDEs +# editorconfig.org + +# WordPress Coding Standards +# https://make.wordpress.org/core/handbook/coding-standards/ + +# From https://github.com/WordPress/wordpress-develop/blob/trunk/.editorconfig with a couple of additions. + +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +indent_style = tab + +[{*.yml,*.feature,.jshintrc,*.json}] +indent_style = space +indent_size = 2 + +[*.md] +trim_trailing_whitespace = false + +[{*.txt,wp-config-sample.php}] +end_of_line = crlf diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..d84f4ad --- /dev/null +++ b/.gitattributes @@ -0,0 +1,14 @@ +/.actrc export-ignore +/.distignore export-ignore +/.editorconfig export-ignore +/.github export-ignore +/.gitignore export-ignore +/.typos.toml export-ignore +/AGENTS.md export-ignore +/behat.yml export-ignore +/features export-ignore +/phpcs.xml.dist export-ignore +/phpstan.neon.dist export-ignore +/phpunit.xml.dist export-ignore +/tests export-ignore +/wp-cli.yml export-ignore diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..f69375f --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @wp-cli/committers diff --git a/.github/dependabot.yml b/.github/dependabot.yml index b60e661..d6c7b8b 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -7,3 +7,11 @@ updates: open-pull-requests-limit: 10 labels: - scope:distribution + - package-ecosystem: github-actions + directory: "/" + schedule: + interval: daily + open-pull-requests-limit: 10 + labels: + - scope:distribution + diff --git a/.github/workflows/check-branch-alias.yml b/.github/workflows/check-branch-alias.yml new file mode 100644 index 0000000..78da637 --- /dev/null +++ b/.github/workflows/check-branch-alias.yml @@ -0,0 +1,14 @@ +name: Check Branch Alias + +on: + release: + types: [released] + workflow_dispatch: + +permissions: + contents: write + pull-requests: write + +jobs: + check-branch-alias: + uses: wp-cli/.github/.github/workflows/reusable-check-branch-alias.yml@main diff --git a/.github/workflows/code-quality.yml b/.github/workflows/code-quality.yml new file mode 100644 index 0000000..e9fe577 --- /dev/null +++ b/.github/workflows/code-quality.yml @@ -0,0 +1,14 @@ +name: Code Quality Checks + +on: + pull_request: + push: + branches: + - main + - master + schedule: + - cron: '17 2 * * *' # Run every day on a seemly random time. + +jobs: + code-quality: + uses: wp-cli/.github/.github/workflows/reusable-code-quality.yml@main diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml new file mode 100644 index 0000000..ffb6f8f --- /dev/null +++ b/.github/workflows/copilot-setup-steps.yml @@ -0,0 +1,47 @@ +name: "Copilot Setup Steps" + +on: + workflow_dispatch: + push: + paths: + - .github/workflows/copilot-setup-steps.yml + pull_request: + paths: + - .github/workflows/copilot-setup-steps.yml + +permissions: + contents: read + +jobs: + copilot-setup-steps: + name: Setup environment + runs-on: ubuntu-latest + permissions: + contents: read + + steps: + - name: Checkout code + uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + with: + persist-credentials: false + + - name: Check existence of composer.json file + id: check_composer_file + run: echo "files_exists=$(test -f composer.json && echo true || echo false)" >> "$GITHUB_OUTPUT" + + - name: Set up PHP environment + if: steps.check_composer_file.outputs.files_exists == 'true' + uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2 + with: + php-version: 'latest' + ini-values: zend.assertions=1, error_reporting=-1, display_errors=On + coverage: 'none' + tools: composer,cs2pr + env: + COMPOSER_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Install Composer dependencies & cache dependencies + if: steps.check_composer_file.outputs.files_exists == 'true' + uses: ramsey/composer-install@65e4f84970763564f46a70b8a54b90d033b3bdda # 4.0.0 + env: + COMPOSER_ROOT_VERSION: dev-${{ github.event.repository.default_branch }} diff --git a/.github/workflows/issue-triage.yml b/.github/workflows/issue-triage.yml new file mode 100644 index 0000000..6833470 --- /dev/null +++ b/.github/workflows/issue-triage.yml @@ -0,0 +1,33 @@ +--- +name: Issue and PR Triage + +'on': + issues: + types: [opened] + pull_request_target: + types: [opened] + workflow_dispatch: + inputs: + issue_number: + description: 'Issue/PR number to triage (leave empty to process all)' + required: false + type: string + +permissions: + issues: write + pull-requests: write + actions: write + contents: read + models: read + +jobs: + issue-triage: + uses: wp-cli/.github/.github/workflows/reusable-issue-triage.yml@main + with: + issue_number: >- + ${{ + (github.event_name == 'workflow_dispatch' && inputs.issue_number) || + (github.event_name == 'pull_request_target' && github.event.pull_request.number) || + (github.event_name == 'issues' && github.event.issue.number) || + '' + }} diff --git a/.github/workflows/manage-labels.yml b/.github/workflows/manage-labels.yml new file mode 100644 index 0000000..45711bd --- /dev/null +++ b/.github/workflows/manage-labels.yml @@ -0,0 +1,19 @@ +--- +name: Manage Labels + +'on': + workflow_dispatch: + push: + branches: + - main + - master + paths: + - 'composer.json' + +permissions: + issues: write + contents: read + +jobs: + manage-labels: + uses: wp-cli/.github/.github/workflows/reusable-manage-labels.yml@main diff --git a/.github/workflows/regenerate-readme.yml b/.github/workflows/regenerate-readme.yml new file mode 100644 index 0000000..6198d63 --- /dev/null +++ b/.github/workflows/regenerate-readme.yml @@ -0,0 +1,19 @@ +name: Regenerate README file + +on: + workflow_dispatch: + push: + branches: + - main + - master + paths-ignore: + - "features/**" + - "README.md" + +permissions: + contents: write + pull-requests: write + +jobs: + regenerate-readme: + uses: wp-cli/.github/.github/workflows/reusable-regenerate-readme.yml@main diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml new file mode 100644 index 0000000..bf67592 --- /dev/null +++ b/.github/workflows/testing.yml @@ -0,0 +1,15 @@ +name: Testing + +on: + workflow_dispatch: + pull_request: + push: + branches: + - main + - master + schedule: + - cron: '17 1 * * *' # Run every day on a seemly random time. + +jobs: + test: + uses: wp-cli/.github/.github/workflows/reusable-testing.yml@main diff --git a/.github/workflows/welcome-new-contributors.yml b/.github/workflows/welcome-new-contributors.yml new file mode 100644 index 0000000..bc01490 --- /dev/null +++ b/.github/workflows/welcome-new-contributors.yml @@ -0,0 +1,15 @@ +name: Welcome New Contributors + +on: + pull_request_target: + types: [opened] + branches: + - main + - master + +permissions: + pull-requests: write + +jobs: + welcome: + uses: wp-cli/.github/.github/workflows/reusable-welcome-new-contributors.yml@main diff --git a/.gitignore b/.gitignore index a4f5cdb..379cd9a 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ vendor .*.swp composer.lock +.phpunit.result.cache diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index c72594f..0000000 --- a/.travis.yml +++ /dev/null @@ -1,26 +0,0 @@ -sudo: false -dist: trusty - -language: php - -php: - - 5.4 - - 5.5 - - 5.6 - - 7.0 - - 7.1 - -matrix: - include: - - dist: precise - php: 5.3 - -before_script: - - php -m - - php --info | grep -i 'intl\|icu\|pcre' - -script: phpunit --debug - -notifications: - email: - on_success: never diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1ff84f6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,121 @@ +# Instructions + +This package is part of WP-CLI, the official command line interface for WordPress. For a detailed explanation of the project structure and development workflow, please refer to the main @README.md file. + +## Best Practices for Code Contributions + +When contributing to this package, please adhere to the following guidelines: + +* **Follow Existing Conventions:** Before writing any code, analyze the existing codebase in this package to understand the coding style, naming conventions, and architectural patterns. +* **Focus on the Package's Scope:** All changes should be relevant to the functionality of the package. +* **Write Tests:** All new features and bug fixes must be accompanied by acceptance tests using Behat. You can find the existing tests in the `features/` directory. There may be PHPUnit unit tests as well in the `tests/` directory. +* **Update Documentation:** If your changes affect the user-facing functionality, please update the relevant inline code documentation. + +### Building and running + +Before submitting any changes, it is crucial to validate them by running the full suite of static code analysis and tests. To run the full suite of checks, execute the following command: `composer test`. + +This single command ensures that your changes meet all the quality gates of the project. While you can run the individual steps separately, it is highly recommended to use this single command to ensure a comprehensive validation. + +### Useful Composer Commands + +The project uses Composer to manage dependencies and run scripts. The following commands are available: + +* `composer install`: Install dependencies. +* `composer test`: Run the full test suite, including linting, code style checks, static analysis, and unit/behavior tests. +* `composer lint`: Check for syntax errors. +* `composer phpcs`: Check for code style violations. +* `composer phpcbf`: Automatically fix code style violations. +* `composer phpstan`: Run static analysis. +* `composer phpunit`: Run unit tests. +* `composer behat`: Run behavior-driven tests. + +### Coding Style + +The project follows the `WP_CLI_CS` coding standard, which is enforced by PHP_CodeSniffer. The configuration can be found in `phpcs.xml.dist`. Before submitting any code, please run `composer phpcs` to check for violations and `composer phpcbf` to automatically fix them. + +## Documentation + +The `README.md` file might be generated dynamically from the project's codebase using `wp scaffold package-readme` ([doc](https://github.com/wp-cli/scaffold-package-command#wp-scaffold-package-readme)). In that case, changes need to be made against the corresponding part of the codebase. + +### Inline Documentation + +Only write high-value comments if at all. Avoid talking to the user through comments. + +## Testing + +The project has a comprehensive test suite that includes unit tests, behavior-driven tests, and static analysis. + +* **Unit tests** are written with PHPUnit and can be found in the `tests/` directory. The configuration is in `phpunit.xml.dist`. +* **Behavior-driven tests** are written with Behat and can be found in the `features/` directory. The configuration is in `behat.yml`. +* **Static analysis** is performed with PHPStan. + +All tests are run on GitHub Actions for every pull request. + +When writing tests, aim to follow existing patterns. Key conventions include: + +* When adding tests, first examine existing tests to understand and conform to established conventions. +* For unit tests, extend the base `WP_CLI\Tests\TestCase` test class. +* For Behat tests, only WP-CLI commands installed in `composer.json` can be run. + +### Behat Steps + +WP-CLI makes use of a Behat-based testing framework and provides a set of custom step definitions to write feature tests. + +> **Note:** If you are expecting an error output in a test, you need to use `When I try ...` instead of `When I run ...` . + +#### Given + +* `Given an empty directory` - Creates an empty directory. +* `Given /^an? (empty|non-existent) ([^\s]+) directory$/` - Creates or deletes a specific directory. +* `Given an empty cache` - Clears the WP-CLI cache directory. +* `Given /^an? ([^\s]+) (file|cache file):$/` - Creates a file with the given contents. +* `Given /^"([^"]+)" replaced with "([^"]+)" in the ([^\s]+) file$/` - Search and replace a string in a file using regex. +* `Given /^that HTTP requests to (.*?) will respond with:$/` - Mock HTTP requests to a given URL. +* `Given WP files` - Download WordPress files without installing. +* `Given wp-config.php` - Create a wp-config.php file using `wp config create`. +* `Given a database` - Creates an empty database. +* `Given a WP install(ation)` - Installs WordPress. +* `Given a WP install(ation) in :subdir` - Installs WordPress in a given directory. +* `Given a WP install(ation) with Composer` - Installs WordPress with Composer. +* `Given a WP install(ation) with Composer and a custom vendor directory :vendor_directory` - Installs WordPress with Composer and a custom vendor directory. +* `Given /^a WP multisite (subdirectory|subdomain)?\s?(install|installation)$/` - Installs WordPress Multisite. +* `Given these installed and active plugins:` - Installs and activates one or more plugins. +* `Given a custom wp-content directory` - Configure a custom `wp-content` directory. +* `Given download:` - Download multiple files into the given destinations. +* `Given /^save (STDOUT|STDERR) ([\'].+[^\'])?\s?as \{(\w+)\}$/` - Store STDOUT or STDERR contents in a variable. +* `Given /^a new Phar with (?:the same version|version "([^"]+)")$/` - Build a new WP-CLI Phar file with a given version. +* `Given /^a downloaded Phar with (?:the same version|version "([^"]+)")$/` - Download a specific WP-CLI Phar version from GitHub. +* `Given /^save the (.+) file ([\'].+[^\'])? as \{(\w+)\}$/` - Stores the contents of the given file in a variable. +* `Given a misconfigured WP_CONTENT_DIR constant directory` - Modify wp-config.php to set `WP_CONTENT_DIR` to an empty string. +* `Given a dependency on current wp-cli` - Add `wp-cli/wp-cli` as a Composer dependency. +* `Given a PHP built-in web server` - Start a PHP built-in web server in the current directory. +* `Given a PHP built-in web server to serve :subdir` - Start a PHP built-in web server in the given subdirectory. + +#### When + +* ``When /^I launch in the background `([^`]+)`$/`` - Launch a given command in the background. +* ``When /^I (run|try) `([^`]+)`$/`` - Run or try a given command. +* ``When /^I (run|try) `([^`]+)` from '([^\s]+)'$/`` - Run or try a given command in a subdirectory. +* `When /^I (run|try) the previous command again$/` - Run or try the previous command again. + +#### Then + +* `Then /^the return code should( not)? be (\d+)$/` - Expect a specific exit code of the previous command. +* `Then /^(STDOUT|STDERR) should( strictly)? (be|contain|not contain):$/` - Check the contents of STDOUT or STDERR. +* `Then /^(STDOUT|STDERR) should be a number$/` - Expect STDOUT or STDERR to be a numeric value. +* `Then /^(STDOUT|STDERR) should not be a number$/` - Expect STDOUT or STDERR to not be a numeric value. +* `Then /^STDOUT should be a table containing rows:$/` - Expect STDOUT to be a table containing the given rows. +* `Then /^STDOUT should end with a table containing rows:$/` - Expect STDOUT to end with a table containing the given rows. +* `Then /^STDOUT should be JSON containing:$/` - Expect valid JSON output in STDOUT. +* `Then /^STDOUT should be a JSON array containing:$/` - Expect valid JSON array output in STDOUT. +* `Then /^STDOUT should be CSV containing:$/` - Expect STDOUT to be CSV containing certain values. +* `Then /^STDOUT should be YAML containing:$/` - Expect STDOUT to be YAML containing certain content. +* `Then /^(STDOUT|STDERR) should be empty$/` - Expect STDOUT or STDERR to be empty. +* `Then /^(STDOUT|STDERR) should not be empty$/` - Expect STDOUT or STDERR not to be empty. +* `Then /^(STDOUT|STDERR) should be a version string (<|<=|>|>=|==|=|<>) ([+\w.{}-]+)$/` - Expect STDOUT or STDERR to be a version string comparing to the given version. +* `Then /^the (.+) (file|directory) should( strictly)? (exist|not exist|be:|contain:|not contain):$/` - Expect a certain file or directory to (not) exist or (not) contain certain contents. +* `Then /^the contents of the (.+) file should( not)? match (((\/.*\/)|(#.#))([a-z]+)?)$/` - Match file contents against a regex. +* `Then /^(STDOUT|STDERR) should( not)? match (((\/.*\/)|(#.#))([a-z]+)?)$/` - Match STDOUT or STDERR against a regex. +* `Then /^an email should (be sent|not be sent)$/` - Expect an email to be sent (or not). +* `Then the HTTP status code should be :code` - Expect the HTTP status code for visiting `http://localhost:8080`. diff --git a/README.md b/README.md index 866a82c..0c9b5e3 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,11 @@ PHP Command Line Tools ====================== -[![Build Status](https://travis-ci.org/wp-cli/php-cli-tools.png?branch=master)](https://travis-ci.org/wp-cli/php-cli-tools) - A collection of functions and classes to assist with command line development. Requirements - * PHP >= 5.3 + * PHP >= 5.6 Suggested PHP extensions diff --git a/composer.json b/composer.json index bec076d..c9b58c0 100644 --- a/composer.json +++ b/composer.json @@ -18,8 +18,19 @@ } ], "require": { - "php": ">= 5.3.0" + "php": ">= 7.2.24" }, + "require-dev": { + "roave/security-advisories": "dev-latest", + "wp-cli/wp-cli-tests": "^5" + }, + "extra": { + "branch-alias": { + "dev-main": "0.12.x-dev" + } + }, + "minimum-stability": "dev", + "prefer-stable": true, "autoload": { "psr-0": { "cli": "lib/" @@ -27,5 +38,28 @@ "files": [ "lib/cli/cli.php" ] + }, + "config": { + "allow-plugins": { + "dealerdirect/phpcodesniffer-composer-installer": true, + "johnpbloch/wordpress-core-installer": true, + "phpstan/extension-installer": true + } + }, + "scripts": { + "behat": "run-behat-tests", + "behat-rerun": "rerun-behat-tests", + "lint": "run-linter-tests", + "phpcs": "run-phpcs-tests", + "phpstan": "run-phpstan-tests", + "phpunit": "run-php-unit-tests", + "prepare-tests": "install-package-tests", + "test": [ + "@lint", + "@phpcs", + "@phpstan", + "@phpunit", + "@behat" + ] } } diff --git a/examples/common.php b/examples/common.php index 5086a13..9c92bec 100644 --- a/examples/common.php +++ b/examples/common.php @@ -4,7 +4,7 @@ die('Must run from command line'); } -error_reporting(E_ALL | E_STRICT); +error_reporting(E_ALL); ini_set('display_errors', 1); ini_set('log_errors', 0); ini_set('html_errors', 0); diff --git a/examples/menu.php b/examples/menu.php index 869cb4f..df0bb3e 100644 --- a/examples/menu.php +++ b/examples/menu.php @@ -19,6 +19,6 @@ break; } - include "${choice}.php"; + include "{$choice}.php"; \cli\line(); } diff --git a/examples/progress-step-format.php b/examples/progress-step-format.php new file mode 100644 index 0000000..a79965d --- /dev/null +++ b/examples/progress-step-format.php @@ -0,0 +1,60 @@ +tick(); + usleep(100000); +} +$progress->finish(); + +echo "\n"; + +// Example 2: Step-based format (current/total) +echo "Example 2: Step-based format (current/total)\n"; +$progress = new \cli\progress\Bar( + 'Step format', + 10, + 100, + '{:msg} {:current}/{:total} [' // Custom formatMessage with current/total +); +for ($i = 0; $i < 10; $i++) { + $progress->tick(); + usleep(100000); +} +$progress->finish(); + +echo "\n"; + +// Example 3: Custom format combining steps and percentage +echo "Example 3: Custom format combining steps and percentage\n"; +$progress = new \cli\progress\Bar( + 'Mixed format', + 50, + 100, + '{:msg} {:current}/{:total} ({:percent}%) [' // Both current/total and percent +); +for ($i = 0; $i < 50; $i++) { + $progress->tick(); + usleep(50000); +} +$progress->finish(); + +echo "\n"; + +// Example 4: Large numbers with step format +echo "Example 4: Large numbers with step format\n"; +$progress = new \cli\progress\Bar( + 'Processing items', + 1000, + 100, + '{:msg} {:current}/{:total} [' +); +for ($i = 0; $i < 1000; $i += 50) { + $progress->tick(50); + usleep(20000); +} +$progress->finish(); diff --git a/examples/table-alignment.php b/examples/table-alignment.php new file mode 100755 index 0000000..cc55e63 --- /dev/null +++ b/examples/table-alignment.php @@ -0,0 +1,103 @@ +#!/usr/bin/env php +setHeaders(['Product', 'Price', 'Stock']); +$table->addRow(['Widget', '$19.99', '150']); +$table->addRow(['Gadget', '$29.99', '75']); +$table->addRow(['Tool', '$9.99', '200']); +$table->display(); +cli\line(); + +// Example 2: Right Alignment for Numeric Columns +cli\line('%Y## Example 2: Right Alignment for Numeric Columns%n'); +cli\line('Notice how the numeric values are much easier to compare when right-aligned.'); +cli\line(); +$table = new cli\Table(); +$table->setHeaders(['Product', 'Price', 'Stock']); +$table->setAlignments([ + 'Product' => cli\table\Column::ALIGN_LEFT, + 'Price' => cli\table\Column::ALIGN_RIGHT, + 'Stock' => cli\table\Column::ALIGN_RIGHT, +]); +$table->addRow(['Widget', '$19.99', '150']); +$table->addRow(['Gadget', '$29.99', '75']); +$table->addRow(['Tool', '$9.99', '200']); +$table->display(); +cli\line(); + +// Example 3: Center Alignment +cli\line('%Y## Example 3: Center Alignment%n'); +cli\line(); +$table = new cli\Table(); +$table->setHeaders(['Left', 'Center', 'Right']); +$table->setAlignments([ + 'Left' => cli\table\Column::ALIGN_LEFT, + 'Center' => cli\table\Column::ALIGN_CENTER, + 'Right' => cli\table\Column::ALIGN_RIGHT, +]); +$table->addRow(['Text', 'Centered', 'More']); +$table->addRow(['Data', 'Values', 'Here']); +$table->addRow(['A', 'B', 'C']); +$table->display(); +cli\line(); + +// Example 4: Real-world Database Table Sizes +cli\line('%Y## Example 4: Database Table Sizes (Real-world Use Case)%n'); +cli\line('This example shows how the alignment feature makes database'); +cli\line('statistics much more readable and easier to compare.'); +cli\line(); +$table = new cli\Table(); +$table->setHeaders(['Table Name', 'Rows', 'Data Size', 'Index Size']); +$table->setAlignments([ + 'Table Name' => cli\table\Column::ALIGN_LEFT, + 'Rows' => cli\table\Column::ALIGN_RIGHT, + 'Data Size' => cli\table\Column::ALIGN_RIGHT, + 'Index Size' => cli\table\Column::ALIGN_RIGHT, +]); +$table->addRow(['wp_posts', '1,234', '5.2 MB', '1.1 MB']); +$table->addRow(['wp_postmeta', '45,678', '23.4 MB', '8.7 MB']); +$table->addRow(['wp_comments', '9,012', '2.3 MB', '0.8 MB']); +$table->addRow(['wp_options', '456', '1.5 MB', '0.2 MB']); +$table->addRow(['wp_users', '89', '0.1 MB', '0.05 MB']); +$table->display(); +cli\line(); + +// Example 5: Alignment Constants +cli\line('%Y## Alignment Constants%n'); +cli\line(); +cli\line('You can use the following constants from %Ccli\table\Column%n:'); +cli\line(' %G*%n %CALIGN_LEFT%n - Left align (default)'); +cli\line(' %G*%n %CALIGN_RIGHT%n - Right align (good for numbers)'); +cli\line(' %G*%n %CALIGN_CENTER%n - Center align'); +cli\line(); +cli\line('Example usage:'); +cli\line(' %c$table->setAlignments([%n'); +cli\line(' %c\'Column1\' => cli\table\Column::ALIGN_LEFT,%n'); +cli\line(' %c\'Column2\' => cli\table\Column::ALIGN_RIGHT,%n'); +cli\line(' %c]);%n'); +cli\line(); + +cli\line('%GDone!%n'); +cli\line(); diff --git a/examples/table-wrapping.php b/examples/table-wrapping.php new file mode 100644 index 0000000..4c91976 --- /dev/null +++ b/examples/table-wrapping.php @@ -0,0 +1,89 @@ +#!/usr/bin/env php +setHeaders($headers); +$table->setRows($data); +$renderer = new \cli\table\Ascii(); +$renderer->setConstraintWidth(70); // Simulate narrower terminal +$table->setRenderer($renderer); +$table->display(); +cli\line(); + +// Example 2: Word-wrap mode (wrap at word boundaries) +cli\line('%Y## Example 2: Word-Wrap Mode (Wrap at Word Boundaries)%n'); +cli\line('Word-wrap mode keeps words together by wrapping at spaces and hyphens.'); +cli\line('This makes it easier to read and copy/paste long values.'); +cli\line(); +$table = new \cli\Table(); +$table->setHeaders($headers); +$table->setRows($data); +$renderer = new \cli\table\Ascii(); +$renderer->setConstraintWidth(70); // Simulate narrower terminal +$table->setRenderer($renderer); +$table->setWrappingMode('word-wrap'); +$table->display(); +cli\line(); + +// Example 3: Truncate mode (truncate with ellipsis) +cli\line('%Y## Example 3: Truncate Mode (Truncate with Ellipsis)%n'); +cli\line('Truncate mode cuts off long content and adds "..." to indicate truncation.'); +cli\line('This is useful when you want a compact display and don\'t need full values.'); +cli\line(); +$table = new \cli\Table(); +$table->setHeaders($headers); +$table->setRows($data); +$renderer = new \cli\table\Ascii(); +$renderer->setConstraintWidth(70); // Simulate narrower terminal +$table->setRenderer($renderer); +$table->setWrappingMode('truncate'); +$table->display(); +cli\line(); + +// Example 4: Usage instructions +cli\line('%Y## Wrapping Mode Options%n'); +cli\line(); +cli\line('You can use the following wrapping modes:'); +cli\line(' %G*%n %Cwrap%n - Default: wrap at character boundaries'); +cli\line(' %G*%n %Cword-wrap%n - Wrap at word boundaries (spaces/hyphens)'); +cli\line(' %G*%n %Ctruncate%n - Truncate with ellipsis (...)'); +cli\line(); +cli\line('Example usage:'); +cli\line(' %c$table->setWrappingMode(\'word-wrap\');%n'); +cli\line(); + +cli\line('%GDone!%n'); +cli\line(); diff --git a/lib/cli/Arguments.php b/lib/cli/Arguments.php index 7d728cc..c6e41de 100644 --- a/lib/cli/Arguments.php +++ b/lib/cli/Arguments.php @@ -19,14 +19,23 @@ /** * Parses command line arguments. + * + * @implements \ArrayAccess */ class Arguments implements \ArrayAccess { + /** @var array> */ protected $_flags = array(); + /** @var array> */ protected $_options = array(); + /** @var bool */ protected $_strict = false; + /** @var array */ protected $_input = array(); + /** @var array */ protected $_invalid = array(); + /** @var array|null */ protected $_parsed; + /** @var Lexer|null */ protected $_lexer; /** @@ -36,37 +45,50 @@ class Arguments implements \ArrayAccess { * * `'help'` is `true` by default, `'strict'` is false by default. * - * @param array $options An array of options for this parser. + * @param array $options An array of options for this parser. */ public function __construct($options = array()) { $options += array( 'strict' => false, - 'input' => array_slice($_SERVER['argv'], 1) + 'input' => isset( $_SERVER['argv'] ) && is_array( $_SERVER['argv'] ) ? array_slice( $_SERVER['argv'], 1 ) : array(), ); - $this->_input = $options['input']; - $this->setStrict($options['strict']); + $input = $options['input']; + if ( ! is_array( $input ) ) { + $input = array(); + } + $this->_input = array_map( function( $item ) { return is_scalar( $item ) ? (string) $item : ''; }, $input ); + $this->setStrict( ! empty( $options['strict'] ) ); - if (isset($options['flags'])) { - $this->addFlags($options['flags']); + if ( isset( $options['flags'] ) && is_array( $options['flags'] ) ) { + /** @var array|string> $flags */ + $flags = $options['flags']; + $this->addFlags( $flags ); } - if (isset($options['options'])) { - $this->addOptions($options['options']); + if ( isset( $options['options'] ) && is_array( $options['options'] ) ) { + /** @var array|string> $opts */ + $opts = $options['options']; + $this->addOptions( $opts ); } } /** * Get the list of arguments found by the defined definitions. * - * @return array + * @return array */ public function getArguments() { if (!isset($this->_parsed)) { $this->parse(); } - return $this->_parsed; + return $this->_parsed ?? []; } + /** + * Get the help screen. + * + * @return HelpScreen + */ public function getHelpScreen() { return new HelpScreen($this); } @@ -77,7 +99,11 @@ public function getHelpScreen() { * @return string */ public function asJSON() { - return json_encode($this->_parsed); + $json = json_encode( $this->_parsed ); + if ( false === $json ) { + throw new \RuntimeException( 'Failed to encode arguments as JSON' ); + } + return $json; } /** @@ -86,12 +112,17 @@ public function asJSON() { * @param mixed $offset An Argument object or the name of the argument. * @return bool */ + #[\ReturnTypeWillChange] public function offsetExists($offset) { if ($offset instanceOf Argument) { $offset = $offset->key; } - return array_key_exists($offset, $this->_parsed); + if ( ! is_string( $offset ) && ! is_int( $offset ) ) { + return false; + } + + return array_key_exists($offset, $this->_parsed ?? []); } /** @@ -100,14 +131,21 @@ public function offsetExists($offset) { * @param mixed $offset An Argument object or the name of the argument. * @return mixed */ + #[\ReturnTypeWillChange] public function offsetGet($offset) { if ($offset instanceOf Argument) { $offset = $offset->key; } + if ( ! is_string( $offset ) && ! is_int( $offset ) ) { + return null; + } + if (isset($this->_parsed[$offset])) { return $this->_parsed[$offset]; } + + return null; } /** @@ -116,11 +154,17 @@ public function offsetGet($offset) { * @param mixed $offset An Argument object or the name of the argument. * @param mixed $value The value to set */ + #[\ReturnTypeWillChange] public function offsetSet($offset, $value) { if ($offset instanceOf Argument) { $offset = $offset->key; } + if ( ! is_string( $offset ) && ! is_int( $offset ) ) { + return; + } + + $offset = (string) $offset; $this->_parsed[$offset] = $value; } @@ -129,11 +173,16 @@ public function offsetSet($offset, $value) { * * @param mixed $offset An Argument object or the name of the argument. */ + #[\ReturnTypeWillChange] public function offsetUnset($offset) { if ($offset instanceOf Argument) { $offset = $offset->key; } + if ( ! is_string( $offset ) && ! is_int( $offset ) ) { + return; + } + unset($this->_parsed[$offset]); } @@ -141,7 +190,7 @@ public function offsetUnset($offset) { * Adds a flag (boolean argument) to the argument list. * * @param mixed $flag A string representing the flag, or an array of strings. - * @param array $settings An array of settings for this flag. + * @param array|string $settings An array of settings for this flag. * @setting string description A description to be shown in --help. * @setting bool default The default value for this flag. * @setting bool stackable Whether the flag is repeatable to increase the value. @@ -156,6 +205,11 @@ public function addFlag($flag, $settings = array()) { $settings['aliases'] = $flag; $flag = array_shift($settings['aliases']); } + if ( is_scalar( $flag ) ) { + $flag = (string) $flag; + } else { + $flag = ''; + } if (isset($this->_flags[$flag])) { $this->_warn('flag already exists: ' . $flag); return $this; @@ -177,7 +231,7 @@ public function addFlag($flag, $settings = array()) { * primary flag character, and the values should be the settings array * used by {addFlag}. * - * @param array $flags An array of flags to add + * @param array|string> $flags An array of flags to add * @return $this */ public function addFlags($flags) { @@ -197,7 +251,7 @@ public function addFlags($flags) { * Adds an option (string argument) to the argument list. * * @param mixed $option A string representing the option, or an array of strings. - * @param array $settings An array of settings for this option. + * @param array|string $settings An array of settings for this option. * @setting string description A description to be shown in --help. * @setting bool default The default value for this option. * @setting array aliases Other ways to trigger this option. @@ -211,6 +265,11 @@ public function addOption($option, $settings = array()) { $settings['aliases'] = $option; $option = array_shift($settings['aliases']); } + if ( is_scalar( $option ) ) { + $option = (string) $option; + } else { + $option = ''; + } if (isset($this->_options[$option])) { $this->_warn('option already exists: ' . $option); return $this; @@ -231,7 +290,7 @@ public function addOption($option, $settings = array()) { * primary option string, and the values should be the settings array * used by {addOption}. * - * @param array $options An array of options to add + * @param array|string> $options An array of options to add * @return $this */ public function addOptions($options) { @@ -265,7 +324,7 @@ public function setStrict($strict) { /** * Get the list of invalid arguments the parser found. * - * @return array + * @return array */ public function getInvalidArguments() { return $this->_invalid; @@ -276,12 +335,16 @@ public function getInvalidArguments() { * * @param mixed $flag Either a string representing the flag or an * cli\arguments\Argument object. - * @return array + * @return array|null */ public function getFlag($flag) { if ($flag instanceOf Argument) { $obj = $flag; - $flag = $flag->value; + $flag = $flag->value(); + } + + if ( ! is_string( $flag ) && ! is_int( $flag ) ) { + return null; } if (isset($this->_flags[$flag])) { @@ -298,12 +361,24 @@ public function getFlag($flag) { return $settings; } } + + return null; } + /** + * Get all flags. + * + * @return array> + */ public function getFlags() { return $this->_flags; } + /** + * Check if there are any flags defined. + * + * @return bool + */ public function hasFlags() { return !empty($this->_flags); } @@ -337,12 +412,16 @@ public function isStackable($flag) { * * @param mixed $option Either a string representing the option or an * cli\arguments\Argument object. - * @return array + * @return array|null */ public function getOption($option) { if ($option instanceOf Argument) { $obj = $option; - $option = $option->value; + $option = $option->value(); + } + + if ( ! is_string( $option ) && ! is_int( $option ) ) { + return null; } if (isset($this->_options[$option])) { @@ -358,12 +437,24 @@ public function getOption($option) { return $settings; } } + + return null; } + /** + * Get all options. + * + * @return array> + */ public function getOptions() { return $this->_options; } + /** + * Check if there are any options defined. + * + * @return bool + */ public function hasOptions() { return !empty($this->_options); } @@ -384,7 +475,7 @@ public function isOption($argument) { * will use either the first long name given or the first name in the list * if a long name is not given. * - * @return array + * @return void * @throws arguments\InvalidArguments */ public function parse() { @@ -394,15 +485,21 @@ public function parse() { $this->_applyDefaults(); - foreach ($this->_lexer as $argument) { - if ($this->_parseFlag($argument)) { - continue; - } - if ($this->_parseOption($argument)) { - continue; - } + if ($this->_lexer) { + foreach ($this->_lexer as $argument) { + if (null === $argument) { + continue; + } + if ($this->_parseFlag($argument)) { + continue; + } + if ($this->_parseOption($argument)) { + continue; + } - array_push($this->_invalid, $argument->raw); + $raw = $argument->raw(); + array_push($this->_invalid, is_scalar($raw) ? (string) $raw : ''); + } } if ($this->_strict && !empty($this->_invalid)) { @@ -414,6 +511,8 @@ public function parse() { * This applies the default values, if any, of all of the * flags and options, so that if there is a default value * it will be available. + * + * @return void */ private function _applyDefaults() { foreach($this->_flags as $flag => $settings) { @@ -428,10 +527,22 @@ private function _applyDefaults() { } } + /** + * Warn about something. + * + * @param string $message + * @return void + */ private function _warn($message) { trigger_error('[' . __CLASS__ .'] ' . $message, E_USER_WARNING); } + /** + * Parse a flag. + * + * @param Argument $argument + * @return bool + */ private function _parseFlag($argument) { if (!$this->isFlag($argument)) { return false; @@ -442,7 +553,8 @@ private function _parseFlag($argument) { $this[$argument->key] = 0; } - $this[$argument->key] += 1; + $current = $this[$argument->key]; + $this[$argument->key] = (is_int($current) ? $current : 0) + 1; } else { $this[$argument->key] = true; } @@ -450,11 +562,19 @@ private function _parseFlag($argument) { return true; } + /** + * Parse an option. + * + * @param Argument $option + * @return bool + */ private function _parseOption($option) { if (!$this->isOption($option)) { return false; } + assert(null !== $this->_lexer); + // Peak ahead to make sure we get a value. if ($this->_lexer->end() || !$this->_lexer->peek->isValue) { $optionSettings = $this->getOption($option->key); @@ -473,13 +593,20 @@ private function _parseOption($option) { // Store as array and join to string after looping for values $values = array(); + $this->_lexer->next(); + // Loop until we find a flag in peak-ahead - foreach ($this->_lexer as $value) { - array_push($values, $value->raw); + while ( $this->_lexer->valid() ) { + $value = $this->_lexer->current(); + if ( null === $value ) { + break; + } + array_push( $values, $value->raw ); - if (!$this->_lexer->end() && !$this->_lexer->peek->isValue) { + if ( ! $this->_lexer->end() && ! $this->_lexer->peek->isValue ) { break; } + $this->_lexer->next(); } $this[$option->key] = join(' ', $values); diff --git a/lib/cli/Colors.php b/lib/cli/Colors.php index 3dd4c2b..fb9e071 100644 --- a/lib/cli/Colors.php +++ b/lib/cli/Colors.php @@ -18,6 +18,7 @@ * Reference: http://graphcomp.com/info/specs/ansi_col.html#colors */ class Colors { + /** @var array> */ static protected $_colors = array( 'color' => array( 'black' => 30, @@ -48,14 +49,28 @@ class Colors { 'white' => 47 ) ); + /** @var bool|null */ static protected $_enabled = null; + /** @var array> */ static protected $_string_cache = array(); + /** + * Enable colorized output. + * + * @param bool $force Force enable. + * @return void + */ static public function enable($force = true) { self::$_enabled = $force === true ? true : null; } + /** + * Disable colorized output. + * + * @param bool $force Force disable. + * @return void + */ static public function disable($force = true) { self::$_enabled = $force === true ? false : null; } @@ -64,6 +79,9 @@ static public function disable($force = true) { * Check if we should colorize output based on local flags and shell type. * * Only check the shell type if `Colors::$_enabled` is null and `$colored` is null. + * + * @param bool|null $colored Force enable or disable the colorized output. + * @return bool */ static public function shouldColorize($colored = null) { return self::$_enabled === true || @@ -75,8 +93,8 @@ static public function shouldColorize($colored = null) { /** * Set the color. * - * @param string $color The name of the color or style to set. - * @return string + * @param string|array $color The name of the color or style to set, or an array of options. + * @return string */ static public function color($color) { if (!is_array($color)) { @@ -92,7 +110,7 @@ static public function color($color) { $colors = array(); foreach (array('color', 'style', 'background') as $type) { $code = $color[$type]; - if (isset(self::$_colors[$type][$code])) { + if (isset($code) && isset(self::$_colors[$type][$code])) { $colors[] = self::$_colors[$type][$code]; } } @@ -108,9 +126,9 @@ static public function color($color) { * Colorize a string using helpful string formatters. If the `Streams::$out` points to a TTY coloring will be enabled, * otherwise disabled. You can control this check with the `$colored` parameter. * - * @param string $string + * @param string $string * @param boolean $colored Force enable or disable the colorized output. If left as `null` the TTY will control coloring. - * @return string + * @return string */ static public function colorize($string, $colored = null) { $passed = $string; @@ -146,6 +164,8 @@ static public function colorize($string, $colored = null) { * @return string A string with color information removed. */ static public function decolorize( $string, $keep = 0 ) { + $string = (string) $string; + if ( ! ( $keep & 1 ) ) { // Get rid of color tokens if they exist $string = str_replace('%%', '%¾', $string); @@ -169,6 +189,7 @@ static public function decolorize( $string, $keep = 0 ) { * @param string $passed The original string before colorization. * @param string $colorized The string after running through self::colorize. * @param string $deprecated Optional. Not used. Default null. + * @return void */ static public function cacheString( $passed, $colorized, $deprecated = null ) { self::$_string_cache[md5($passed)] = array( @@ -182,7 +203,7 @@ static public function cacheString( $passed, $colorized, $deprecated = null ) { * Return the length of the string without color codes. * * @param string $string the string to measure - * @return int + * @return int */ static public function length($string) { return safe_strlen( self::decolorize( $string ) ); @@ -194,7 +215,7 @@ static public function length($string) { * @param string $string The string to measure. * @param bool $pre_colorized Optional. Set if the string is pre-colorized. Default false. * @param string|bool $encoding Optional. The encoding of the string. Default false. - * @return int + * @return int */ static public function width( $string, $pre_colorized = false, $encoding = false ) { return strwidth( $pre_colorized || self::shouldColorize() ? self::decolorize( $string, $pre_colorized ? 1 /*keep_tokens*/ : 0 ) : $string, $encoding ); @@ -208,9 +229,11 @@ static public function width( $string, $pre_colorized = false, $encoding = false * @param bool $pre_colorized Optional. Set if the string is pre-colorized. Default false. * @param string|bool $encoding Optional. The encoding of the string. Default false. * @param int $pad_type Optional. Can be STR_PAD_RIGHT, STR_PAD_LEFT, or STR_PAD_BOTH. If pad_type is not specified it is assumed to be STR_PAD_RIGHT. - * @return string + * @return string */ static public function pad( $string, $length, $pre_colorized = false, $encoding = false, $pad_type = STR_PAD_RIGHT ) { + $string = (string) $string; + $real_length = self::width( $string, $pre_colorized, $encoding ); $diff = strlen( $string ) - $real_length; $length += $diff; @@ -221,7 +244,7 @@ static public function pad( $string, $length, $pre_colorized = false, $encoding /** * Get the color mapping array. * - * @return array Array of color tokens mapped to colors and styles. + * @return array> Array of color tokens mapped to colors and styles. */ static public function getColors() { return array( @@ -264,7 +287,7 @@ static public function getColors() { /** * Get the cached string values. * - * @return array The cached string values. + * @return array> The cached string values. */ static public function getStringCache() { return self::$_string_cache; @@ -272,8 +295,107 @@ static public function getStringCache() { /** * Clear the string cache. + * + * @return void */ static public function clearStringCache() { self::$_string_cache = array(); } + + /** + * Get the ANSI reset code. + * + * @return string The ANSI reset code. + */ + static public function getResetCode() { + return "\x1b[0m"; + } + + /** + * Wrap a pre-colorized string at a specific width, preserving color codes. + * + * This function wraps text that contains ANSI color codes, ensuring that: + * 1. Color codes are never split in the middle + * 2. Active colors are properly terminated and restored across line breaks + * 3. The wrapped segments maintain the correct display width + * + * Note: This implementation tracks only the most recent ANSI code and does not + * support layered formatting (e.g., bold + color). When multiple formatting + * codes are applied, only the last one will be preserved across line breaks. + * + * @param string $string The string to wrap (with ANSI codes). + * @param int $width The maximum display width per line. + * @param string|bool $encoding Optional. The encoding of the string. Default false. + * @return array Array of wrapped string segments. + */ + static public function wrapPreColorized( $string, $width, $encoding = false ) { + $wrapped = array(); + $current_line = ''; + $current_width = 0; + $active_color = ''; + + // Pattern to match ANSI escape sequences + $ansi_pattern = '/(\x1b\[[0-9;]*m)/'; + + // Split the string into parts: ANSI codes and text + $parts = preg_split( $ansi_pattern, $string, -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY ); + + if ( false === $parts ) { + $parts = array( $string ); + } + + foreach ( $parts as $part ) { + // Check if this part is an ANSI code + if ( preg_match( $ansi_pattern, $part ) ) { + // It's an ANSI code, add it to current line without counting width + $current_line .= $part; + + // Track the active color - check for reset codes consistently + if ( preg_match( '/\x1b\[0m/', $part ) ) { + // Reset code (ESC[0m) + $active_color = ''; + } elseif ( preg_match( '/\x1b\[([0-9;]+)m/', $part, $matches ) ) { + // Non-reset color/formatting code + $active_color = $part; + } + } else { + // It's text content, process it character by character + $text_length = \cli\safe_strlen( $part, $encoding ); + $offset = 0; + + while ( $offset < $text_length ) { + $char = \cli\safe_substr( $part, $offset, 1, false, $encoding ); + assert( is_string( $char ) ); + $char_width = \cli\strwidth( $char, $encoding ); + + // Check if adding this character would exceed the width + if ( $current_width + $char_width > $width && $current_width > 0 ) { + // Need to wrap - finish current line + if ( $active_color ) { + $current_line .= self::getResetCode(); + } + $wrapped[] = $current_line; + + // Start new line + $current_line = $active_color ? $active_color : ''; + $current_width = 0; + } + + // Add the character + $current_line .= $char; + $current_width += $char_width; + $offset++; + } + } + } + + // Add the last line if there's any displayable content + $visible_content = preg_replace( $ansi_pattern, '', $current_line ); + $visible_width = $visible_content !== null ? \cli\strwidth( $visible_content, $encoding ) : 0; + if ( $visible_width > 0 ) { + $wrapped[] = $current_line; + } + + return $wrapped; + } } diff --git a/lib/cli/Memoize.php b/lib/cli/Memoize.php index cedbc19..b08a619 100644 --- a/lib/cli/Memoize.php +++ b/lib/cli/Memoize.php @@ -13,8 +13,15 @@ namespace cli; abstract class Memoize { + /** @var array */ protected $_memoCache = array(); + /** + * Magic getter to retrieve memoized properties. + * + * @param string $name Property name. + * @return mixed + */ public function __get($name) { if (isset($this->_memoCache[$name])) { return $this->_memoCache[$name]; @@ -29,11 +36,16 @@ public function __get($name) { return ($this->_memoCache[$name] = null); } - $method = array($this, $name); - ($this->_memoCache[$name] = call_user_func($method)); + ($this->_memoCache[$name] = $this->$name()); return $this->_memoCache[$name]; } + /** + * Unmemoize a property or all properties. + * + * @param string|bool $name Property name to unmemoize, or true to unmemoize all. + * @return void + */ protected function _unmemo($name) { if ($name === true) { $this->_memoCache = array(); diff --git a/lib/cli/Notify.php b/lib/cli/Notify.php index a163f96..9fa9d42 100644 --- a/lib/cli/Notify.php +++ b/lib/cli/Notify.php @@ -24,15 +24,27 @@ * of characters to indicate progress is being made. */ abstract class Notify { + /** @var int */ protected $_current = 0; + /** @var bool */ protected $_first = true; + /** @var int */ protected $_interval; + /** @var string */ protected $_message; + /** @var int|null */ protected $_start; + /** @var float|null */ protected $_timer; + /** @var float|int|null */ + protected $_tick; + /** @var int */ + protected $_iteration = 0; + /** @var float|int */ + protected $_speed = 0; /** - * Instatiates a Notification object. + * Instantiates a Notification object. * * @param string $msg The text to display next to the Notifier. * @param int $interval The interval in milliseconds between updates. @@ -49,11 +61,14 @@ public function __construct($msg, $interval = 100) { * @abstract * @param boolean $finish * @see cli\Notify::tick() + * @return void */ abstract public function display($finish = false); /** * Reset the notifier state so the same instance can be used in multiple loops. + * + * @return void */ public function reset() { $this->_current = 0; @@ -89,26 +104,24 @@ public function elapsed() { * Calculates the speed (number of ticks per second) at which the Notifier * is being updated. * - * @return int The number of ticks performed in 1 second. + * @return float|int The number of ticks performed in 1 second. */ public function speed() { - static $tick, $iteration = 0, $speed = 0; - if (!$this->_start) { return 0; - } else if (!$tick) { - $tick = $this->_start; + } else if (!$this->_tick) { + $this->_tick = $this->_start; } $now = microtime(true); - $span = $now - $tick; + $span = $now - $this->_tick; if ($span > 1) { - $iteration++; - $tick = $now; - $speed = ($this->_current / $iteration) / $span; + $this->_iteration++; + $this->_tick = $now; + $this->_speed = ($this->_current / $this->_iteration) / $span; } - return $speed; + return $this->_speed; } /** @@ -119,7 +132,7 @@ public function speed() { * @return string The formatted time span. */ public function formatTime($time) { - return floor($time / 60) . ':' . str_pad($time % 60, 2, 0, STR_PAD_LEFT); + return sprintf('%02d:%02d', (int)floor($time / 60), $time % 60); } /** @@ -127,6 +140,7 @@ public function formatTime($time) { * no longer needed. * * @see cli\Notify::display() + * @return void */ public function finish() { Streams::out("\r"); @@ -139,6 +153,7 @@ public function finish() { * the ticker is incremented by 1. * * @param int $increment The amount to increment by. + * @return void */ public function increment($increment = 1) { $this->_current += $increment; @@ -173,6 +188,7 @@ public function shouldUpdate() { * @see cli\Notify::increment() * @see cli\Notify::shouldUpdate() * @see cli\Notify::display() + * @return void */ public function tick($increment = 1) { $this->increment($increment); diff --git a/lib/cli/Progress.php b/lib/cli/Progress.php index 95ef4fe..c9acbfd 100644 --- a/lib/cli/Progress.php +++ b/lib/cli/Progress.php @@ -20,6 +20,7 @@ * @see cli\Notify */ abstract class Progress extends \cli\Notify { + /** @var int */ protected $_total = 0; /** @@ -40,6 +41,7 @@ public function __construct($msg, $total, $interval = 100) { * * @param int $total The total number of times this indicator should be `tick`ed. * @throws \InvalidArgumentException Thrown if the `$total` is less than 0. + * @return void */ public function setTotal($total) { $this->_total = (int)$total; @@ -51,6 +53,9 @@ public function setTotal($total) { /** * Reset the progress state so the same instance can be used in multiple loops. + * + * @param int|null $total Optional new total. + * @return void */ public function reset($total = null) { parent::reset(); @@ -85,8 +90,8 @@ public function total() { * Calculates the estimated total time for the tick count to reach the * total ticks given. * - * @return int The estimated total number of seconds for all ticks to be - * completed. This is not the estimated time left, but total. + * @return int|float The estimated total number of seconds for all ticks to be + * completed. This is not the estimated time left, but total. * @see cli\Notify::speed() * @see cli\Notify::elapsed() */ @@ -101,8 +106,10 @@ public function estimated() { } /** - * Forces the current tick count to the total ticks given at instatiation + * Forces the current tick count to the total ticks given at instantiation * time before passing on to `cli\Notify::finish()`. + * + * @return void */ public function finish() { $this->_current = $this->_total; @@ -114,6 +121,7 @@ public function finish() { * the ticker is incremented by 1. * * @param int $increment The amount to increment by. + * @return void */ public function increment($increment = 1) { $this->_current = min($this->_total, $this->_current + $increment); diff --git a/lib/cli/Shell.php b/lib/cli/Shell.php index 037fe77..a3bb95d 100755 --- a/lib/cli/Shell.php +++ b/lib/cli/Shell.php @@ -31,7 +31,7 @@ static public function columns() { $columns = null; } if ( null === $columns ) { - if ( function_exists( 'exec' ) ) { + if ( ! ( $columns = (int) getenv( 'COLUMNS' ) ) && function_exists( 'exec' ) ) { if ( self::is_windows() ) { // Cater for shells such as Cygwin and Git bash where `mode CON` returns an incorrect value for columns. if ( ( $shell = getenv( 'SHELL' ) ) && preg_match( '/(?:bash|zsh)(?:\.exe)?$/', $shell ) && getenv( 'TERM' ) ) { @@ -49,15 +49,13 @@ static public function columns() { } } } else { - if ( ! ( $columns = (int) getenv( 'COLUMNS' ) ) ) { - $size = exec( '/usr/bin/env stty size 2>/dev/null' ); - if ( '' !== $size && preg_match( '/[0-9]+ ([0-9]+)/', $size, $matches ) ) { - $columns = (int) $matches[1]; - } - if ( ! $columns ) { - if ( getenv( 'TERM' ) ) { - $columns = (int) exec( '/usr/bin/env tput cols 2>/dev/null' ); - } + $size = exec( '/usr/bin/env stty size 2>/dev/null' ); + if ( $size && preg_match( '/[0-9]+ ([0-9]+)/', $size, $matches ) ) { + $columns = (int) $matches[1]; + } + if ( ! $columns ) { + if ( getenv( 'TERM' ) ) { + $columns = (int) exec( '/usr/bin/env tput cols 2>/dev/null' ); } } } @@ -101,7 +99,9 @@ static public function isPiped() { /** * Uses `stty` to hide input/output completely. + * * @param boolean $hidden Will hide/show the next data. Defaults to true. + * @return void */ static public function hide($hidden = true) { system( 'stty ' . ( $hidden? '-echo' : 'echo' ) ); @@ -112,8 +112,12 @@ static public function hide($hidden = true) { * * @return bool */ - static private function is_windows() { - return strtoupper(substr(PHP_OS, 0, 3)) === 'WIN'; + static public function is_windows() { + $test_is_windows = getenv( 'WP_CLI_TEST_IS_WINDOWS' ); + if ( false !== $test_is_windows && '' !== $test_is_windows ) { + return (bool) $test_is_windows; + } + return strtoupper( substr( PHP_OS, 0, 3 ) ) === 'WIN'; } } diff --git a/lib/cli/Streams.php b/lib/cli/Streams.php index 7322760..22a22e5 100755 --- a/lib/cli/Streams.php +++ b/lib/cli/Streams.php @@ -4,20 +4,36 @@ class Streams { + /** @var resource */ protected static $out = STDOUT; + /** @var resource */ protected static $in = STDIN; + /** @var resource */ protected static $err = STDERR; + /** + * Call a method on this class. + * + * @param string $func The method name. + * @param array $args The arguments. + * @return mixed + */ static function _call( $func, $args ) { - $method = __CLASS__ . '::' . $func; + $method = array( __CLASS__, $func ); + assert( is_callable( $method ) ); return call_user_func_array( $method, $args ); } - static public function isTty() { - if ( function_exists('stream_isatty') ) { - return !stream_isatty(static::$out); + /** + * Check if the stream is a TTY. + * + * @return bool + */ + public static function isTty() { + if ( function_exists( 'stream_isatty' ) ) { + return stream_isatty( static::$out ); } else { - return (function_exists('posix_isatty') && !posix_isatty(static::$out)); + return ( function_exists( 'posix_isatty' ) && posix_isatty( static::$out ) ); } } @@ -27,34 +43,37 @@ static public function isTty() { * then each key in the array will be the placeholder name. Placeholders are of the * format {:key}. * - * @param string $msg The message to render. - * @param mixed ... Either scalar arguments or a single array argument. + * @param string $msg The message to render. + * @param mixed ...$args Either scalar arguments or a single array argument. * @return string The rendered string. */ - public static function render( $msg ) { - $args = func_get_args(); - + public static function render( $msg, ...$args ) { // No string replacement is needed - if( count( $args ) == 1 || ( is_string( $args[1] ) && '' === $args[1] ) ) { + if ( empty( $args ) || ( is_string( $args[0] ) && '' === $args[0] ) ) { return Colors::shouldColorize() ? Colors::colorize( $msg ) : $msg; } // If the first argument is not an array just pass to sprintf - if( !is_array( $args[1] ) ) { - // Colorize the message first so sprintf doesn't bitch at us + if ( ! is_array( $args[0] ) ) { + // Normalize color tokens before sprintf: colorize or strip them so no raw %tokens reach sprintf if ( Colors::shouldColorize() ) { - $args[0] = Colors::colorize( $args[0] ); + $msg = Colors::colorize( $msg ); + } else { + $msg = Colors::decolorize( $msg ); } // Escape percent characters for sprintf - $args[0] = preg_replace('/(%([^\w]|$))/', "%$1", $args[0]); + $msg = (string) preg_replace( '/(%([^\w]|$))/', '%$1', $msg ); - return call_user_func_array( 'sprintf', $args ); + $sprintf_args = array_merge( array( $msg ), $args ); + /** @var string $rendered */ + $rendered = call_user_func_array( 'sprintf', $sprintf_args ); + return $rendered; } // Here we do named replacement so formatting strings are more understandable - foreach( $args[1] as $key => $value ) { - $msg = str_replace( '{:' . $key . '}', $value, $msg ); + foreach ( $args[0] as $key => $value ) { + $msg = str_replace( '{:' . $key . '}', is_scalar( $value ) ? (string) $value : '', $msg ); } return Colors::shouldColorize() ? Colors::colorize( $msg ) : $msg; } @@ -64,24 +83,26 @@ public static function render( $msg ) { * through `sprintf` before output. * * @param string $msg The message to output in `printf` format. - * @param mixed ... Either scalar arguments or a single array argument. + * @param mixed ...$args Either scalar arguments or a single array argument. * @return void * @see \cli\render() */ - public static function out( $msg ) { - fwrite( static::$out, self::_call( 'render', func_get_args() ) ); + public static function out( $msg, ...$args ) { + $rendered = self::_call( 'render', func_get_args() ); + fwrite( static::$out, is_scalar( $rendered ) ? (string) $rendered : '' ); } /** * Pads `$msg` to the width of the shell before passing to `cli\out`. * * @param string $msg The message to pad and pass on. - * @param mixed ... Either scalar arguments or a single array argument. + * @param mixed ...$args Either scalar arguments or a single array argument. * @return void * @see cli\out() */ - public static function out_padded( $msg ) { - $msg = self::_call( 'render', func_get_args() ); + public static function out_padded( $msg, ...$args ) { + $rendered = self::_call( 'render', func_get_args() ); + $msg = is_scalar( $rendered ) ? (string) $rendered : ''; self::out( str_pad( $msg, \cli\Shell::columns() ) ); } @@ -89,12 +110,14 @@ public static function out_padded( $msg ) { * Prints a message to `STDOUT` with a newline appended. See `\cli\out` for * more documentation. * + * @param string $msg The message to print. + * @return void * @see cli\out() */ public static function line( $msg = '' ) { // func_get_args is empty if no args are passed even with the default above. - $args = array_merge( func_get_args(), array( '' ) ); - $args[0] .= "\n"; + $args = array_merge( func_get_args(), array( '' ) ); + $args[0] = ( is_scalar( $args[0] ) ? (string) $args[0] : '' ) . "\n"; self::_call( 'out', $args ); } @@ -105,14 +128,15 @@ public static function line( $msg = '' ) { * * @param string $msg The message to output in `printf` format. With no string, * a newline is printed. - * @param mixed ... Either scalar arguments or a single array argument. + * @param mixed ...$args Either scalar arguments or a single array argument. * @return void */ - public static function err( $msg = '' ) { + public static function err( $msg = '', ...$args ) { // func_get_args is empty if no args are passed even with the default above. - $args = array_merge( func_get_args(), array( '' ) ); - $args[0] .= "\n"; - fwrite( static::$err, self::_call( 'render', $args ) ); + $args = array_merge( func_get_args(), array( '' ) ); + $args[0] = ( is_scalar( $args[0] ) ? (string) $args[0] : '' ) . "\n"; + $rendered = self::_call( 'render', $args ); + fwrite( static::$err, is_scalar( $rendered ) ? (string) $rendered : '' ); } /** @@ -127,10 +151,11 @@ public static function err( $msg = '' ) { * @throws \Exception Thrown if ctrl-D (EOT) is sent as input. */ public static function input( $format = null, $hide = false ) { - if ( $hide ) + if ( $hide ) { Shell::hide(); + } - if( $format ) { + if ( $format ) { fscanf( static::$in, $format . "\n", $line ); } else { $line = fgets( static::$in ); @@ -141,11 +166,11 @@ public static function input( $format = null, $hide = false ) { echo "\n"; } - if( $line === false ) { + if ( $line === false ) { throw new \Exception( 'Caught ^D during input' ); } - return trim( $line ); + return trim( (string) $line ); } /** @@ -160,19 +185,21 @@ public static function input( $format = null, $hide = false ) { * @return string The users input. * @see cli\input() */ - public static function prompt( $question, $default = null, $marker = ': ', $hide = false ) { - if( $default && strpos( $question, '[' ) === false ) { + public static function prompt( $question, $default = false, $marker = ': ', $hide = false ) { + if ( $default && strpos( $question, '[' ) === false ) { $question .= ' [' . $default . ']'; } - while( true ) { + while ( true ) { self::out( $question . $marker ); $line = self::input( null, $hide ); - if ( trim( $line ) !== '' ) + if ( trim( $line ) !== '' ) { return $line; - if( $default !== false ) - return $default; + } + if ( $default !== false ) { + return (string) $default; + } } } @@ -182,27 +209,31 @@ public static function prompt( $question, $default = null, $marker = ': ', $hide * * @param string $question The question to ask the user. * @param string $choice A string of characters allowed as a response. Case is ignored. - * @param string $default The default choice. NULL if a default is not allowed. + * @param string|null $default The default choice. NULL if a default is not allowed. * @return string The users choice. * @see cli\prompt() */ public static function choose( $question, $choice = 'yn', $default = 'n' ) { - if( !is_string( $choice ) ) { + if ( ! is_string( $choice ) ) { $choice = join( '', $choice ); } // Make every choice character lowercase except the default - $choice = str_ireplace( $default, strtoupper( $default ), strtolower( $choice ) ); - // Seperate each choice with a forward-slash - $choices = trim( join( '/', preg_split( '//', $choice ) ), '/' ); + if ( null !== $default ) { + $choice = str_ireplace( $default, strtoupper( $default ), strtolower( $choice ) ); + } else { + $choice = strtolower( $choice ); + } + // Separate each choice with a forward-slash + $choices = trim( join( '/', str_split( $choice ) ), '/' ); - while( true ) { - $line = self::prompt( sprintf( '%s? [%s]', $question, $choices ), $default, '' ); + while ( true ) { + $line = self::prompt( sprintf( '%s? [%s]', $question, $choices ), $default ?? false, '' ); - if( stripos( $choice, $line ) !== false ) { + if ( stripos( $choice, $line ) !== false ) { return strtolower( $line ); } - if( !empty( $default ) ) { + if ( ! empty( $default ) ) { return strtolower( $default ); } } @@ -213,8 +244,8 @@ public static function choose( $question, $choice = 'yn', $default = 'n' ) { * choose an option. The array must be a single dimension with either strings * or objects with a `__toString()` method. * - * @param array $items The list of items the user can choose from. - * @param string $default The index of the default item. + * @param array $items The list of items the user can choose from. + * @param string|null $default The index of the default item. * @param string $title The message displayed to the user when prompted. * @return string The index of the chosen item. * @see cli\line() @@ -224,29 +255,42 @@ public static function choose( $question, $choice = 'yn', $default = 'n' ) { public static function menu( $items, $default = null, $title = 'Choose an item' ) { $map = array_values( $items ); - if( $default && strpos( $title, '[' ) === false && isset( $items[$default] ) ) { - $title .= ' [' . $items[$default] . ']'; + if ( $default && strpos( $title, '[' ) === false && isset( $items[ $default ] ) ) { + $default_item = $items[ $default ]; + $default_str = ''; + if ( is_scalar( $default_item ) ) { + $default_str = (string) $default_item; + } elseif ( is_object( $default_item ) && method_exists( $default_item, '__toString' ) ) { + $default_str = (string) $default_item; + } + $title .= ' [' . $default_str . ']'; } - foreach( $map as $idx => $item ) { - self::line( ' %d. %s', $idx + 1, (string)$item ); + foreach ( $map as $idx => $item ) { + $item_str = ''; + if ( is_scalar( $item ) ) { + $item_str = (string) $item; + } elseif ( is_object( $item ) && method_exists( $item, '__toString' ) ) { + $item_str = (string) $item; + } + self::line( ' %d. %s', $idx + 1, $item_str ); } self::line(); - while( true ) { + while ( true ) { fwrite( static::$out, sprintf( '%s: ', $title ) ); $line = self::input(); - if( is_numeric( $line ) ) { - $line--; - if( isset( $map[$line] ) ) { - return array_search( $map[$line], $items ); + if ( is_numeric( $line ) ) { + --$line; + if ( isset( $map[ $line ] ) ) { + return (string) array_search( $map[ $line ], $items ); } - if( $line < 0 || $line >= count( $map ) ) { + if ( $line < 0 || $line >= count( $map ) ) { self::err( 'Invalid menu selection: out of range' ); } - } else if( isset( $default ) ) { + } elseif ( isset( $default ) ) { return $default; } } @@ -269,15 +313,16 @@ public static function menu( $items, $default = null, $title = 'Choose an item' * @throws \Exception Thrown if $stream is not a resource of the 'stream' type. */ public static function setStream( $whichStream, $stream ) { - if( !is_resource( $stream ) || get_resource_type( $stream ) !== 'stream' ) { + if ( ! is_resource( $stream ) || get_resource_type( $stream ) !== 'stream' ) { throw new \Exception( 'Invalid resource type!' ); } - if( property_exists( __CLASS__, $whichStream ) ) { + if ( property_exists( __CLASS__, $whichStream ) ) { static::${$whichStream} = $stream; } - register_shutdown_function( function() use ($stream) { - fclose( $stream ); - } ); + register_shutdown_function( + function () use ( $stream ) { + fclose( $stream ); + } + ); } - } diff --git a/lib/cli/Table.php b/lib/cli/Table.php index 8b0cf93..c75f3fa 100644 --- a/lib/cli/Table.php +++ b/lib/cli/Table.php @@ -15,6 +15,7 @@ use cli\Shell; use cli\Streams; use cli\table\Ascii; +use cli\table\Column; use cli\table\Renderer; use cli\table\Tabular; @@ -22,11 +23,25 @@ * The `Table` class is used to display data in a tabular format. */ class Table { + /** @var \cli\table\Renderer */ protected $_renderer; + /** @var array */ protected $_headers = array(); + /** @var array */ protected $_footers = array(); + /** @var array */ protected $_width = array(); + /** @var array> */ protected $_rows = array(); + /** @var array|array */ + protected $_alignments = array(); + + /** + * Cached map of valid alignment constants. + * + * @var array|null + */ + private static $_valid_alignments_map = null; /** * Initializes the `Table` class. @@ -40,45 +55,84 @@ class Table { * table are used as the header values. * 3. Pass nothing and use `setHeaders()` and `addRow()` or `setRows()`. * - * @param array $headers Headers used in this table. Optional. - * @param array $rows The rows of data for this table. Optional. - * @param array $footers Footers used in this table. Optional. + * @param array $headers Headers used in this table. Optional. + * @param array $rows The rows of data for this table. Optional. + * @param array $footers Footers used in this table. Optional. + * @param array $alignments Column alignments. Optional. */ - public function __construct(array $headers = null, array $rows = null, array $footers = null) { - if (!empty($headers)) { + public function __construct( array $headers = array(), array $rows = array(), array $footers = array(), array $alignments = array() ) { + $safe_strval = function ( $v ) { + return ( is_scalar( $v ) || ( is_object( $v ) && method_exists( $v, '__toString' ) ) ) ? (string) $v : ''; + }; + + if ( ! empty( $headers ) ) { // If all the rows is given in $headers we use the keys from the // first row for the header values - if ($rows === null) { - $rows = $headers; - $keys = array_keys(array_shift($headers)); + if ( $rows === array() ) { + $rows = $headers; + $first_row = array_shift( $headers ); + $keys = is_array( $first_row ) ? array_keys( $first_row ) : array(); + $headers = array(); + foreach ( $keys as $key ) { + $headers[ $key ] = $safe_strval( $key ); + } + } else { + $headers = array_map( $safe_strval, $headers ); + } + + $this->setHeaders( $headers ); - foreach ($keys as $header) { - $headers[$header] = $header; + $safe_rows = array(); + foreach ( $rows as $row ) { + if ( is_array( $row ) ) { + $normalized_row = array(); + foreach ( $headers as $key => $header_val ) { + $normalized_row[ $key ] = isset( $row[ $key ] ) ? $safe_strval( $row[ $key ] ) : ''; + } + $safe_rows[] = $normalized_row; } } + $this->setRows( $safe_rows ); + } - $this->setHeaders($headers); - $this->setRows($rows); + if ( ! empty( $footers ) ) { + $this->setFooters( array_map( $safe_strval, $footers ) ); } - if (!empty($footers)) { - $this->setFooters($footers); + if ( ! empty( $alignments ) ) { + /** @var array|array $alignments */ + $this->setAlignments( $alignments ); } - if (Shell::isPiped()) { - $this->setRenderer(new Tabular()); + if ( Shell::isPiped() ) { + $this->setRenderer( new Tabular() ); } else { - $this->setRenderer(new Ascii()); + $this->setRenderer( new Ascii() ); } } - public function resetTable() - { - $this->_headers = array(); - $this->_width = array(); + /** + * Reset the table state. + * + * @return $this + */ + public function resetTable() { + $this->_headers = array(); + $this->_width = array(); + $this->_rows = array(); + $this->_footers = array(); + $this->_alignments = array(); + return $this; + } + + /** + * Resets only the rows in the table, keeping headers, footers, and width information. + * + * @return $this + */ + public function resetRows() { $this->_rows = array(); - $this->_footers = array(); return $this; } @@ -89,22 +143,23 @@ public function resetTable() * @see table\Renderer * @see table\Ascii * @see table\Tabular + * @return void */ - public function setRenderer(Renderer $renderer) { + public function setRenderer( Renderer $renderer ) { $this->_renderer = $renderer; } /** * Loops through the row and sets the maximum width for each column. * - * @param array $row The table row. - * @return array $row + * @param array $row The table row. + * @return array $row */ - protected function checkRow(array $row) { - foreach ($row as $column => $str) { + protected function checkRow( array $row ) { + foreach ( $row as $column => $str ) { $width = Colors::width( $str, $this->isAsciiPreColorized( $column ) ); - if (!isset($this->_width[$column]) || $width > $this->_width[$column]) { - $this->_width[$column] = $width; + if ( ! isset( $this->_width[ $column ] ) || $width > $this->_width[ $column ] ) { + $this->_width[ $column ] = $width; } } @@ -120,11 +175,40 @@ protected function checkRow(array $row) { * @uses cli\Shell::isPiped() Determine what format to output * * @see cli\Table::renderRow() + * @return void */ public function display() { - foreach( $this->getDisplayLines() as $line ) { + foreach ( $this->getDisplayLines() as $line ) { + Streams::line( $line ); + } + } + + /** + * Display a single row without headers or top border. + * + * This method is useful for adding rows incrementally to an already-rendered table. + * It will display the row with side borders and a bottom border (if using Ascii renderer). + * + * @param array $row The row data to display. + * @return void + */ + public function displayRow( array $row ) { + // Update widths if this row has wider content + $row = $this->checkRow( $row ); + + // Recalculate widths for the renderer + $this->_renderer->setWidths( $this->_width, false ); + + $rendered_row = $this->_renderer->row( $row ); + $row_lines = explode( PHP_EOL, $rendered_row ); + foreach ( $row_lines as $line ) { Streams::line( $line ); } + + $border = $this->_renderer->border(); + if ( isset( $border ) ) { + Streams::line( $border ); + } } /** @@ -133,34 +217,37 @@ public function display() { * @see cli\Table::display() * @see cli\Table::renderRow() * - * @return array + * @return array */ public function getDisplayLines() { - $this->_renderer->setWidths($this->_width, $fallback = true); + $this->_renderer->setWidths( $this->_width, $fallback = true ); + $this->_renderer->setHeaders( $this->_headers ); + $this->_renderer->setAlignments( $this->_alignments ); $border = $this->_renderer->border(); $out = array(); - if (isset($border)) { + if ( isset( $border ) ) { $out[] = $border; } - $out[] = $this->_renderer->row($this->_headers); - if (isset($border)) { + $out[] = $this->_renderer->row( $this->_headers ); + if ( isset( $border ) ) { $out[] = $border; } - foreach ($this->_rows as $row) { - $row = $this->_renderer->row($row); + foreach ( $this->_rows as $row ) { + $row = $this->_renderer->row( $row ); $row = explode( PHP_EOL, $row ); $out = array_merge( $out, $row ); } - if (isset($border)) { + // Only add final border if there are rows + if ( ! empty( $this->_rows ) && isset( $border ) ) { $out[] = $border; } - if ($this->_footers) { - $out[] = $this->_renderer->row($this->_footers); - if (isset($border)) { + if ( $this->_footers ) { + $out[] = $this->_renderer->row( $this->_footers ); + if ( isset( $border ) ) { $out[] = $border; } } @@ -171,69 +258,107 @@ public function getDisplayLines() { * Sort the table by a column. Must be called before `cli\Table::display()`. * * @param int $column The index of the column to sort by. + * @return void */ - public function sort($column) { - if (!isset($this->_headers[$column])) { - trigger_error('No column with index ' . $column, E_USER_NOTICE); + public function sort( $column ) { + if ( ! isset( $this->_headers[ $column ] ) ) { + trigger_error( 'No column with index ' . $column, E_USER_NOTICE ); return; } - usort($this->_rows, function($a, $b) use ($column) { - return strcmp($a[$column], $b[$column]); - }); + usort( + $this->_rows, + function ( $a, $b ) use ( $column ) { + return strcmp( $a[ $column ], $b[ $column ] ); + } + ); } /** * Set the headers of the table. * - * @param array $headers An array of strings containing column header names. + * @param array $headers An array of strings containing column header names. + * @return void */ - public function setHeaders(array $headers) { - $this->_headers = $this->checkRow($headers); + public function setHeaders( array $headers ) { + $this->_headers = $this->checkRow( $headers ); } /** * Set the footers of the table. * - * @param array $footers An array of strings containing column footers names. + * @param array $footers An array of strings containing column footers names. + * @return void */ - public function setFooters(array $footers) { - $this->_footers = $this->checkRow($footers); + public function setFooters( array $footers ) { + $this->_footers = $this->checkRow( $footers ); } + /** + * Set the alignments of the table. + * + * @param array|array $alignments An array of alignment constants keyed by column name or index. + * @return void + */ + public function setAlignments( array $alignments ) { + // Initialize the cached valid alignments map on first use + if ( null === self::$_valid_alignments_map ) { + self::$_valid_alignments_map = array_flip( array( Column::ALIGN_LEFT, Column::ALIGN_RIGHT, Column::ALIGN_CENTER ) ); + } + + $headers_map = ! empty( $this->_headers ) ? array_flip( $this->_headers ) : null; + foreach ( $alignments as $column => $alignment ) { + if ( ! isset( self::$_valid_alignments_map[ $alignment ] ) ) { + throw new \InvalidArgumentException( "Invalid alignment value '$alignment' for column '$column'." ); + } + // Only validate column names if headers are already set + if ( $headers_map !== null && ! isset( $headers_map[ $column ] ) ) { + throw new \InvalidArgumentException( "Column '$column' does not exist in table headers." ); + } + } + $this->_alignments = $alignments; + } /** * Add a row to the table. * - * @param array $row The row data. + * @param array $row The row data. * @see cli\Table::checkRow() + * @return void */ - public function addRow(array $row) { - $this->_rows[] = $this->checkRow($row); + public function addRow( array $row ) { + $this->_rows[] = $this->checkRow( $row ); } /** * Clears all previous rows and adds the given rows. * - * @param array $rows A 2-dimensional array of row data. + * @param array> $rows A 2-dimensional array of row data. * @see cli\Table::addRow() + * @return void */ - public function setRows(array $rows) { + public function setRows( array $rows ) { $this->_rows = array(); - foreach ($rows as $row) { - $this->addRow($row); + foreach ( $rows as $row ) { + $this->addRow( $row ); } } + /** + * Count the number of rows in the table. + * + * @return int + */ public function countRows() { - return count($this->_rows); + return count( $this->_rows ); } /** * Set whether items in an Ascii table are pre-colorized. * - * @param bool|array $precolorized A boolean to set all columns in the table as pre-colorized, or an array of booleans keyed by column index (number) to set individual columns as pre-colorized. + * @param bool|array $pre_colorized A boolean to set all columns in the table as pre-colorized, or an array of booleans keyed by column index (number) to set individual columns as pre-colorized. * @see cli\Ascii::setPreColorized() + * @return void */ public function setAsciiPreColorized( $pre_colorized ) { if ( $this->_renderer instanceof Ascii ) { @@ -241,6 +366,20 @@ public function setAsciiPreColorized( $pre_colorized ) { } } + /** + * Set the wrapping mode for table cells. + * + * @param string $mode One of: 'wrap' (default - wrap at character boundaries), + * 'word-wrap' (word boundaries), or 'truncate' (truncate with ellipsis). + * @see cli\Ascii::setWrappingMode() + * @return void + */ + public function setWrappingMode( $mode ) { + if ( $this->_renderer instanceof Ascii ) { + $this->_renderer->setWrappingMode( $mode ); + } + } + /** * Is a column in an Ascii table pre-colorized? * diff --git a/lib/cli/Tree.php b/lib/cli/Tree.php index 7570902..b1df849 100644 --- a/lib/cli/Tree.php +++ b/lib/cli/Tree.php @@ -17,7 +17,9 @@ */ class Tree { + /** @var \cli\tree\Renderer */ protected $_renderer; + /** @var array */ protected $_data = array(); /** @@ -27,6 +29,7 @@ class Tree { * @see tree\Renderer * @see tree\Ascii * @see tree\Markdown + * @return void */ public function setRenderer(tree\Renderer $renderer) { $this->_renderer = $renderer; @@ -41,7 +44,8 @@ public function setRenderer(tree\Renderer $renderer) { * ], * 'Thing', * ] - * @param array $data + * @param array $data + * @return void */ public function setData(array $data) { @@ -60,6 +64,8 @@ public function render() /** * Display the rendered tree + * + * @return void */ public function display() { diff --git a/lib/cli/arguments/Argument.php b/lib/cli/arguments/Argument.php index 0706afb..7ab070b 100644 --- a/lib/cli/arguments/Argument.php +++ b/lib/cli/arguments/Argument.php @@ -16,16 +16,26 @@ /** * Represents an Argument or a value and provides several helpers related to parsing an argument list. + * + * @property-read bool $isLong + * @property-read bool $isShort + * @property-read bool $isArgument + * @property-read bool $canExplode + * @property-read array $exploded + * @property-read string $raw + * @property-read bool $isValue */ class Argument extends Memoize { /** * The canonical name of this argument, used for aliasing. * - * @param string + * @var string */ public $key; + /** @var string */ private $_argument; + /** @var string */ private $_raw; /** @@ -77,7 +87,7 @@ public function raw() { * @return bool */ public function isLong() { - return (0 == strncmp($this->_raw, '--', 2)); + return (0 == strncmp((string)$this->_raw, '--', 2)); } /** @@ -86,7 +96,7 @@ public function isLong() { * @return bool */ public function isShort() { - return !$this->isLong && (0 == strncmp($this->_raw, '-', 1)); + return !$this->isLong && (0 == strncmp((string)$this->_raw, '-', 1)); } /** @@ -121,7 +131,7 @@ public function canExplode() { * Returns all but the first character of the argument, removing them from the * objects representation at the same time. * - * @return array + * @return array */ public function exploded() { $exploded = array(); @@ -130,7 +140,7 @@ public function exploded() { array_push($exploded, $this->_argument[$i - 1]); } - $this->_argument = array_pop($exploded); + $this->_argument = (string) array_pop($exploded); $this->_raw = '-' . $this->_argument; return $exploded; } diff --git a/lib/cli/arguments/HelpScreen.php b/lib/cli/arguments/HelpScreen.php index 2b2f77f..27e6bc8 100644 --- a/lib/cli/arguments/HelpScreen.php +++ b/lib/cli/arguments/HelpScreen.php @@ -18,105 +18,165 @@ * Arguments help screen renderer */ class HelpScreen { + /** @var array> */ protected $_flags = array(); - protected $_maxFlag = 0; + /** @var int */ + protected $_flagMax = 0; + /** @var array> */ protected $_options = array(); - protected $_maxOption = 0; - - public function __construct(Arguments $arguments) { - $this->setArguments($arguments); + /** @var int */ + protected $_optionMax = 0; + + /** + * @param Arguments $arguments + */ + public function __construct( Arguments $arguments ) { + $this->setArguments( $arguments ); } + /** + * @return string + */ public function __toString() { return $this->render(); } - public function setArguments(Arguments $arguments) { - $this->consumeArgumentFlags($arguments); - $this->consumeArgumentOptions($arguments); + /** + * @param Arguments $arguments + * @return void + */ + public function setArguments( Arguments $arguments ) { + $this->consumeArgumentFlags( $arguments ); + $this->consumeArgumentOptions( $arguments ); } - public function consumeArgumentFlags(Arguments $arguments) { - $data = $this->_consume($arguments->getFlags()); + /** + * @param Arguments $arguments + * @return void + */ + public function consumeArgumentFlags( Arguments $arguments ) { + $data = $this->_consume( $arguments->getFlags() ); - $this->_flags = $data[0]; + $this->_flags = $data[0]; $this->_flagMax = $data[1]; } - public function consumeArgumentOptions(Arguments $arguments) { - $data = $this->_consume($arguments->getOptions()); + /** + * @param Arguments $arguments + * @return void + */ + public function consumeArgumentOptions( Arguments $arguments ) { + $data = $this->_consume( $arguments->getOptions() ); - $this->_options = $data[0]; + $this->_options = $data[0]; $this->_optionMax = $data[1]; } + /** + * @return string + */ public function render() { $help = array(); - array_push($help, $this->_renderFlags()); - array_push($help, $this->_renderOptions()); + array_push( $help, $this->_renderFlags() ); + array_push( $help, $this->_renderOptions() ); + + $help = array_filter( $help, function ( $v ) { + return $v !== null && $v !== ''; + } ); - return join("\n\n", $help); + return join( "\n\n", $help ); } + /** + * @return string|null + */ private function _renderFlags() { - if (empty($this->_flags)) { + if ( empty( $this->_flags ) ) { return null; } - return "Flags\n" . $this->_renderScreen($this->_flags, $this->_flagMax); + return "Flags\n" . $this->_renderScreen( $this->_flags, $this->_flagMax ); } + /** + * @return string|null + */ private function _renderOptions() { - if (empty($this->_options)) { + if ( empty( $this->_options ) ) { return null; } - return "Options\n" . $this->_renderScreen($this->_options, $this->_optionMax); + return "Options\n" . $this->_renderScreen( $this->_options, $this->_optionMax ); } - private function _renderScreen($options, $max) { + /** + * @param array> $options + * @param int $max + * @return string + */ + private function _renderScreen( $options, $max ) { $help = array(); - foreach ($options as $option => $settings) { - $formatted = ' ' . str_pad($option, $max); + foreach ( $options as $option => $settings ) { + $formatted = ' ' . str_pad( $option, $max ); - $dlen = 80 - 4 - $max; + $dlen = max( 1, 80 - 4 - $max ); + $settings_desc = $settings['description']; + $desc_str = ( is_scalar( $settings_desc ) || ( is_object( $settings_desc ) && method_exists( $settings_desc, '__toString' ) ) ) ? (string) $settings_desc : ''; - $description = str_split($settings['description'], $dlen); - $formatted.= ' ' . array_shift($description); + $description = array(); + if ( '' !== $desc_str ) { + $description = str_split( $desc_str, $dlen ); + } - if ($settings['default']) { - $formatted .= ' [default: ' . $settings['default'] . ']'; + if ( empty( $description ) ) { + $description = array( '' ); } - $pad = str_repeat(' ', $max + 3); - while ($desc = array_shift($description)) { - $formatted .= "\n${pad}${desc}"; + $formatted .= ' ' . array_shift( $description ); + + if ( ! empty( $settings['default'] ) ) { + $default_val = $settings['default']; + $default_str = ( is_scalar( $default_val ) || ( is_object( $default_val ) && method_exists( $default_val, '__toString' ) ) ) ? (string) $default_val : ''; + if ( '' !== $default_str ) { + $formatted .= ' [default: ' . $default_str . ']'; + } } - array_push($help, $formatted); + $pad = str_repeat( ' ', $max + 3 ); + while ( $desc = array_shift( $description ) ) { + $formatted .= "\n{$pad}{$desc}"; + } + + array_push( $help, $formatted ); } - return join("\n", $help); + return join( "\n", $help ); } - private function _consume($options) { + /** + * @param array> $options + * @return array{0: array>, 1: int} + */ + private function _consume( $options ) { $max = 0; $out = array(); - foreach ($options as $option => $settings) { - $names = array('--' . $option); + foreach ( $options as $option => $settings ) { + $names = array( '--' . $option ); - foreach ($settings['aliases'] as $alias) { - array_push($names, '-' . $alias); + $aliases = $settings['aliases']; + if ( is_array( $aliases ) ) { + foreach ( $aliases as $alias ) { + array_push( $names, '-' . ( is_scalar( $alias ) ? (string) $alias : '' ) ); + } } - $names = join(', ', $names); - $max = max(strlen($names), $max); - $out[$names] = $settings; + $names = join( ', ', $names ); + $max = max( strlen( $names ), $max ); + $out[ $names ] = $settings; } - return array($out, $max); + return array( $out, $max ); } } - diff --git a/lib/cli/arguments/InvalidArguments.php b/lib/cli/arguments/InvalidArguments.php index 633c8c6..5a0b315 100644 --- a/lib/cli/arguments/InvalidArguments.php +++ b/lib/cli/arguments/InvalidArguments.php @@ -16,10 +16,11 @@ * Thrown when undefined arguments are detected in strict mode. */ class InvalidArguments extends \InvalidArgumentException { + /** @var array */ protected $arguments; /** - * @param array $arguments A list of arguments that do not fit the profile. + * @param array $arguments A list of arguments that do not fit the profile. */ public function __construct(array $arguments) { $this->arguments = $arguments; @@ -29,12 +30,15 @@ public function __construct(array $arguments) { /** * Get the arguments that caused the exception. * - * @return array + * @return array */ public function getArguments() { return $this->arguments; } + /** + * @return string + */ private function _generateMessage() { return 'unknown argument' . (count($this->arguments) > 1 ? 's' : '') . diff --git a/lib/cli/arguments/Lexer.php b/lib/cli/arguments/Lexer.php index f6012ef..381e3a6 100644 --- a/lib/cli/arguments/Lexer.php +++ b/lib/cli/arguments/Lexer.php @@ -14,14 +14,25 @@ use cli\Memoize; +/** + * @property-read Argument $peek + * + * @implements \Iterator + */ class Lexer extends Memoize implements \Iterator { + /** @var Argument|null */ + private $_item; + /** @var array */ private $_items = array(); + /** @var int */ private $_index = 0; + /** @var int */ private $_length = 0; + /** @var bool */ private $_first = true; /** - * @param array $items A list of strings to process as tokens. + * @param array $items A list of strings to process as tokens. */ public function __construct(array $items) { $this->_items = $items; @@ -31,8 +42,9 @@ public function __construct(array $items) { /** * The current token. * - * @return string + * @return Argument|null */ + #[\ReturnTypeWillChange] public function current() { return $this->_item; } @@ -49,6 +61,7 @@ public function peek() { /** * Move the cursor forward 1 element if it is valid. */ + #[\ReturnTypeWillChange] public function next() { if ($this->valid()) { $this->_shift(); @@ -60,6 +73,7 @@ public function next() { * * @return int */ + #[\ReturnTypeWillChange] public function key() { return $this->_index; } @@ -68,6 +82,7 @@ public function key() { * Move forward 1 element and, if the method hasn't been called before, reset * the cursor's position to 0. */ + #[\ReturnTypeWillChange] public function rewind() { $this->_shift(); if ($this->_first) { @@ -81,6 +96,7 @@ public function rewind() { * * @return bool */ + #[\ReturnTypeWillChange] public function valid() { return ($this->_index < $this->_length); } @@ -89,9 +105,11 @@ public function valid() { * Push an element to the front of the stack. * * @param mixed $item The value to set + * @return void */ public function unshift($item) { - array_unshift($this->_items, $item); + $item_str = (is_scalar($item) || (is_object($item) && method_exists($item, '__toString'))) ? (string)$item : ''; + array_unshift($this->_items, $item_str); $this->_length += 1; } @@ -104,16 +122,23 @@ public function end() { return ($this->_index + 1) == $this->_length; } + /** + * @return void + */ private function _shift() { - $this->_item = new Argument(array_shift($this->_items)); + $shifted = array_shift($this->_items); + $this->_item = null !== $shifted ? new Argument($shifted) : null; $this->_index += 1; $this->_explode(); $this->_unmemo('peek'); } + /** + * @return void + */ private function _explode() { - if (!$this->_item->canExplode) { - return false; + if (null === $this->_item || !$this->_item->canExplode) { + return; } foreach ($this->_item->exploded as $piece) { diff --git a/lib/cli/cli.php b/lib/cli/cli.php index 6aeb867..d412b96 100755 --- a/lib/cli/cli.php +++ b/lib/cli/cli.php @@ -19,12 +19,12 @@ * then each key in the array will be the placeholder name. Placeholders are of the * format {:key}. * - * @param string $msg The message to render. - * @param mixed ... Either scalar arguments or a single array argument. + * @param string $msg The message to render. + * @param mixed ...$args Either scalar arguments or a single array argument. * @return string The rendered string. */ -function render( $msg ) { - return Streams::_call( 'render', func_get_args() ); +function render( $msg, ...$args ) { + return Streams::render( $msg, ...$args ); } /** @@ -32,11 +32,11 @@ function render( $msg ) { * through `sprintf` before output. * * @param string $msg The message to output in `printf` format. - * @param mixed ... Either scalar arguments or a single array argument. + * @param mixed ...$args Either scalar arguments or a single array argument. * @return void * @see \cli\render() */ -function out( $msg ) { +function out( $msg, ...$args ) { Streams::_call( 'out', func_get_args() ); } @@ -44,11 +44,11 @@ function out( $msg ) { * Pads `$msg` to the width of the shell before passing to `cli\out`. * * @param string $msg The message to pad and pass on. - * @param mixed ... Either scalar arguments or a single array argument. + * @param mixed ...$args Either scalar arguments or a single array argument. * @return void * @see cli\out() */ -function out_padded( $msg ) { +function out_padded( $msg, ...$args ) { Streams::_call( 'out_padded', func_get_args() ); } @@ -56,9 +56,12 @@ function out_padded( $msg ) { * Prints a message to `STDOUT` with a newline appended. See `\cli\out` for * more documentation. * + * @param string $msg Message to print. + * @param mixed ...$args Either scalar arguments or a single array argument. + * @return void * @see cli\out() */ -function line( $msg = '' ) { +function line( $msg = '', ...$args ) { Streams::_call( 'line', func_get_args() ); } @@ -68,10 +71,10 @@ function line( $msg = '' ) { * * @param string $msg The message to output in `printf` format. With no string, * a newline is printed. - * @param mixed ... Either scalar arguments or a single array argument. + * @param mixed ...$args Either scalar arguments or a single array argument. * @return void */ -function err( $msg = '' ) { +function err( $msg = '', ...$args ) { Streams::_call( 'err', func_get_args() ); } @@ -94,7 +97,7 @@ function input( $format = null ) { * continue displaying until input is received. * * @param string $question The question to ask the user. - * @param string $default A default value if the user provides no input. + * @param string|false $default A default value if the user provides no input. Default false. * @param string $marker A string to append to the question and default value on display. * @param boolean $hide If the user input should be hidden * @return string The users input. @@ -140,7 +143,7 @@ function confirm( $question, $default = false ) { * choose an option. The array must be a single dimension with either strings * or objects with a `__toString()` method. * - * @param array $items The list of items the user can choose from. + * @param array $items The list of items the user can choose from. * @param string $default The index of the default item. * @param string $title The message displayed to the user when prompted. * @return string The index of the chosen item. @@ -162,10 +165,10 @@ function menu( $items, $default = null, $title = 'Choose an item' ) { */ function safe_strlen( $str, $encoding = false ) { // Allow for selective testings - "1" bit set tests grapheme_strlen(), "2" preg_match_all( '/\X/u' ), "4" mb_strlen(), "other" strlen(). - $test_safe_strlen = getenv( 'PHP_CLI_TOOLS_TEST_SAFE_STRLEN' ); + $test_safe_strlen = (int) getenv( 'PHP_CLI_TOOLS_TEST_SAFE_STRLEN' ); - // Assume UTF-8 if no encoding given - `grapheme_strlen()` will return null if given non-UTF-8 string. - if ( ( ! $encoding || 'UTF-8' === $encoding ) && can_use_icu() && null !== ( $length = grapheme_strlen( $str ) ) ) { + // Assume UTF-8 if no encoding given - `grapheme_strlen()` will return false on failure. + if ( ( ! $encoding || 'UTF-8' === $encoding ) && can_use_icu() && is_int( $length = grapheme_strlen( $str ) ) ) { if ( ! $test_safe_strlen || ( $test_safe_strlen & 1 ) ) { return $length; } @@ -181,10 +184,12 @@ function safe_strlen( $str, $encoding = false ) { if ( ! $encoding ) { $encoding = mb_detect_encoding( $str, null, true /*strict*/ ); } - $length = $encoding ? mb_strlen( $str, $encoding ) : mb_strlen( $str ); // mbstring funcs can fail if given `$encoding` arg that evals to false. + $length = is_string( $encoding ) ? mb_strlen( $str, $encoding ) : mb_strlen( $str ); // mbstring funcs can fail if given `$encoding` arg that evals to false. if ( 'UTF-8' === $encoding ) { // Subtract combining characters. - $length -= preg_match_all( get_unicode_regexs( 'm' ), $str, $dummy /*needed for PHP 5.3*/ ); + $m_regex = get_unicode_regexs( 'm' ); + assert( is_string( $m_regex ) ); + $length -= preg_match_all( $m_regex, $str, $dummy /*needed for PHP 5.3*/ ); } if ( ! $test_safe_strlen || ( $test_safe_strlen & 4 ) ) { return $length; @@ -215,6 +220,8 @@ function safe_substr( $str, $start, $length = false, $is_width = false, $encodin // Normalize `$length` when not specified - PHP 5.3 substr takes false as full length, PHP > 5.3 takes null. if ( null === $length || false === $length ) { $length = $safe_strlen; + } else { + $length = (int) $length; } // Normalize `$start` - various methods treat this differently. if ( $start > $safe_strlen ) { @@ -225,7 +232,7 @@ function safe_substr( $str, $start, $length = false, $is_width = false, $encodin } // Allow for selective testings - "1" bit set tests grapheme_substr(), "2" preg_split( '/\X/' ), "4" mb_substr(), "8" substr(). - $test_safe_substr = getenv( 'PHP_CLI_TOOLS_TEST_SAFE_SUBSTR' ); + $test_safe_substr = (int) getenv( 'PHP_CLI_TOOLS_TEST_SAFE_SUBSTR' ); // Assume UTF-8 if no encoding given - `grapheme_substr()` will return false (not null like `grapheme_strlen()`) if given non-UTF-8 string. if ( ( ! $encoding || 'UTF-8' === $encoding ) && can_use_icu() && false !== ( $try = grapheme_substr( $str, $start, $length ) ) ) { @@ -248,7 +255,7 @@ function safe_substr( $str, $start, $length = false, $is_width = false, $encodin $encoding = mb_detect_encoding( $str, null, true /*strict*/ ); } // Bug: not adjusting for combining chars. - $try = $encoding ? mb_substr( $str, $start, $length, $encoding ) : mb_substr( $str, $start, $length ); // mbstring funcs can fail if given `$encoding` arg that evals to false. + $try = is_string( $encoding ) ? mb_substr( $str, $start, $length, $encoding ) : mb_substr( $str, $start, $length ); // mbstring funcs can fail if given `$encoding` arg that evals to false. if ( 'UTF-8' === $encoding && $is_width ) { $try = _safe_substr_eaw( $try, $length ); } @@ -262,11 +269,14 @@ function safe_substr( $str, $start, $length = false, $is_width = false, $encodin /** * Internal function used by `safe_substr()` to adjust for East Asian double-width chars. * + * @param string $str + * @param int $length * @return string */ function _safe_substr_eaw( $str, $length ) { // Set the East Asian Width regex. $eaw_regex = get_unicode_regexs( 'eaw' ); + assert( is_string( $eaw_regex ) ); // If there's any East Asian double-width chars... if ( preg_match( $eaw_regex, $str ) ) { @@ -279,6 +289,9 @@ function _safe_substr_eaw( $str, $length ) { } else { // Explode string into an array of UTF-8 chars. Based on core `_mb_substr()` in "wp-includes/compat.php". $chars = preg_split( '/([\x00-\x7f\xc2-\xf4][^\x00-\x7f\xc2-\xf4]*)/', $str, $length + 1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY ); + if ( false === $chars ) { + $chars = array( $str ); + } $cnt = min( count( $chars ), $length ); $width = $length; @@ -319,11 +332,15 @@ function safe_str_pad( $string, $length, $encoding = false ) { * @return int The string's width. */ function strwidth( $string, $encoding = false ) { + $string = (string) $string; + // Set the East Asian Width and Mark regexs. - list( $eaw_regex, $m_regex ) = get_unicode_regexs(); + $regexs = get_unicode_regexs(); + assert( is_array( $regexs ) ); + list( $eaw_regex, $m_regex ) = $regexs; // Allow for selective testings - "1" bit set tests grapheme_strlen(), "2" preg_match_all( '/\X/u' ), "4" mb_strwidth(), "other" safe_strlen(). - $test_strwidth = getenv( 'PHP_CLI_TOOLS_TEST_STRWIDTH' ); + $test_strwidth = (int) getenv( 'PHP_CLI_TOOLS_TEST_STRWIDTH' ); // Assume UTF-8 if no encoding given - `grapheme_strlen()` will return null if given non-UTF-8 string. if ( ( ! $encoding || 'UTF-8' === $encoding ) && can_use_icu() && null !== ( $width = grapheme_strlen( $string ) ) ) { @@ -342,7 +359,7 @@ function strwidth( $string, $encoding = false ) { if ( ! $encoding ) { $encoding = mb_detect_encoding( $string, null, true /*strict*/ ); } - $width = $encoding ? mb_strwidth( $string, $encoding ) : mb_strwidth( $string ); // mbstring funcs can fail if given `$encoding` arg that evals to false. + $width = is_string( $encoding ) ? mb_strwidth( $string, $encoding ) : mb_strwidth( $string ); // mbstring funcs can fail if given `$encoding` arg that evals to false. if ( 'UTF-8' === $encoding ) { // Subtract combining characters. $width -= preg_match_all( $m_regex, $string, $dummy /*needed for PHP 5.3*/ ); @@ -379,7 +396,7 @@ function can_use_pcre_x() { static $can_use_pcre_x = null; if ( null === $can_use_pcre_x ) { - // '\X' introduced (as Unicde extended grapheme cluster) in PCRE 8.32 - see https://vcs.pcre.org/pcre/code/tags/pcre-8.32/ChangeLog?view=markup line 53. + // '\X' introduced (as Unicode extended grapheme cluster) in PCRE 8.32 - see https://vcs.pcre.org/pcre/code/tags/pcre-8.32/ChangeLog?view=markup line 53. // Older versions of PCRE were bundled with PHP <= 5.3.23 & <= 5.4.13. $pcre_version = substr( PCRE_VERSION, 0, strspn( PCRE_VERSION, '0123456789.' ) ); // Remove any trailing date stuff. $can_use_pcre_x = version_compare( $pcre_version, '8.32', '>=' ) && false !== @preg_match( '/\X/u', '' ); @@ -391,8 +408,8 @@ function can_use_pcre_x() { /** * Get the regexs generated from Unicode data. * - * @param string $idx Optional. Return a specific regex only. Default null. - * @return array|string Returns keyed array if not given $idx or $idx doesn't exist, otherwise the specific regex string. + * @param string|null $idx Optional. Return a specific regex only. Default null. + * @return array|string Returns keyed array if not given $idx or $idx doesn't exist, otherwise the specific regex string. */ function get_unicode_regexs( $idx = null ) { static $eaw_regex; // East Asian Width regex. Characters that count as 2 characters as they're "wide" or "fullwidth". See http://www.unicode.org/reports/tr11/tr11-19.html diff --git a/lib/cli/notify/Dots.php b/lib/cli/notify/Dots.php index 9852e51..2d00de2 100644 --- a/lib/cli/notify/Dots.php +++ b/lib/cli/notify/Dots.php @@ -16,15 +16,18 @@ use cli\Streams; /** - * A Notifer that displays a string of periods. + * A Notifier that displays a string of periods. */ class Dots extends Notify { + /** @var int */ protected $_dots; + /** @var string */ protected $_format = '{:msg}{:dots} ({:elapsed}, {:speed}/s)'; - protected $_iteration; + /** @var int */ + protected $_iteration = 0; /** - * Instatiates a Notification object. + * Instantiates a Notification object. * * @param string $msg The text to display next to the Notifier. * @param int $dots The number of dots to iterate through. @@ -46,6 +49,7 @@ public function __construct($msg, $dots = 3, $interval = 100) { * * @param boolean $finish `true` if this was called from * `cli\Notify::finish()`, `false` otherwise. + * @return void * @see cli\out_padded() * @see cli\Notify::formatTime() * @see cli\Notify::speed() diff --git a/lib/cli/notify/Spinner.php b/lib/cli/notify/Spinner.php index 8da7890..80f5faf 100644 --- a/lib/cli/notify/Spinner.php +++ b/lib/cli/notify/Spinner.php @@ -19,8 +19,11 @@ * The `Spinner` Notifier displays an ASCII spinner. */ class Spinner extends Notify { + /** @var string */ protected $_chars = '-\|/'; + /** @var string */ protected $_format = '{:msg} {:char} ({:elapsed}, {:speed}/s)'; + /** @var int */ protected $_iteration = 0; /** @@ -29,6 +32,7 @@ class Spinner extends Notify { * * @param boolean $finish `true` if this was called from * `cli\Notify::finish()`, `false` otherwise. + * @return void * @see cli\out_padded() * @see cli\Notify::formatTime() * @see cli\Notify::speed() diff --git a/lib/cli/progress/Bar.php b/lib/cli/progress/Bar.php index e800509..8f32fff 100644 --- a/lib/cli/progress/Bar.php +++ b/lib/cli/progress/Bar.php @@ -26,17 +26,46 @@ * ^MSG PER% [======================= ] 00:00 / 00:00$ */ class Bar extends Progress { + /** @var string */ protected $_bars = '=>'; + /** @var string */ protected $_formatMessage = '{:msg} {:percent}% ['; + /** @var string */ protected $_formatTiming = '] {:elapsed} / {:estimated}'; + /** @var string */ protected $_format = '{:msg}{:bar}{:timing}'; + /** + * Instantiates a Progress Bar. + * + * @param string $msg The text to display next to the Notifier. + * @param int $total The total number of ticks we will be performing. + * @param int $interval The interval in milliseconds between updates. + * @param string|null $formatMessage Optional format string for the message portion. + * @param string|null $formatTiming Optional format string for the timing portion. + * @param string|null $format Optional format string for the overall display. + */ + public function __construct($msg, $total, $interval = 100, $formatMessage = null, $formatTiming = null, $format = null) { + parent::__construct($msg, $total, $interval); + + if ($formatMessage !== null) { + $this->_formatMessage = $formatMessage; + } + if ($formatTiming !== null) { + $this->_formatTiming = $formatTiming; + } + if ($format !== null) { + $this->_format = $format; + } + } + /** * Prints the progress bar to the screen with percent complete, elapsed time * and estimated total time. * * @param boolean $finish `true` if this was called from * `cli\Notify::finish()`, `false` otherwise. + * @return void * @see cli\out() * @see cli\Notify::formatTime() * @see cli\Notify::elapsed() @@ -47,25 +76,31 @@ class Bar extends Progress { public function display($finish = false) { $_percent = $this->percent(); - $percent = str_pad(floor($_percent * 100), 3); + $percent = str_pad((string)(int)floor($_percent * 100), 3); $msg = $this->_message; - $msg = Streams::render($this->_formatMessage, compact('msg', 'percent')); + $current = $this->current(); + $total = $this->total(); + $msg = Streams::render($this->_formatMessage, compact('msg', 'percent', 'current', 'total')); - $estimated = $this->formatTime($this->estimated()); + $estimated = $this->formatTime((int)$this->estimated()); $elapsed = str_pad($this->formatTime($this->elapsed()), strlen($estimated)); - $timing = Streams::render($this->_formatTiming, compact('elapsed', 'estimated')); + $timing = Streams::render($this->_formatTiming, compact('elapsed', 'estimated', 'current', 'total', 'percent')); $size = Shell::columns(); + // On Windows, the cursor wraps to the next line if the output fills the entire width. + if ( Shell::is_windows() ) { + $size -= 1; + } $size -= strlen($msg . $timing); if ( $size < 0 ) { $size = 0; } - $bar = str_repeat($this->_bars[0], floor($_percent * $size)) . $this->_bars[1]; + $bar = str_repeat($this->_bars[0], (int)floor($_percent * $size)) . $this->_bars[1]; // substr is needed to trim off the bar cap at 100% $bar = substr(str_pad($bar, $size, ' '), 0, $size); - Streams::out($this->_format, compact('msg', 'bar', 'timing')); + Streams::out($this->_format, compact('msg', 'bar', 'timing', 'current', 'total', 'percent')); } /** @@ -74,6 +109,7 @@ public function display($finish = false) { * * @param int $increment The amount to increment by. * @param string $msg The text to display next to the Notifier. (optional) + * @return void * @see cli\Notify::tick() */ public function tick($increment = 1, $msg = null) { diff --git a/lib/cli/table/Ascii.php b/lib/cli/table/Ascii.php index cb2e8a8..b71d5d4 100644 --- a/lib/cli/table/Ascii.php +++ b/lib/cli/table/Ascii.php @@ -19,26 +19,62 @@ * The ASCII renderer renders tables with ASCII borders. */ class Ascii extends Renderer { + /** + * Valid wrapping modes. + */ + private const VALID_WRAPPING_MODES = array( 'wrap', 'word-wrap', 'truncate' ); + + /** + * Ellipsis character(s) used for truncation. + */ + private const ELLIPSIS = '...'; + + /** + * Width of the ellipsis in characters. + */ + private const ELLIPSIS_WIDTH = 3; + + /** + * @var array + */ protected $_characters = array( 'corner' => '+', 'line' => '-', 'border' => '|', 'padding' => ' ', ); + + /** + * @var string|null + */ protected $_border = null; + + /** + * @var int|null + */ protected $_constraintWidth = null; + + /** + * @var bool|array + */ protected $_pre_colorized = false; + /** + * @var string + */ + protected $_wrapping_mode = 'wrap'; // 'wrap', 'word-wrap', or 'truncate' + /** * Set the widths of each column in the table. * - * @param array $widths The widths of the columns. - * @param bool $fallback Whether to use these values as fallback only. + * @param array $widths The widths of the columns. + * @param bool $fallback Whether to use these values as fallback only. + * @return void */ - public function setWidths(array $widths, $fallback = false) { - if ($fallback) { + public function setWidths( array $widths, $fallback = false ) { + if ( $fallback ) { foreach ( $this->_widths as $index => $value ) { - $widths[$index] = $value; + $widths[ $index ] = $value; } } $this->_widths = $widths; @@ -46,18 +82,18 @@ public function setWidths(array $widths, $fallback = false) { if ( is_null( $this->_constraintWidth ) ) { $this->_constraintWidth = (int) Shell::columns(); } - $col_count = count( $widths ); - $col_borders_count = $col_count ? ( ( $col_count - 1 ) * strlen( $this->_characters['border'] ) ) : 0; + $col_count = count( $widths ); + $col_borders_count = $col_count ? ( ( $col_count - 1 ) * strlen( $this->_characters['border'] ) ) : 0; $table_borders_count = strlen( $this->_characters['border'] ) * 2; - $col_padding_count = $col_count * strlen( $this->_characters['padding'] ) * 2; - $max_width = $this->_constraintWidth - $col_borders_count - $table_borders_count - $col_padding_count; + $col_padding_count = $col_count * strlen( $this->_characters['padding'] ) * 2; + $max_width = $this->_constraintWidth - $col_borders_count - $table_borders_count - $col_padding_count; if ( $widths && $max_width && array_sum( $widths ) > $max_width ) { - $avg = floor( $max_width / count( $widths ) ); + $avg = (int) floor( $max_width / count( $widths ) ); $resize_widths = array(); - $extra_width = 0; - foreach( $widths as $width ) { + $extra_width = 0; + foreach ( $widths as $width ) { if ( $width > $avg ) { $resize_widths[] = $width; } else { @@ -66,8 +102,8 @@ public function setWidths(array $widths, $fallback = false) { } if ( ! empty( $resize_widths ) && $extra_width ) { - $avg_extra_width = floor( $extra_width / count( $resize_widths ) ); - foreach( $widths as &$width ) { + $avg_extra_width = (int) floor( $extra_width / count( $resize_widths ) ); + foreach ( $widths as &$width ) { if ( in_array( $width, $resize_widths ) ) { $width = $avg + $avg_extra_width; array_shift( $resize_widths ); @@ -79,30 +115,47 @@ public function setWidths(array $widths, $fallback = false) { } } } - } $this->_widths = $widths; + // Reset border cache when widths change + $this->_border = null; } /** * Set the constraint width for the table * * @param int $constraintWidth + * @return void */ public function setConstraintWidth( $constraintWidth ) { $this->_constraintWidth = $constraintWidth; } + /** + * Set the wrapping mode for table cells. + * + * @param string $mode One of: 'wrap' (default - wrap at character boundaries), + * 'word-wrap' (wrap at word boundaries), or 'truncate' (truncate with ellipsis). + * @return void + */ + public function setWrappingMode( $mode ) { + if ( ! in_array( $mode, self::VALID_WRAPPING_MODES, true ) ) { + throw new \InvalidArgumentException( "Invalid wrapping mode '$mode'. Must be one of: " . implode( ', ', self::VALID_WRAPPING_MODES ) ); + } + $this->_wrapping_mode = $mode; + } + /** * Set the characters used for rendering the Ascii table. * * The keys `corner`, `line` and `border` are used in rendering. * - * @param $characters array Characters used in rendering. + * @param array $characters Characters used in rendering. + * @return void */ - public function setCharacters(array $characters) { - $this->_characters = array_merge($this->_characters, $characters); + public function setCharacters( array $characters ) { + $this->_characters = array_merge( $this->_characters, $characters ); } /** @@ -112,10 +165,10 @@ public function setCharacters(array $characters) { * @return string The table border. */ public function border() { - if (!isset($this->_border)) { + if ( ! isset( $this->_border ) ) { $this->_border = $this->_characters['corner']; - foreach ($this->_widths as $width) { - $this->_border .= str_repeat($this->_characters['line'], $width + 2); + foreach ( $this->_widths as $width ) { + $this->_border .= str_repeat( $this->_characters['line'], $width + 2 ); $this->_border .= $this->_characters['corner']; } } @@ -126,89 +179,235 @@ public function border() { /** * Renders a row for output. * - * @param array $row The table row. - * @return string The formatted table row. + * @param array $row The table row. + * @return string The formatted table row. */ public function row( array $row ) { $extra_row_count = 0; + $extra_rows = []; if ( count( $row ) > 0 ) { $extra_rows = array_fill( 0, count( $row ), array() ); - foreach( $row as $col => $value ) { + foreach ( $row as $col => $value ) { + $value = ( is_scalar( $value ) || ( is_object( $value ) && method_exists( $value, '__toString' ) ) ) ? (string) $value : ''; + $col_width = $this->_widths[ $col ]; + $encoding = function_exists( 'mb_detect_encoding' ) ? mb_detect_encoding( $value, null, true /*strict*/ ) : false; + $original_val_width = Colors::width( $value, self::isPreColorized( $col ), $encoding ); + if ( $col_width && ( $original_val_width > $col_width || strpos( $value, "\n" ) !== false ) ) { + $split_lines = preg_split( '/\r\n|\n/', $value ); + if ( false === $split_lines ) { + $split_lines = array( $value ); + } - $value = str_replace( array( "\r\n", "\n" ), ' ', $value ); + $wrapped_lines = []; + foreach ( $split_lines as $line ) { + $line_wrapped = $this->wrapText( $line, $col_width, $encoding, self::isPreColorized( $col ) ); + $wrapped_lines = array_merge( $wrapped_lines, $line_wrapped ); + } - $col_width = $this->_widths[ $col ]; - $encoding = function_exists( 'mb_detect_encoding' ) ? mb_detect_encoding( $value, null, true /*strict*/ ) : false; - $original_val_width = Colors::width( $value, self::isPreColorized( $col ), $encoding ); - if ( $col_width && $original_val_width > $col_width ) { - $row[ $col ] = \cli\safe_substr( $value, 0, $col_width, true /*is_width*/, $encoding ); - $value = \cli\safe_substr( $value, \cli\safe_strlen( $row[ $col ], $encoding ), null /*length*/, false /*is_width*/, $encoding ); - $i = 0; - do { - $extra_value = \cli\safe_substr( $value, 0, $col_width, true /*is_width*/, $encoding ); - $val_width = Colors::width( $extra_value, self::isPreColorized( $col ), $encoding ); - if ( $val_width ) { - $extra_rows[ $col ][] = $extra_value; - $value = \cli\safe_substr( $value, \cli\safe_strlen( $extra_value, $encoding ), null /*length*/, false /*is_width*/, $encoding ); - $i++; - if ( $i > $extra_row_count ) { - $extra_row_count = $i; - } - } - } while( $value ); + $row[ $col ] = array_shift( $wrapped_lines ); + foreach ( $wrapped_lines as $wrapped_line ) { + $extra_rows[ $col ][] = $wrapped_line; + ++$extra_row_count; + } } - } } - $row = array_map(array($this, 'padColumn'), $row, array_keys($row)); - array_unshift($row, ''); // First border - array_push($row, ''); // Last border + $row = array_map( array( $this, 'padColumn' ), $row, array_keys( $row ) ); + array_unshift( $row, '' ); // First border + array_push( $row, '' ); // Last border - $ret = join($this->_characters['border'], $row); + $ret = join( $this->_characters['border'], $row ); if ( $extra_row_count ) { - foreach( $extra_rows as $col => $col_values ) { - while( count( $col_values ) < $extra_row_count ) { + foreach ( $extra_rows as $col => $col_values ) { + while ( count( $col_values ) < $extra_row_count ) { $col_values[] = ''; } } do { $row_values = array(); - $has_more = false; - foreach( $extra_rows as $col => &$col_values ) { - $row_values[ $col ] = array_shift( $col_values ); + $has_more = false; + foreach ( $extra_rows as $col => &$col_values ) { + $row_values[ $col ] = ! empty( $col_values ) ? array_shift( $col_values ) : ''; if ( count( $col_values ) ) { $has_more = true; } } - $row_values = array_map(array($this, 'padColumn'), $row_values, array_keys($row_values)); - array_unshift($row_values, ''); // First border - array_push($row_values, ''); // Last border + $row_values = array_map( array( $this, 'padColumn' ), $row_values, array_keys( $row_values ) ); + array_unshift( $row_values, '' ); // First border + array_push( $row_values, '' ); // Last border - $ret .= PHP_EOL . join($this->_characters['border'], $row_values); - } while( $has_more ); + $ret .= PHP_EOL . join( $this->_characters['border'], $row_values ); + } while ( $has_more ); } return $ret; } - private function padColumn($content, $column) { - return $this->_characters['padding'] . Colors::pad( $content, $this->_widths[ $column ], $this->isPreColorized( $column ) ) . $this->_characters['padding']; + /** + * Get the alignment for a column. + * + * @param int $column Column index. + * @return int Alignment constant (STR_PAD_LEFT, STR_PAD_RIGHT, or STR_PAD_BOTH). + */ + private function getColumnAlignment( $column ) { + $column_name = isset( $this->_headers[ $column ] ) ? $this->_headers[ $column ] : ''; + if ( $column_name !== '' && array_key_exists( $column_name, $this->_alignments ) ) { + return $this->_alignments[ $column_name ]; + } + return Column::ALIGN_LEFT; + } + + /** + * Pad a column value. + * + * @param string $content The column content. + * @param int $column The column index. + * @return string The padded column. + */ + private function padColumn( $content, $column ) { + $alignment = $this->getColumnAlignment( $column ); + $content = str_replace( "\t", ' ', (string) $content ); + return $this->_characters['padding'] . Colors::pad( $content, $this->_widths[ $column ], $this->isPreColorized( $column ), false, $alignment ) . $this->_characters['padding']; } /** * Set whether items are pre-colorized. * - * @param bool|array $colorized A boolean to set all columns in the table as pre-colorized, or an array of booleans keyed by column index (number) to set individual columns as pre-colorized. + * @param bool|array $pre_colorized A boolean to set all columns in the table as pre-colorized, or an array of booleans keyed by column index (number) to set individual columns as pre-colorized. + * @return void */ public function setPreColorized( $pre_colorized ) { $this->_pre_colorized = $pre_colorized; } + /** + * Wrap text based on the configured wrapping mode. + * + * @param string $text The text to wrap. + * @param int $width The maximum width. + * @param string|bool $encoding The text encoding. + * @param bool $is_precolorized Whether the text is pre-colorized. + * @return array Array of wrapped lines. + */ + protected function wrapText( $text, $width, $encoding, $is_precolorized ) { + if ( ! $width ) { + return array( $text ); + } + + $text_width = Colors::width( $text, $is_precolorized, $encoding ); + + // If text fits, no wrapping needed + if ( $text_width <= $width ) { + return array( $text ); + } + + // Handle truncate mode + if ( 'truncate' === $this->_wrapping_mode ) { + if ( $width <= self::ELLIPSIS_WIDTH ) { + // Not enough space for ellipsis, just truncate + return array( (string) \cli\safe_substr( $text, 0, $width, true /*is_width*/, $encoding ) ); + } + + // Truncate and add ellipsis + $truncated = (string) \cli\safe_substr( $text, 0, $width - self::ELLIPSIS_WIDTH, true /*is_width*/, $encoding ); + return array( $truncated . self::ELLIPSIS ); + } + + // Handle word-wrap mode + if ( 'word-wrap' === $this->_wrapping_mode ) { + return $this->wordWrap( $text, $width, $encoding, $is_precolorized ); + } + + // Default: character-boundary wrapping + $wrapped_lines = array(); + $line = $text; + + // Use the new color-aware wrapping for pre-colorized content + if ( $is_precolorized ) { + $wrapped_lines = Colors::wrapPreColorized( $line, $width, $encoding ); + } else { + // For non-colorized content, use character-boundary wrapping + do { + $wrapped_value = (string) \cli\safe_substr( $line, 0, $width, true /*is_width*/, $encoding ); + $val_width = Colors::width( $wrapped_value, $is_precolorized, $encoding ); + if ( $val_width ) { + $wrapped_lines[] = $wrapped_value; + $line = (string) \cli\safe_substr( $line, \cli\safe_strlen( $wrapped_value, $encoding ), null /*length*/, false /*is_width*/, $encoding ); + } + } while ( $line ); + } + + return $wrapped_lines; + } + + /** + * Wrap text at word boundaries. + * + * @param string $text The text to wrap. + * @param int $width The maximum width. + * @param string|bool $encoding The text encoding. + * @param bool $is_precolorized Whether the text is pre-colorized. + * @return array Array of wrapped lines. + */ + protected function wordWrap( $text, $width, $encoding, $is_precolorized ) { + $wrapped_lines = array(); + $current_line = ''; + $current_line_width = 0; + + // Split by spaces and hyphens while keeping the delimiters + $words = preg_split( '/(\s+|-)/u', $text, -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY ); + if ( false === $words ) { + $words = array( $text ); + } + + foreach ( $words as $word ) { + $word_width = Colors::width( $word, $is_precolorized, $encoding ); + + // If this word alone exceeds the width, we need to split it + if ( $word_width > $width ) { + // Flush current line if not empty + if ( $current_line !== '' ) { + $wrapped_lines[] = $current_line; + $current_line = ''; + $current_line_width = 0; + } + + // Split the long word at character boundaries + $remaining_word = $word; + while ( $remaining_word ) { + $chunk = (string) \cli\safe_substr( $remaining_word, 0, $width, true /*is_width*/, $encoding ); + $wrapped_lines[] = $chunk; + $remaining_word = (string) \cli\safe_substr( $remaining_word, \cli\safe_strlen( $chunk, $encoding ), null /*length*/, false /*is_width*/, $encoding ); + } + continue; + } + + // Check if adding this word would exceed the width + if ( $current_line !== '' && $current_line_width + $word_width > $width ) { + // Start a new line + $wrapped_lines[] = $current_line; + $current_line = $word; + $current_line_width = $word_width; + } else { + // Add to current line + $current_line .= $word; + $current_line_width += $word_width; + } + } + + // Add any remaining content + if ( $current_line !== '' ) { + $wrapped_lines[] = $current_line; + } + + return $wrapped_lines ?: array( '' ); + } + /** * Is a column pre-colorized? * diff --git a/lib/cli/table/Column.php b/lib/cli/table/Column.php new file mode 100644 index 0000000..5c1f733 --- /dev/null +++ b/lib/cli/table/Column.php @@ -0,0 +1,22 @@ + + * @copyright 2010 James Logsdom (http://girsbrain.org) + * @license http://www.opensource.org/licenses/mit-license.php The MIT License + */ + +namespace cli\table; + +/** + * Column alignment constants for table rendering. + */ +interface Column { + const ALIGN_LEFT = STR_PAD_RIGHT; + const ALIGN_RIGHT = STR_PAD_LEFT; + const ALIGN_CENTER = STR_PAD_BOTH; +} diff --git a/lib/cli/table/Renderer.php b/lib/cli/table/Renderer.php index 3ac7be5..10aa85a 100644 --- a/lib/cli/table/Renderer.php +++ b/lib/cli/table/Renderer.php @@ -16,17 +16,58 @@ * Table renderers are used to change how a table is displayed. */ abstract class Renderer { + /** + * @var array + */ protected $_widths = array(); - public function __construct(array $widths = array()) { + /** + * @var array + */ + protected $_alignments = array(); + + /** + * @var array + */ + protected $_headers = array(); + + /** + * Constructor. + * + * @param array $widths Column widths. + * @param array $alignments Column alignments. + */ + public function __construct(array $widths = array(), array $alignments = array()) { $this->setWidths($widths); + $this->setAlignments($alignments); + } + + /** + * Set the alignments of each column in the table. + * + * @param array $alignments The alignments of the columns. + * @return void + */ + public function setAlignments(array $alignments) { + $this->_alignments = $alignments; + } + + /** + * Set the headers of the table. + * + * @param array $headers The headers of the table. + * @return void + */ + public function setHeaders(array $headers) { + $this->_headers = $headers; } /** * Set the widths of each column in the table. * - * @param array $widths The widths of the columns. - * @param bool $fallback Whether to use these values as fallback only. + * @param array $widths The widths of the columns. + * @param bool $fallback Whether to use these values as fallback only. + * @return void */ public function setWidths(array $widths, $fallback = false) { if ($fallback) { @@ -41,7 +82,7 @@ public function setWidths(array $widths, $fallback = false) { * Render a border for the top and bottom and separating the headers from the * table rows. * - * @return string The table border. + * @return string|null The table border. */ public function border() { return null; @@ -50,8 +91,8 @@ public function border() { /** * Renders a row for output. * - * @param array $row The table row. - * @return string The formatted table row. + * @param array $row The table row. + * @return string The formatted table row. */ - abstract public function row(array $row); + abstract public function row( array $row ); } diff --git a/lib/cli/table/Tabular.php b/lib/cli/table/Tabular.php index 6e7c502..f373799 100644 --- a/lib/cli/table/Tabular.php +++ b/lib/cli/table/Tabular.php @@ -19,10 +19,41 @@ class Tabular extends Renderer { /** * Renders a row for output. * - * @param array $row The table row. - * @return string The formatted table row. + * @param array $row The table row. + * @return string The formatted table row. */ - public function row(array $row) { - return implode("\t", array_values($row)); + public function row( array $row ) { + /** @var array> $rows */ + $rows = []; + $output = ''; + $split_lines = []; + $col = null; + + foreach ( $row as $col => $value ) { + $value = ( isset( $value ) && ( is_scalar( $value ) || ( is_object( $value ) && method_exists( $value, '__toString' ) ) ) ) ? (string) $value : ''; + $value = str_replace( "\t", ' ', $value ); + $split_lines = preg_split( '/\r\n|\n/', $value ); + if ( false === $split_lines ) { + $split_lines = array( $value ); + } + // Keep anything before the first line break on the original line + $row[ $col ] = array_shift( $split_lines ); + } + + $rows[] = $row; + + if ( null !== $col ) { + foreach ( $split_lines as $i => $line ) { + if ( ! isset( $rows[ $i + 1 ] ) ) { + $rows[ $i + 1 ] = array_fill_keys( array_keys( $row ), '' ); + } + $rows[ $i + 1 ][ $col ] = $line; + } + } + + foreach ( $rows as $r ) { + $output .= implode( "\t", $r ) . PHP_EOL; + } + return rtrim( $output, PHP_EOL ); } } diff --git a/lib/cli/tree/Ascii.php b/lib/cli/tree/Ascii.php index 00edf38..a94a8ef 100644 --- a/lib/cli/tree/Ascii.php +++ b/lib/cli/tree/Ascii.php @@ -18,7 +18,7 @@ class Ascii extends Renderer { /** - * @param array $tree + * @param array $tree * @return string */ public function render(array $tree) diff --git a/lib/cli/tree/Markdown.php b/lib/cli/tree/Markdown.php index ba1fd05..7f718f7 100644 --- a/lib/cli/tree/Markdown.php +++ b/lib/cli/tree/Markdown.php @@ -37,7 +37,7 @@ function __construct($padding = null) /** * Renders the tree * - * @param array $tree + * @param array $tree * @param int $level Optional * @return string */ diff --git a/lib/cli/tree/Renderer.php b/lib/cli/tree/Renderer.php index ff352bc..8348ffe 100644 --- a/lib/cli/tree/Renderer.php +++ b/lib/cli/tree/Renderer.php @@ -18,7 +18,7 @@ abstract class Renderer { /** - * @param array $tree + * @param array $tree * @return string|null */ abstract public function render(array $tree); diff --git a/phpstan.neon.dist b/phpstan.neon.dist new file mode 100644 index 0000000..4611d49 --- /dev/null +++ b/phpstan.neon.dist @@ -0,0 +1,9 @@ +parameters: + level: 9 + paths: + - lib + scanDirectories: + - vendor/wp-cli/wp-cli/php + scanFiles: + - vendor/php-stubs/wordpress-stubs/wordpress-stubs.php + treatPhpDocTypesAsCertain: false diff --git a/phpunit.xml b/phpunit.xml deleted file mode 100644 index 69cda7f..0000000 --- a/phpunit.xml +++ /dev/null @@ -1,10 +0,0 @@ - - - - tests/ - - - diff --git a/phpunit.xml.dist b/phpunit.xml.dist new file mode 100644 index 0000000..2ccf7d3 --- /dev/null +++ b/phpunit.xml.dist @@ -0,0 +1,24 @@ + + + tests/ + + + + + lib/ + + + diff --git a/tests/test-arguments.php b/tests/Test_Arguments.php similarity index 78% rename from tests/test-arguments.php rename to tests/Test_Arguments.php index f828926..33ff728 100644 --- a/tests/test-arguments.php +++ b/tests/Test_Arguments.php @@ -1,14 +1,15 @@ $this->flags, 'options' => $this->options ); + + set_error_handler( + static function ( $errno, $errstr ) { + throw new \Exception( $errstr, $errno ); + }, + E_ALL + ); } /** * Tear down fixtures */ - public function tearDown() + public function tear_down() { $this->flags = null; $this->options = null; $this->settings = null; self::clearArgv(); + restore_error_handler(); } /** @@ -150,7 +159,7 @@ public function testAddOptions() * * @return array set of args and expected parsed values */ - public function settingsWithValidOptions() + public static function settingsWithValidOptions() { return array( array( @@ -173,7 +182,7 @@ public function settingsWithValidOptions() * * @return array set of args and expected parsed values */ - public function settingsWithMissingOptions() + public static function settingsWithMissingOptions() { return array( array( @@ -192,7 +201,7 @@ public function settingsWithMissingOptions() * * @return array set of args and expected parsed values */ - public function settingsWithMissingOptionsWithDefault() + public static function settingsWithMissingOptionsWithDefault() { return array( array( @@ -206,7 +215,7 @@ public function settingsWithMissingOptionsWithDefault() ); } - public function settingsWithNoOptionsWithDefault() + public static function settingsWithNoOptionsWithDefault() { return array( array( @@ -246,6 +255,7 @@ private function _testParse($cliParams, $expectedValues) * * @dataProvider settingsWithValidOptions */ + #[DataProvider( 'settingsWithValidOptions' )] // phpcs:ignore PHPCompatibility.Attributes.NewAttributes.PHPUnitAttributeFound public function testParseWithValidOptions($cliParams, $expectedValues) { $this->_testParse($cliParams, $expectedValues); @@ -255,11 +265,12 @@ public function testParseWithValidOptions($cliParams, $expectedValues) * @param array $args arguments as they appear in the cli * @param array $expectedValues expected values after parsing * @dataProvider settingsWithMissingOptions - * @expectedException PHPUnit_Framework_Error_Warning - * @expectedExceptionMessage no value given for --option1 */ + #[DataProvider( 'settingsWithMissingOptions' )] // phpcs:ignore PHPCompatibility.Attributes.NewAttributes.PHPUnitAttributeFound public function testParseWithMissingOptions($cliParams, $expectedValues) { + $this->expectException(\Exception::class); + $this->expectExceptionMessage('no value given for --option1'); $this->_testParse($cliParams, $expectedValues); } @@ -268,6 +279,7 @@ public function testParseWithMissingOptions($cliParams, $expectedValues) * @param array $expectedValues expected values after parsing * @dataProvider settingsWithMissingOptionsWithDefault */ + #[DataProvider( 'settingsWithMissingOptionsWithDefault' )] // phpcs:ignore PHPCompatibility.Attributes.NewAttributes.PHPUnitAttributeFound public function testParseWithMissingOptionsWithDefault($cliParams, $expectedValues) { $this->_testParse($cliParams, $expectedValues); @@ -278,7 +290,33 @@ public function testParseWithMissingOptionsWithDefault($cliParams, $expectedValu * @param array $expectedValues expected values after parsing * @dataProvider settingsWithNoOptionsWithDefault */ + #[DataProvider( 'settingsWithNoOptionsWithDefault' )] // phpcs:ignore PHPCompatibility.Attributes.NewAttributes.PHPUnitAttributeFound public function testParseWithNoOptionsWithDefault($cliParams, $expectedValues) { $this->_testParse($cliParams, $expectedValues); } + + public function testHelpScreenRender() { + $args = new \cli\Arguments( $this->settings ); + $help = $args->getHelpScreen(); + + $output = $help->render(); + + // It should contain Flags and Options sections + $this->assertStringContainsString( 'Flags', $output ); + $this->assertStringContainsString( 'Options', $output ); + + // Now test with ONLY flags + $settings = array( + 'flags' => $this->flags, + ); + $args = new \cli\Arguments( $settings ); + $help = $args->getHelpScreen(); + $output = $help->render(); + + $this->assertStringContainsString( 'Flags', $output ); + $this->assertStringNotContainsString( 'Options', $output ); + + // It should NOT have leading/trailing newlines or empty sections + $this->assertSame( trim( $output ), $output, 'Output should not have leading/trailing whitespace' ); + } } diff --git a/tests/test-cli.php b/tests/Test_Cli.php similarity index 96% rename from tests/test-cli.php rename to tests/Test_Cli.php index 5df0b6a..bd4476d 100644 --- a/tests/test-cli.php +++ b/tests/Test_Cli.php @@ -1,10 +1,11 @@ assertSame( 11, \cli\strwidth( $str ) ); // Tests grapheme_strlen(). + $this->assertSame( 8, \cli\strwidth( $str ) ); // Tests grapheme_strlen() - ICU treats conjuncts as single graphemes. putenv( 'PHP_CLI_TOOLS_TEST_STRWIDTH=2' ); // Test preg_split( '/\X/u' ). $this->assertSame( 11, \cli\strwidth( $str ) ); } else { @@ -550,4 +553,20 @@ function test_safe_strlen() { mb_detect_order( $mb_detect_order ); } } + + function test_render_with_color_tokens_and_sprintf_args_colors_disabled() { + Colors::disable( true ); + + // Color tokens in format string must not cause "sprintf(): Too few arguments". + $result = \cli\render( '[%C%k%s%N] Starting!', '2024-01-01 12:00:00' ); + $this->assertSame( '[2024-01-01 12:00:00] Starting!', $result ); + } + + function test_render_with_color_tokens_and_sprintf_args_colors_enabled() { + Colors::enable( true ); + + $result = \cli\render( '[%C%k%s%N] Starting!', '2024-01-01 12:00:00' ); + $this->assertStringContainsString( '2024-01-01 12:00:00', $result ); + $this->assertStringContainsString( 'Starting!', $result ); + } } diff --git a/tests/test-colors.php b/tests/Test_Colors.php similarity index 62% rename from tests/test-colors.php rename to tests/Test_Colors.php index e7be7a0..b7d28ff 100644 --- a/tests/test-colors.php +++ b/tests/Test_Colors.php @@ -1,13 +1,16 @@ $color ) { $ret[] = array( $str, $color ); diff --git a/tests/test-shell.php b/tests/Test_Shell.php similarity index 79% rename from tests/test-shell.php rename to tests/Test_Shell.php index 3db9c02..f793027 100644 --- a/tests/test-shell.php +++ b/tests/Test_Shell.php @@ -1,11 +1,12 @@ assertSame( 3, count( $result ) ); - $this->assertSame( '1あいうえ ', $result[0] ); // 1 single width, 4 double-width, space = 10. + $this->assertSame( '1あいうえ ', $result[0] ); // 1 single-width, 4 double-width, space = 10. $this->assertSame( 'おか2きくｶ', $result[1] ); // 2 double-width, 1 single-width, 2 double-width, 1 half-width = 10. $this->assertSame( 'けこ ', $result[2] ); // 2 double-width, 8 spaces = 10. @@ -242,4 +246,256 @@ public function test_ascii_pre_colorized_widths() { $this->assertSame( 56, strlen( $out[6] ) ); } + public function test_preserve_trailing_tabs() { + $table = new cli\Table(); + $renderer = new cli\Table\Tabular(); + $table->setRenderer( $renderer ); + + $table->setHeaders( array( 'Field', 'Type', 'Null', 'Key', 'Default', 'Extra' ) ); + + // Add row with missing values at the end + $table->addRow( array( 'date', 'date', 'NO', 'PRI', '', '' ) ); + $table->addRow( array( 'awesome_stuff', 'text', 'YES', '', '', '' ) ); + + $out = $table->getDisplayLines(); + + $expected = [ + "Field\tType\tNull\tKey\tDefault\tExtra", + "date\tdate\tNO\tPRI\t\t", + "awesome_stuff\ttext\tYES\t\t\t", + ]; + + $this->assertSame( $expected, $out, 'Trailing tabs should be preserved in table output.' ); + } + + public function test_null_values_are_handled() { + $table = new cli\Table(); + $renderer = new cli\Table\Tabular(); + $table->setRenderer( $renderer ); + + $table->setHeaders( array( 'Field', 'Type', 'Null', 'Key', 'Default', 'Extra' ) ); + + // Add row with a null value in the middle + $table->addRow( array( 'id', 'int', 'NO', 'PRI', null, 'auto_increment' ) ); + + // Add row with a null value at the end + $table->addRow( array( 'name', 'varchar(255)', 'YES', '', 'NULL', null ) ); + + $out = $table->getDisplayLines(); + + $expected = [ + "Field\tType\tNull\tKey\tDefault\tExtra", + "id\tint\tNO\tPRI\t\tauto_increment", + "name\tvarchar(255)\tYES\t\tNULL\t", + ]; + $this->assertSame( $expected, $out, 'Null values should be safely converted to empty strings in table output.' ); + } + + public function test_default_alignment() { + $table = new cli\Table(); + $table->setRenderer( new cli\Table\Ascii() ); + $table->setHeaders( array( 'Header1', 'Header2' ) ); + $table->addRow( array( 'Row1Col1', 'Row1Col2' ) ); + + $out = $table->getDisplayLines(); + + // By default, columns should be left-aligned. + $this->assertStringContainsString( '| Header1 | Header2 |', $out[1] ); + $this->assertStringContainsString( '| Row1Col1 | Row1Col2 |', $out[3] ); + } + + public function test_right_alignment() { + $table = new cli\Table(); + $table->setRenderer( new cli\Table\Ascii() ); + $table->setHeaders( array( 'Name', 'Size' ) ); + $table->setAlignments( array( 'Name' => \cli\table\Column::ALIGN_RIGHT, 'Size' => \cli\table\Column::ALIGN_RIGHT ) ); + $table->addRow( array( 'file.txt', '1024 B' ) ); + + $out = $table->getDisplayLines(); + + // Headers should be right-aligned in their columns + $this->assertStringContainsString( '| Name | Size |', $out[1] ); + // Data should be right-aligned + $this->assertStringContainsString( '| file.txt | 1024 B |', $out[3] ); + } + + public function test_center_alignment() { + $table = new cli\Table(); + $table->setRenderer( new cli\Table\Ascii() ); + $table->setHeaders( array( 'A', 'B' ) ); + $table->setAlignments( array( 'A' => \cli\table\Column::ALIGN_CENTER, 'B' => \cli\table\Column::ALIGN_CENTER ) ); + $table->addRow( array( 'test', 'data' ) ); + + $out = $table->getDisplayLines(); + + // Headers should be center-aligned + $this->assertStringContainsString( '| A | B |', $out[1] ); + // Data should be center-aligned + $this->assertStringContainsString( '| test | data |', $out[3] ); + } + + public function test_mixed_alignments() { + $table = new cli\Table(); + $table->setRenderer( new cli\Table\Ascii() ); + $table->setHeaders( array( 'Name', 'Count', 'Status' ) ); + $table->setAlignments( array( + 'Name' => \cli\table\Column::ALIGN_LEFT, + 'Count' => \cli\table\Column::ALIGN_RIGHT, + 'Status' => \cli\table\Column::ALIGN_CENTER, + ) ); + $table->addRow( array( 'Item', '42', 'OK' ) ); + + $out = $table->getDisplayLines(); + + // Headers line should show all three with proper alignment + $this->assertStringContainsString( '| Name | Count | Status |', $out[1] ); + // Data line: Name left, Count right, Status center + $this->assertStringContainsString( '| Item | 42 | OK |', $out[3] ); + } + + public function test_invalid_alignment_value() { + $this->expectException( \InvalidArgumentException::class ); + $table = new cli\Table(); + $table->setHeaders( array( 'Header1' ) ); + $table->setAlignments( array( 'Header1' => 'invalid-alignment' ) ); + } + + public function test_invalid_alignment_column() { + $this->expectException( \InvalidArgumentException::class ); + $table = new cli\Table(); + $table->setHeaders( array( 'Header1' ) ); + $table->setAlignments( array( 'NonExistent' => \cli\table\Column::ALIGN_LEFT ) ); + } + + public function test_alignment_before_headers() { + // Test that alignments can be set before headers without throwing an error + $table = new cli\Table(); + $table->setRenderer( new cli\Table\Ascii() ); + $table->setAlignments( array( 'Name' => \cli\table\Column::ALIGN_RIGHT ) ); + $table->setHeaders( array( 'Name' ) ); + $table->addRow( array( 'LongName' ) ); + + $out = $table->getDisplayLines(); + + // Should be right-aligned - "Name" is 4 chars, "LongName" is 8 chars, so column width is 8 + $this->assertStringContainsString( '| Name |', $out[1] ); + $this->assertStringContainsString( '| LongName |', $out[3] ); + } + + public function test_resetRows() { + $table = new cli\Table(); + $table->setHeaders( array( 'Name', 'Age' ) ); + $table->addRow( array( 'Alice', '30' ) ); + $table->addRow( array( 'Bob', '25' ) ); + + $this->assertEquals( 2, $table->countRows() ); + + $table->resetRows(); + + $this->assertEquals( 0, $table->countRows() ); + + // Headers should still be intact + $out = $table->getDisplayLines(); + $this->assertGreaterThan( 0, count( $out ) ); + } + + public function test_shortcut_constructor_tabular() { + $headers = array( + array( 'Name' => 'Alice', 'Age' => '30' ), + array( 'Name' => 'Bob', 'Age' => '25' ), + ); + + $table = new cli\Table( $headers ); + $table->setRenderer( new cli\Table\Tabular() ); + + $out = $table->getDisplayLines(); + + $expected = [ + "Name\tAge", + "Alice\t30", + "Bob\t25", + ]; + + $this->assertSame( $expected, $out ); + } + + public function test_shortcut_constructor_normalization() { + $headers = array( + array( 'Name' => 'Alice', 'Age' => '30' ), + array( 'Age' => '25', 'Name' => 'Bob' ), // Different order + array( 'Name' => 'Charlie' ), // Missing Age + ); + + $table = new cli\Table( $headers ); + $table->setRenderer( new cli\Table\Tabular() ); + + $out = $table->getDisplayLines(); + + $expected = [ + "Name\tAge", + "Alice\t30", + "Bob\t25", // Order should be normalized to match headers! + "Charlie\t", // Missing value should be empty string + ]; + + $this->assertSame( $expected, $out ); + } + + public function test_displayRow_ascii() { + $mockFile = tempnam( sys_get_temp_dir(), 'temp' ); + $resource = fopen( $mockFile, 'wb' ); + + try { + \cli\Streams::setStream( 'out', $resource ); + + $table = new cli\Table(); + $renderer = new cli\Table\Ascii(); + $table->setRenderer( $renderer ); + $table->setHeaders( array( 'Name', 'Age' ) ); + + // Display a single row + $table->displayRow( array( 'Alice', '30' ) ); + + $output = file_get_contents( $mockFile ); + + // Should contain the row data + $this->assertStringContainsString( 'Alice', $output ); + $this->assertStringContainsString( '30', $output ); + + // Should contain borders + $this->assertStringContainsString( '|', $output ); + $this->assertStringContainsString( '+', $output ); + } finally { + if ( $mockFile && file_exists( $mockFile ) ) { + unlink( $mockFile ); + } + } + } + + public function test_displayRow_tabular() { + $mockFile = tempnam( sys_get_temp_dir(), 'temp' ); + $resource = fopen( $mockFile, 'wb' ); + + try { + \cli\Streams::setStream( 'out', $resource ); + + $table = new cli\Table(); + $renderer = new cli\Table\Tabular(); + $table->setRenderer( $renderer ); + $table->setHeaders( array( 'Name', 'Age' ) ); + + // Display a single row + $table->displayRow( array( 'Alice', '30' ) ); + + $output = file_get_contents( $mockFile ); + + // Should contain the row data with tabs + $this->assertStringContainsString( 'Alice', $output ); + $this->assertStringContainsString( '30', $output ); + } finally { + if ( $mockFile && file_exists( $mockFile ) ) { + unlink( $mockFile ); + } + } + } } diff --git a/tests/test-table-ascii.php b/tests/Test_Table_Ascii.php similarity index 68% rename from tests/test-table-ascii.php rename to tests/Test_Table_Ascii.php index e5ffece..39cc99f 100644 --- a/tests/test-table-ascii.php +++ b/tests/Test_Table_Ascii.php @@ -1,9 +1,10 @@ _mockFile = tempnam(sys_get_temp_dir(), 'temp'); $resource = fopen($this->_mockFile, 'wb'); Streams::setStream('out', $resource); @@ -36,7 +37,7 @@ public function setUp() { /** * Cleans temporary file */ - public function tearDown() { + public function tear_down() { if (file_exists($this->_mockFile)) { unlink($this->_mockFile); } @@ -113,6 +114,118 @@ public function testDrawOneColumnColorDisabledTable() { $this->assertInOutEquals(array($headers, $rows), $output); } + /** + * Test that colorized text wraps correctly while maintaining color codes. + */ + public function testWrappedColorizedText() { + Colors::enable( true ); + $headers = array('Column 1', 'Column 2'); + $green_code = "\x1b\x5b\x33\x32\x3b\x31\x6d"; // Green + bright + $reset_code = "\x1b\x5b\x30\x6d"; // Reset + + // Create a long colorized string that will wrap + $long_text = Colors::colorize('%GThis is a long green text%n', true); + + $rows = array( + array('Short', $long_text), + ); + + // Expected output with wrapped text maintaining colors + // The color codes are preserved across wrapped lines + $output = <<_instance->setHeaders($headers); + $this->_instance->setRows($rows); + $renderer = new Ascii([10, 12]); + $renderer->setConstraintWidth(30); + $this->_instance->setRenderer($renderer); + $this->_instance->setAsciiPreColorized(true); + $this->_instance->display(); + $this->assertOutFileEqualsWith($output); + } + + /** + * Test word-wrapping mode keeps words together. + */ + public function testWordWrappingMode() { + $headers = array('name', 'status'); + $rows = array( + array('all-in-one-wp-migration-multisite-extension', 'inactive'), + ); + + // With word-wrap, the hyphenated words should wrap at hyphens + $output = <<<'OUT' ++----------------------+----------+ +| name | status | ++----------------------+----------+ +| all-in-one-wp- | inactive | +| migration-multisite- | | +| extension | | ++----------------------+----------+ + +OUT; + + $this->_instance->setHeaders($headers); + $this->_instance->setRows($rows); + $renderer = new Ascii([20, 8]); + $renderer->setConstraintWidth(36); + $this->_instance->setRenderer($renderer); + $this->_instance->setWrappingMode('word-wrap'); + $this->_instance->display(); + $this->assertOutFileEqualsWith($output); + } + + /** + * Test truncate mode with ellipsis. + */ + public function testTruncateMode() { + $headers = array('name', 'status'); + $rows = array( + array('all-in-one-wp-migration-multisite-extension', 'inactive'), + array('short', 'active'), + ); + + // With truncate, long names should be truncated with ellipsis + $output = <<<'OUT' ++----------------------+----------+ +| name | status | ++----------------------+----------+ +| all-in-one-wp-mig... | inactive | +| short | active | ++----------------------+----------+ + +OUT; + + $this->_instance->setHeaders($headers); + $this->_instance->setRows($rows); + $renderer = new Ascii([20, 8]); + $renderer->setConstraintWidth(36); + $this->_instance->setRenderer($renderer); + $this->_instance->setWrappingMode('truncate'); + $this->_instance->display(); + $this->assertOutFileEqualsWith($output); + } + + /** + * Test that wrapping mode setter validates input. + */ + public function testWrappingModeValidation() { + $this->expectException(\InvalidArgumentException::class); + $this->expectExceptionMessage("Invalid wrapping mode 'invalid'"); + + $renderer = new Ascii(); + $renderer->setWrappingMode('invalid'); + } + /** * Checks that spacing and borders are handled correctly in table */ @@ -248,7 +361,6 @@ public function testDrawWithHeadersNoData() { +----------+----------+ | header 1 | header 2 | +----------+----------+ -+----------+----------+ OUT; $this->assertInOutEquals(array($headers, $rows), $output); @@ -274,6 +386,9 @@ private function assertInOutEquals(array $input, $output) { * @param mixed $expected Expected output */ private function assertOutFileEqualsWith($expected) { - $this->assertEquals($expected, file_get_contents($this->_mockFile)); + $actual = file_get_contents($this->_mockFile); + $actual = str_replace("\r\n", "\n", $actual); + $expected = str_replace("\r\n", "\n", $expected); + $this->assertEquals($expected, $actual); } } diff --git a/tests/bootstrap.php b/tests/bootstrap.php index 31af8b9..1770859 100644 --- a/tests/bootstrap.php +++ b/tests/bootstrap.php @@ -1,20 +1,12 @@ =' ) ) { - - class_alias( 'PHPUnit\Framework\TestCase', 'PHPUnit_Framework_TestCase' ); - class_alias( 'PHPUnit\Framework\Exception', 'PHPUnit_Framework_Exception' ); - class_alias( 'PHPUnit\Framework\ExpectationFailedException', 'PHPUnit_Framework_ExpectationFailedException' ); - class_alias( 'PHPUnit\Framework\Error\Notice', 'PHPUnit_Framework_Error_Notice' ); - class_alias( 'PHPUnit\Framework\Error\Warning', 'PHPUnit_Framework_Error_Warning' ); - class_alias( 'PHPUnit\Framework\Test', 'PHPUnit_Framework_Test' ); - class_alias( 'PHPUnit\Framework\Warning', 'PHPUnit_Framework_Warning' ); - class_alias( 'PHPUnit\Framework\AssertionFailedError', 'PHPUnit_Framework_AssertionFailedError' ); - class_alias( 'PHPUnit\Framework\TestSuite', 'PHPUnit_Framework_TestSuite' ); - class_alias( 'PHPUnit\Framework\TestListener', 'PHPUnit_Framework_TestListener' ); - class_alias( 'PHPUnit\Util\GlobalState', 'PHPUnit_Util_GlobalState' ); - class_alias( 'PHPUnit\Util\Getopt', 'PHPUnit_Util_Getopt' ); - -} diff --git a/typos.toml b/typos.toml new file mode 100644 index 0000000..965f891 --- /dev/null +++ b/typos.toml @@ -0,0 +1,6 @@ +[default] +extend-ignore-re = [ + "(?Rm)^.*(#|//)\\s*spellchecker:disable-line$", + "(?s)(#|//)\\s*spellchecker:off.*?\\n\\s*(#|//)\\s*spellchecker:on", + "(#|//)\\s*spellchecker:ignore-next-line\\n.*" +]