476 lines
19 KiB
Markdown
476 lines
19 KiB
Markdown
# Complete Image Generation Process Audit
|
|
|
|
## Summary
|
|
|
|
This document provides a comprehensive audit of the current image generation process in the Igny8 AI SEO plugin. The system has been reorganized with image generation functions moved to a dedicated module and improved queue processing.
|
|
|
|
### Files Involved
|
|
- **`ai/writer/images/image-generation.php`** - Main image generation functions (featured & article images)
|
|
- **`core/admin/ajax.php`** - AJAX handlers for image generation requests
|
|
- **`assets/js/image-queue-processor.js`** - JavaScript queue processing and UI
|
|
- **`ai/modules-ai.php`** - Content generation response handler (saves image prompts)
|
|
- **`ai/openai-api.php`** - OpenAI DALL-E API integration
|
|
- **`ai/runware-api.php`** - Runware API integration
|
|
|
|
### Functions and Purposes
|
|
- **`igny8_generate_featured_image_for_post()`** - Generates featured images using AI prompts
|
|
- **`igny8_generate_single_article_image()`** - Generates in-article images for specific sections
|
|
- **`igny8_ajax_ai_generate_single_image()`** - AJAX handler for single image generation
|
|
- **`igny8_add_inarticle_image_meta()`** - Saves image metadata to post meta
|
|
- **`igny8_format_image_prompts_for_ai()`** - Formats image prompts for AI content generation
|
|
- **`igny8_create_post_from_ai_response()`** - Saves image prompts from AI response
|
|
|
|
## Overview
|
|
This document provides a comprehensive audit of the image generation process in the Igny8 AI SEO plugin, covering every function, hook, setting, and data flow from button click to final image save.
|
|
|
|
## 1. Entry Point - Generate Images Button
|
|
|
|
### Location
|
|
- **File**: `modules/components/actions-tpl.php`
|
|
- **Lines**: 42-45
|
|
- **Button ID**: `writer_drafts_generate_images_btn`
|
|
- **HTML**:
|
|
```html
|
|
<button id="writer_drafts_generate_images_btn" class="igny8-btn igny8-btn-accent" disabled>
|
|
<span class="dashicons dashicons-format-image"></span> Generate Images
|
|
</button>
|
|
```
|
|
|
|
### JavaScript Event Handler
|
|
- **File**: `assets/js/image-queue-processor.js`
|
|
- **Function**: `processAIImageGenerationDrafts(postIds)`
|
|
- **Lines**: 7-84
|
|
- **Validation**: Max 10 posts, requires selection
|
|
|
|
## 2. JavaScript Processing Flow
|
|
|
|
### Main Processing Function
|
|
- **File**: `assets/js/image-queue-processor.js`
|
|
- **Function**: `processAIImageGenerationDrafts(postIds)`
|
|
- **Lines**: 7-84
|
|
|
|
### Settings Retrieved
|
|
```javascript
|
|
const desktopEnabled = window.IGNY8_PAGE?.imageSettings?.desktop_enabled || false;
|
|
const mobileEnabled = window.IGNY8_PAGE?.imageSettings?.mobile_enabled || false;
|
|
const maxInArticleImages = window.IGNY8_PAGE?.imageSettings?.max_in_article_images || 1;
|
|
```
|
|
|
|
### Image Calculation
|
|
- **Featured Images**: Always 1 per post
|
|
- **Desktop Images**: `maxInArticleImages` per post (if enabled)
|
|
- **Mobile Images**: `maxInArticleImages` per post (if enabled)
|
|
- **Total**: `postIds.length * imagesPerPost`
|
|
|
|
### Queue Processing
|
|
- **Sequential Processing**: One image at a time to avoid API limits
|
|
- **Progress Tracking**: Real-time progress updates with individual progress bars
|
|
- **Error Handling**: Continue processing on individual failures
|
|
- **Modal Display**: Shows progress for each image being generated
|
|
|
|
## 3. AJAX Handlers
|
|
|
|
### Primary Handler
|
|
- **File**: `core/admin/ajax.php`
|
|
- **Function**: `igny8_ajax_ai_generate_images_drafts()`
|
|
- **Lines**: 2913-3150
|
|
- **Hook**: `wp_ajax_igny8_ai_generate_images_drafts`
|
|
|
|
### Single Image Handler
|
|
- **File**: `core/admin/ajax.php`
|
|
- **Function**: `igny8_ajax_ai_generate_single_image()`
|
|
- **Lines**: 3283-3350
|
|
- **Hook**: `wp_ajax_igny8_ai_generate_single_image`
|
|
- **Process**:
|
|
1. Validates task ID and retrieves WordPress post ID
|
|
2. Calls appropriate generation function based on type
|
|
3. Saves image metadata to post meta
|
|
4. Returns success/error response
|
|
|
|
### Supporting Handlers
|
|
- **Image Counts**: `igny8_ajax_get_image_counts()` (Lines 2645-2809)
|
|
- **Single Image Queue**: `igny8_ajax_generate_single_image_queue()` (Lines 2814-2908)
|
|
- **Settings Save**: `igny8_ajax_save_image_settings()` (Lines 4408-4457)
|
|
- **Template Save**: `igny8_ajax_save_image_prompt_template()` (Lines 4461-4505)
|
|
|
|
## 4. Settings and Configuration
|
|
|
|
### WordPress Options
|
|
| **Option** | **Default** | **Purpose** |
|
|
|------------|-------------|-------------|
|
|
| `igny8_desktop_enabled` | `'1'` | Enable desktop image generation |
|
|
| `igny8_mobile_enabled` | `'0'` | Enable mobile image generation |
|
|
| `igny8_max_in_article_images` | `1` | Maximum in-article images per post |
|
|
| `igny8_image_type` | `'realistic'` | Image style type |
|
|
| `igny8_image_provider` | `'runware'` | AI provider for image generation |
|
|
| `igny8_image_format` | `'jpg'` | Output image format |
|
|
| `igny8_negative_prompt` | `'text, watermark, logo, overlay, title, caption, writing on walls, writing on objects, UI, infographic elements, post title'` | Negative prompt for image generation |
|
|
| `igny8_image_prompt_template` | `'Create a high-quality {image_type} image to use as a featured photo for a blog post titled "{post_title}". The image should visually represent the theme, mood, and subject implied by the image prompt: {image_prompt}. Focus on a realistic, well-composed scene that naturally communicates the topic without text or logos. Use balanced lighting, pleasing composition, and photographic detail suitable for lifestyle or editorial web content. Avoid adding any visible or readable text, brand names, or illustrative effects. **And make sure image is not blurry.**'` | Image prompt template |
|
|
|
|
### Settings Page
|
|
- **File**: `modules/settings/general-settings.php`
|
|
- **Lines**: 309-462
|
|
- **Form Fields**: Desktop/Mobile toggles, Max images dropdown, Image type, Provider, Format, Negative prompt, Template
|
|
|
|
## 5. Image Generation Functions
|
|
|
|
### Core Generation Functions
|
|
- **File**: `ai/writer/images/image-generation.php`
|
|
|
|
#### Featured Image Generation
|
|
- **Function**: `igny8_generate_featured_image_for_post($post_id, $image_size_type = 'featured')`
|
|
- **Lines**: 24-200
|
|
- **Process**:
|
|
1. Get featured image prompt from `_igny8_featured_image_prompt`
|
|
2. Get image generation settings from WordPress options
|
|
3. Build final prompt using template with placeholders
|
|
4. Call AI provider (Runware/OpenAI) with appropriate dimensions
|
|
5. Download image from AI provider URL
|
|
6. Upload via `media_handle_sideload()`
|
|
7. Set as featured image with `set_post_thumbnail()`
|
|
8. Generate attachment metadata
|
|
|
|
#### In-Article Image Generation
|
|
- **Function**: `igny8_generate_single_article_image($post_id, $device_type = 'desktop', $index = 1)`
|
|
- **Lines**: 202-400
|
|
- **Process**:
|
|
1. Get article image prompts from `_igny8_article_images_data`
|
|
2. Extract prompt for specific index (`prompt-img-1`, `prompt-img-2`, etc.)
|
|
3. Get image generation settings from WordPress options
|
|
4. Build final prompt using template with placeholders
|
|
5. Call AI provider with device-specific dimensions
|
|
6. Download image from AI provider URL
|
|
7. Upload via `media_handle_sideload()`
|
|
8. Return attachment ID and metadata
|
|
|
|
### Supporting Functions
|
|
- **Image Dimensions**: `igny8_get_image_dimensions($size_preset, $provider)` (Lines 1526-1558 in ai/modules-ai.php)
|
|
- **Safe Quantity**: `igny8_calculate_safe_image_quantity($idea_data, $max_in_article_images)` (Lines 918-933 in ai/modules-ai.php)
|
|
- **Image Meta**: `igny8_add_inarticle_image_meta($post_id, $attachment_id, $label, $device, $section)` (Lines 933-963 in ai/modules-ai.php)
|
|
|
|
## 6. AI Provider Integration
|
|
|
|
### Runware API Integration
|
|
- **File**: `ai/runware-api.php`
|
|
- **Function**: `igny8_runway_generate_image($prompt, $negative_prompt, $width, $height, $steps, $cfg_scale, $number_results, $output_format)`
|
|
- **API Endpoint**: `https://api.runware.ai/v1`
|
|
- **Authentication**: API key via `igny8_runware_api_key` option
|
|
- **Model**: `runware:97@1` (HiDream-I1 Full)
|
|
- **Request Format**:
|
|
```json
|
|
[
|
|
{
|
|
"taskType": "authentication",
|
|
"apiKey": "api_key_here"
|
|
},
|
|
{
|
|
"taskType": "imageInference",
|
|
"taskUUID": "uuid_here",
|
|
"positivePrompt": "prompt_text",
|
|
"negativePrompt": "negative_prompt",
|
|
"model": "runware:97@1",
|
|
"width": 1024,
|
|
"height": 1024,
|
|
"steps": 30,
|
|
"CFGScale": 7.5,
|
|
"numberResults": 1,
|
|
"outputFormat": "jpg"
|
|
}
|
|
]
|
|
```
|
|
- **Response Handling**: Extract `data[0].imageURL` from response
|
|
- **Error Handling**: Log API errors, return error messages
|
|
|
|
### OpenAI DALL-E Integration
|
|
- **File**: `ai/openai-api.php`
|
|
- **Function**: `igny8_call_openai_images($prompt, $api_key, $model, $size, $quality, $style)`
|
|
- **API Endpoint**: `https://api.openai.com/v1/images/generations`
|
|
- **Authentication**: API key via `igny8_api_key` option
|
|
- **Model**: `dall-e-3`
|
|
- **Request Format**:
|
|
```json
|
|
{
|
|
"model": "dall-e-3",
|
|
"prompt": "prompt_text",
|
|
"n": 1,
|
|
"size": "1024x1024",
|
|
"quality": "standard",
|
|
"style": "natural"
|
|
}
|
|
```
|
|
- **Response Handling**: Extract `data[0].url` from response
|
|
- **Error Handling**: Log API errors, return error messages
|
|
|
|
### Provider Detection and Selection
|
|
- **Settings**: `igny8_image_provider` option (`runware` or `openai`)
|
|
- **API Key Validation**: Check `igny8_runware_api_key` or `igny8_api_key`
|
|
- **Dynamic Selection**: Based on user settings in prompts page
|
|
- **Fallback Handling**: Return error if required API key not configured
|
|
|
|
### Image Dimensions by Provider
|
|
- **Runware Dimensions**:
|
|
- Featured: 1280x832
|
|
- Desktop: 1024x1024
|
|
- Mobile: 960x1280
|
|
- **OpenAI Dimensions**:
|
|
- Featured: 1024x1024
|
|
- Desktop: 1024x1024
|
|
- Mobile: 1024x1024
|
|
|
|
## 7. Data Storage and Meta Keys
|
|
|
|
### Post Meta Keys
|
|
| **Meta Key** | **Purpose** | **Data Type** |
|
|
|--------------|-------------|---------------|
|
|
| `_igny8_featured_image_prompt` | Featured image AI prompt | Text |
|
|
| `_igny8_article_images_data` | In-article image prompts | JSON Array |
|
|
| `_igny8_inarticle_images` | Generated image metadata | JSON Object |
|
|
|
|
### Image Prompts Data Structure
|
|
```json
|
|
[
|
|
{
|
|
"prompt-img-1": "A close-up of a neatly made bed showcasing a well-fitted duvet cover that enhances the aesthetic of the room."
|
|
},
|
|
{
|
|
"prompt-img-2": "An image of tools laid out for measuring a duvet insert, including a measuring tape, notepad, and a flat surface."
|
|
},
|
|
{
|
|
"prompt-img-3": "A detailed size chart displaying different duvet cover sizes alongside their corresponding duvet insert dimensions."
|
|
},
|
|
{
|
|
"prompt-img-4": "An infographic illustrating common mistakes when choosing duvet covers, highlighting shrinkage risks and misreading labels."
|
|
}
|
|
]
|
|
```
|
|
|
|
### Image Metadata Structure
|
|
```json
|
|
{
|
|
"desktop-1": {
|
|
"label": "desktop-1",
|
|
"attachment_id": 1825,
|
|
"url": "https://example.com/image.jpg",
|
|
"device": "desktop",
|
|
"section": 1
|
|
},
|
|
"mobile-1": {
|
|
"label": "mobile-1",
|
|
"attachment_id": 1826,
|
|
"url": "https://example.com/image2.jpg",
|
|
"device": "mobile",
|
|
"section": 1
|
|
}
|
|
}
|
|
```
|
|
|
|
## 8. Image Processing Workflow
|
|
|
|
### Step-by-Step Process
|
|
1. **Button Click**: User selects posts and clicks "Generate Images"
|
|
2. **Validation**: Check selection count (max 10), get settings
|
|
3. **Queue Building**: Build image queue with featured and in-article images
|
|
4. **Progress Modal**: Show progress with individual progress bars
|
|
5. **Sequential Processing**: Process each image individually
|
|
6. **Image Generation**: For each image:
|
|
- Get prompt from appropriate meta field
|
|
- Call AI provider with settings
|
|
- Download image from provider URL
|
|
- Upload to WordPress Media Library
|
|
- Save metadata to post meta
|
|
7. **Progress Updates**: Update UI with success/failure status
|
|
8. **Completion**: Show final results
|
|
|
|
### Error Handling
|
|
- **Download Failures**: Log errors, continue with next image
|
|
- **Upload Failures**: Log errors, return failure status
|
|
- **API Failures**: Log errors, return failure status
|
|
- **Progress Tracking**: Update modal with success/failure counts
|
|
- **JSON Parsing**: Handle HTML content in prompts with `wp_strip_all_tags()`
|
|
|
|
## 9. Content Generation Integration
|
|
|
|
### Image Prompts in Content Generation
|
|
- **File**: `ai/modules-ai.php`
|
|
- **Function**: `igny8_create_post_from_ai_response($ai_response)`
|
|
- **Lines**: 1119-1462
|
|
- **Process**:
|
|
1. AI generates content with image prompts
|
|
2. Featured image prompt saved to `_igny8_featured_image_prompt`
|
|
3. In-article image prompts saved to `_igny8_article_images_data`
|
|
4. HTML tags stripped from prompts using `wp_strip_all_tags()`
|
|
5. JSON structure validated and saved
|
|
|
|
### Prompt Template Processing
|
|
- **Template**: Uses `{image_type}`, `{post_title}`, `{image_prompt}` placeholders
|
|
- **Replacement**: Dynamic replacement with actual values
|
|
- **Settings Integration**: Uses all settings from prompts page
|
|
|
|
## 10. Image Generation Queue Mechanism
|
|
|
|
### Queue Processing
|
|
- **File**: `assets/js/image-queue-processor.js`
|
|
- **Function**: `processAIImageGenerationDrafts(postIds)`
|
|
- **Lines**: 7-84
|
|
- **Process**: Sequential image generation with progress tracking
|
|
|
|
### Queue Features
|
|
- **Sequential Processing**: One image at a time to avoid API limits
|
|
- **Progress Tracking**: Real-time progress updates with individual bars
|
|
- **Error Handling**: Continue processing on individual failures
|
|
- **Batch Management**: Handle multiple posts with image counts
|
|
- **Modal Display**: Shows detailed progress for each image
|
|
|
|
### Queue Handler
|
|
- **File**: `core/admin/ajax.php`
|
|
- **Function**: `igny8_ajax_ai_generate_single_image()`
|
|
- **Lines**: 3283-3350
|
|
- **Hook**: `wp_ajax_igny8_ai_generate_single_image`
|
|
|
|
## 11. Debug and Logging
|
|
|
|
### Debug Functions
|
|
- **File**: `debug/module-debug.php`
|
|
- **Lines**: 1185-1221 (HTML), 1447-1613 (JavaScript)
|
|
- **Features**:
|
|
- Image generation logs interface
|
|
- Refresh/clear buttons (`refresh-image-gen`, `clear-image-gen`)
|
|
- Real-time event display (`image-gen-events`)
|
|
- Status messages (`image-gen-message`, `image-gen-details`)
|
|
- Global debug function (`window.addImageGenDebugLog`)
|
|
|
|
### Comprehensive Logging System
|
|
- **Event-Based Logging**: `IMAGE_GEN_EVENT_1` through `IMAGE_GEN_EVENT_9`
|
|
- **Debug Events Array**: `$debug_events[]` for detailed tracking
|
|
- **Error Logging**: `error_log()` with specific prefixes
|
|
- **AI Event Logging**: `igny8_log_ai_event()` for AI interactions
|
|
|
|
### Logging Points
|
|
- **AJAX Entry**: `error_log('Igny8: AJAX HANDLER CALLED - igny8_ajax_ai_generate_images_drafts')`
|
|
- **Task Validation**: `error_log('Igny8: IMAGE_GEN_EVENT_3 - Task IDs validated')`
|
|
- **Post Retrieval**: `error_log('Igny8: IMAGE_GEN_EVENT_4 - WordPress post IDs retrieved')`
|
|
- **Image Prompts**: `error_log('Igny8: IMAGE_GEN_EVENT_5 - Image prompts loaded')`
|
|
- **Featured Generation**: `error_log('Igny8: IMAGE_GEN_EVENT_6 - Featured image generation initiated')`
|
|
- **API Requests**: `error_log('Igny8: IMAGE_GEN_EVENT_7 - API request sent')`
|
|
- **Image URLs**: `error_log('Igny8: IMAGE_GEN_EVENT_8 - Image URL received')`
|
|
- **WordPress Save**: `error_log('Igny8: IMAGE_GEN_EVENT_9 - Saving image to WordPress')`
|
|
- **Success/Failure**: `error_log('Igny8: IMAGE_GEN_EVENT_9_SUCCESS/ERROR')`
|
|
|
|
## 12. File Dependencies
|
|
|
|
### Core Files
|
|
- `ai/writer/images/image-generation.php` - Main image generation functions
|
|
- `core/admin/ajax.php` - AJAX handlers
|
|
- `assets/js/image-queue-processor.js` - Queue processing JavaScript
|
|
- `ai/modules-ai.php` - Content generation response handler
|
|
- `ai/openai-api.php` - OpenAI DALL-E API integration
|
|
- `ai/runware-api.php` - Runware API integration
|
|
|
|
### Settings Files
|
|
- `modules/settings/general-settings.php` - Main image generation settings page
|
|
- `modules/thinker/prompts.php` - Image prompt templates only
|
|
- `modules/thinker/image-testing.php` - Image testing interface
|
|
- `modules/modules-pages/writer.php` - Settings localization
|
|
|
|
### Debug Files
|
|
- `debug/module-debug.php` - Debug interface
|
|
|
|
## 13. Hooks and Actions
|
|
|
|
### WordPress Hooks
|
|
- `wp_ajax_igny8_ai_generate_images_drafts` - Main generation handler
|
|
- `wp_ajax_igny8_ai_generate_single_image` - Single image handler
|
|
- `wp_ajax_igny8_generate_single_image_queue` - Queue handler
|
|
- `wp_ajax_igny8_get_image_counts` - Image count preview
|
|
- `wp_ajax_igny8_save_image_settings` - Settings save
|
|
- `wp_ajax_igny8_save_image_prompt_template` - Template save
|
|
- `wp_ajax_igny8_reset_image_prompt_template` - Template reset
|
|
|
|
### Internal Hooks
|
|
- `transition_post_status` - Post status changes
|
|
- `save_post` - Post save events
|
|
|
|
## 14. Security Considerations
|
|
|
|
### Nonce Verification
|
|
- All AJAX handlers verify nonces
|
|
- Settings forms use proper nonce fields
|
|
- User capability checks for admin functions
|
|
|
|
### Data Sanitization
|
|
- All input data sanitized with `sanitize_text_field()`
|
|
- File uploads handled via WordPress functions
|
|
- Image URLs validated before processing
|
|
- HTML tags stripped from prompts using `wp_strip_all_tags()`
|
|
|
|
## 15. Performance Considerations
|
|
|
|
### Sequential Processing
|
|
- Images generated one at a time to avoid API limits
|
|
- Progress tracking for user feedback
|
|
- Error handling to continue processing
|
|
|
|
### Media Library Integration
|
|
- Proper WordPress Media Library registration
|
|
- Automatic thumbnail generation
|
|
- Metadata attachment for SEO
|
|
|
|
## 16. Complete Function Reference
|
|
|
|
### AJAX Handlers
|
|
- `igny8_ajax_ai_generate_images_drafts()` - Main generation
|
|
- `igny8_ajax_ai_generate_single_image()` - Single image
|
|
- `igny8_ajax_generate_single_image_queue()` - Queue processing
|
|
- `igny8_ajax_get_image_counts()` - Count preview
|
|
- `igny8_ajax_save_image_settings()` - Settings save
|
|
- `igny8_ajax_save_image_prompt_template()` - Template save
|
|
- `igny8_ajax_reset_image_prompt_template()` - Template reset
|
|
|
|
### Generation Functions
|
|
- `igny8_generate_featured_image_for_post()` - Featured image
|
|
- `igny8_generate_single_article_image()` - In-article image
|
|
- `igny8_get_image_dimensions()` - Size calculation
|
|
- `igny8_calculate_safe_image_quantity()` - Quantity safety
|
|
|
|
### Content Functions
|
|
- `igny8_add_inarticle_image_meta()` - Image metadata saving
|
|
- `igny8_format_image_prompts_for_ai()` - Prompt formatting
|
|
- `igny8_create_post_from_ai_response()` - Content generation response handler
|
|
|
|
### Queue Processing Functions
|
|
- `processAIImageGenerationDrafts()` - Main queue processor
|
|
- `generateAllImagesForPost()` - Single post processing
|
|
- `updateProgressModal()` - Progress updates
|
|
|
|
### API Functions
|
|
- `igny8_runway_generate_image()` - Runware API integration
|
|
- `igny8_call_openai_images()` - OpenAI DALL-E API integration
|
|
|
|
### Settings Functions
|
|
- `igny8_ajax_save_image_settings()` - Settings save
|
|
- `igny8_ajax_save_image_prompt_template()` - Template save
|
|
- `igny8_ajax_reset_image_prompt_template()` - Template reset
|
|
|
|
## 17. Recent Changes and Improvements
|
|
|
|
### Code Reorganization
|
|
- **Image generation functions moved** from `ai/modules-ai.php` to `ai/writer/images/image-generation.php`
|
|
- **Dedicated module** for image generation functionality
|
|
- **Improved separation of concerns** between content generation and image generation
|
|
|
|
### Enhanced Error Handling
|
|
- **JSON parsing improvements** with HTML tag stripping
|
|
- **Better error messages** for debugging
|
|
- **Graceful fallbacks** for API failures
|
|
|
|
### Improved Queue Processing
|
|
- **Individual progress bars** for each image
|
|
- **Better error tracking** and reporting
|
|
- **Enhanced user feedback** during processing
|
|
|
|
### Settings Integration
|
|
- **Dynamic settings** from prompts page
|
|
- **Template-based prompts** with placeholder replacement
|
|
- **Provider selection** with appropriate API key validation
|
|
|
|
This audit covers every aspect of the current image generation process from initial button click to final image storage and metadata saving, including the complete queue mechanism, settings integration, and content generation workflow. |