DEV Community: Jaafar Abazid

Arabic search in WordPress: the matches it silently misses

Jaafar Abazid — Fri, 24 Jul 2026 23:34:45 +0000

Two hundred and fifty thousand articles, and the thing editors complained about was the search box. Not the accuracy of it. The wait. Type a name into the newsroom's admin search, go and do something else, come back.

That is the easy complaint, because it arrives. Someone tells you. What never arrives is the other one, and it took me far too long to notice it was missing: nobody has ever told me the search came back empty for a story we definitely published. Nobody ever will. A search that returns nothing does not look like a bug. It looks like proof you never covered it.

So we fixed the loud one, and left the quiet one running for years.

It is the same seam as an earlier piece on Arabic slugs: Arabic quietly breaking an assumption WordPress never knew it was making. Last time it was the URL. This time it is the search box.

What WordPress actually does with an Arabic query

Type a term into WordPress search and WP_Query builds this, near enough:

WHERE post_title   LIKE '%term%'
   OR post_excerpt LIKE '%term%'
   OR post_content LIKE '%term%'

That is the whole mechanism. Not a search engine, not an index, a substring test run three times per row. It knows nothing about words, and nothing at all about Arabic.

We measured what that means on a throwaway WordPress 7.0.2 and MySQL 8.0.35: one post per spelling, then the obvious searches.

you search	you get back
محمد	only the plain post
مُحَمَّد (with tashkeel)	only the tashkeel post
محمـــد (with tatweel)	only the tatweel post
أحمد (hamza alef)	only the hamza post
احمد (bare alef)	only the bare alef post
مصطفى (alef maqsura)	only the maqsura post
مصطفي (yaa)	only the yaa post
مكتبه (haa for taa marbuta)	nothing at all

Read that right-hand column again. Every search returns only its own exact spelling, and the last returns nothing at all, even though every term on the left is the same word to a human being. A reader who types a name without diacritics never sees the article that has them. Someone who writes أحمد never finds احمد. Someone who ends a word with ه instead of ة gets an empty page.

The one result that looks like a success is the exception that proves the point. Searching كتاب does return الكتاب. That is not the search understanding the definite article, it is the letters ك ت ا ب happening to sit inside الكتاب as a literal substring. Search وكتاب, the same word with a prefixed و, and you get nothing, because the bare word is no longer embedded in it.

The admin post list behaves identically to the front end, which is the part that matters, because that is where your editors live.

The same word, written three ways, and a reader means one thing by all of them. WordPress compares raw bytes with LIKE, so the three stay three different strings and none finds the others. Fold them with the same normaliser and they collapse to a single token that matches every time.

The database already knows. WordPress never asks it.

This is the part that genuinely surprised me.

WordPress does not inherit your server's collation. It forces its own onto its tables, utf8mb4_unicode_520_ci, whatever MySQL's default happens to be. And that collation is not naive about Arabic. Ask MySQL directly, with an equality test:

SELECT 'مُحَمَّد' = 'محمد' COLLATE utf8mb4_unicode_520_ci;   -- 1

One. True. The collation folds the diacritics away and says these are the same string. On MySQL 8's utf8mb4_0900_ai_ci it folds tatweel as well.

Now ask it the way WordPress asks it:

SELECT 'مُحَمَّد' LIKE '%محمد%' COLLATE utf8mb4_unicode_520_ci;   -- 0

Zero. Same data, same collation, same server, opposite answer. Wildcard pattern matching does not apply the collation's character folding, so every piece of Arabic knowledge sitting in your database is thrown away the moment you wrap the term in %. We tested four collations. Under =, the good ones fold. Under LIKE '%…%', all four return zero.

The capability was already in the building. The search architecture walks straight past it.

The identical pair, the diacritic-marked spelling and the plain one, under WordPress's own collation. Compared with =, the collation folds the tashkeel away and returns 1: they are equal. Compared with LIKE and a wildcard, that folding is skipped and it returns 0. Same data, same collation, opposite answer, and WordPress search asks with LIKE.

Even reaching it would not be enough

It is tempting to stop here and go looking for a way to make WordPress compare with =. It would not save you, and the measurements show why.

A collation folds accents. Tashkeel are accents, combining marks that sit on top of a letter, which is exactly why they fold.

Hamza is not an accent. أ and ا are different letters. So are ى and ي. So are ة and ه. None of them fold, in any collation we tested, under any comparison. And these are not edge cases in Arabic, they are the ordinary daily variation: the same name spelled أحمد by one editor and احمد by another, the same word ending ى in one headline and ي in the next.

So the database will hand you diacritics for free if you ask it correctly, and it will never hand you the rest. Anything that actually works has to normalise the text itself, deliberately, on both sides of the comparison.

What it costs, and why the broken searches are the expensive ones

The other half of this is the half your editors do complain about.

A LIKE with a leading wildcard cannot use an index. Not "is slow to use one", cannot use one, ever. EXPLAIN on the query WordPress generates says it plainly:

type: ALL     key: NULL     rows: 50013

Full scan, no key, every row. We seeded 50,000 realistic Arabic posts and timed it with a fresh PHP process per run, because repeating it inside one process makes WordPress's in-request cache report a fraction of a millisecond, which is a lie:

a term matching one post: about 215 ms
a term matching nothing: about 225 ms

The search that finds nothing is the slowest, and that is not a rounding artefact. LIKE '%term%' gives up on a row the instant it finds the substring, so a row that matches is cheap: often the title matches and the long body is never read at all. A row that does not match has to be read to the last byte of every field before MySQL can be certain the word is absent. Proving absence is the expensive case. And in Arabic, the searches that come back empty are precisely the variant spellings in the table above.

You might expect LIMIT 10 to rescue this. It cannot, and MySQL says so in plain words. WordPress needs a total for pagination, so it asks for SQL_CALC_FOUND_ROWS, and the query plan reports the consequence itself:

Limit: 10 row(s) (no early end due to SQL_CALC_FOUND_ROWS)

Ten results on the page, every matching row enumerated to produce them.

The scan cost tracks table size, so a 250,000-article archive lands somewhere around a second per search, per concurrent searcher, with no index able to help. (That figure is an extrapolation from the 50k measurement, not a measurement of a 250k table.)

Now put the two halves together. The searches that silently return nothing are the same searches that scan your entire archive in order to return nothing. In Arabic, those are every variant spelling your readers and editors actually type. The complaint you get and the complaint you never get are the same query.

What we built, and what it fixed

We did the obvious right thing, and it worked.

We built a table outside WordPress, on AWS, one row per article: id, title, body, author, categories. Every time a post was published, updated or deleted, that row was kept in step. Search stopped asking the WordPress database to scan a quarter of a million rows and started asking a store built for the job. Public search had already been handed off to a Google Custom Search Engine, so between the two, search stopped being the thing anyone raised in a meeting.

(That table later grew into something much larger, a recommendation engine that learns what a reader is interested in and chooses their next article. That is a story for another day.)

By every measure we were watching, we had fixed search.

What it did not fix

We never normalised the Arabic.

The new table was faster. It was still storing and matching the same raw strings, with the same orthographic variation, in the same literal way. A reader typing محمد still missed مُحَمَّد. أحمد still missed احمد. مكتبه still found nothing. We had rebuilt the entire search path, moved it to another cloud, and put a proper store underneath it, and every one of those searches failed exactly as it had before.

That is the lesson, and it took us years to see it: the speed problem was an infrastructure problem, and the matching problem never was. Scale, indexes and a store designed for querying will fix a scan. None of them will turn two spellings of the same word into the same token. Normalisation is a text problem, and if you do not solve it, it follows you to AWS.

And because nobody ever complains about a search that returns nothing, nothing ever forced the issue. The loud problem got an entire re-architecture. The quiet one just carried on.

The layer we were missing

The fix is small, and it is the same fix wherever your index lives.

Normalise both sides. Keep a normalised copy of the searchable text, index that, and put every incoming query through the identical normaliser before matching. Both halves matter: normalise only the stored text and a query carrying diacritics still misses, normalise only the query and it misses the stored variants.

What the normaliser has to do:

Strip the diacritics. Tashkeel are combining marks (U+064B to U+0652 and friends). Remove them entirely.
Strip tatweel (U+0640). It is decoration and carries no meaning.
Unify the alef forms. أ إ آ ٱ all become ا.
Unify ى to ي, and decide about ة to ه. These are conventions, not truths. Pick one, apply it to both sides, write it down.
Strip the definite article الـ, so الكتاب and كتاب fold to one token. Guard it, so it only comes off when enough of the word is left to still be a word, otherwise ال on the front of a short word gets eaten too. And stop there. It is tempting to strip the single-letter prefixes و ف ب ك ل as well, but those letters begin ordinary words, so بيت would lose its ب and فكرة would become كرة, a genuinely different word. So وكتاب will not fold to كتاب, and that conservative choice is the correct one.
Leave Latin alone. Newsroom copy is full of WordPress, AWS, S3 and half-transliterated terms. A normaliser that mangles those breaks more than it fixes.

Do that and the table from earlier collapses into a single row: every spelling of محمد, however it was typed, becomes one token that matches all the others. And because the normalised copy is matched through an index instead of a leading-wildcard scan, the query that used to take a second stops scanning the table at all.

And none of this needs a cloud. The story above happened to run through a table we put on AWS, but that was our answer to scale, not to matching. On an ordinary single-server WordPress, the same normalised copy in the same database, with the query folded the same way, fixes both the misses and the scan with nothing external at all. That is the layer we were missing, and it would have been missing just as badly on one server as on twenty.

One change, both complaints.

The plugin

The whole fix is one file. It goes in wp-content/mu-plugins/, and in its default mode it needs nothing else: no cloud, no service, no configuration.

composer require mantekio/wp-arabic-search

On save it folds everything searchable about a post, title, excerpt and body, into one normalised column in a shadow table with a real FULLTEXT index, and rewrites WordPress search to match against that column through the identical normaliser. The public site and the wp-admin post list both run through WP_Query, so both are fixed at once. Build the index over what you already have with one command:

wp arabic-search reindex

Media gets the same treatment, which turned out to matter more than expected. An attachment keeps its text in four places: the title, the caption, the alt text and the filename. All four go into the same column, so a picture captioned in Arabic is findable by that caption, and صورة-بيروت.jpg is findable by its own name. WordPress does not search alt text at all, so on that one the plugin is not restoring parity, it is adding something core never had. This changes what the Media Library can find, not what appears anywhere else: the plugin decides which rows match the text, and WordPress still decides which post types and statuses are allowed in the results.

It ships with two modes, because the normaliser is the reusable part and the index is not. The default, index, is the self-contained one just described. The other, normaliser, maintains nothing and rewrites nothing: it exposes the normalising function and fires an action carrying the normalised text on every save, so a pipeline that indexes somewhere else (the AWS table we built, OpenSearch, anything) can fold its stored text and its queries with the same code. That is the guarantee that actually matters, and it is the one we did not have for years: both sides normalised by identical code.

define( 'WPAS_MODE', 'normaliser' );

One thing it deliberately refuses to do. InnoDB does not index words shorter than three characters, which in Arabic covers من, في, ما and عن: real words, typed constantly. An index that has never seen a word cannot find it, so requiring one would return an empty page for a search plain WordPress answers perfectly well. That is exactly the failure this article is about, and it would have been ours. So the plugin drops those tokens rather than requiring them, and where a search contains nothing else it hands the query back to core's LIKE untouched. Search a two-letter word and you get precisely what WordPress would have given you; search two words where only one clears the threshold and the long one still matches. The rule it follows is that where it cannot help, it stands aside rather than answer worse than the search it replaced. There is nothing to configure for this, and no reason to go changing innodb_ft_min_token_size on your server: it needs a MySQL restart and a rebuild of every full-text index on the box, and it buys you nothing here.

Which raises the question any search tool eventually gets asked, usually by an editor who is certain the article exists: why did this not match? Answering it used to mean reading the source, so there is now a command that just tells you.

$ wp arabic-search explain "من المكتبة"
normalised:  من مكتبه

+--------+------+--------------------------------------------------+
| token  | used | reason                                           |
+--------+------+--------------------------------------------------+
| من     | no   | shorter than innodb_ft_min_token_size (3)        |
| مكتبه  | yes  | indexable                                        |
+--------+------+--------------------------------------------------+

matches with: MATCH(search_text) AGAINST ('+مكتبه' IN BOOLEAN MODE)

The folded form, every token with whether it was used and why not, and the exact query that runs. It is the smallest feature in the plugin and the one I would miss most, because "search is broken" and "search is working exactly as designed on a word the index cannot hold" look identical from the outside, and this is the difference between them.

We eventually ran it against the real thing: a quarter of a million Arabic articles, plus half a million media items, on a copy of a live newsroom archive. One search settles the whole argument.

searching مُحَمَّد across 250,000 articles	results	time
WordPress	1	4.8 s
with the plugin	28,238	0.55 s

One. Out of twenty-eight thousand articles that contain that name, plain WordPress found a single one, because only one of them happened to spell it with exactly those diacritics. The other 28,237 were in the database the whole time, and no one searching for that name would ever have seen them.

The speed is the part you would have put in the ticket. The other column is the part nobody was ever going to report.

The rest of the numbers come from a controlled 50,000-post rig, where the match count can be dialled precisely, before and after:

matches, out of 50,000	default WordPress	with the plugin
1	about 215 ms	5 ms
500 (1%)	about 212 ms	10 ms
5,000 (10%)	about 230 ms	24 ms
25,000 (50%)	about 250 ms	115 ms
50,000 (100%)	about 310 ms	about 210 ms

EXPLAIN tells the same story as the clock. Before, every search was the full scan:

type: ALL        key: NULL        rows: 50013

After, the index drives it:

type: fulltext   key: search_ft   rows: 1

We had that bottom row wrong for a while, and the way it was wrong is worth repeating, because it is a trap set for anyone who benchmarks a text search. Our first measurement said the index lost on a term matching everything. It did not. The word we had seeded happened to sit near the start of every document, and since LIKE abandons a row the moment it finds a match, we were timing the scan at its luckiest: first few bytes, done, next row. Move the same word to the end of the same documents, and the result inverts.

a term matching all 50,000 rows	default WordPress	with the plugin
the word sits at the start of every document	140 ms	208 ms
the word sits at the end of every document	300 ms	205 ms

Read the plugin column first: it barely moves, because an index does not care where in the text the word happens to sit. Now read the other one, which doubles. We had benchmarked the scan's single luckiest case and called it a fair fight.

