DEV Community: Softminal

We built an all-in-one WordPress image toolkit. Here's the architecture behind it

Softminal — Thu, 13 Aug 2026 11:03:01 +0000

We want to talk about why most WordPress image plugins exist as separate, single-purpose tools — and why we think that's the wrong approach.

If you manage WordPress sites, you've probably installed some combination of these: an AI alt text generator, a compression plugin, a WebP converter, a media file renamer, and maybe something to catch broken images. Each one solves a real problem. But together, they create new ones.

They fight over hook priority on wp_get_attachment_image. They store overlapping metadata without knowing about each other. They enqueue separate admin scripts on the same pages. And when one of them breaks on a WordPress update, you're debugging a five-plugin interaction.

ImageCraft is our answer to this. One plugin, one pipeline, every image optimization task in a single codebase. It's free and open source on WordPress.org.

We want to walk through the technical decisions, because we think they're more interesting than a feature list.

Direct AI provider integration

Most AI alt text plugins work on a credit model. You buy credits from the developer, they proxy your request to OpenAI or Claude, and pocket the margin. The markup is significant — GPT-4o-mini costs about $0.15 per 100 images at retail, but credit-based plugins charge $3–6 for the same volume.

ImageCraft connects directly to the AI provider from your server. No middleman, no credit packs. You pay the provider at their published rates.

Three providers are supported: Anthropic (Claude), OpenAI, and Google Gemini. Each extends a BaseAIProvider class that handles image fetching, base64 encoding, MIME detection, and prompt construction. Adding a new provider means implementing one method: generateAltText().

API keys are AES-256-CBC encrypted in a custom database table. The REST API never returns the key — only a boolean has_key field.

Combined meta generation (one call, three outputs)

A naive implementation would make separate API calls for alt text, title, and caption. Three network round trips, three token charges, three latency waits.

ImageCraft makes one call that returns all three in a structured JSON response:

{
  "alt_text": "Tan leather crossbody bag with brass buckle and adjustable strap",
  "title": "Aria Crossbody Bag - Tan Leather",
  "caption": "Handcrafted crossbody bag from the Aria Collection, featuring full-grain tan leather and antique brass hardware."
}

The prompt instructs the model to return this exact shape. A parseMetaJson() helper handles the response — including edge cases like markdown-wrapped JSON, extra fields, and truncated responses. Each field has a configurable max length with a capText() function that truncates at the last word boundary rather than mid-word.

For WooCommerce images, the prompt includes product metadata (name, SKU, categories, price) before the image, so the model writes with product context rather than describing the image generically.

Server-side compression: why not an external service?

Most compression plugins — ShortPixel, Imagify, TinyPNG — upload your images to an external API, compress them there, and download the result. This makes sense if your server doesn't have good image libraries. But most modern hosts have Imagick installed, and it's plenty capable.

ImageCraft compresses directly on the server:

