imagify / docs / api / wp-cli.md

wp-cli.md in Imagify Image Optimization: Optimize Images | Compress & Convert to WebP/AVIF 2.2.9, at docs/api/wp-cli.md

159 lines 5.2 KB

Raw Download Zip

1	# WP-CLI Commands
2
3	Imagify registers WP-CLI subcommands under the `imagify` root command.
4	All commands are registered in `classes/Plugin.php` via `imagify_add_command()`.
5
6	---
7
8	## `wp imagify bulk-optimize <contexts...>`
9
10	Enqueues asynchronous ActionScheduler jobs to optimize all unoptimized images
11	for one or more bulk contexts.
12
13	Class: `Imagify\CLI\BulkOptimizeCommand`
14
15	### Arguments
16
17	\| Name \| Required \| Repeating \| Description \|
18	\|---\|---\|---\|---\|
19	\| `contexts` \| yes \| yes \| One or more contexts to run. Valid values: `wp`, `custom-folders`. \|
20
21	### Options
22
23	\| Option \| Default \| Description \|
24	\|---\|---\|---\|
25	\| `--optimization-level` \| account default \| `0` (normal), `1` (aggressive), `2` (ultra). \|
26
27	### Behaviour
28
29	Delegates to `Imagify\Bulk\Bulk::run_optimize()`, which calls
30	`get_unoptimized_media_ids()` on the matching `AbstractBulk` subclass and
31	enqueues one `imagify_optimize_media` ActionScheduler action per ID.
32
33	A warning is emitted via `WP_CLI::warning()` if a context has no images to optimize.
34
35	---
36
37	## `wp imagify restore [<contexts>...]`
38
39	Synchronously restores all optimized images back to their original files
40	for one or more bulk contexts.
41
42	Class: `Imagify\CLI\RestoreCommand`
43
44	Since: 2.3 (issue #922)
45
46	### Arguments
47
48	\| Name \| Required \| Repeating \| Description \|
49	\|---\|---\|---\|---\|
50	\| `contexts` \| no \| yes \| One or more contexts to restore. Valid values: `library`, `custom-folders`. Defaults to both if omitted. \|
51
52	`library` is an alias for the WordPress media library (`wp` context).
53
54	### Examples
55
56	```bash
57	# Restore all optimized images (library + custom folders).
58	wp imagify restore
59
60	# Restore only the WordPress media library.
61	wp imagify restore library
62
63	# Restore only custom folders.
64	wp imagify restore custom-folders
65
66	# Restore both contexts explicitly.
67	wp imagify restore library custom-folders
68	```
69
70	### Behaviour
71
72	1. For each context, calls `Imagify\Bulk\Bulk::run_restore( $context )`.
73	2. `run_restore()` calls `get_optimized_media_ids()` on the matching `AbstractBulk`
74	subclass. Only images that have a backup file on disk are included.
75	3. For each eligible image, calls `imagify_get_optimization_process( $media_id, $context )->restore()` synchronously (no ActionScheduler queue).
76	4. Prints per-context counts (restored / errors / total) and a final success or warning message.
77
78	A `WP_CLI::warning()` is emitted if:
79	- A context has no eligible images.
80	- The overall restore completed but some images failed.
81
82	`WP_CLI::success()` is emitted only when all processed images were restored without errors.
83
84	### Return structure from `Bulk::run_restore()`
85
86	\| Key \| Type \| Description \|
87	\|---\|---\|---\|
88	\| `success` \| bool \| `false` if no eligible images were found; `true` otherwise. \|
89	\| `message` \| string \| `no-images` or `success`. \|
90	\| `restored` \| int \| Number of images successfully restored. \|
91	\| `errors` \| int \| Number of images that failed to restore. \|
92	\| `total` \| int \| Total number of images processed. \|
93
94	---
95
96	## `wp imagify generate-missing-nextgen <contexts...>`
97
98	Synchronously generates missing next-gen image versions (WebP, AVIF, etc.) for
99	all images that do not yet have them, for one or more bulk contexts.
100
101	Class: `Imagify\CLI\GenerateMissingNextgenCommand`
102
103	### Arguments
104
105	\| Name \| Required \| Repeating \| Description \|
106	\|---\|---\|---\|---\|
107	\| `contexts` \| yes \| yes \| One or more contexts to run. Valid values: `wp`, `custom-folders`. \|
108
109	### Examples
110
111	```bash
112	# Generate missing next-gen images for the WordPress media library.
113	wp imagify generate-missing-nextgen wp
114
115	# Generate missing next-gen images for both contexts.
116	wp imagify generate-missing-nextgen wp custom-folders
117	```
118
119	### Behaviour
120
121	1. Calls `Imagify\Bulk\Bulk::run_generate_nextgen( $contexts, $formats )`.
122	2. `$formats` is resolved at runtime via `imagify_nextgen_images_formats()`, which
123	reads the `optimization_format` plugin option and applies the
124	`imagify_nextgen_images_formats` filter.
125	3. If no formats are configured (option set to `off`) the method returns `no-images`
126	without processing any files.
127
128	A one-line log message is emitted via `WP_CLI::log()` after the operation completes.
129
130	---
131
132	## Context resolution
133
134	Both bulk commands resolve the concrete `AbstractBulk` subclass through the
135	`imagify_bulk_class_name` filter (applied via `wpm_apply_filters_typed()`).
136	The default mapping is:
137
138	\| Context \| Class \|
139	\|---\|---\|
140	\| `wp` \| `Imagify\Bulk\WP` \|
141	\| `custom-folders` \| `Imagify\Bulk\CustomFolders` \|
142
143	---
144
145	## `get_optimized_media_ids()` — context implementations
146
147	`BulkInterface::get_optimized_media_ids(): array` returns a flat list of media IDs
148	(integers) that are eligible for restoration:
149
150	- `Imagify\Bulk\WP` — queries `wp_posts` INNER JOIN `wp_postmeta` for
151	attachments with `_imagify_status` IN `('success', 'already_optimized')`, then
152	filters to only those with an existing backup file (`get_imagify_attachment_backup_path()`).
153	- `Imagify\Bulk\CustomFolders` — queries `imagify_files` INNER JOIN
154	`imagify_folders` for files with `status IN ('success', 'already_optimized')`,
155	then filters to only those with an existing backup file
156	(`Imagify_Custom_Folders::get_file_backup_path()`).
157	- `Imagify\Bulk\Noop` and `Imagify\ThirdParty\NGG\Bulk\NGG` — return `[]`
158	(restore is not supported for these contexts).
159