So the honest shape is a crossover, not a caveat. Against a term the scan actually has to read, the index wins across the entire range in the table above. Against a term positioned for the scan's best possible case, the index still wins until roughly 70% of the archive matches. A query that matches seventy per cent of a newsroom archive is not a search, it is a SELECT * with extra steps.

And the case that used to hurt most is now the cheapest. The old worst case was the search that came back empty, because proving absence meant reading every byte of every row. An index that finds nothing has nothing to read.

One honest word on where it is in its life. It is new, and it ships as 0.9.3. That it is already on its fourth release says something worth saying plainly: six rounds of adversarial testing found a bug every single time, and not one of them was found by reading the code.

The worst was in the first release. Search a two-letter Arabic word, من or في, and it returned nothing at all. The check meant to drop words too short for the index counted bytes, and an Arabic letter is two bytes, so every one of those words sailed through and became a required term the index had never held. A plugin whose entire argument is that Arabic search silently returns nothing had shipped a way to make Arabic search silently return nothing. Others followed: a health check that could not detect the condition it existed to detect, and a reindex command that announced success having written not one row.

They are all fixed, and every fix is in the changelog, but the pattern is the point. Each one was invisible from the code and obvious the moment something actually ran it. If this piece has a moral it is that one, and it applies to your search too: the failure that returns nothing looks exactly like the absence of anything to find.

What it has not yet had is months in a live newsroom, so it is out in the open under the GPL, on GitHub and Packagist, being hardened in daylight. The repository is github.com/mantekio/wp-arabic-search. Same loop as the pieces before it: the article explains the thinking, the repository is the plugin, the package is the one-line install, and each points at the other two.

Known limits

Being clear about what a tool does not do is part of the tool.

Single-letter prefixes are deliberately not stripped. Folding the definite article is safe behind a length guard; folding و ف ب ك ل is not, because they also start ordinary words, so it would turn بيت into يت and فكرة into كرة. The cost of that safety is that وكتاب does not fold to كتاب. Real prefix handling needs morphology, not a character map.
Folding is not stemming. It will not connect كتاب to its broken plural كتب, because Arabic plurals rewrite the word rather than append to it. That needs a root dictionary, and that is a different project.
The results are only as complete as the index. Nothing walks your archive when you install it, so run wp arabic-search reindex once. After that each save keeps its own row current, and wp arabic-search status exits non-zero the moment the index falls behind, goes stale, or carries rows for posts that no longer exist. Drift is something you get told about rather than something a reader discovers for you.
It costs disk, inside the database. A second normalised copy of your searchable text is still a copy. On that quarter-million-article archive the table came to about 1.1 GB, roughly 3 KB per article, though the FULLTEXT index on top of it was only 17 MB. Media is nearly free: attachments were two thirds of the rows and a sixteenth of the bytes.
Words the index cannot hold are correct, not fast. A search that falls back gets core's behaviour entirely, including core's speed, because it is core's query. On that same archive a two-letter word took about three seconds, exactly as it always had, while an indexed search of the same corpus took well under one. Nothing is worse than before. Nothing is better either.
Normalisation is lossy on purpose. Folding ة into ه, or ى into ي, will occasionally merge two words that genuinely differ. In an archive search that trade is nearly always worth it, but it is a trade: decide it deliberately and document it, rather than discovering it later.
Past a certain size, use a real search engine. OpenSearch ships an arabic analyser that does normalisation, stemming and stopwords properly, and gives you relevance ranking a LIKE will never have. If the archive is large and search matters, that is the destination. You still need the normaliser, because the same text problem travels with you. Ours did.

A quarter of a million articles, and the only thing anyone ever told us about search was that it was slow. So we made it fast. We built the table, moved the queries to AWS, kept it in sync on every post, the complaints stopped, and for a long time we took that to mean we had finished.

The searches that returned nothing never produced a single complaint, because a search that returns nothing looks exactly like a subject you never covered. The archive was full of articles nobody could find, and the silence around them read as success.

That is the part worth keeping, whatever your stack: complaints tell you about the loud failures and nothing at all about the quiet ones. Someone has to go and look.

That is how we run WordPress on AWS for newsrooms: fix what people report, then go hunting for what they cannot. If your archive is in Arabic and you have never tested what your search does with a hamza, let's talk.

WordPress cron behind a load balancer: fixing 'Missed schedule'

Jaafar Abazid — Wed, 22 Jul 2026 17:33:33 +0000

A newsroom schedules its lead story for six in the morning. At 6:05 it is not on the homepage. Nobody did anything wrong: the post was written, scheduled, saved, and its publish time has come and gone. There is no error, no failed job, nothing in the log. The post just sits in the admin list with a small grey label beside it, Missed schedule, as though it had quietly decided not to happen.

This is the worst kind of bug, the completely silent kind. And on WordPress spread across more than one server, it is barely a bug at all. It is what the default setup does under load, and the fix nearly everyone reaches for makes it worse, in a way that is genuinely hard to see.

wp-cron is not cron

The name lies. wp-cron is not a system scheduler. On a default install, WordPress checks for due jobs on a normal page load: near the end of a request it fires a non-blocking loopback call to wp-cron.php, which runs whatever is due. No visitors, nothing runs. A quiet site can sit for hours with nothing firing; a busy one runs its cron on the back of a random reader's page view.

On one server that is merely untidy. Put it behind a load balancer and it starts to fail in ways you cannot see. The loopback goes to your own domain, which resolves to the load balancer, which hands it to some instance, not necessarily the one that fired it. If an instance cannot reach the public hostname, the loopback silently does nothing. You now have a scheduler whose reliability depends on reader traffic and internal networking, for jobs like publishing the morning's lead story.

The fix everyone gives you, and the one it hides

Search this and every answer is the same two lines: switch the loopback off, and drive cron yourself.

define( 'DISABLE_WP_CRON', true );

* * * * * wget -q -O - https://www.example.com/wp-cron.php?doing_wp_cron >/dev/null 2>&1

We ran exactly that. Then, because a crontab lives on one machine and our machines come and go, we moved the trigger to a Lambda that hit the site every minute, so nothing depended on a single box staying alive. It looked correct. The request went out every minute, on schedule, forever.

And posts kept coming up Missed schedule.

Both rows want the same thing: the due events run on time. The top row triggers cron with an HTTP request, so it inherits everything sitting in front of the origin, a cache that can answer the same fixed URL without ever running PHP, a load balancer that can hand it to a draining node, and a web request that dies on a stuck lock or a mid-run recycle. The bottom row runs cron in-process with WP-CLI, so none of that is in the path.

The mistake is buried in that one-liner, and it is the same mistake whether a crontab or a Lambda fires it: we were still triggering cron with an HTTP request. Everything wrong with that survives the move to Lambda, because it has nothing to do with who makes the request and everything to do with the request itself.

Follow the path it takes. It hits your public URL, so it meets your CDN first. Our trigger was one fixed URL, wp-cron.php?doing_wp_cron, the same string every minute, which is precisely what a cache exists to answer without troubling the origin. So a good share of those tidy every-minute hits were served from cache as an empty 200, and PHP never ran. The dashboards were green. Cron was not running.

Past the cache it meets the load balancer, which sends it to whichever instance it likes, including one that is draining. If it does reach a live node, wp-cron.php runs as an ordinary web request, under the web server's timeout, holding a lock other requests respect for sixty seconds. Let one heavy job overrun that lock, or let the instance recycle mid-run, and cron wedges or dies with the queue half done. The publish_future_post event for the 6am story is somewhere in that unfinished tail.

None of it surfaces as an error. The trigger fires, something returns 200, and the post sits at Missed schedule until an editor asks why.

Stop hitting a URL

Here is the turn that fixed it, and it is smaller than it sounds: the reliable way to run cron makes no HTTP request at all.

wp cron event run --due-now

WP-CLI boots WordPress in a normal PHP process on the machine and runs the due events straight against the database. No page, so no CDN to cache it. No loopback, so no load balancer to misroute it. It runs in the CLI, which has no web timeout, so a slow job finishes instead of being cut off. Every fragile link in the HTTP path is simply not in this one.

That is the whole distance between "keep hitting the server so cron stays alive" and "run cron". Hitting a page keeps it triggered. It does not keep it finishing, on time, and finishing is the only thing a scheduled post cares about.

Which leaves one question, the one that turns this from a one-liner into a fleet problem: if cron now runs in-process on a machine, which machine?

Which machine?

Cron now runs in-process, which means it runs on whichever machine the crontab sits on. In a fleet, that innocent question is the whole problem, because there are only two obvious answers and both are wrong.

Pin it to one machine and you are back where you started. That machine is cattle: a deploy replaces it, a scale-in retires it, a health check recycles it, and your one crontab leaves with it. Cron stops, silently, and the 6am story misses again. A single runner is a single point of failure wearing a tidier hat.

So put it on every machine, bake it into the image, and let every node run cron. Now the opposite breaks. wp cron event run on each node executes the due events locally, against the shared database, in the same minute. The event that publishes the lead story fires on all of them. Readers get the newsletter three times, the post publishes and re-publishes, the feed importer runs in triplicate. The transient lock core uses for the loopback does not save you here, because each CLI process is its own world and, unless your object cache is shared, they cannot even see each other's lock.

Run everywhere, execute once

The answer is to keep cron on every node, so there is no single box to lose, and put one shared lock in front of the run, so only one node does the work each minute.

Every instance runs the trigger, so there is no single box to lose, but each run first tries to take a shared lock (a MySQL advisory lock, or a Redis key), and only the winner executes the due events. The runner records each successful pass, so a total stall is loud instead of silent.

Every node's crontab calls the same command every minute. The first thing it does is ask for a lock. Exactly one node gets it; the rest are turned away in a millisecond and exit having done nothing. The winner runs the due events and releases the lock. Next minute the race is run again, and it does not matter who wins.

For the lock you already have the one shared thing you need: the database. Every instance talks to the same MySQL, so a MySQL advisory lock is a coordinator with nothing new to deploy:

SELECT GET_LOCK('wp_fleet_cron', 0);

Ask for it with a zero-second timeout, run cron only if you got it, release it when you are done. There is a second reason to prefer this over the transient lock WordPress uses: an advisory lock lives on the database connection, so if the runner is killed mid-job, the connection closes and the lock releases itself. The stuck-lock failure that wedges the transient one for sixty seconds cannot happen here. If you run Redis across the fleet, a SET key value NX PX key does the same job; the point is that the lock is shared, not which store holds it.

Make the silence loud

One thing is still missing, and it is the thing that started all this. Elected and locked, cron runs correctly, right up until the day it does not: a bad deploy, a lock a broken database will not grant, a crontab that quietly stopped being installed. A scheduler that fails silently is the whole reason we are here.

So the runner writes down every successful pass, the time and the node that did it. That one record turns the unanswerable question, "is cron running?", into a check anything can make:

wp fleet-cron status || send-me-an-alert

It exits non-zero the moment the last run is older than it should be, so an outage pages you before an editor finds it. The missed 6am story stops being a mystery someone stumbles on and becomes an alert you already handled. It is the same rule that runs through our WordPress mail plugin: a failure you cannot see is worse than one that shouts.

The plugin

It is one file. Drop it into wp-content/mu-plugins/, add one line to wp-config.php, and run one command from system cron on every node:

define( 'DISABLE_WP_CRON', true );

* * * * * cd /var/www/html && wp fleet-cron run --quiet

Then hand the health check to your monitoring, so a stall reaches you rather than an editor:

wp fleet-cron status || send-me-an-alert

Or install it with Composer:

composer require mantekio/wp-fleet-cron

One honest word on where it is in its life. It is new, and it ships as 0.9.0. It has been exercised end to end against a real database and WP-CLI: a single runner elected out of five firing at once, a lock that frees itself when the holder is killed mid-job, the watchdog going loud the moment a run goes stale. What it has not yet had is months in a live multi-node fleet, so it is out in the open under the GPL, on GitHub and Packagist, being hardened in daylight rather than behind a curtain. The repository is github.com/mantekio/wp-fleet-cron. Same loop as the pieces before it: the article explains the thinking, the repository is the working plugin, the package is the one-line install, and each points at the other two.

Known limits

Being clear about what a tool does not do is part of the tool.

The lock assumes a single primary database. That is the normal case, and it is the one thing every node in a fleet already shares. On a multi-primary topology, or behind a connection pooler that hands one session to different callers, swap in a Redis key (SET key value NX PX); the plugin leaves a seam for it.
It assumes you can run system cron on the nodes. If your host forbids that, keep the loopback, but the watchdog still tells you the instant cron stops.
A long job serialises cron behind it. The lock is held for the length of a run, so a job that overruns the minute makes the next tick skip rather than stack a second copy on top. That is deliberate, you never want two, but a genuinely heavy job wants its own queue, not a seat in the cron tick.
Some managed hosts already run cron correctly for a fleet. Check what yours does before adding anything.

Publishing a post on time is the most solved problem in WordPress, on one server. Across a fleet, on the morning a scheduled lead has to be live at six, it turns out to be a small distributed-systems problem in a CMS costume, and the fixes are the dull, correct ones: run cron where nothing can cache or misroute it, let exactly one node act, and make the silence loud the instant it falls. None of it is clever. All of it is the distance between a scheduler you hope is running and one you know is.

That is the shape of running WordPress on AWS for a newsroom: the real problems hide inside the boring infrastructure, and the work is making the boring parts unbreakable. If a scheduled post has ever quietly failed to appear, and you would rather it never did again, let's talk.

Your WordPress says the email sent. It didn't.

Jaafar Abazid — Sat, 18 Jul 2026 13:01:04 +0000

A user tells you they never got the password-reset email. You check: WordPress says it sent. wp_mail() returned true. There is nothing in the logs, because there is nothing to log. The mail left the building and vanished.

This is the worst kind of bug. It is silent, it is invisible, and it happens in the one flow where the user is already locked out and already frustrated. And on a default WordPress install, it is not a bug at all. It is the design.

Why WordPress email is broken by default

Out of the box, wp_mail() hands your message to PHPMailer, which hands it to PHP's mail(), which hands it to sendmail on the web server. That path has no sending reputation, no SPF alignment, and no DKIM signature. To a modern mail provider, a message from a random web server, unsigned and unaligned, is indistinguishable from spam, so Gmail and Outlook quietly bin it. Often without even a bounce.

And wp_mail() reports none of this. Its entire failure vocabulary is a single false, and on the default path it usually does not even return that: sendmail accepts the message, so wp_mail() returns true, and the mail dies somewhere downstream where WordPress will never hear about it.

