Do you find all information about us and our services?
Extensions by Category
💻 9. Advanced Usage: CLI, API, and Developer Topics
This section is for developers, agencies, and advanced users who want to leverage the full programmatic capabilities of the JaJuMa Ultimate Image Optimizer for Magento 2. It covers the Command-Line Interface (CLI), techniques for handling CSS background images, and the developer API for custom integrations.
9.1 Command-Line Interface (CLI) Reference
The CLI is essential for automation, cron job debugging, and managing the extension's processes outside of the Magento Admin UI. All commands should be run from your Magento root directory.
⚠️ Warning: For the
jajuma:imageopti:runcommand to function, both Enable Image Optimization and Enable Conversion Cron Job must be set to "Yes" in the extension's general configuration.
CLI Command Reference
| Command | Description | Parameters | Example |
|---|---|---|---|
jajuma:imageopti:scan |
Scans media directories to find and record images for optimization. Equivalent to clicking "Scan Images" in the admin panel. | (none) | php bin/magento jajuma:imageopti:scan |
jajuma:imageopti:run |
Runs the conversion process for all images with a "Pending" status. | --limit <N|all>, --thread <N> |
php bin/magento jajuma:imageopti:run --limit all --thread 4 |
jajuma:imageopti:scan-unused-images |
Scans for product images that are no longer used in the database. Equivalent to clicking "Find Unused Product Images". | (none) | php bin/magento jajuma:imageopti:scan-unused-images |
9.2 Optimizing CSS Background Images
The extension automatically handles background images that are applied via inline styles (e.g., style="background-image: url(...);" or <style>...</style>). However, for background images defined in external .css files, a manual approach is needed because the extension cannot parse and modify static CSS files.
The extension assists with this by adding helper classes to your site's HTML structure:
.webpand.avifclasses are added to the<html>tag for browsers that do support WebP/AVIF.- A
.no-webpclass is added to the<body>tag for browsers that do not support WebP.
You can use these classes to create a CSS-based fallback system.
💡 Pro Tip: For this method to work, you must ensure the
.webpand.avifversions of your background images are generate via cron or manually generate using a tool likecwebpor an online converter. The extension does not automatically convert images in.cssfiles on-the-fly.
Example Implementation
Let's say your original CSS is:
.my-hero-banner {
background-image: url('../images/hero-banner.jpg');
}To add WebP and AVIF support, first convert your hero-banner.jpg to hero-banner.webp and hero-banner.avif. Then, update your CSS like this:
/* Default: WebP for modern browsers */
.my-hero-banner {
background-image: url('../images/hero-banner.webp');
}
/* AVIF for browsers that support it (overrides WebP) */
html.avif .my-hero-banner {
background-image: url('../images/hero-banner.avif');
}
/* Fallback to JPG for old browsers that don't support WebP */
body.no-webp .my-hero-banner {
background-image: url('../images/hero-banner.jpg');
}9.3 Developer API for Custom Integrations
For maximum compatibility with third-party extensions, custom themes, and dynamic content loaded via AJAX, the extension provides a clean, injectable API interface. This is a critical feature for developers needing to apply optimizations to content that is not present in the initial page load (e.g., quick views, infinite scroll results).
Interface:
\Jajuma\ImageOptimizerUltimate\Api\ImageOptimizerInterface9.3.1 optimizeHtmlImages(string $htmlContent): string
- Description: Takes a string of HTML content, finds all
<img>tags within it, and replaces them with the full<picture>tag structure for AVIF/WebP. - Use Case: Perfect for processing the HTML response of an AJAX request before injecting it into the DOM.
9.3.2 optimizeImageByPath(string $imagePath): array
- Description: Takes the absolute server file path of an image and returns an array containing the paths to its original, WebP, and AVIF versions.
- Use Case: Useful in backend models or helpers where you have the file path and need to generate URLs for optimized versions.
9.3.3 optimizeImageByUrl(string $imageUrl): array
- Description: Takes the public URL of an image and returns an array containing the URLs of its original, WebP, and AVIF versions.
- Use Case: Useful in frontend JavaScript or PHTML templates where you only have the image URL and need to construct a
<picture>element dynamically.
Example Usage in a Custom Extension
To use the API, inject the interface into your class's constructor:
<?php
namespace Vendor\MyModule\Model;
use Jajuma\ImageOptimizerUltimate\Api\ImageOptimizerInterface;
class MyCustomClass
{
/**
* @var ImageOptimizerInterface
*/
private $imageOptimizer;
public function __construct(ImageOptimizerInterface $imageOptimizer)
{
$this->imageOptimizer = $imageOptimizer;
}
/**
* Example method that takes an AJAX response and optimizes its images.
*
* @param string $ajaxHtmlResponse
* @return string
*/
public function processAjaxContent(string $ajaxHtmlResponse): string
{
// Optimize all images within the HTML string
$optimizedHtml = $this->imageOptimizer->optimizeHtmlImages($ajaxHtmlResponse);
return $optimizedHtml;
}
}📞 Need Help?
Having trouble with the setup? Check our Troubleshooting, FAQ & Best Practices for common solutions.
Still have questions or need help with custom integrations? Our expert team is here to assist. Please don't hesitate to contact our support team for personalized assistance.
Ready to unlock these features for your store?
The JaJuMa Ultimate Image Optimizer is the all-in-one solution for a faster, higher-ranking Magento store.
Find all you need to know and more valuable insights about Hyvä and Magento.
Expertly curated by JaJuMa:
🚀
Launch the JaJuMa Hyväverse
Your central resource for everything Hyvä.
Explore the Magento Metropolis!
Your central resource for everything Magento.
