File manager - Edit - /home/vblioqus/unfreezetiktok.com/wp-content/plugins/kadence-blocks/includes/resources/Optimizer/README.md
Back
# Kadence Performance Optimizer A client-side analysis and server-side optimization system that improves Core Web Vitals (LCP, CLS, INP) by intelligently managing image loading, section rendering, and resource hints. ## Overview The Optimizer works in two phases: 1. **Analysis Phase** (client-side): When a user triggers optimization in wp-admin, JavaScript analyzes the page using `@stellarwp/perf-analyzer-client` to detect critical images, section heights, and optimal image sizes for both desktop and mobile viewports. 2. **Application Phase** (server-side): On subsequent requests, the stored analysis data is used to apply optimizations like proper lazy loading, `content-visibility` for below-the-fold sections, and optimal image `sizes` attributes. ## Architecture ``` Optimizer/ ├── Database/ # Custom tables (kb_optimizer, kb_optimizer_viewport_hash) ├── Store/ # Decorator-based storage layer ├── Hash/ # HTML hash comparison for invalidation ├── Image/ # Image processing pipeline ├── Lazy_Load/ # Element & background lazy loading ├── Skip_Rules/ # Conditions to bypass optimization ├── Rest/ # REST API endpoints ├── Response/ # DTOs (WebsiteAnalysis, DeviceAnalysis, ImageAnalysis, etc.) ├── Status/ # Post optimization status tracking ├── Post_List_Table/ # Admin column & bulk actions └── assets/js/ # Frontend analyzer scripts ``` ### Key Design Patterns - **Provider Pattern**: Each subdomain has a `Provider.php` that registers dependencies - **Decorator Pattern**: Store layer uses decorators for caching, expiration, exclusion, and status sync - **Strategy Pattern**: Image processors and skip rules are pluggable ## Enabling the Optimizer Users enable the optimizer through the **Kadence Blocks Controls** sidebar in the Gutenberg editor: 1. Open any post/page in the block editor 2. Click the Kadence "K" icon in the top toolbar to open **Kadence Blocks Controls** 3. Expand the **Performance Optimizer** panel 4. Toggle **"Globally Enable The Performance Optimizer"** This saves the `performance_optimizer_enabled` setting to `kadence_blocks_settings` option. ## Store Decorator Chain The `Store` interface is wrapped in decorators that execute top-to-bottom: ``` Expired_Store_Decorator ← Filters stale data (isStale = true) └─ Cached_Store_Decorator ← Request-level memoization └─ Excluded_Store_Decorator ← Blocks excluded posts └─ Status_Sync_Store_Decorator ← Syncs post meta status └─ Table_Store ← Database operations ``` This means: - Expired data is filtered even from cache - Excluded posts never receive optimization data - Post meta status stays in sync with database state ## REST API Endpoints Base: `/wp-json/kb-optimizer/v1/optimize` | Method | Endpoint | Description | |--------|----------|-------------| | POST | `/optimize` | Store analysis data for a post | | GET | `/optimize` | Retrieve analysis data | | DELETE | `/optimize` | Remove optimization for a post | | POST | `/optimize/posts-metadata` | Get metadata for bulk optimization | | DELETE | `/optimize/bulk/delete` | Bulk remove optimizations | All endpoints require `edit_post` capability for the target post(s). ## Skip Rules Optimization is bypassed when any skip rule returns `true`: | Rule | Condition | |------|-----------| | `Optimizer_Request_Rule` | Request has optimizer query params | | `Ignored_Query_Var_Rule` | Has preview or filtered query vars | | `Not_Found_Rule` | 404 response | | `Logged_In_Rule` | User is logged in | | `Post_Excluded_Rule` | Post marked as excluded | ### Adding Ignored Query Variables The `Ignored_Query_Var_Rule` skips optimization when specific query parameters are present. Add custom query vars to ignore: ```php add_filter( 'kadence_blocks_optimizer_rule_skip_query_vars', static fn( array $vars ): array => [ ...$vars, 'my_custom_preview', ]); ``` ## Image Processing The `Image_Processor` uses output buffering to modify `<img>` tags: 1. **Lazy_Load_Processor**: Removes `loading="lazy"` from critical (above-fold) images, adds it to below-fold images 2. **Sizes_Attribute_Processor**: Sets optimal `sizes` attribute based on actual rendered dimensions ### Filtering Image Processing ```php add_filter( 'kadence_blocks_optimizer_image_processor', static fn( bool $should, string $src ): bool => $should && ! str_contains( $src, 'logo.png' ), 10, 5 ); ``` ## Section Lazy Loading Below-the-fold Kadence Row and Column blocks receive `content-visibility: auto` with calculated `contain-intrinsic-size`: ```php // Exclude specific classes from section lazy loading. add_filter( 'kadence_blocks_optimizer_section_lazy_load_excluded_classes', static fn( array $classes ): array => [ ...$classes, 'my-parallax-section', ]); ``` **Note**: `kt-jarallax` is excluded by default since parallax sections need immediate rendering. ## Hash-Based Invalidation The system compares HTML hashes on each request to detect content changes: 1. After optimization, hashes are stored for desktop and mobile viewports 2. On subsequent requests, current HTML is hashed and compared 3. If hashes differ, analysis is marked `isStale = true` 4. Stale data is filtered by `Expired_Store_Decorator`, forcing re-optimization ### Triggering Hash Storage ``` ?kadence_set_optimizer_hash=1 # Desktop hash ?kadence_set_optimizer_hash=1&kadence_is_mobile=1 # Mobile hash ``` ## Post Status Values Status is stored in post meta (`_kb_optimizer_status`): | Value | Constant | Description | |-------|----------|-------------| | -1 | `EXCLUDED` | User excluded from optimization | | 0 | `NOT_OPTIMIZED` | No optimization data | | 1 | `OPTIMIZED` | Active optimization | | 2 | `STALE` | Outdated, pending re-optimization | ## Actions & Filters Reference ### Actions ```php // Fired after hash is stored. do_action( 'kadence_blocks_optimizer_set_hash', $hash, $path, $viewport ); // Fired when optimization data is invalidated. do_action( 'kadence_blocks_optimizer_data_invalidated', $is_stale, $path ); // Fired after hash check completes. do_action( 'kadence_blocks_hash_check_complete' ); ``` ### Filters ```php // Force enable/disable the entire Optimizer feature, overidding the user's setting. // Force enable. add_filter( 'kadence_blocks_optimizer_enabled', '__return_true' ); // Force disable. add_filter( 'kadence_blocks_optimizer_enabled', '__return_false' ); // Customize skip query vars/ add_filter( 'kadence_blocks_optimizer_rule_skip_query_vars', fn( array $vars ) => $vars ); // Exclude sections from lazy loading. add_filter( 'kadence_blocks_optimizer_section_lazy_load_excluded_classes', fn( array $classes ) => $classes ); // Control image processing per-image. add_filter( 'kadence_blocks_optimizer_image_processor', fn( bool $should, $src, $classes, $processor, $path ) => $should, 10, 5 ); ``` ## Debugging ### Enable Debug Logging Set `WP_DEBUG` to `true` in `wp-config.php` to enable comprehensive logging via PHP's `error_log()`: ```php define( 'WP_DEBUG', true ); ``` Logs are prefixed with `[Kadence Blocks]:` and written to your PHP error log (location depends on server configuration). ### Check if a page is optimized Look for the `kb-optimized` class on the `<body>` tag. ### View optimization data ```php $store = KadenceWP\KadenceBlocks\Container::get( \KadenceWP\KadenceBlocks\Optimizer\Store\Contracts\Store::class ); $path = new \KadenceWP\KadenceBlocks\Optimizer\Path\Path( '/my-page/', $post_id ); $analysis = $store->get( $path ); ``` ### Preview optimized view Add `?kadence_optimizer_preview=1` to any URL to see the optimized version regardless of skip rules (logged-in users, etc.). ## Common Issues ### Optimization not applying 1. Check skip rules - logged-in users are skipped by default 2. Verify post is published (drafts can't be optimized) 3. Check if post is excluded (`Status::EXCLUDED`) 4. Look for `isStale = true` in stored analysis ### Content-visibility causing layout shifts Exclude problematic sections via the filter: ```php add_filter( 'kadence_blocks_optimizer_section_lazy_load_excluded_classes', static fn( array $classes ): array => [ ...$classes, 'my-problematic-section', ]); ``` ### Images loading incorrectly The system uses a queue-based approach for critical images. If the same image appears multiple times, only the first N occurrences (matching the critical images count) are treated as critical.
| ver. 1.4 |
Github
|
.
| PHP 8.2.30 | Generation time: 0.01 |
proxy
|
phpinfo
|
Settings