So the real problem is two problems. The mail is unauthenticated, and the failure is silent. Any fix has to solve both, or it has not fixed anything.

WordPress builds the same message either way. On the default path it goes to PHP's mail() and out unsigned, where wp_mail() still returns true. The plugin swaps only the transport: a PHPMailer subclass hands the finished message to the SES API, signed, and it arrives aligned.

Why the usual fix is a half-fix

Search for this problem and every answer is the same: install an SMTP plugin, point it at a real mail service, done. WP Mail SMTP, Post SMTP, and a dozen others all do it, and they do fix the authentication half. Your mail now goes through a reputable server that signs it.

But look at where the credentials live. An SMTP plugin hooks phpmailer_init, sets $phpmailer->Host, $phpmailer->Username, and $phpmailer->Password, and it has to get those values from somewhere. That somewhere is the database, in wp_options.

Sit with what that means. Your SMTP username and password, the ones that let anything send mail as your domain, are now sitting in a table that ends up in every place a database ends up. The nightly backup. The S3 bucket that backup lands in. The staging clone a contractor pulled last month. The dump you emailed yourself to debug something. Anyone who touches any copy of that database can now send mail as you, DKIM-signed by your own domain, and there is no fingerprint that says it was not you.

For a brochure site, that is a small risk. For a newsroom whose domain reputation is an asset, it is the sort of thing that should keep you up at night. The half-fix traded a deliverability problem for a credential-management one, and then hid the trade in a settings screen.

The architecture: three moves

The fix is three decisions, and each one removes an entire class of the problem rather than mitigating it.

One: send through the SES API, not SMTP. SMTP means a username and a password, which means a secret at rest. The Amazon SES API is a signed HTTPS request. There is no long-lived password in the flow at all.

Two: authenticate with an IAM role, not a stored key. This is the move that makes the difference. If your WordPress runs on AWS compute, EC2 or ECS, the instance or task carries an IAM role, and AWS hands short-lived credentials to the machine automatically, rotated for you, never written down. The plugin reads them from the instance metadata endpoint at send time and uses them for that one request. Nothing is stored. Not in the database, not in wp-config.php, not on disk. There is no secret to leak because there is no secret at rest.

Three: replace only the transport, and reimplement nothing. This is the move that keeps the plugin honest, and it has a story behind it.

A seam, not a fork

WordPress 5.7 added a filter called pre_wp_mail. Return a non-null value from it and wp_mail() short-circuits, handing you the whole job. It is tempting to take it: hook the filter, build the SES call, return true.

It is also a trap, and I know the shape of this trap well, because I walked into a version of it once already. The last must-use plugin I wrote forked a core function, a copy of sanitize_title_with_dashes(), because core gave me no seam. That fork then drifted from core for three releases without anyone noticing, dropping an entire block of character handling, until it was mangling exactly the Arabic text it was meant to protect. The postscript on that article is a confession: a hand-copy of a core contract rots silently.

Short-circuiting pre_wp_mail would be the same mistake in a new costume. Take over wp_mail() and you now own its entire contract: header parsing, Cc and Bcc, Reply-To, content type, charset, attachments, and every wp_mail_* filter a hundred other plugins hook into. Reimplement all of that and your copy will drift from core the moment core changes, silently, exactly like last time.

So this plugin reimplements none of it. Core builds its own PHPMailer object, but only when the global is not already one:

global $phpmailer;
if ( ! ( $phpmailer instanceof PHPMailer\PHPMailer\PHPMailer ) ) {
    // ...core builds the mailer...
}

That if is the seam. Hand core a subclass of PHPMailer before it looks, and it uses yours. Core still assembles the entire message, still honours every filter, still does everything it always did. The subclass overrides one method, postSend(), the point where PHPMailer would normally talk to the transport, and ships the finished message to SES instead:

class WPSES_Mailer extends \PHPMailer\PHPMailer\PHPMailer {
    public function postSend() {
        $raw  = $this->getSentMIMEMessage();     // core built this, not us
        $sent = wpses_send_raw( $raw, /* recipients */ );

        if ( is_wp_error( $sent ) ) {
            // Throwing lands in core's own wp_mail_failed path.
            throw new \PHPMailer\PHPMailer\Exception( $sent->get_error_message() );
        }
        return true;
    }
}

We take the fully assembled MIME message that core produced and put it on the wire. We replace the transport and nothing else. There is no contract to reimplement, so there is nothing to drift. The lesson from the slug plugin, learned the expensive way, is baked into the architecture of this one: when core gives you a real seam, take the seam, never the fork.

Fail loudly, because the alternative is what we are here to fix

Go back to the password reset that vanished. The reason it vanished is that the failure was silent. So the cardinal rule of this plugin is that it is never silent.

When SES refuses a message, it tells you exactly why: an unverified sender, a sandbox restriction, a throttle. The plugin does not swallow that into a bare false. It logs the real SES error code, fires an action other code can hook, and, by throwing, lets the failure land in core's own wp_mail_failed so anything already listening for mail failures keeps working. A false is not a diagnosis. The SES error is.

And there is one thing the plugin pointedly refuses to do: fall back to PHP mail(). A fallback feels like the safe, considerate choice, and it is the exact opposite. Falling back means the mail appears to send, wp_mail() returns true, and the message lands in spam, which is the silent failure we started with, dressed up as resilience. A loud failure gets noticed and fixed. A silent success that lands in spam is never even seen.

The same principle governs what happens when the plugin is misconfigured. It does not shrug and let WordPress use sendmail. It refuses to send, and says why, on every admin screen and in the log. A must-use plugin that quietly stands aside is worse than no plugin at all, because now you believe your mail is going through SES when it is going straight to the spam folder.

Same rejected send, two outcomes. The plugin throws, so the failure lands in core's own wp_mail_failed with the real SES reason and wp_mail() returns false. The path it replaces swallows the error and returns true, and the message is gone with nothing logged.

The part every tutorial skips: bounces and complaints

Send real mail at any volume and some of it will bounce: addresses go dead, mailboxes fill up, people hit the spam button. Amazon SES watches those two numbers, your bounce rate and your complaint rate, and it is not being advisory. Cross the thresholds and it throttles your sending; stay across them and it suspends the account outright. One careless WordPress install, cheerfully emailing a list of addresses that stopped existing years ago, is enough to put a whole domain's ability to send at risk.

WordPress, left alone, will do exactly that. It has no memory of a bounce. Ask it to email a deleted address a thousand times and it will try a thousand times, because nothing in wp_mail() ever hears that the last nine hundred and ninety-nine failed.

So the plugin keeps the memory WordPress lacks. SES publishes every bounce and complaint to an SNS topic; the plugin exposes one endpoint for that topic, writes each dead or complaining address to a suppression table, and checks that table before every send. An address that hard-bounced or marked you as spam is simply never sent to again. That one feedback loop is most of the distance between a plugin that works on your blog and one you would run under a masthead. And if the plugin cannot record a bounce for a moment, a database blip mid-notification, it does not pretend it succeeded: it tells SNS so, and SNS holds the message and delivers it again, rather than letting a bounce quietly evaporate.

There is a sharp edge here that is easy to miss, and getting it wrong is worse than not having the feature at all. That SNS endpoint is a public URL. Anything on the internet can POST to it. An endpoint that believes whatever it receives is an open invitation: forge a notification and you could add any address you liked to the suppression list, silently blocking a site's own users from ever receiving its mail. So the endpoint trusts nothing by default. It pins the single SNS topic it is allowed to act on, and it verifies Amazon's cryptographic signature on every message before one row is written. A notification that is not from your topic, or whose signature does not check out, is refused. The last plugin taught the same lesson from the other side: the input you do not validate is the one that hurts you.

The traps worth naming

None of these are subtle once you know them, and every one has cost someone an afternoon. Named here so they cost you none:

Sandbox mode. A fresh SES account is sandboxed: it can only send to addresses you have verified, and the quota is tiny. Everything looks configured, and mail to real recipients is refused. The one-time fix is to request production access; the plugin's verify command tells you which mode you are in.
Region mismatch. SES identities are per-region. Verify your domain in eu-west-1, point the plugin at us-east-1, and every send fails for a reason that has nothing to do with your code. Send from the region you verified in.
An unverified From. SES will only send as an identity you own and have verified. The From domain has to be a verified identity, or the send is rejected outright, loudly, which is the whole point.
Alignment is DNS, not code. DKIM and SPF passing is what carries you to the inbox, and both are records you add, not switches the plugin can flip. Turn on Easy DKIM (the three CNAMEs SES hands you), set a custom MAIL FROM so SPF aligns, and DMARC then passes. The plugin signs the request; your DNS is what makes the result trusted.
The quotas are real. SES caps both a per-second rate and a rolling twenty-four-hour volume. A blast that ignores them does not queue politely, it fails. Know your limits before you lean on them.

Verifying it, and why the checker refuses to lie

A must-use plugin that sends mail silently is the problem. A plugin that tells you it is configured when it is not is the same problem wearing a badge. So the plugin ships a command whose entire job is to refuse to lie about its own health:

wp ses verify

It signs two real requests to SES with the exact code the send path uses, so a green result is proof the signing works, not a mock of it. It reports the things that actually break delivery: which region it is talking to, where the credentials came from (a role, ideally, not a stray key shadowing it), whether the From identity is verified, whether DKIM is on, whether the account is still sandboxed, the current quota, and whether the bounce topic is wired up. And it exits non-zero when any of that is wrong, so it composes:

wp ses verify || send-me-an-alert

Put that line in cron and a drifted config pages you before your users find it. This is the same discipline as the verify command in the slug plugin: a checker earns the right to say PASS by exercising the real thing, and it reports a failure it has not disproven rather than a reassuring green it has not earned. A check that cannot fail is not a check.

The plugin

It is one file. Drop it into wp-content/mu-plugins/, add a region and a From address to wp-config.php, give the machine an IAM role that can call SES, and WordPress mail goes through SES from the next send. No AWS SDK, no settings screen, no credentials in the database.

One honest word on where it is in its life: it is new. It is feature-complete and has been hardened through repeated adversarial review, with the SES signing checked against AWS's own test vectors, but I am shipping it as 0.9.0 while I run it end-to-end against a live SES account. So it is out in the open under the GPL, on GitHub and on Packagist, being finished in daylight rather than behind a curtain:

composer require mantekio/wp-ses-mail

The repository is github.com/mantekio/wp-ses-mail. It is the same loop as the last one: the article explains the thinking, the repository is the working plugin, the package is the one-line install, and each points at the other two.

Known limits

Being honest about what a tool does not do is part of the tool. This one has edges worth stating plainly:

It is a transport, not a mailing-list engine. It sends the mail WordPress already wants to send, one message at a time, well. A newsletter blast to tens of thousands of subscribers wants a queue and probably a dedicated bulk sender; leaning on this for that just meets SES throttling as a failed send.
No retry or backoff yet. A send SES refuses fails loudly and stops. It does not queue and try again later. For transactional mail that is usually the right behaviour (you want to know now); if you need durable retries, that is a queue in front of the plugin, not the plugin.
There is a message-size ceiling. SES caps the size of a single message. A mail with very large inline attachments can exceed it, and that send will fail rather than be silently truncated.
Alignment is yours to configure. The plugin signs every message, but DKIM, SPF and DMARC alignment are DNS decisions it cannot make for you. It can tell you they are missing; it cannot add the records.
It needs WordPress 5.7 or newer. The whole clean design rests on pre_wp_mail, which arrived in 5.7. On anything older there is no seam to take: mail falls through to sendmail, and the plugin can warn you but cannot stop it. If you are on a WordPress that old, the mail path is not the first thing to fix.

Sending an email from WordPress is easy. Running mail you can trust for a newsroom, where a lost password reset is a locked-out journalist and a suspended domain is every address on it going quiet, is a different job, and the difference lives entirely in the boring parts. No secret at rest, because there is no secret. A failure you can see, because silence is the bug. A memory of every bounce, because SES keeps score whether or not you do. None of it is clever. All of it is the distance between mail that works on a blog and mail that holds up under a masthead.

That is the whole of how we treat WordPress on AWS: take the seam core gives you, store nothing you would mind leaking, and fail where someone can see it. If your WordPress mail is a mystery you would rather it were not, let's talk.

The day YouTube deleted our channel

Jaafar Abazid — Sat, 04 Jul 2026 22:39:51 +0000

It took a single notice. The YouTube channel that held years of a newsroom's
video was gone in one action, and every video embed across the site was suddenly
pointing at something that no longer existed. On a publication that runs video on
most of its articles, that is the kind of morning that empties an archive.

It was a non-event. We changed one setting, the whole site began playing the same
videos from our own storage, and readers never saw a gap. This is the story of why
a deleted channel was a configuration change rather than a catastrophe, and the one
decision, made years earlier, that made the difference.

Platforms can delete you, and you do not get a vote

Channels and accounts get removed for all sorts of reasons, and most of them are
not a fair fight: an automated copyright match against music in the background, a
strike from a report, a policy you did not know had changed, a regional block, an
API quietly deprecated, or an entire product shut down (the internet is littered
with services that were permanent right up until they were not).

The common thread is that the decision is theirs, the timing is theirs, and the
content you put on their platform was never fully in your hands. For a newsroom,
video on a third-party platform is best treated as reach, not as custody.

Publish to platforms, never store on them

The decision that turned the incident into a shrug was made on the very first
upload: every video goes to our own S3 bucket first. The original lives with us.
Pushing a copy out to YouTube, Dailymotion or Vimeo is a distribution step, for
reach and free bandwidth, not the place the file actually lives.

It is the same discipline behind the rest of our media handling: the original is
offloaded to storage we control on upload, and everything downstream is a copy or
a rendition of it. So when a platform pulls a video, or an entire channel, nothing
is actually lost. The master is still sitting in the bucket exactly where it was
put.

One video, four sources

On top of that, each video is a single logical asset with up to four play sources
linked behind it: YouTube, Dailymotion, Vimeo, and Amazon (the file served from
our own S3 through CloudFront).

The important word is source. Where a video plays is a stored setting, not an
embed baked into the post. That one distinction is the whole game. If the player
reads a source field, you can change where every video comes from without editing
a single article. If instead every post contains a literal YouTube iframe,
changing the source later is a database migration under pressure, which is exactly
when you do not want one.

The original lives in S3 and is published out to YouTube, Dailymotion and Vimeo. Where a video actually plays is a stored setting, a site-wide default with a per-video override, so any source can be the active one.