Detect if Imagick is available; fall back to GD
Strip EXIF metadata and color profiles (these add kilobytes browsers don't use)
Apply progressive JPEG encoding (loads top-to-bottom instead of block-by-block)
Optionally downscale if the longest edge exceeds a threshold (default 2048px)
Write to a temp file and compare sizes
Only commit if the compressed file is actually smaller

That last step is important. Some already-optimized images (especially PNGs with good compression) get larger after re-encoding. The never-enlarge guard prevents this silently.

Originals are backed up to wp-content/uploads/icais-originals/ with the same directory structure. One-click restore copies the backup over the compressed version.

// Simplified never-enlarge guard
$tempPath = $this->compressToTemp($sourcePath, $quality);
if (filesize($tempPath) >= filesize($sourcePath)) {
    unlink($tempPath);
    return; // original is already optimal
}

WebP sidecars: the least-invasive approach

There are broadly three ways to serve WebP on WordPress:

Rewrite rules — .htaccess or nginx config that serves a .webp file when the browser sends Accept: image/webp. Fragile. Breaks on some hosts. Requires server-level config.
URL replacement — change the image URL in the HTML from .jpg to .webp. Breaks caching. Confuses CDNs. Hard to reverse.
<picture> wrapping — keep the original <img> intact, wrap it in a <picture> element with <source> entries for WebP/AVIF. The browser picks the best format. The original URL stays as the fallback.

We went with approach 3. The converter generates sidecar files (photo.jpg.webp, photo.jpg.avif) next to the originals — for the full-size image and all registered intermediate sizes. A manifest is stored in post meta (_icais_nextgen) with relative paths and byte savings.

On the frontend, two hooks handle delivery:

wp_content_img_tag (WP 6.0+) — wraps content images
post_thumbnail_html — wraps featured images

Both hooks bail on is_admin() and are wrapped in try/catch (\Throwable) so a conversion bug can never break the frontend rendering. The worst case is: the <picture> wrapper fails silently and the original <img> renders as it always did.

<!-- Before -->
<img src="photo.jpg" srcset="photo-300x200.jpg 300w, photo-768x512.jpg 768w" ...>

<!-- After (automatic, on the frontend only) -->
<picture>
  <source type="image/webp"
          srcset="photo.jpg.webp 1024w, photo-300x200.jpg.webp 300w, photo-768x512.jpg.webp 768w">
  <img src="photo.jpg" srcset="photo-300x200.jpg 300w, photo-768x512.jpg 768w" ...>
</picture>

Cleanup removes all sidecar files and the post meta. The original images and markup are exactly as they were before.

Broken image fallbacks: a `get_post_metadata` trick

The broken image fallback has two parts: a frontend JavaScript listener and a PHP metadata filter.

The JS part is straightforward — a capture-phase error listener on document that catches <img> load failures and swaps in the fallback URL. It also does an initial sweep for images with naturalWidth === 0.

The PHP part is more interesting. For missing featured images, we needed has_post_thumbnail() to return true even when the real thumbnail is gone. The function checks get_post_meta($postId, '_thumbnail_id', true), and if that returns a valid attachment ID that happens to be deleted, has_post_thumbnail() returns true but the image render fails.

For posts where _thumbnail_id is completely empty (the meta doesn't exist), we hook get_post_metadata with a filter:

add_filter('get_post_metadata', function ($value, $postId, $metaKey) {
    if ($metaKey !== '_thumbnail_id') return $value;
    // ... bail checks, recursion guard, settings check ...
    return $fallbackImageId;
}, 10, 3);

This makes has_post_thumbnail() return true for any post type in the allow-list, and get_the_post_thumbnail() renders the fallback image. The real database is never modified — it's a read-time filter only.

The recursion guard matters because get_post_meta for the fallback image's own _thumbnail_id would trigger the same filter. A static flag prevents the infinite loop.

Usage limiting without being annoying

The free tier allows 50 actions per day across a rolling 24-hour window. Generation and compression share the same pool.

The implementation uses a single wp_options key per user:

// Stored as: icais_daily_usage_{userId}
[
    'started_at'     => 1691942400,  // window start timestamp
    'ids'            => [41, 42, 43], // attachment IDs (deduped)
    'compress_count' => 7,            // compression count (NOT deduped)
]

There's an intentional asymmetry here: generation is deduped per attachment ID (re-generating alt text for the same image within the window is free), while every compression counts. The reasoning is that regenerating alt text is a common review workflow (generate, reject, regenerate with a different tone), but re-compressing the same image is an unusual action that probably indicates a settings change.

totalCount() = count(ids) + compress_count. When it hits 50, the API returns a 429 with a human-readable message about when the window resets.

Pro (detected via the ICAIS_PRO constant defined by the separate Pro add-on plugin) bypasses the check entirely.

Things we got wrong and fixed

A few mistakes from earlier versions, in case they're useful to someone building similar tools:

Catching \Exception instead of \Throwable. PHP 7+ throws \Error for things like missing classes and type mismatches. catch (\Exception) doesn't catch those. Any integration point with an external library or optional dependency now catches \Throwable. This one nearly caused a white-screen on a site that had an older PHP version with a missing Imagick extension.

Settings double-prefix. Our settings system prepends icais_ to every key, and the keys in the defaults array already start with icais_. So everything is stored as icais_icais_default_tone. We caught this too late to fix without breaking existing installations. It works. It's ugly. It's documented. We moved on.

The wizard gate. Early versions required an API key to get past the setup wizard. Then we added compression, which doesn't need an API key at all. Users who only wanted compression were blocked by a screen asking for an AI provider key. The wizard is now skippable, and the plugin works fine without any API key configured — you just don't get the AI features.

Try it

ImageCraft is free on WordPress.org. Search "ImageCraft" in your plugin installer, or search for "imagecraft ai alt text" to find it.

Why Most WooCommerce 'B2B' Plugins Break at Checkout (and How We Fixed It)

Softminal — Thu, 13 Aug 2026 04:17:30 +0000

You know the bug before you've even opened the store. The product page says $12. The cart says $10.80. Checkout Blocks says something else entirely. And now it's late, you've got six plugins active, and you're grepping for woocommerce_product_get_price trying to work out which one fired last.

I've lost enough evenings to that exact thing that I stopped blaming the plugins. None of them is wrong, really. They're just five strangers hooking the same filter, and the price a customer pays comes down to load order. That's not a store. That's a negotiation, and it's happening live in front of someone with a credit card out.

We built Softminal B2B Suite for WooCommerce mostly to stop living like that. So instead of a feature tour, here's what actually changed underneath — the three calls that decide whether a B2B plugin is safe on a store taking real money.

The setup that keeps breaking

Go look at the plugins page of pretty much any WooCommerce store selling to businesses. You'll find some version of this:

wholesale pricing, a "hide price until login" thing, a plugin for registration fields, request-a-quote, min/max quantities, and something for invoices. Six add-ons. Each one solves its own slice fine. The trouble is none of them knows the others exist, and they're all elbowing for the same price and visibility filters.

So the final price isn't decided by a rule you can point at. It's decided by whoever hooked in last. And when a buyer emails asking why their line came to $68.40, you honestly can't tell them — because nothing in your store knows either. You'd be guessing along with them.

What we did instead

One resolver. Everything goes through it. That's a rule we actually enforce on ourselves in the codebase — price mutation runs through a single Pricing\Resolver pipeline, and if you find a stray Woo price filter somewhere, that's a bug to rip out, not a feature.

When someone looks at a product, the pipeline walks the options in a fixed order and stops at the first hit:

accepted quote
  → customer-specific rule
    → company rule
      → group rule
        → category / tag rule
          → sale price
            → regular price

Nothing clever. The whole point is that it's boring and it's one path. The same walk answers the shop, the product page, the cart, the Store API that Checkout Blocks reads from, and the little "why this price" panel. There's no second code path that can quietly disagree with the first.

And that second-order effect is the part I care about most. Because the explainer is generated from the same walk that charges the customer, it can't drift. When a price panel recomputes the answer on its own, you've just written a second bug that's going to disagree with the first one eventually. Ours literally can't, because it's the same code. So when that "why is this $68.40?" email lands, you pull up which rule won and which ones it skipped, and you answer it in ten seconds.

The postmeta trap

The other line we won't cross: no B2B data in postmeta. Pricing rules, companies, quotes, credit — all of it lives in its own smb2b_ tables.

I get why people reach for postmeta. It's right there, it's easy, update_post_meta and you're done. And then six months later the shop page is doing a meta_query join against a table with a few million rows and taking four seconds to paint, and nobody can figure out why.

B2B pricing is a relational problem wearing a shopping-cart costume. Customers belong to groups, groups own rules, rules target categories, companies carry a credit ledger. Model that in real indexed tables and pricing stays quick as the catalogue grows, a credit ledger is an actual append-only ledger you can query instead of a serialized blob, and uninstall.php can drop the whole thing cleanly instead of leaving junk scattered across wp_postmeta forever.

HPOS and Blocks aren't a "later" thing

A B2B plugin lives at the checkout, which is the one part of WordPress that punishes you hardest for cutting corners. Two things there just aren't negotiable for us.

All order access goes through WC_Order CRUD — never a direct query against wp_posts. If your plugin is still reading orders out of the posts table, it's already broken on any store that's flipped on HPOS, whether or not anyone's noticed yet.

And every checkout-affecting feature has to work in classic checkout and Cart & Checkout Blocks, Store API included. "Works on classic" is half a plugin shipped as a whole one. A lot of the older B2B plugins predate both HPOS and Blocks and got patched forward — which means building on them today is inheriting all of that debt on day one.

What it actually gives you

None of the above matters to a store owner on its own — it matters because of what it lets the plugin do without falling over:

group and wholesale pricing (percentage, amount off, or fixed — shop-wide down to a single customer), hide prices until login, trade registration with an approval queue, company accounts with roles and spend limits and approval chains, net terms and credit on a real ledger, request-a-quote that turns an accepted quote into a real order at the agreed numbers, and a bulk order form for the fifty-line reorder by SKU or pasted CSV.

The free plugin on WordPress.org runs a full single-group wholesale channel end to end — it's not a nagware trial. Pro stacks the organisational stuff on top (unlimited groups, companies, credit, quoting, EU VIES VAT validation, webhooks) on the same tables and the same resolver, so you install free first and add Pro whenever your buyers force the issue, without redoing anything.

If you're evaluating one of these

Skip the feature grid for a minute. The questions that actually predict whether you'll be up at 11pm are:

Does one thing decide the price, or do several filters race for it?
Can it explain a price using the same code that charged it?
Is the B2B data in real tables, or smeared across postmeta?
Does it work in Blocks and HPOS, or just classic?

Get those four right and honestly the features sort themselves out. Get them wrong and no feature list is going to save you.

Softminal B2B Suite is live on WordPress.org — free is a real wholesale channel on its own. b2bsuitewp.com.

Real B2B deserves better than a discount table. And a lot better than five of them stitched together.