Add WP-CLI command for bulk alt text generation#436
Add WP-CLI command for bulk alt text generation#436adamsilverstein wants to merge 6 commits intoWordPress:developfrom
Conversation
Introduce `wp ai alt-text generate` to backfill alt text for existing media library images using the ai/alt-text-generation ability. Supports --batch-size, --dry-run, --force, --ids, and --delay flags. Processes images server-side in batches with progress reporting and memory management. Closes WordPress#435
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## develop #436 +/- ##
=============================================
+ Coverage 67.72% 68.56% +0.83%
- Complexity 959 994 +35
=============================================
Files 60 61 +1
Lines 4836 5000 +164
=============================================
+ Hits 3275 3428 +153
- Misses 1561 1572 +11
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Add php-stubs/wp-cli-stubs for PHPStan to recognize WP-CLI classes. Add cli\progress\Bar ignore pattern since the WP-CLI progress bar internals are not in the stubs package. Fix type annotations and add unreachable returns after WP_CLI::error() for static analysis. Add 10 integration tests covering: admin user setup, attachment ID querying (with/without alt text, force flag, specific IDs, invalid IDs), memory cleanup, summary output, and dry-run display.
Add WP-CLI stubs that allow testing the CLI command without requiring a full WP-CLI install. This raises patch coverage above the codecov threshold and exercises the main process_images() and generate() paths. New tests cover: - process_images generates and saves alt text - process_images handles decorative images - process_images skips existing alt text without --force - process_images force flag overwrites existing alt text - process_images handles WP_Error responses from the ability - print_summary with zero results path - ensure_admin_user error when no admin exists - generate errors when ability is not registered
Cover the main entry point paths not previously tested:
- generate() with no matching images (early return)
- generate() errors without AI credentials
- generate() processes attachments end-to-end
- generate() --dry-run does not modify alt text
Register a real fake ability via wp_register_ability() using the WP
core test pattern of faking $wp_current_filter to satisfy
doing_action('wp_abilities_api_init') without triggering re-entrant
init calls from the registry singleton.
…xt-generate # Conflicts: # composer.lock # phpstan.neon.dist
dkotter
left a comment
dkotter
left a comment
There was a problem hiding this comment.
Left a few comments, open to discussion on those. Also looks like PHPStan is failing so that needs looked at
| } | ||
|
|
||
| if ( ! has_valid_ai_credentials() ) { | ||
| WP_CLI::error( 'No valid AI credentials found. Configure a provider in Settings > AI.' ); |
There was a problem hiding this comment.
| WP_CLI::error( 'No valid AI credentials found. Configure a provider in Settings > AI.' ); | |
| WP_CLI::error( 'No valid AI credentials found. Configure a provider in Settings > Connectors.' ); |
| 'post_type' => 'attachment', | ||
| 'post_mime_type' => 'image', | ||
| 'post_status' => 'inherit', | ||
| 'posts_per_page' => -1, |
There was a problem hiding this comment.
Any concern here on sites with lots of attachments, thinking multiple thousands? Wonder if we should instead implement batch processing, where we only query for a set number at a time and then continue to iterate until we've processed them all?
There was a problem hiding this comment.
a batch capability makes sense, I'll add that!
| private function display_dry_run( array $attachment_ids ): void { | ||
| $items = array(); | ||
| foreach ( $attachment_ids as $id ) { | ||
| $alt = get_post_meta( $id, '_wp_attachment_image_alt', true ); |
There was a problem hiding this comment.
Seems we default to only getting images without alt text set unless the $force argument is passed. Should we be using that argument here so the results we show are accurate to what would actually be processed?
There was a problem hiding this comment.
right, good point!
| return; | ||
| } | ||
|
|
||
| WP_CLI::log( sprintf( 'Found %d image(s) to process.', count( $attachment_ids ) ) ); |
There was a problem hiding this comment.
I also wonder if we need some sort of "Are you sure?" protection here to prevent someone from accidentally running this to generate alt text on thousands of images (and thus rack up a nice API bill). You could argue that if someone has access to WP-CLI and they decide to run this, that's on them but also think it would be nice to use the confirm method to get user input first
There was a problem hiding this comment.
makes sense, maybe with a flag you can pass to skip that.
3 participants
Summary
wp ai alt-text generate— the plugin's first WP-CLI commandai/alt-text-generationability--batch-size,--dry-run,--force,--ids, and--delayflagsCloses #435
Test plan
wp ai alt-text generate --dry-runlists images missing alt text without making changeswp ai alt-text generate --batch-size=2processes images with progress bar, verify alt text saved in DBwp ai alt-text generate --ids=<id1>,<id2> --forceregenerates for specific images even if they already have alt text--delayflag adds visible pause between API callsAI use
I used Claude code to write this PR with a series of prompts. I tested the command manually and reviewed the code.