Two dials: site-wide and per video

The source has two levels of control.

Site-wide, you set the default that every video plays from. We ran on YouTube,
because that is where the audience and the bandwidth were.

Per video, you can override that default, and in a newsroom that is not a rare
event. Long videos that carry clips or background music from other sources get
flagged by YouTube's automated Content ID constantly, often even when you hold the
rights, and clearing a strike means filing an appeal and waiting days. So those
videos are set, right there on the upload screen, to play from Dailymotion, Vimeo
or S3 instead, while the rest of the library stays on YouTube. The content most
likely to be struck simply sidesteps the platform that polices it hardest, with no
downtime and no appeal queue.

The site-wide default sets the source for every video at once. A per-video override pins a single clip to another source: the long documentary full of licensed music is set to Vimeo on the upload screen, so it sidesteps the platform most likely to strike it, while everything else stays on the default.

The day the whole channel went

Then the version of the problem you cannot patch one video at a time: the entire
channel was deleted at once. Every video that defaulted to YouTube would fail in
the player, all at the same moment, across the whole archive.

Because the play source was a single site-wide setting, and because every original
was already sitting in S3, the fix was to change the default from YouTube to Amazon
and save. Every embed on the site re-pointed to the S3 copies, served through
CloudFront, in one action. The outage was as long as it takes to change a dropdown.

Compare that to the alternative if YouTube had been the storage rather than a
distribution target: the archive would simply be gone, and the "recovery" would be
re-sourcing and re-uploading thousands of videos that no longer existed.

When the channel was deleted, every video that defaulted to YouTube failed at once. Because the play source is a single site-wide setting and the originals were already in S3, changing the default to Amazon restored the entire archive in one click.

The fallback is not a downgrade

It is worth being clear that playing from your own infrastructure is not a degraded
emergency mode. The S3 source plays through CloudFront like any other CDN-backed
asset. When you want adaptive streaming at scale, you put it in front: an upload
event triggers AWS Elemental MediaConvert to produce HLS renditions, CloudFront
caches the segments, and a standard player streams quality that adapts to each
viewer's connection.

In other words, falling back to your own storage is not making do. For many sites
it is the best source they have. The platforms were the convenience, not the
foundation.

What it is really about: custody

Strip away the specifics and the principle is simple. Own the original, and treat
every external platform as interchangeable reach you opt into, never as the home of
your media. In practice that is three habits:

Keep the master somewhere you control (for us, S3).
Make playback a setting, not a hard-coded embed, so the source is a dial.
Publish to platforms for reach, but never let one become your only copy.

Do that, and platform risk (a strike, a deleted channel, a shut-down service, a
pricing change you cannot stomach) stops being an existential event and becomes a
switch you flip. The same thinking applies anywhere you syndicate: images to a CDN,
articles to third-party readers, audio to podcast directories. Keep the master,
keep the destination swappable.

A two-minute gut check for your own setup

Three questions worth answering honestly:

If your video platform closed your account tonight, do the originals exist anywhere else? If the only copy is on the platform, that is the first thing to fix, before anything clever.
Is playback a per-post embed, or a source you can change centrally? If it is baked into content, switching later is a migration, not a setting.
Do you publish to platforms, or store on them? Publishing is healthy. Storing is the trap.

If the answers make you uncomfortable, you already know where to start.

The bottom line

We keep newsrooms fast and unbreakable on WordPress and AWS, and
this is the resilience side of the same coin as keeping the media pipeline lean:
the originals never leave your control, so neither a platform nor a traffic spike
can take the archive down.

If your video lives on someone else's platform and losing it would hurt,
let's talk.

Make WordPress do less: offloading media to S3 and the edge

Jaafar Abazid — Mon, 29 Jun 2026 23:10:24 +0000

A default WordPress install does a surprising amount of work every time someone
uploads an image. It generates a stack of resized copies on the spot (thumbnail,
medium, medium_large, large, a couple of extra-large sizes, plus whatever the
theme registers), writes every one of them to disk, and records them in the
attachment metadata. Most are never requested. The CMS we replaced for one
newsroom generated more than twenty versions of every single image and stored
all of them. Multiply that across an archive of hundreds of thousands of photos
and you are paying, in storage and in upload-time CPU, for work nobody asked for.

Video is the opposite extreme. A single original broadcast clip can run to several
gigabytes, and pushing that upload through the web server (PHP memory limits,
request timeouts, a reverse proxy in the middle) is a reliable way to fall over.

The media pipeline we run for NUZ takes both problems off the server. On
the way in, the browser uploads large files straight to S3. On the way out, the
edge produces exactly the image sizes that are actually requested, and nothing
else. WordPress goes back to doing what it is good at, which is editorial, not
image processing. This is the same WordPress-on-AWS work we have written about
surviving breaking-news spikes
with, viewed from the storage side.

The shape of it

Two ideas carry the whole design:

Store little, derive on demand. For images, keep two copies in S3: the pristine original in cold storage, and one working master in hot storage. Every size a visitor sees is produced on the fly at the CDN and lives only in the CDN cache, never in S3.
Move the heavy lifting to the ends. Large uploads go from the browser directly to S3. Transformations happen at the edge. The origin server stays out of the byte path in both directions.

Everything below is an application of those two rules, plus the WordPress glue
that makes them invisible to editors.

One upload becomes two stored objects: a cold original you keep, and a hot working master the edge resizes on demand. Every size a visitor sees is produced by the Image Handler and cached at the CDN, never stored in S3.

Stop WordPress from making thumbnails

This is the change that surprises people, so it goes first: we turn off
WordPress's intermediate image generation entirely. If the edge can produce any
size on request, pre-generating a fixed menu of sizes on upload is pure waste:
CPU and I/O at the worst possible moment (while the editor waits), and a pile of
files that mostly never get served.

In the NUZ theme it is a couple of filters:

// Stop WordPress generating intermediate sizes on upload.
add_filter( 'intermediate_image_sizes_advanced', '__return_empty_array' );

// Keep the true original: don't let WordPress downscale large uploads to 2560px.
add_filter( 'big_image_size_threshold', '__return_false' );

The one catch worth planning for: once WordPress stops creating named sizes,
any code that asks for the_post_thumbnail( 'medium' ) or a registered size has
to resolve to the edge instead. So the same theme layer maps each requested size
to an edge URL with the right dimensions. Skip that step and you get broken
images where a medium used to be. Handle it once, in the hooks that build image
URLs, and editors never notice the difference.

Resize at the edge, not on upload

The hot working master is the only image S3 serves to the transformer, and the
transformer is the AWS Serverless Image
Handler:
CloudFront in front of a Lambda that runs Sharp. A request describes the
transformation it wants in the URL, the Lambda produces it once, and CloudFront
caches the result. The URL form is configurable; the Thumbor-style path is easy
to read:

https://cdn.example.com/fit-in/800x0/filters:format(webp):quality(80)/20250727-1753632511534.jpg

Three things matter here:

Format negotiation. Ask for format(auto) and modern browsers get AVIF or WebP by their Accept header, older ones get JPEG, from one master.
Compute only on a miss. The Lambda runs the first time a given size is requested. After that CloudFront serves it. Sizes nobody requests cost nothing.
Nothing extra in S3. Derivatives live in the CDN cache, not the bucket. The bucket holds two objects per image, forever.

Two copies, two storage classes

The original and the master have different jobs, so they get different homes:

Copy	Storage tier	Why
Original (full-resolution, as shot)	Cold · S3 Glacier Instant Retrieval	Rarely read, but you may need it fast one day; millisecond retrieval at a fraction of Standard's price
Working master (high-quality, max served dimension)	Hot · S3 Standard	The transformer's source; read often, downscaled to every served size

A lifecycle policy moves originals to the cold class automatically. We avoid
Glacier Deep Archive precisely because retrieval there takes hours, and the whole
point of keeping the original is to be able to re-derive from it. The master is not the raw original. It is a web-optimised copy: sized to the
largest dimension you will ever serve (no 4K masters when nothing on the page ever
renders past, say, 2048px) and stored in an efficient format (WebP for images,
WebM for video). Optimise the dimensions and the format, but keep the quality
near-lossless, so every derivative downscales from a clean source rather than
inheriting compression artefacts.

Clean keys, by generation not by accident

We never store a file under the name the user uploaded. On upload we generate an
ASCII-safe, time-based key with a millisecond stamp and a short random suffix,
something like:

20250727-1753632511534

The generator is small: a UTC date, a millisecond timestamp, and a short random
suffix against same-millisecond collisions, with the extension carried over:

function nuz_media_key( $ext ) {
    $stamp = gmdate( 'Ymd' ) . '-' . (int) round( microtime( true ) * 1000 );
    return $stamp . '-' . wp_generate_password( 6, false, false ) . '.' . strtolower( $ext );
}
// e.g. 20250727-1753632511534-h7k2qp.jpg

For an Arabic newsroom this is not cosmetic. Original filenames arrive full of
Arabic characters and spaces, which become percent-encoded mojibake the moment
they enter a URL or an object key, the same class of encoding trap we dissected
in the 200-byte slug problem.
Generating the key sidesteps all of it: keys stay short, ASCII, and predictable.

There is a quiet bonus. Because every upload gets a unique key, replacing an
asset produces a new URL, so there is no stale-cache problem to solve at the
CDN. You never have to invalidate; the old object simply stops being referenced.
Clean keys and cache-busting turn out to be the same decision.

The WordPress glue

None of this should leak into the editing experience, and the seam that keeps it
invisible is URL generation. The NUZ theme overrides WordPress's default asset
handling with hooks rather than rewriting the database, so the content stays
portable and the behaviour is reversible. The functions that build image URLs
(wp_get_attachment_url, wp_get_attachment_image_src,
wp_calculate_image_srcset and friends) return edge URLs at render time. In
practice that is one filter per entry point, each mapping the requested size to a
transformation the edge understands:

// Point a requested size at the Serverless Image Handler instead of a local file.
add_filter( 'wp_get_attachment_image_src', function ( $image, $id, $size ) {
    if ( ! $image ) {
        return $image;
    }
    [ $w, $h ] = nuz_dimensions_for( $size );     // 'medium' => [800, 0], etc.
    $key = get_post_meta( $id, '_wp_attached_file', true );
    $image[0] = sprintf(
        'https://cdn.example.com/fit-in/%dx%d/filters:format(auto):quality(80)/%s',
        $w, $h, $key
    );
    return $image;
}, 10, 3 );

📦 Prefer it ready-made? The image-delivery half of this (disabling intermediate sizes and rewriting image URLs to the Image Handler, with a synthesized srcset) is open-source as mantekio/wp-edge-images, or composer require mantekio/wp-edge-images. It is URL layer only, so it pairs with any S3 offload.

If you are migrating an existing library, one caveat is worth stating plainly:
the URLs that actually serve images live in post_content (embedded when an
image is inserted) and are generated from the _wp_attached_file meta, not in
the guid column. The guid looks like the file URL but is an identifier, and
WordPress documentation is explicit that you should not rewrite it. So a one-time
migration targets post_content; ongoing serving is best handled with the
runtime hooks above.

Big video: let the browser do the upload

Images are small and cheap to transform, so we generate them on demand. Video is
neither, so it plays by opposite rules.

The problem is the upload itself. Original television files are large, and they
should not travel through WordPress at all. So the editor works in a custom
upload screen that asks our admin endpoint for a short-lived presigned S3 URL,
then sends the file from the browser straight to the bucket:

// 1) ask the server for a presigned URL, scoped to one key + content type, short-lived
const { url, key } = await fetch('/nuz/presign?type=video/mp4').then(r => r.json());

// 2) PUT the file directly to S3 from the browser, with a real progress bar
await putWithProgress(url, file, onProgress); // XHR upload events drive the bar

On the server the presign is a few lines with the AWS SDK, scoped to one key, one
content type, and a short expiry:

$s3  = new Aws\S3\S3Client( [ 'region' => 'me-central-1', 'version' => 'latest' ] );
$key = 'videos/' . nuz_media_key( 'mp4' );
$req = $s3->createPresignedRequest(
    $s3->getCommand( 'PutObject', [
        'Bucket'      => 'nuz-media-hot',
        'Key'         => $key,
        'ContentType' => 'video/mp4',
    ] ),
    '+15 minutes'
);
wp_send_json( [ 'url' => (string) $req->getUri(), 'key' => $key ] );

The server signs a tightly scoped, expiring URL and never touches the bytes.
The browser handles the transfer, the upload screen shows a progress bar (a
multi-gigabyte broadcast file can take a while, and editors need to see it
moving), and the same screen collects the title, the cover image, and the rest of
the metadata. From there, one click distributes the video to YouTube, Dailymotion
or Vimeo, streamed directly from S3 to each platform's resumable-upload API. The
editor never uploads again: the file already lives in S3, so distribution is a
server-to-server transfer, not a second upload of the file. The newsroom publishes
once and distributes everywhere, without a gigabyte ever passing through PHP.

For on-site playback you extend the same pattern: an S3 upload event triggers
AWS Elemental MediaConvert, which transcodes the source into adaptive-bitrate
renditions (HLS or DASH) plus a poster frame, stores the renditions in the hot
bucket, and serves them through CloudFront to an hls.js player. Note the
inversion from images: video transformation is expensive, so you do it once on
upload and store the result, rather than per request. Storing little works for
images precisely because resizing is cheap; storing renditions works for video
precisely because transcoding is not.

Images are cheap to resize, so the edge generates each size on demand and stores nothing extra. Video is expensive to transcode, so you do it once on upload and store the renditions. Opposite strategies, same bucket.

What it saves

No hard numbers to share here, but the shape of the win is consistent:

Storage. Two image objects instead of twenty-plus. Originals on a cold class that costs a fraction of Standard.
Server load. No thumbnail jobs competing for CPU on every upload, and no multi-gigabyte uploads occupying PHP workers, memory and connections.
Delivery. Variants are produced once at the edge and cached, so origin and Lambda costs scale with unique sizes requested, not with traffic.

The pattern is "let each layer do what it is best at": the browser moves bytes,
S3 stores them, the edge transforms them, MediaConvert handles the expensive
video work, and WordPress orchestrates editorial without carrying the files.

Gotchas worth knowing

Lock the buckets. Neither bucket is public. CloudFront reads via Origin Access Control; the transformer reads via its execution role. Public buckets are how media libraries leak.
Presigned uploads need guardrails. Scope each URL to a single key, a content type and a short expiry, and configure S3 CORS for the admin origin. A presigned URL is a capability; keep it narrow and short-lived.
Don't compound compression. A lossy working master makes every derivative worse. Keep the master near-lossless.
Mind the named-size mapping. The day you disable WordPress sizes, audit the theme and plugins for hard-coded size names and make sure they resolve to the edge.

