Add column alignment support for tables

[Copilot]

Table Column Alignment Feature

This PR implements table column alignment functionality to address wp-cli/db-command#239, which requests the ability to right-align numeric values in tables for better readability.

Visual Comparison

BEFORE: Database Table Sizes (Left-Aligned - Hard to Compare)

+-------------+--------+-----------+------------+------------+
| Table Name  | Rows   | Data Size | Index Size | Total Size |
+-------------+--------+-----------+------------+------------+
| wp_posts    | 1,234  | 5.2 MB    | 1.1 MB     | 6.3 MB     |
| wp_postmeta | 45,678 | 23.4 MB   | 8.7 MB     | 32.1 MB    |
| wp_comments | 9,012  | 2.3 MB    | 0.8 MB     | 3.1 MB     |
| wp_options  | 456    | 1.5 MB    | 0.2 MB     | 1.7 MB     |
| wp_users    | 89     | 0.1 MB    | 0.05 MB    | 0.15 MB    |
+-------------+--------+-----------+------------+------------+

AFTER: Database Table Sizes (Right-Aligned - Easy to Compare!)

+-------------+--------+-----------+------------+------------+
| Table Name  |   Rows | Data Size | Index Size | Total Size |
+-------------+--------+-----------+------------+------------+
| wp_posts    |  1,234 |    5.2 MB |     1.1 MB |     6.3 MB |
| wp_postmeta | 45,678 |   23.4 MB |     8.7 MB |    32.1 MB |
| wp_comments |  9,012 |    2.3 MB |     0.8 MB |     3.1 MB |
| wp_options  |    456 |    1.5 MB |     0.2 MB |     1.7 MB |
| wp_users    |     89 |    0.1 MB |    0.05 MB |    0.15 MB |
+-------------+--------+-----------+------------+------------+

Notice how the numeric values now line up vertically, making it much easier to compare sizes at a glance!

Usage

$table = new cli\Table();
$table->setHeaders(['Name', 'Size']);
$table->setAlignments([
    'Name' => cli\table\Column::ALIGN_LEFT,
    'Size' => cli\table\Column::ALIGN_RIGHT,
]);
$table->addRow(['wp_posts', '46792704 B']);
$table->display();

Implementation Details

New Files:

• lib/cli/table/Column.php - Interface defining alignment constants
• examples/table-alignment.php - Comprehensive usage examples

Modified Files:

• lib/cli/table/Renderer.php - Base class support for alignments and headers
• lib/cli/table/Ascii.php - Applies alignment when padding columns
• lib/cli/Table.php - Table class with alignment support
• tests/Test_Table.php - Comprehensive test coverage

Alignment Constants:

• Column::ALIGN_LEFT (default) - Left-align text
• Column::ALIGN_RIGHT - Right-align (perfect for numbers)
• Column::ALIGN_CENTER - Center-align text

PR #171 Feedback Addressed

This implementation addresses all feedback from PR #171:

1. ✅ Headers passed explicitly to renderer (#171 comment)

   • Headers are now passed via setHeaders() method instead of being inferred from the first row
   • Prevents issues with renderer reuse and ensures reliable column mapping

2. ✅ Validation allows setting alignments before headers (#171 comment)

   • Column name validation only occurs when headers are already set
   • Allows flexible initialization order

3. ✅ Code quality improvements

   • Extracted getColumnAlignment() method for better readability
   • Optimized validation with array_flip() for O(1) lookups
   • Cached valid alignments map to avoid redundant array creation

Backward Compatibility

• ✅ Fully backward compatible - defaults to left alignment
• ✅ All existing tests pass without modification (86 tests, 463 assertions)
• ✅ New parameters are optional

Testing

• ✅ All tests pass (phpunit, phpcs, phpstan, lint)
• ✅ Comprehensive test coverage:
  • Default left alignment
  • Right alignment
  • Center alignment
  • Mixed alignments
  • Invalid alignment values
  • Invalid column names
  • Setting alignments before headers

Use Cases

This feature enables:

• Database statistics - Right-align file sizes, row counts for easy comparison
• Financial reports - Right-align prices, totals, quantities
• Status displays - Center-align status indicators
• Mixed data - Different alignment per column based on data type

Example Output

See examples/table-alignment.php for a complete demonstration with multiple real-world examples.

---

Closes wp-cli/db-command#239
Based on PR #171 by @rolf-yoast

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Is it possible to enhance table format with right-align numeric values easily?</issue_title>
<issue_description>because the length is already calculated / formatted correctly but is very unhandy to check/read while numbers are left-aligned like here:

root@test-server ~ # sudo -u www-data -s -- wp db size --path=/path/to/wordpress/staging/current --tables
+-----------------------+--------------+
| Name                  | Size         |
+-----------------------+--------------+
| wp_commentmeta        | 49152 B      |
| wp_comments           | 98304 B      |
| wp_links              | 32768 B      |
| wp_options            | 4751360 B    |
| wp_postmeta           | 2267021312 B |
| wp_posts              | 46792704 B   |
| wp_term_relationships | 3178496 B    |
| wp_term_taxonomy      | 507904 B     |
| wp_termmeta           | 950272 B     |
| wp_terms              | 573440 B     |
| wp_usermeta           | 425984 B     |
| wp_users              | 65536 B      |
+-----------------------+--------------+

As far I can see the table output is triggered in
https://github.com/wp-cli/db-command/blob/master/src/DB_Command.php#L875-L876

and uses Formatter object/functions (without orderby / include_totals) of this module:
https://github.com/wp-cli/profile-command/blob/master/inc/class-formatter.php#L77

(but not sure - normally using no PHP as system administrator 😄) </issue_description>

<agent_instructions>You may be able to use #171 as a starting point.

Apply changes based on this feedback and this feedback</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@swissspidy Looking at https://github.com//issues/121 and https://github.com//pull/120, it seems like it should be possible. Just a matter of making this available for this command (and others) via `wp-cli/wp-cli`.

• See Is it possible to enhance table format with right-align numeric values easily? db-command#239
• Supersedes Add alignment functionality to tables #171

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[codecov]

Codecov Report

❌ Patch coverage is 93.10345% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
lib/cli/Table.php	87.50%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!