The deeper point

The instinct with a media library is to make the CMS responsible for everything:
storing, resizing, naming, serving. The leaner design is to make the CMS
responsible for almost none of it, and to let purpose-built layers each take one
job. WordPress stays fast and boring, which is exactly what you want from the
system your newsroom logs into every day.

This is the kind of architecture we build and run on
WordPress + AWS. If you are wrestling a heavy media library on
WordPress, let's talk.

Short links that outlive the vendor: a newsroom URL shortener on WordPress and AWS

Jaafar Abazid — Wed, 24 Jun 2026 20:32:21 +0000

An editor hits publish on a breaking story and pushes it to a million followers.
The headline is sharp. The link beneath it is forty characters of
%D8%A7%D9%84%D8%B0..., unreadable, often cut off by the platform, telling the
reader nothing about where the tap will take them.

That is what a long URL looks like on social when the slug is Arabic. WordPress
stores and emits the slug percent-encoded, so a clean Arabic headline turns into
a wall of %XX bytes the moment it leaves your site:

/الذكاء-الاصطناعي  →  /%D8%A7%D9%84%D8%B0%D9%83%D8%A7%D8%A1-%D8%A7%D9%84%D8%A7%D8%B5%D8%B7%D9%86%D8%A7%D8%B9%D9%8A

(We have written before about how those Arabic slugs get truncated in the first
place. This is the other half of the
story: what happens to them out in the world.)

Every serious newsroom solves this the same way, with branded short links:
sho.rt/9Kx2a instead of the wall of bytes. Short, on brand, and the same length
whether the article is Arabic, English, or anything else. The only real question
is whether you buy that capability from a service like Bitly or TinyURL, or build
it yourself.

We did both, on purpose. Here is why, and how.

Why both

A short link, once shared, is effectively permanent. It lives in tweets, Telegram
channels, WhatsApp forwards, and printed QR codes for years. So the day a vendor
raises its prices, retires a feature, or simply shuts down, every one of those
links dies, and the traffic with them. For a newsroom whose archive is its
capital, that is not an acceptable dependency.

So we set one rule: the ability to resolve our own short links must never depend
on a company we do not control. Buy the convenience, own the lifeline.

In practice that means Bitly serves the short domain today, because it gives the
newsroom polished click analytics and a link UI editors like. But sitting behind
it, fully in sync, is an in-house resolver running on our own AWS edge, ready to
take over with a single DNS change. The reader never sees the seam, because the
short codes are identical on both fronts. This runs on the same WordPress and AWS
stack we have written about before:
WordPress on EC2 behind an Application Load Balancer, Aurora for the database, and
CloudFront at the edge.

One short code, two interchangeable fronts. DNS decides who answers, so failover is a single DNS change, and the reader always lands on the same canonical article.

The one decision everything hangs on

Before any infrastructure, there is a single design choice that makes the rest
possible: one short ID, minted once in WordPress, reused everywhere. The same
string is the key in our database, the key in DynamoDB, and the custom back-half
on Bitly.

Because 9Kx2a is literally the same value in all three places, switching who
answers the short domain is invisible to anyone holding the link. There is no
remapping, no lookup table between vendors, no links left behind. That one
decision is what turns "own the lifeline" from a slogan into a DNS change.
Everything below serves it.

Generating the ID

The ID is drawn from a 64-character, URL-safe alphabet: A-Z, a-z, 0-9, plus
- and _. Those 64 characters all live in a URL path without encoding, so the
short link stays clean no matter what.

We generate it only when a post is published, never on draft. That keeps the
keyspace clean (no IDs burned on posts that never go live), avoids leaking a URL
for unpublished work, and means a short link never resolves to a 404 or a private
draft. A short link should only ever exist for something a reader can actually
read.

The generator uses a cryptographic random source, not rand(), so codes are not
guessable or enumerable, and it leans on a UNIQUE constraint to stay correct:

const SHORTLINK_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
const SHORTLINK_LENGTH   = 5;  // 64^5 ≈ 1.07B. Use 6 for ≈ 68.7B of headroom.

function mantek_generate_short_id(): string {
    $alphabet = SHORTLINK_ALPHABET;
    $max      = strlen( $alphabet ) - 1;
    $id       = '';
    for ( $i = 0; $i < SHORTLINK_LENGTH; $i++ ) {
        $id .= $alphabet[ random_int( 0, $max ) ];  // CSPRNG: not guessable
    }
    return $id;
}

// Runs on the publish transition only. The UNIQUE index on short_id turns a
// collision into a failed INSERT, so we simply re-mint and try again.
function mantek_assign_short_id( int $post_id ): string {
    global $wpdb;
    $table = $wpdb->prefix . 'short_links';

    for ( $attempt = 0; $attempt < 5; $attempt++ ) {
        $short_id = mantek_generate_short_id();
        $inserted = $wpdb->query( $wpdb->prepare(
            "INSERT INTO {$table} (short_id, post_id, full_url, provider, status, created_at)
             VALUES (%s, %d, %s, %s, 'active', NOW())",
            $short_id, $post_id, get_permalink( $post_id ), mantek_active_provider()
        ) );
        if ( false !== $inserted ) {
            return $short_id;  // clean insert: the ID was free
        }
        // Duplicate key (MySQL 1062): the ID was taken. Loop and re-mint.
    }
    throw new RuntimeException( "Could not mint a unique short_id for post {$post_id}" );
}

A fair question: with random generation, will codes collide? Yes, and you must
plan for it rather than hope. The maths is the birthday problem, not the raw
keyspace: at five characters you have a better-than-even chance of some
collision once you have minted roughly 38,000 links, which a busy newsroom passes
within a year. That is exactly why the UNIQUE constraint and the retry loop are
not optional.

What that maths does not mean is that the retry fires often. The chance that any
single new code clashes is the number of live links divided by the keyspace, so
even at a million live links roughly one insert in a thousand needs a second try,
and a third try is a one-in-a-million event. Five characters with the retry is
comfortable essentially forever; six characters (about 68.7 billion) makes the
retry all but theoretical, at the cost of one extra character. Pick five unless
you want the longest possible runway.

Where the mapping lives

The short code needs a home in WordPress. The tempting shortcut is the existing
guid column on wp_posts, since it already holds something URL-shaped. Resist
it (more on why in a moment). We use a dedicated table instead:

Column	Role
`short_id`	the code itself, with a `UNIQUE` index for the retry loop and the reverse lookup
`post_id`	the local post this code is attached to, used to refresh `full_url`; instance-local, never used for resolution
`full_url`	the article's current canonical URL, a pointer we refresh when it changes
`provider`	which backend was active when the code was minted (`bitly`, `inhouse`); a historical marker, since the DNS is the real router
`status`	lifecycle: `active`, `pending`, or `gone`, so the resolver knows what to do when a post is unpublished
`created_at` / `updated_at`	timestamps for reconciliation

A dedicated table owns its own schema, is properly indexed for the reverse lookup,
and has zero blast radius on the rest of WordPress.

Why not just reuse the guid column? Because the GUID is not a usable URL,
despite looking like one. Its real job is to be a permanent, never-changed
identifier that feed readers use to decide whether an item is new. Overwrite it
and you risk re-notifying every subscriber, breaking the WXR importer's
de-duplication (and newsrooms migrate often), and corrupting media references,
since for attachments the GUID is the real file URL. Indexing it also means
altering a core table. A dedicated table avoids all of that for almost nothing.

Resolving at the edge: redirect, not proxy

Here is the most important architectural decision, and the one most people get
subtly wrong. A short link should redirect. It resolves the code to the
article's URL and returns a 301, and the reader's browser then loads the real
article from the normal stack. The short-link layer never fetches or serves the
article's HTML itself.

The alternative, serving the article's HTML under the short URL, is a trap. It
splits every article across two URLs, which confuses search engines and forces
canonical-tag gymnastics, it leaves the reader looking at a sho.rt address
instead of your trusted domain, and it doubles your cache, since CloudFront now
stores the full article twice. The redirect keeps the short-link layer trivially
small: the cached object is a few hundred bytes, and it points everyone at the one
canonical article.

That also dissolves a performance worry worth naming. Resolving a short link is
one key lookup followed by a redirect. It never disassembles the full URL into
date, category, and slug, and it never runs a WP_Query. WordPress already
resolves its permalinks once, for all traffic, and CloudFront caches the result.
The short link does not add that cost; it just prepends a tiny redirect hop in
front of it.

The in-house path works like this. The short domain's DNS points at CloudFront. On
a cache hit, CloudFront returns the cached 301 immediately, with no compute at
all. On a miss, it runs a small Lambda@Edge function that does a single DynamoDB
lookup on the short code, builds the redirect, and caches it for next time:

// Lambda@Edge, viewer-request on the short domain's CloudFront distribution.
// Resolves /<short_id> to a 301 toward the article's current URL.
const { DynamoDBClient, GetItemCommand } = require('@aws-sdk/client-dynamodb');
const ddb = new DynamoDBClient({ region: 'us-east-1' });

exports.handler = async (event) => {
  const request = event.Records[0].cf.request;
  const shortId = request.uri.replace(/^\/+/, '').split('/')[0];
  if (!shortId) return notFound();

  const { Item } = await ddb.send(new GetItemCommand({
    TableName: 'short_links',
    Key: { short_id: { S: shortId } },
    ProjectionExpression: 'full_url, #s',
    ExpressionAttributeNames: { '#s': 'status' },
  }));

  if (!Item || Item.status?.S === 'gone') return goneOrNotFound(Item);

  const target = Item.full_url.S;
  if (!isOwnDomain(target)) return notFound();  // open-redirect guard

  return {
    status: '301',
    statusDescription: 'Moved Permanently',
    headers: {
      location:        [{ key: 'Location',      value: appendUtm(target) }],
      'cache-control': [{ key: 'Cache-Control', value: 'public, max-age=86400' }],
    },
  };
};

A DynamoDB lookup on the partition key is single-digit milliseconds, and most hits
never reach it anyway, because CloudFront is serving the cached redirect. One
detail to know: a Lambda@Edge function is authored in us-east-1 and replicated to
every edge, and its DynamoDB call reaches the table's home region, so for global
low latency you either replicate the table with DynamoDB Global Tables or front it
with DAX. In practice it rarely bites, precisely because the cache absorbs the vast
majority of requests.

A few decisions baked into that function:

301, not 302. We want search engines to consolidate the article's ranking signals on the canonical URL, and they treat the 301 status itself as that signal. The explicit Cache-Control keeps the redirect from being pinned forever in browser caches, so a later URL change is still picked up.
Open-redirect guard. The resolver only ever sends readers to our own domains. An unknown or tampered target returns a plain 404, so the shortener can never be abused to bounce users to a phishing page. Random codes make scanning for valid links low-yield too.
API Gateway, honestly. You will see URL shorteners put API Gateway in this path. Its only real job there is to expose a regional Lambda to CloudFront as an origin. For a pure redirect you usually do not need it: Lambda@Edge resolves directly, and where a regional function is preferred, a Lambda Function URL is a lighter front door. (This architecture already runs API Gateway, but for headless apps, not for the shortener.)

Resolving the short link is one cached redirect at the edge, with a DynamoDB lookup only on a cache miss. The browser then follows the 301 to the article through the normal stack, exactly like any other reader.

Migration-proof by design

Notice what we actually resolve by. The durable handle is the short_id itself,
the value we mint, control, and put out into the world. The full_url is just a
pointer we keep current beside it. That pairing is what lets a short link outlast
not only a vendor but your own URL scheme.

It is worth being precise about why, because the obvious candidate for a permanent
identity, the WordPress post_id, is not actually stable. Post IDs are
auto-increment integers local to one database; migrate to a fresh WordPress (or to
anything else) and they get reassigned. So we never resolve by post_id. We
resolve by the short_id, and we carry the short_id → full_url mapping across
every migration, refreshing full_url to wherever the article now lives. Newsrooms
re-platform, restructure categories, and change permalink patterns over the years,
and each time the old URLs change. A short link keyed on the ID we own does not
care: share sho.rt/9Kx2a once, and it keeps landing on the right article through
every future migration, because resolution ends at a code we control, never at a
database's internal ID or a frozen URL string.

The one rule that keeps this true: when an article's URL changes, update the
full_url in DynamoDB and invalidate the cached redirect. Active invalidation is
the primary mechanism, so the change is picked up at once, and the bounded
Cache-Control is a safety net that heals anything an invalidation missed within a
day. For an everyday slug edit, invalidate the single path. For a mass migration of
thousands of URLs at once, let a short TTL expire instead, since firing thousands
of individual invalidations is slower and costlier. This is also why the serving
mapping lives in DynamoDB rather than only inside WordPress: it sits outside the
CMS, so it survives any migration by definition. After a re-platform you refresh the
full_url values to the new URLs, and every link already in the wild keeps
resolving.

Keeping the stores in sync at publish

When a post goes live, three things happen in order: WordPress mints the ID into
its own table, upserts the mapping into DynamoDB, and calls the active shortener.
Each store has a clear, non-overlapping role:

Store	Role
WordPress (`wp_short_links`)	Authoring source of truth: mints the ID, knows the canonical URL
DynamoDB	Serving source of truth at the edge, and the vendor-neutral warm standby
Bitly	Downstream replica: the active analytics front today, and swappable

The honest complication with writing to three places is partial failure: the
DynamoDB write succeeds but the Bitly call times out, say. So the external call
goes through a small queue (SQS) with retries, so a transient blip never silently
loses a mapping, and a periodic reconciliation job diffs WordPress against
DynamoDB and Bitly to catch any drift. WordPress is always the tie-breaker.

On publish, WordPress mints the id and writes its own table, then upserts DynamoDB and enqueues the Bitly call through SQS, so a transient failure never loses a mapping. WordPress stays the source of truth.

Why Bitly, and how we keep it swappable

The call to the shortener does not name Bitly. It goes through an interface, so
Bitly is one implementation behind a contract the rest of the code never has to
think about:

interface ShortLinkProvider {
    public function create( string $shortId, string $fullUrl ): ShortLinkResult;
    public function updateTarget( string $shortId, string $newUrl ): ShortLinkResult;
    public function stats( string $shortId ): ?ShortLinkStats;  // if the vendor exposes it
}

final class BitlyProvider implements ShortLinkProvider {
    public function create( string $shortId, string $fullUrl ): ShortLinkResult {
        $res = $this->api( 'POST', '/v4/bitlinks', [
            'long_url'       => $fullUrl,
            'domain'         => $this->brandedDomain,               // our custom short domain
            'custom_bitlink' => "{$this->brandedDomain}/{$shortId}", // our ID as the back-half
        ] );

        // Bitly may SILENTLY fall back to a random back-half if ours is somehow
        // taken, instead of failing. Never accept that: it would break the
        // "same ID everywhere" invariant. Assert it returned exactly what we asked.
        if ( $res->backHalf() !== $shortId ) {
            throw new ShortLinkCollision( $shortId );  // caller re-mints and retries
        }
        return ShortLinkResult::ok( $res->link() );
    }
    // updateTarget(), stats() ...
}

Two things we confirmed against Bitly's own documentation before relying on them:

Custom back-halves are unique per branded domain, not globally. On our own short domain, any code that is unique in our database is automatically unique on Bitly, so our UNIQUE constraint is the single source of truth. No second uniqueness problem to manage.
Bitly links are case-sensitive, which is why our mixed-case alphabet is safe and why 9Kx2a and 9kX2A are different links.

The one trap, captured in the code above: if you request a custom back-half that is
already in use, Bitly may return a link with a random back-half rather than an
error. Accept that blindly and your database says 9Kx2a while Bitly serves
something else. The integration must assert the returned back-half matches the
requested one, and treat a mismatch as a collision.

While Bitly is the active front, our DynamoDB table is effectively write-only,
since the short domain points at Bitly and our resolver is never triggered. That is
not waste, it is a warm standby. Storing a few hundred bytes per link and doing the
occasional write costs almost nothing, and it is exactly what makes failover a DNS
change rather than a frantic rebuild.

The payoff: failover is a DNS change

Put it together and the failover story is almost boring, which is the point. The
short domain points at Bitly today. To take it back in-house, you repoint its DNS
to our CloudFront distribution. Every link already in the wild keeps working,
because the codes are identical on both fronts and our DynamoDB table already holds
every mapping.

The one operational honesty here: that cutover is only as fast as DNS lets it be,
and the TTL is a knob you manage, not a constant. In steady state, pointing at
Bitly with no change in sight, a normal TTL (say an hour) is fine; the record is
not changing, so there is nothing to propagate faster. The TTL only matters around
a switch. For a planned move off Bitly, lower it to 60 to 300 seconds a day or two
ahead (long enough for the old, higher TTL to age out everywhere), make the change,
then raise it back. If instead you want to be ready for an unplanned failover, say
Bitly itself goes down, keep the TTL permanently low as cheap insurance, since the
cost on modern anycast DNS is negligible. One caveat: some resolvers clamp very low
values, so do not go below about 60 seconds or treat the TTL as an absolute
guarantee.

With DNS control on your side, the short-link layer survives a vendor shutdown, a
price hike, a removed feature, or a full CMS re-platform. The links keep resolving
regardless.

The honest part: analytics

If the in-house resolver can do everything, why pay Bitly at all? Analytics. Bitly
gives a newsroom per-link click counts, geographic and referrer breakdowns, an
editor-friendly UI for creating and tracking links, and the bot-filtering that
makes those numbers trustworthy. That is real product work, and it is the reason to
buy rather than build.

Could you build it? Yes, and the edge resolver is the perfect place to tap, because
every redirect is already an event. There are two complementary ways to capture it:

Client-side, by having the redirect append a marker (UTM parameters) to the destination, so the analytics already on the article page (GA4, or newsroom tools like Chartbeat and Parse.ly) attribute the visit. This counts human readers and naturally excludes bots.
Server-side, by having the resolver send a GA4 Measurement Protocol event on each resolution, which counts every hit including the ones that never render a page, closer to how Bitly counts.

One correction worth making, since it is a common assumption: GA cannot read the
request headers of a redirect, and the redirect runs no JavaScript. The signal that
reaches your analytics is the marker parameter or the server-side event, not a
header.

So the honest line is not "GA cannot track short links." It can. The gap is that
matching Bitly's per-link dashboards, editor UI, and bot filtering is a product you
would own and maintain, and for many newsrooms paying for that polish is the right
call. We built the durable core so we are never locked in, and we let Bitly handle
the analytics, with our own edge waiting as the hot standby. Buy the convenience,
own the lifeline.

That is the whole shape of it: build the part that must never disappear, the
resolution and the mapping, buy the convenience layer on top, and keep them
interchangeable so a vendor decision is never an existential one. A short link your
newsroom shared years ago should still land tomorrow, no matter who is answering
the domain.

This is the kind of WordPress and AWS engineering our practice is
built on. If you run a publication that lives on social and cannot afford to lose
the links it has shared, let's talk.

A WordPress update can silently truncate your long Arabic URLs — the bug's in core, in 3 places. I traced it and wrote a fix that survives every update: https://dev.to/jafarabazid/the-200-byte-trap-why-wordpress-core-updates-break-arabic-urls-5d5k

Jaafar Abazid — Sun, 21 Jun 2026 13:44:27 +0000

The 200-byte trap: why WordPress core updates break Arabic URLs - DEV Community

You update WordPress on a quiet afternoon, a routine release, the kind you've installed a hundred...

dev.to

The 200-byte trap: why WordPress core updates break Arabic URLs

Jaafar Abazid — Sun, 21 Jun 2026 12:47:31 +0000

You update WordPress on a quiet afternoon, a routine release, the kind you've
installed a hundred times. The dashboard says everything went fine. Then the
404s start: not a handful, but every long-headlined article in your archive, all
at once, all in Arabic.

Nothing in the update log mentions it. No plugin changed. And the cruel part:
the data that made those URLs work is already gone, shaved off inside a
database-upgrade routine that ran for a few milliseconds and reported success.
This isn't a freak accident or a broken plugin. It's three separate assumptions
baked into WordPress core, each hard-coding the same number, 200, and
Arabic sites are almost uniquely exposed to all three. We hit this running
WordPress for Arabic newsrooms, the same high-traffic publishing we've written
about surviving breaking-news spikes.
We traced it to the exact lines in core and built a fix that survives every
future update. Here's the whole story.

Why Arabic URLs hit a wall English never does

WordPress stores a post's slug in the post_name column of wp_posts, and a
category or tag slug in the slug column of wp_terms. Both are VARCHAR(200)
by default: room for 200 characters, which for an English headline is generous.
"Everything you need to know about our new pricing" is barely fifty. You'd have
to write a paragraph to run out.

Arabic is a different arithmetic, because of what WordPress actually stores in
that column. It doesn't keep the raw Arabic text; it stores the
percent-encoded form, the same %XX sequence that travels in the URL. Take a
single word:

الذكاء  →  %d8%a7%d9%84%d8%b0%d9%83%d8%a7%d8%a1

Every Arabic letter is two bytes in UTF-8, and every byte becomes a
three-character %XX token. So one Arabic character costs about six characters
of column space. Do the division: VARCHAR(200) holds roughly 33 Arabic
characters. A normal news headline, "القبض على المتهمين في قضية الاحتيال
الإلكتروني", blows past that before it's halfway done.

So Arabic publishers learn early to widen the columns:

ALTER TABLE wp_posts MODIFY post_name VARCHAR(1024) NOT NULL DEFAULT '';
ALTER TABLE wp_terms MODIFY slug      VARCHAR(1024) NOT NULL DEFAULT '';

VARCHAR(1024) holds about 170 Arabic characters, comfortable. Permalinks
resolve, the newsroom publishes, and the problem looks solved.

It isn't. It's about one-third solved, and the other two-thirds are waiting
for the next core update. (This isn't only an Arabic problem, either: any
non-Latin script that percent-encodes (Persian, Urdu, Hebrew, Greek) hits the
same wall. Arabic publishers just hit it first and hardest.)

The number 200 lives in three places, not one

Here's the insight that turns this from a recurring mystery into something you
can actually close out. WordPress hard-codes "200" in three independent
places, and widening the column only touches the first:

Layer	What it caps at 200	Does widening the column fix it?
1, Storage	the column that physically stores the slug	Yes, but a core update silently undoes it
2, Generation	every new slug, the moment it is created	No, it's PHP; needs a code override
3, De-duplication	slugs that collide and need a numeric suffix	No, but this only fires on collisions

Your ALTER fixes Layer 1's storage. But Layer 2 means that even with a
1024-wide column, every new slug is still cut to 200 bytes before it's ever
saved, unless something on your site already overrode it. (If long Arabic
slugs save correctly for you today, a plugin, your theme, or a past developer
already patched Layer 2, which means you have an undocumented dependency you
didn't know you were relying on.) And Layer 1, the storage you so carefully
widened, is exactly the one a core update quietly reverts. Let's take each in
turn.

Layer 1: how a core update erases your column width

WordPress keeps a canonical description of its own database schema, and on every
major update it reconciles the live database against that description. The chain
is short and deterministic:

A new release bumps $wp_db_version in version.php.
On the next admin request, wp_upgrade() notices the bump and runs the database upgrade.
That calls make_db_current_silent(), which calls dbDelta( wp_get_db_schema() ).
wp_get_db_schema() is the canonical schema, and it says, verbatim:

post_name varchar(200) NOT NULL default '',
...
slug varchar(200) NOT NULL default '',

dbDelta() then runs a DESCRIBE on every live table, compares each column to
the canonical definition, and for any mismatch emits an ALTER TABLE … CHANGE COLUMN to "correct" it. Your post_name is VARCHAR(1024); the canonical says
VARCHAR(200); they don't match, so dbDelta dutifully issues a CHANGE COLUMN
back to 200, MySQL rebuilds the table, and every byte past the 200th is
discarded.

Here's the detail that makes it unrecoverable. Years ago, core added downsize
protection to dbDelta, but only for TEXT and BLOB columns (it was
Trac #36748, born from exactly
this kind of data loss). VARCHAR got no such guard. So a TEXT column is safe
from accidental shrinking; your VARCHAR(1024) slug column is not. dbDelta
shrinks it without hesitation, and restoring the column to 1024 afterwards brings
back the width but not the data; those bytes were handed to MySQL and
dropped.

That's why your fix keeps coming undone: always right after an update, always
silently. It isn't a bug aimed at you; it's core doing exactly what it was
designed to do, to a column you were never expected to change.

For accuracy: a separate routine, pre_schema_upgrade(), also runs hand-written
ALTERs, but those are version-gated to historic migrations and won't touch a
modern site's post_name. The reversion you're seeing is dbDelta.

The fix: don't repair the damage, prevent the shrink

The instinct is to write something that detects the reverted column and
re-widens it after each update. Resist it. By the time you can detect the shrink,
the data is already gone; you'd just be putting an empty wider column back over
truncated slugs. The only fix that actually saves the data is one that stops
the shrink from ever happening.

And core hands you the seam to do it. dbDelta exposes a filter,
dbdelta_create_queries, that receives the canonical CREATE TABLE statements
before they're compared to the live database. Rewrite the canonical
post_name varchar(200) to varchar(1024) in that filter, and dbDelta's idea of
"correct" now matches what's actually on disk. It sees no mismatch. It emits no
CHANGE COLUMN. There is nothing to truncate.

<?php
/**
 * Plugin Name: Arabic Slug Schema Guard (must-use)
 * Description: Keeps wp_posts.post_name and wp_terms.slug at VARCHAR(1024) across
 *              core DB upgrades, so long Arabic slugs are never truncated.
 *              Prevention-first: dbDelta never even tries to shrink them.
 */
defined( 'ABSPATH' ) || exit;

const SLUG_COLUMN_LEN = 1024;

// Rewrite the canonical schema dbDelta diffs against, so "desired" already
// equals the live 1024-wide column — no CHANGE COLUMN is ever emitted.
add_filter( 'dbdelta_create_queries', function ( $queries ) {
    global $wpdb;

    foreach ( array( $wpdb->posts => 'post_name', $wpdb->terms => 'slug' ) as $table => $column ) {
        if ( isset( $queries[ $table ] ) ) {
            $queries[ $table ] = preg_replace(
                '/(\b' . $column . '\s+varchar\()\s*200\s*(\))/i',
                '${1}' . SLUG_COLUMN_LEN . '${2}',
                $queries[ $table ]
            );
        }
    }
    return $queries;
} );

That single filter is the whole prevention story for Layer 1, and it's robust in
a way an after-the-fact repair can never be: it runs inside dbDelta, so it
covers every path that triggers a schema reconcile: the admin "database
update required" screen, background auto-updates, and wp core update-db on the
CLI alike.

Where this code lives matters as much as what it does. Put it in a must-use
plugin (a single .php file in wp-content/mu-plugins/), not a regular
plugin. MU-plugins always load, can't be deactivated from the dashboard, and load
before the upgrade routine runs. And because a core update only ever replaces
wp-admin, wp-includes and the root PHP files (it never touches wp-content),
your guard is guaranteed to still be in place at the exact moment the upgrade
fires. A regular plugin could be deactivated the one time it mattered; don't bet
your archive on a toggle.

Layer 2: stop new slugs truncating at birth

Prevention on the column keeps your existing slugs safe. But Layer 2 is still
cutting every new slug to 200 bytes at the moment of creation, inside
sanitize_title_with_dashes(). The relevant line, unchanged in current core, is:

$title = utf8_uri_encode( $title, 200 );

That function is attached to the sanitize_title filter, so you can cleanly swap
it for an identical copy that uses a larger byte budget:

// Layer 2: replace core's slug generator with a byte-for-byte copy whose only
// change is the encoding cap. The copy self-tests against core (see below), so a
// future core rewrite of this function is caught instead of drifting silently.
remove_filter( 'sanitize_title', 'sanitize_title_with_dashes' );
add_filter( 'sanitize_title', 'asg_sanitize_title_with_dashes', 10, 3 );

function asg_sanitize_title_with_dashes( $title, $raw_title = '', $context = 'display' ) {
    // … the body is line-for-line core, with one change:
    //     utf8_uri_encode( $title, 200 )  →  utf8_uri_encode( $title, 1000 )
    // 1000 leaves headroom under the 1024 column for a "-2" collision suffix.
}

Pick a sane budget: around 1000 bytes (≈ 160 Arabic characters) leaves room
under the column for the numeric suffix WordPress adds to resolve duplicates. You
don't want unlimited slugs; you want enough.

Layer 3 (_truncate_post_slug()) caps at 200 too, but it only runs when a slug
collides and needs a -2 suffix. For unique news headlines that almost never
fires, and it isn't filterable, so most sites can leave it alone. If you
genuinely need more than 200 bytes even on collisions, you take over uniqueness
through the pre_wp_unique_post_slug filter, an advanced case worth a footnote,
not a paragraph.

Keeping the fork honest

Copying a core function buys a maintenance debt: the day WordPress rewrites
sanitize_title_with_dashes(), your copy diverges, silently, which is the exact
failure mode we're trying to kill. Pinning the copy to a core version and re-diffing
by hand works right up until the release someone forgets to check, which on a
long-lived site is when, not if. So don't rely on remembering. Make the plugin
re-diff itself.

The lever: remove_filter() only unhooks the function; sanitize_title_with_dashes()
stays callable. So you can use core's own current code as a live oracle and assert
your fork still agrees with it on short inputs, where neither byte cap fires and
the only thing left that could differ is the cleanup logic:

// Run once per core version. Short fixtures => neither length cap engages,
// so any difference is pure logic drift, not the byte budget.
foreach ( array( 'الذكاء الاصطناعي', 'عاجل: «مهم» اليوم', 'foo/bar &mdash; baz' ) as $f ) {
    if ( sanitize_title_with_dashes( $f, $f, 'save' )
         !== asg_sanitize_title_with_dashes( $f, $f, 'save' ) ) {
        // core changed the cleanup logic — log + email ops, and (optionally) fall
        // back to core's generator so slugs cap at 200 again: degraded, but safe
        // and known, never a malformed slug from a stale copy.
    }
}

This beats a source-hash check on two counts. It's semantic, not textual: it
stays quiet when core only touches the length handling (which you override anyway)
and fires only when a change actually breaks your output, so the alerts that do
fire get acted on. And it degrades safely: on drift you fall back to core's exact
behaviour: worst case, new slugs cap at 200 until you re-sync, never a half-encoded
slug from a stale copy. Loud-and-safe beats silent-and-wrong. The full guard (with
the per-core-version cache and the optional fail-safe switch) is in the complete
plugin below.

A tripwire, because silent failure is the real enemy

The filter prevents the known incident. But the failure mode that actually hurt
you was that it happened silently, so the last piece is making sure you'd
never again learn about it from a drop in search traffic. The same MU-plugin can
verify the column widths after every update and shout if anything is wrong:

Hook upgrader_process_complete to flag that a core update just ran.
On the next admin request, check the real column widths in information_schema and, if either has shrunk, write to the error log and email ops.
Expose a WP-CLI command for cron-based monitoring:

# Nightly: verify the slug columns, email ops if either has reverted.
0 3 * * *  cd /var/www/site && wp asg verify | grep -q REVERTED \
           && wp asg verify | mail -s "WP slug schema reverted on $(hostname)" ops@example.com

One discipline to internalise: this tripwire restores confidence, not data.
If it ever reports a reverted column, treat it as an incident, not a self-healing
event; the slugs longer than the new width are already gone and must come back
from a backup. Prevention (the filter) and backups are your safety net; the
tripwire just tells you when to reach for them.

"Isn't VARCHAR(1024) dangerous?": no, and the reason is reassuring

Widening these columns sounds risky (indexes, utf8mb4, InnoDB limits), and
it's the part people most often get scared off by. It's almost entirely a
non-issue, and one fact explains why:

The index on these columns is a fixed 191-character prefix, independent of
the column's declared length. Core defines KEY post_name (post_name(191)); it
indexes the first 191 characters whether the column is 200 wide or 1024. Widening
the column doesn't enlarge the index by a single byte.

That dissolves the usual worries:

Index / InnoDB prefix limits. The old InnoDB prefix ceiling is 767 bytes; WordPress chose 191 because 191 × 4 (utf8mb4's worst case) = 764, just under it. Because the prefix stays at 191 no matter how wide the column grows, you never move towards that limit. (A quiet irony: slugs are stored as percent-encoded ASCII, so they were never going to hit four bytes per character anyway.)
Row size. VARCHAR stores the actual length of each value, not its declared maximum; a 30-character slug takes ~30 bytes in a VARCHAR(1024) exactly as it would in a VARCHAR(200). Rows don't get bigger because the ceiling moved up.
Query plans. Lookups use the same 191-prefix index to narrow, then verify the full value. Identical behaviour at 200 or 1024.
Plugins. SEO plugins, caches and CDNs read post_name and emit longer URLs without complaint.

The genuine risks aren't in steady state; they're tools that recreate the
schema from an old definition: a migration plugin that runs its own
CREATE TABLE, or, most commonly, restoring a SQL dump taken before you widened
the columns. A dump of the current database preserves VARCHAR(1024)
correctly; importing an old structure silently puts you back at 200. Write that
one down in your runbook.

Doing it safely on a site with millions of posts

There's one operational gotcha, and it's about the migration itself, not the
result. Going from VARCHAR(200) to VARCHAR(1024) cannot be an instant,
in-place change. InnoDB only keeps a VARCHAR length change "in place" while both
lengths stay in the same size class: values under 256 use one length byte,
values 256 and over use two. Crossing 255 forces ALGORITHM=COPY: a full table
rebuild. On a wp_posts with millions of rows, a raw ALTER means a long
operation and a problematic lock.

So on a large live site, do the initial widening with an online schema-change
tool, not a bare ALTER:

pt-online-schema-change \
  --alter "MODIFY post_name VARCHAR(1024) NOT NULL DEFAULT ''" \
  --chunk-time=0.5 --max-load Threads_running=50 \
  --execute D=wordpress,t=wp_posts

(gh-ost is an equally good triggerless alternative.) wp_terms is tiny and
takes a plain ALTER without ceremony; wp_posts is the one that needs the
online tool. The rollout that's bitten no one:

Back up, and confirm the dump shows VARCHAR(1024) afterwards.
Clone to staging, deploy the MU-plugin, and run a real major core update there. Confirm no CHANGE COLUMN appears and the verify command reports OK.
Deploy the MU-plugin to production before the next core update: prevention has to be in place ahead of the event it prevents.
Widen the production columns off-peak with pt-osc / gh-ost.
Add a nightly verify cron and a 404 monitor, so anything unexpected surfaces in hours, not in a month of lost rankings.
Keep the MU-plugin in version control, and never import a pre-widening structure dump.

The deeper fix: stop betting your URLs on a column width

Everything above makes Arabic slugs safe. But there's a more permanent way to
think about it, and for a large news archive it's worth the shift: don't let
the URL depend on the slug surviving at all.

Anchor your permalinks on the numeric post ID, and keep the Arabic slug as a
descriptive (but cosmetic) suffix:

https://example.com/123456/الذكاء-الاصطناعي

Resolve the post by its ID, and the slug becomes decoration. If it's ever
truncated, malformed, or edited, the URL still resolves to the right article
instead of 404-ing, and WordPress can 301 to the canonical form. You keep the
Arabic keywords in the URL for search relevance and you become structurally
immune to the entire class of problem. (If you want to stop touching core tables
altogether, you can go one step further and store the long slug in your own
indexed routing table, which dbDelta has no opinion about, but for most teams,
ID-anchored permalinks are the sweet spot.)

That's the difference between patching a bug and designing it out.

The complete plugin

Everything above, assembled into one must-use plugin. Drop it in
wp-content/mu-plugins/wp-arabic-slug-schema-guard.php, widen the columns once with
an online schema-change tool, and all three layers, plus the tripwire, are
handled in a single place. The slug generator is a copy of core's
sanitize_title_with_dashes(); only the byte cap differs.

📦 Prefer it ready-made? The plugin is open-source on GitHub as mantekio/wp-arabic-slug-schema-guard, or composer require mantekio/wp-arabic-slug-schema-guard. Star it, file an issue, or lift it whole.

<?php
/**
 * Plugin Name: Arabic Slug Schema Guard (must-use)
 * Description: Keeps wp_posts.post_name and wp_terms.slug at VARCHAR(1024) across
 *              core DB upgrades, lets core generate long URL-encoded Arabic slugs,
 *              and verifies + alerts after every update. Prevention-first:
 *              dbDelta never truncates, because the canonical schema it diffs
 *              against already says 1024. The slug fork self-tests against core
 *              on each update and can fail safe.
 */
defined( 'ABSPATH' ) || exit;

const ASG_COLUMN_LEN = 1024;  // physical column width (bytes)
const ASG_SLUG_BYTES = 1000;  // max generated slug length, under the column width
const ASG_SCHEMA_SIG = 'post_name:1024;slug:1024';
// define( 'ASG_ALERT_EMAIL', 'ops@example.com' );  // optional, set in wp-config.php
// define( 'ASG_L2_FAILSAFE', true );               // optional: on Layer-2 drift, fall back to core (slugs cap at 200) until you re-sync

/* LAYER 1 — PREVENTION
 * Rewrite the canonical CREATE TABLE dbDelta diffs against, so "desired" already
 * equals the live 1024-wide column and no destructive CHANGE COLUMN is emitted. */
add_filter( 'dbdelta_create_queries', function ( $queries ) {
    global $wpdb;
    foreach ( array( $wpdb->posts => 'post_name', $wpdb->terms => 'slug' ) as $table => $column ) {
        if ( isset( $queries[ $table ] ) ) {
            $queries[ $table ] = preg_replace(
                '/(\b' . $column . '\s+varchar\()\s*200\s*(\))/i',
                '${1}' . ASG_COLUMN_LEN . '${2}',
                $queries[ $table ]
            );
        }
    }
    return $queries;
} );

/* LAYER 2 — GENERATION
 * Core caps new slugs at 200 bytes via utf8_uri_encode($title, 200). Swap in a
 * copy of sanitize_title_with_dashes() whose only change is the byte budget.
 * Installed conditionally: if the drift guard (below) flagged THIS core version
 * and ASG_L2_FAILSAFE is on, stay on core's default (caps at 200 — degraded but
 * safe and known) rather than run a fork we know has drifted. */
if ( get_option( 'asg_l2_status' ) === 'drift:' . $GLOBALS['wp_version']
     && defined( 'ASG_L2_FAILSAFE' ) && ASG_L2_FAILSAFE ) {
    // Known-drifted on this core version → leave core's generator in place.
} else {
    remove_filter( 'sanitize_title', 'sanitize_title_with_dashes' );
    add_filter( 'sanitize_title', 'asg_sanitize_title_with_dashes', 10, 3 );
}

function asg_sanitize_title_with_dashes( $title, $raw_title = '', $context = 'display' ) {
    $title = strip_tags( $title );
    // Preserve already-encoded octets through the cleanup below.
    $title = preg_replace( '|%([a-fA-F0-9][a-fA-F0-9])|', '---$1---', $title );
    $title = str_replace( '%', '', $title );
    $title = preg_replace( '|---([a-fA-F0-9][a-fA-F0-9])---|', '%$1', $title );

    if ( seems_utf8( $title ) ) {
        if ( function_exists( 'mb_strtolower' ) ) {
            $title = mb_strtolower( $title, 'UTF-8' );
        }
        $title = utf8_uri_encode( $title, ASG_SLUG_BYTES );  // core hard-codes 200 here
    }

    $title = strtolower( $title );

    if ( 'save' === $context ) {
        // EVERYTHING here is copied verbatim from core. The ONLY sanctioned difference
        // between this fork and core is the byte budget above. Drop a line and you have
        // drifted — see the note under the drift guard below.

        // Turn non-breaking spaces, en/em dashes and slashes into hyphens.
        $title = str_replace( array( '%c2%a0', '%e2%80%93', '%e2%80%94' ), '-', $title );
        $title = str_replace( array( '&nbsp;', '&#160;', '&ndash;', '&#8211;', '&mdash;', '&#8212;' ), '-', $title );
        $title = str_replace( '/', '-', $title );

        // Strip these characters entirely. Note %c2%ab / %c2%bb: the guillemets Arabic
        // uses as quotation marks. And %e2%80%8e / %e2%80%8f: the LRM and RTL marks.
        $title = str_replace(
            array(
                '%c2%ad',                                            // soft hyphen
                '%c2%a1', '%c2%bf',                                  // iexcl, iquest
                '%c2%ab', '%c2%bb', '%e2%80%b9', '%e2%80%ba',        // angle quotes
                '%e2%80%98', '%e2%80%99', '%e2%80%9c', '%e2%80%9d',  // curly quotes
                '%e2%80%9a', '%e2%80%9b', '%e2%80%9e', '%e2%80%9f',
                '%e2%80%a2',                                         // bullet
                '%c2%a9', '%c2%ae', '%c2%b0', '%e2%80%a6', '%e2%84%a2',
                '%c2%b4', '%cb%8a', '%cc%81', '%cd%81',              // acute accents
                '%cc%80', '%cc%84', '%cc%8c',                        // grave, macron, caron
                '%e2%80%8b', '%e2%80%8c', '%e2%80%8d',               // zero-width chars
                '%e2%80%8e', '%e2%80%8f',                            // LRM, RTL mark
                '%e2%80%aa', '%e2%80%ab', '%e2%80%ac',
                '%e2%80%ad', '%e2%80%ae',
                '%ef%bb%bf',                                         // byte order mark
                '%ef%bf%bc',                                         // object replacement
            ),
            '',
            $title
        );

        // Convert &times to 'x'.
        $title = str_replace( '%c3%97', 'x', $title );
    }

    $title = preg_replace( '/&.+?;/', '', $title );          // strip remaining entities
    $title = str_replace( '.', '-', $title );
    $title = preg_replace( '/[^%a-z0-9 _-]/', '', $title );  // keep only slug-safe chars
    $title = preg_replace( '/\s+/', '-', $title );
    $title = preg_replace( '|-+|', '-', $title );
    return trim( $title, '-' );
}

/* LAYER 2 DRIFT GUARD — self-test the fork against core's live implementation.
 * remove_filter() only unhooks sanitize_title_with_dashes(); the function stays
 * callable, so we use core's CURRENT code as a live oracle and assert our fork
 * still agrees on SHORT inputs (where neither byte cap engages — the only thing
 * the fork changed). Any divergence == core altered the cleanup logic and our
 * copy has drifted. Runs once per core version; shouts, and can fail safe. */
add_action( 'admin_init', 'asg_guard_layer2_drift' );

function asg_guard_layer2_drift() {
    $ok      = 'ok:' . $GLOBALS['wp_version'];
    $drifted = 'drift:' . $GLOBALS['wp_version'];
    if ( in_array( get_option( 'asg_l2_status' ), array( $ok, $drifted ), true ) ) {
        return;  // already settled for this core version
    }
    if ( ! function_exists( 'sanitize_title_with_dashes' ) ) {
        return;  // core refactored it away — no oracle to diff against; the fork
                 // still runs as a standalone copy (it needs no removed function).
    }

    // Deliberately SHORT fixtures so neither length cap fires — any difference is
    // pure cleanup-logic drift, not the byte budget.
    $fixtures = array(
        'الذكاء الاصطناعي',
        'عاجل: تطورات «مهمة» اليوم',
        'Mixed عربي + English — dash',
        'foo/bar &mdash; baz',
        'UPPER   multiple   spaces',
        '%d8%a7 pre-encoded octet',
    );

    $drift = array();
    foreach ( $fixtures as $f ) {
        $core = sanitize_title_with_dashes( $f, $f, 'save' );
        $ours = asg_sanitize_title_with_dashes( $f, $f, 'save' );
        if ( $core !== $ours ) {
            $drift[] = "in=[{$f}] core=[{$core}] ours=[{$ours}]";
        }
    }

    if ( $drift ) {
        $msg = "[Arabic Slug Schema Guard] Layer-2 DRIFT on WP {$GLOBALS['wp_version']}: core "
             . "sanitize_title_with_dashes() no longer matches our fork — re-sync the copy.\n"
             . implode( "\n", $drift );
        error_log( $msg );
        if ( defined( 'ASG_ALERT_EMAIL' ) && function_exists( 'wp_mail' ) ) {
            wp_mail( ASG_ALERT_EMAIL, 'WP slug Layer-2 drift: ' . wp_parse_url( home_url(), PHP_URL_HOST ), $msg );
        }
        update_option( 'asg_l2_status', $drifted, true );  // autoload — the fail-safe reads it every request
        return;  // do NOT cache "ok" while drifted
    }
    update_option( 'asg_l2_status', $ok, true );
}

/* LAYER 3 — DE-DUPLICATION (optional)
 * _truncate_post_slug() also caps at 200, but only when a slug COLLIDES and needs
 * a "-2" suffix — rare for unique headlines, and it isn't filterable. If you need
 * >200 bytes even on collisions, take over uniqueness here. Most sites skip this.
 *
 * add_filter( 'pre_wp_unique_post_slug', 'asg_unique_post_slug', 10, 6 );
 */

/* TRIPWIRE — verify + alert after every core update
 * This only detects and alerts: it restores the COLUMN, never bytes already
 * truncated. Treat any revert as an incident — restore from backup. */
add_action( 'upgrader_process_complete', function ( $upgrader, $extra ) {
    if ( isset( $extra['type'] ) && 'core' === $extra['type'] ) {
        delete_option( 'asg_schema_sig' );  // force a re-check on the next admin_init
    }
}, 10, 2 );

add_action( 'admin_init', function () {
    if ( get_option( 'asg_schema_sig' ) === ASG_SCHEMA_SIG ) {
        return;  // fast path: already verified since the last update
    }
    $reverted = asg_reverted_columns();
    if ( $reverted ) {
        $msg = '[Arabic Slug Schema Guard] Column(s) reverted: ' . implode( ', ', $reverted )
             . '. Long slugs were truncated — restore from backup and check 404 logs.';
        error_log( $msg );
        if ( defined( 'ASG_ALERT_EMAIL' ) ) {
            wp_mail( ASG_ALERT_EMAIL, 'WP slug schema reverted: ' . wp_parse_url( home_url(), PHP_URL_HOST ), $msg );
        }
        return;  // do NOT cache "ok" while broken
    }
    update_option( 'asg_schema_sig', ASG_SCHEMA_SIG, false );
} );

function asg_reverted_columns() {
    global $wpdb;
    $reverted = array();
    foreach ( array( array( $wpdb->posts, 'post_name' ), array( $wpdb->terms, 'slug' ) ) as list( $table, $column ) ) {
        $len = (int) $wpdb->get_var( $wpdb->prepare(
            "SELECT CHARACTER_MAXIMUM_LENGTH FROM information_schema.COLUMNS
              WHERE TABLE_SCHEMA = %s AND TABLE_NAME = %s AND COLUMN_NAME = %s",
            DB_NAME, $table, $column
        ) );
        if ( $len && $len < ASG_COLUMN_LEN ) {
            $reverted[] = "{$table}.{$column} (now {$len})";
        }
    }
    return $reverted;
}

/* WP-CLI — `wp asg verify` for cron-based monitoring */
if ( defined( 'WP_CLI' ) && WP_CLI ) {
    WP_CLI::add_command( 'asg verify', function () {
        foreach ( asg_reverted_columns() ?: array( 'ok' ) as $row ) {
            WP_CLI::log( 'ok' === $row ? 'Schema OK — both columns at VARCHAR(1024).' : "REVERTED: {$row}" );
        }
    } );
}

A postscript: the drift guard caught us

The argument above is that a fork of a core function drifts silently, so the guard
matters more than the copy. That turned out to be true in the least comfortable way.

Versions 1.0.0 through 1.2.0 of the released plugin shipped a fork that was missing
core's entire "strip these characters entirely" block, along with the × to x
mapping. The consequence lands exactly on the readers this post is written for: Arabic
guillemets (« ») and the LRM/RTL direction marks survived into slugs as
%c2%ab, %c2%bb, %e2%80%8f. The character filter at the end cannot remove them,
because %c2%ab is built entirely from permitted characters.

The drift guard printed above would have caught it on the first admin_init. Its
second fixture is 'عاجل: تطورات «مهمة» اليوم'. It never fired, because the guard is
bound to admin_init and nobody had opened wp-admin on an install running that
fork. A guard on a hook that never fires is a comment.

Both are fixed in v1.3.0: the fork is re-synced (the block above is now complete
and verified against core by an offline oracle on every build), and wp asg verify
evaluates the drift oracle itself rather than waiting for an admin page load. If you
lifted this code before July 2026, take the str_replace block above.

This is the kind of problem that never shows up in a tutorial. It lives where
WordPress internals, MySQL's storage rules, Arabic character encoding and SEO all
overlap, and it only reveals itself at the worst possible moment. It's also the
territory we work in every day: keeping Arabic publishing fast, multilingual and
unbreakable on WordPress, right through to AWS at scale.

If you run a WordPress publication in Arabic and want it to survive its own
updates, let's talk.

How we built mantek.io for the price of a domain

Jaafar Abazid — Tue, 16 Jun 2026 23:43:33 +0000

The site you're reading costs us almost nothing to run. There's no server invoice, no hosting bill, no monthly platform fee — just the domain name, renewed once a year. Everything else runs on infrastructure that's free at our scale and fast everywhere in the world.

That isn't a corner we cut. It's a set of deliberate choices — static output, edge delivery, git as the backbone — that happen to be cheaper and faster and simpler than the alternative. Here's the whole stack, and the thinking behind it.

The whole bill is the domain

Take the site apart and look for the costs, and there's only one line item.

Hosting and CDN: nothing. The site lives on Cloudflare Pages, which serves it from data centres in hundreds of cities, with unlimited bandwidth on the free tier. The thing that usually costs the most — global delivery — costs zero here.
DNS: nothing. Managed on Cloudflare alongside the domain.
Email Sending: nothing. Contact-form mail goes through Resend's free tier.
The domain: the only invoice. Renewed yearly, and that's the entire running cost.

The infrastructure is free; the engineering is the investment. That's the trade — and for a site that has to be fast, bilingual and maintainable for years, it's the right one.

Static output, Git as the pipeline

The site is built with Astro and compiled to plain HTML and CSS. There's no application server running in the background — nothing to patch, scale, or wake up when a visitor arrives. Cloudflare serves the finished files from the edge location nearest each reader, which is why pages feel instant.

Deployment is just git. We push to the main branch; Cloudflare builds the site and publishes it worldwide in a minute or less. Every branch gets its own preview URL, so a change can be reviewed on a real address before it goes live. And because the repository is the source of truth, undoing a bad change is a git revert — not a 2 a.m. restore from backup.

A CMS with no database

This blog is editable in the browser, but there's no database behind it and no CMS server to keep alive. The editor is git-based: saving a post commits a Markdown file to the repository and rides the same automatic deploy as the code.

That has quiet benefits. Every edit is versioned like code, with full history. There's no database to back up, secure, or migrate. The editor sits behind GitHub sign-in, so there's no separate set of passwords to manage and very little for a scanner to find. Content and code live in one place, and ship the same way.

A contact form without a back end

A contact form normally means a server somewhere waiting to receive it. Ours is a single serverless function that runs at the edge, on demand: it validates the submission and hands it to Resend, which sends the email. No always-on back end, no queue, no infrastructure to maintain between messages.

The credentials never touch the codebase. The Resend API key lives in Cloudflare's encrypted environment variables, read by the function at run time — it isn't in the repository and isn't in the published site. Spam is caught with a hidden honeypot field and server-side checks rather than a third-party CAPTCHA. And the form degrades gracefully: with JavaScript switched off it submits natively and returns a thank-you page; with JavaScript on it posts in the background and shows inline status. No cookies, either way.

Chasing a perfect score

A static site is a fast start, not a finished one. Getting to a perfect Lighthouse score — 100 across Performance, Accessibility, Best Practices and SEO — took a series of small, deliberate decisions:

Self-hosted fonts, preloaded. The fonts are served from our own domain, not a third-party font CDN, and the one the headline renders in is preloaded so it's ready for the first paint. The Arabic typeface only downloads on Arabic pages.
No render-blocking JavaScript. What little script the site needs is inlined and tiny; there's no framework runtime shipping to the browser. These are HTML pages with a few grams of JavaScript, not an app pretending to be a page.
One shared stylesheet. The CSS is a single file, cached across every page, so moving around the site re-downloads nothing.
Work the browser can skip. Sections below the fold are marked so the browser doesn't spend layout effort on them until they're about to be seen.
No flash, no shift. The colour theme is resolved before the first paint, so nothing flickers from light to dark or jumps around as it loads.

None of these is dramatic on its own. Together they're the difference between "fast enough" and a perfect score.

Cached hard, but never stale

Speed and freshness usually pull against each other; the right caching rules give you both. Build assets get fingerprinted filenames, cached for a year and marked immutable — the browser never asks about them again. Images are cached for a week. But the HTML itself is always revalidated, so the moment we publish, every reader sees the new version.

The one lesson worth passing on: immutable means exactly that. It belongs only on files whose name changes when their contents do. Put it on a stable URL and you'll spend a day fighting your own cache.

Secure and findable by default

A set of security headers is applied at the edge, for free: strict HTTPS (HSTS), protection against clickjacking and MIME-sniffing, a conservative referrer policy, and a permissions policy that switches off the camera, microphone and location access the site never uses. There's one canonical hostname; everything else redirects to it.

Findability is built in the same spirit. Every page declares its canonical URL and its English/Arabic alternates, so search engines read the two languages as one site rather than duplicate content. Each post generates its own social-share card. Structured data, an auto-generated sitemap and an RSS feed ship on every build. And the analytics are cookieless — which means no consent banner slowing the page down or greeting the reader with a pop-up.

Two languages, one build

The site is fully bilingual: English at the root, Arabic — right-to-left — under /ar/. There's no duplicate site and no translation plugin. The same components render both languages from a dictionary, down to mirrored layouts and translated structured data. Adding a language is additive, not a rebuild.

If you're building something similar

Default to static. If a page can be HTML, it should be. Everything downstream — speed, cost, security — gets easier.
Make git the backbone. Deploys, content, rollbacks and history in one place beats four systems that have to be kept in sync.
Spend the savings on judgement. Free infrastructure frees the budget for the part that actually matters — the engineering.

This is the same discipline we bring to client work: systems that are fast, cheap to run, and built to last. If you'd like a site that behaves like this one, see what we do or start a conversation.

DEV Community: Jaafar Abazid

Arabic search in WordPress: the matches it silently misses

What WordPress actually does with an Arabic query

The database already knows. WordPress never asks it.

Even reaching it would not be enough

What it costs, and why the broken searches are the expensive ones

What we built, and what it fixed

What it did not fix

The layer we were missing

The plugin

Known limits

WordPress cron behind a load balancer: fixing 'Missed schedule'

wp-cron is not cron

The fix everyone gives you, and the one it hides

Stop hitting a URL

Which machine?

Run everywhere, execute once

Make the silence loud

The plugin

Known limits

Your WordPress says the email sent. It didn't.

Why WordPress email is broken by default

Why the usual fix is a half-fix

The architecture: three moves

A seam, not a fork

Fail loudly, because the alternative is what we are here to fix

The part every tutorial skips: bounces and complaints

The traps worth naming

Verifying it, and why the checker refuses to lie

The plugin

Known limits

The day YouTube deleted our channel

Platforms can delete you, and you do not get a vote

Publish to platforms, never store on them

One video, four sources

Two dials: site-wide and per video

The day the whole channel went

The fallback is not a downgrade

What it is really about: custody

A two-minute gut check for your own setup

The bottom line

Further reading

Make WordPress do less: offloading media to S3 and the edge

The shape of it

Stop WordPress from making thumbnails

Resize at the edge, not on upload

Two copies, two storage classes

Clean keys, by generation not by accident

The WordPress glue

Big video: let the browser do the upload

What it saves

Gotchas worth knowing

The deeper point

Further reading

Short links that outlive the vendor: a newsroom URL shortener on WordPress and AWS

Why both

The one decision everything hangs on

Generating the ID

Where the mapping lives

Resolving at the edge: redirect, not proxy

Migration-proof by design

Keeping the stores in sync at publish

Why Bitly, and how we keep it swappable

The payoff: failover is a DNS change

The honest part: analytics

Further reading

A WordPress update can silently truncate your long Arabic URLs — the bug's in core, in 3 places. I traced it and wrote a fix that survives every update: https://dev.to/jafarabazid/the-200-byte-trap-why-wordpress-core-updates-break-arabic-urls-5d5k

The 200-byte trap: why WordPress core updates break Arabic URLs - DEV Community

The 200-byte trap: why WordPress core updates break Arabic URLs

Why Arabic URLs hit a wall English never does

The number 200 lives in three places, not one

Layer 1: how a core update erases your column width

The fix: don't repair the damage, prevent the shrink

Layer 2: stop new slugs truncating at birth

Keeping the fork honest

A tripwire, because silent failure is the real enemy

"Isn't VARCHAR(1024) dangerous?": no, and the reason is reassuring

Doing it safely on a site with millions of posts

The deeper fix: stop betting your URLs on a column width

The complete plugin