DEV Community: Susumu Takahashi

The Basics of `$wpdb->prepare()` — Why You Should Never Build SQL Queries With String Concatenation

Susumu Takahashi — Mon, 19 Oct 2026 23:44:15 +0000

When a WordPress plugin or theme needs to talk to the database directly, it uses the core-provided global object $wpdb. The one thing to absolutely avoid when doing so is dropping user input straight into a SQL string through concatenation. The tool WordPress provides instead is $wpdb->prepare(). This post looks at why that matters and what the function actually does under the hood.

Note: SQL injection is a broad term for attacks where unexpected input gets mixed into a SQL statement an application builds, rewriting what that statement actually tells the database to do. Any value coming from outside the application — form fields, URL parameters, and so on — is the starting point to be suspicious of.

Why String Concatenation Is Dangerous

Consider the following code (purely illustrative pseudo-code, not something to actually run on a live WordPress site):

// Dangerous: user input is dropped straight into the string
$title = $_GET['title'];
$sql = "SELECT * FROM {$wpdb->posts} WHERE post_title = '$title'";
$results = $wpdb->get_results($sql);

This works fine as long as $title is an ordinary string. But if $title is set to something like ' OR '1'='1, the resulting SQL statement becomes:

SELECT * FROM wp_posts WHERE post_title = '' OR '1'='1'

Since '1'='1' is always true, the WHERE clause is effectively neutralized, and a query meant to return one specific post ends up returning every post instead. That's a simple example, but the same idea can be extended toward retrieving, modifying, or deleting data the application never intended to expose. The root cause is the act of building a SQL statement out of a value that came from outside the application. No amount of careful checking of the value's contents removes the underlying risk as long as the statement itself is assembled through string concatenation.

What `$wpdb->prepare()` Actually Solves

The solution WordPress core provides is $wpdb->prepare(), used like this:

// Safe: use a placeholder instead
$title = $_GET['title'];
$sql = $wpdb->prepare(
    "SELECT * FROM {$wpdb->posts} WHERE post_title = %s",
    $title
);
$results = $wpdb->get_results($sql);

The %s is a placeholder, and the value passed as the second argument gets inserted there. The key point is that prepare() isn't doing simple string substitution — it escapes any special characters in the value first, so they can never be interpreted as part of the SQL statement's structure, before inserting it. Pass the same ' OR '1'='1 value through prepare(), and it's treated purely as a literal string to search for; the structure of the SQL statement itself never changes.

Why the Placeholder Type Matters

$wpdb->prepare() supports a few main placeholder types.

Placeholder	Purpose
`%s`	String
`%d`	Integer
`%f`	Floating-point number

The reason to use %d or %f isn't only escaping — it's that the value gets coerced into the expected type. For a post ID field using %d, a value like 123abc would simply become the integer 123. Using %s where a number is expected, on the other hand, wraps the value in quotes as a string literal in the SQL statement, which can lead to unintended behavior or errors. Choosing the placeholder type that matches the meaning of the value being passed is just as important as using prepare() in the first place.

Where Plain Placeholders Fall Short: `LIKE` and `IN`

LIKE clauses, commonly used for search features, are a well-known spot where the basic use of prepare() isn't quite enough on its own. LIKE interprets % and _ as wildcards meaning "any string" and "any single character" respectively, so if a search keyword happens to contain those characters, the query can produce results the user never intended. WordPress core addresses this with a dedicated function, $wpdb->esc_like(), which escapes those wildcard characters before the value is handed to prepare().

$keyword = $wpdb->esc_like($_GET['s']);
$sql = $wpdb->prepare(
    "SELECT * FROM {$wpdb->posts} WHERE post_title LIKE %s",
    '%' . $keyword . '%'
);

Similarly, passing a list of values into an IN (...) clause requires building out a placeholder for each value dynamically — it can't be handled with a single %s. Being aware that a handful of patterns like these don't map cleanly onto the basic placeholder syntax is worth keeping in mind whenever $wpdb is involved.

Why This Theme Never Touches `$wpdb` At All

Looking through the implementation of this blog's theme, wpmm-blog, $wpdb is never referenced directly anywhere — not in functions.php, not in any template file. Post listings, archives, and search results are all retrieved through WP_Query and template tags (have_posts(), the_post(), and so on), so there's simply no point in the theme where a raw SQL statement needs to be assembled by hand.

That's not an accident — it reflects a design principle recommended throughout WordPress theme and plugin development. High-level APIs like WP_Query already perform the equivalent of $wpdb->prepare() internally, so the calling code never has to think about SQL at all. Reaching for the core-provided high-level API instead of writing raw SQL, wherever that's an option, is just as practical a guideline for avoiding SQL injection as using prepare() correctly when raw SQL genuinely is needed.

Summary

Situation	What to do
Inserting an ordinary value into a SQL statement	Use `$wpdb->prepare()` with the right placeholder (`%s` / `%d` / `%f`)
A value used inside a `LIKE` clause	Escape wildcards first with `$wpdb->esc_like()`, then pass the result to `prepare()`
A situation where raw SQL can be avoided entirely	Let a core API like `WP_Query` handle it instead of assembling a query by hand

The core of SQL injection defense is turning the mindset of "never trust input" into a concrete habit: using $wpdb->prepare(). It's an easy problem to miss if string concatenation has become second nature, so whenever you're reading or writing code that touches $wpdb, it's worth making a habit of checking first whether placeholders are actually being used.

WordPress Hooks Explained: How Plugins and Themes Extend Core Without Editing It

Susumu Takahashi — Mon, 19 Oct 2026 00:18:56 +0000

WordPress plugins and themes change what gets displayed and how data gets processed without ever touching WordPress core's own files (the code under wp-includes / wp-admin). What makes that possible is a mechanism called hooks, which come in two flavors: actions and filters. This blog's own theme, wpmm-blog, uses both extensively in its functions.php, so this article walks through real code from it.

Note: a hook is a point WordPress core deliberately builds in for outside code to plug into. At specific points in core's own source, calls like do_action() and apply_filters() are already embedded. Plugins and themes "hook" their own functions onto those points to intercept what core does there, without editing core itself.

What separates an action from a filter

The two hook types split cleanly along one line: whether they return a value.

Action: runs some code at a given moment. It doesn't need to return anything — it's for side effects (writing a log, saving data, making an outbound request)
Filter: receives a value core already has, transforms it, and hands it back. It's for changing data right before core uses or displays it

In short: an action interrupts a moment to do something; a filter rewrites a value and returns it. Once you know which of the two your code needs to do, whether to register it with add_action() or add_filter() follows naturally.

A filter example: excerpt length and the "read more" marker

WordPress core truncates the excerpt shown on archive pages to 55 words by default, appending […] at the end. Changing that behavior doesn't require touching core's source — it just means registering functions on two filter hooks, excerpt_length and excerpt_more.

if (!function_exists('wpmm_blog_excerpt_length')) {
    function wpmm_blog_excerpt_length($length) {
        // Japanese content is measured in "words" here too, but 60
        // reads as a reasonable length even with full-width characters
        return 60;
    }
}
add_filter('excerpt_length', 'wpmm_blog_excerpt_length');

if (!function_exists('wpmm_blog_excerpt_more')) {
    function wpmm_blog_excerpt_more($more) {
        return ' …';
    }
}
add_filter('excerpt_more', 'wpmm_blog_excerpt_more');

The key detail: each function receives core's default value as an argument and returns a replacement. wpmm_blog_excerpt_length($length) gets core's default (55) as $length, but this implementation ignores it and always returns a fixed 60. Core's internal logic takes whatever the function returns and uses that as the excerpt length going forward.

An action example: pre-generating an OGP image on save

For an action example, this blog pre-generates and caches a post's OGP (Open Graph) image at the moment a post is saved or published, hooked onto the save_post action.

add_action('save_post', '_wpmm_blog_pregenerate_ogp_on_publish', 10, 3);

add_action() takes, in order: the hook name, the callback function, a priority, and the number of arguments the callback expects. This call uses priority 10 (the default) and requests 3 arguments.

save_post is capable of passing three arguments to its callbacks — $post_ID, $post (the post object), and $update (a boolean for whether this was an update vs. a new post) — but that capability only applies if the callback explicitly asks for that many; by default only the first is passed. The 3 at the end of this call exists specifically so the callback can use all three.

Why priority exists

A widely-used hook like save_post often has more than one plugin or theme registering a callback on it simultaneously, alongside core's own internal use of the same hook. When every callback shares the same default priority (10), they run in registration order — but real requirements sometimes call for "run after this other callback" or "run before everything else," and priority is the explicit numeric knob for that. Lower numbers run earlier; higher numbers run later.

Why this means core never has to be edited directly

WordPress core's own source has do_action('hook-name', ...) (firing an action) and apply_filters('hook-name', $value, ...) (applying a filter) calls built into it at deliberate points throughout. Plugins and themes register callbacks against those pre-built entry points with add_action() / add_filter() — they never modify core's files at all.

That has a very concrete practical payoff. When WordPress core is updated, automatically or manually, its files get replaced wholesale with the new version's. Any customization made by editing core files directly would be silently wiped out on the next update. Customization made through hooks lives in its own file, under wp-content/themes/ or wp-content/plugins/, entirely separate from core — so it survives core updates untouched.

Summary

Type	Purpose	Return value	Example from this blog
Action	Run code at a given moment	None (side effects only)	`save_post` → pre-generate the OGP image
Filter	Transform a value core hands it	The transformed value	`excerpt_length` → change the excerpt word count to 60

Actions and filters, together, are the entire mechanism that lets WordPress core, plugins, and themes cooperate without any of the three ever editing another's source. When reading unfamiliar WordPress code, checking just two things — is this add_action or add_filter, and which hook name is it registered on — is usually enough to figure out exactly where in core's flow it's intercepting, and how.

Timezone Conversion Pitfalls: Where UTC/JST Bugs Actually Come From

Susumu Takahashi — Sat, 17 Oct 2026 01:24:52 +0000

Japan Standard Time (JST) is a fixed UTC+9 offset with no daylight saving time to complicate it. That simplicity makes it tempting to assume timezone handling is "just add or subtract nine hours." In practice, most timezone bugs don't come from getting that arithmetic wrong — they come from losing track of which basis a given timestamp is even using in the first place. This article walks through three real examples, drawn from actual code, logging, and this very blog's own publishing workflow.

Pitfall 1: values that don't carry their own timezone

Note: a "naive" datetime is a date/time value with no timezone information attached at all. An "aware" datetime is one that carries that information.

Python's datetime.now() returns the current time in the server's local timezone, but the returned datetime object itself carries no tag saying "this is JST." datetime.utcnow() has the same problem in reverse — it returns UTC, but nothing about the value says so.

from datetime import datetime

local_now = datetime.now()      # e.g. 2026-09-15 14:30:00, but nothing says "JST"
utc_now = datetime.utcnow()     # e.g. 2026-09-15 05:30:00, but nothing says "UTC"

Put these two side by side and there's no way to tell which is which without knowing how the code that produced them was written. Log one and persist the other to a database, and whoever reads it later — including you, months from now — has no way to know which basis it's in.

That's exactly the shape of bug that slips past review. A value that's off by nine hours still looks like a perfectly plausible timestamp on its own; the mistake only becomes visible once you compare it against something known to be correct.

datetime.utcnow() was deprecated in Python 3.12, for precisely this reason — a naive value's timezone isn't self-evident. The replacement, datetime.now(timezone.utc), returns a value that carries "this is UTC" as part of itself (an aware datetime).

from datetime import datetime, timezone

utc_now = datetime.now(timezone.utc)  # tzinfo=UTC travels with the value

Pitfall 2: log timestamps default to local time

An earlier article on log-level design used maintenance_agent.py's logging.Formatter as an example. The %(asctime)s that formatter produces is built, by default, using time.localtime — the server's own local timezone. That's Python's logging module default, not something the code opts into.

_log_fmt = logging.Formatter('%(asctime)s - [%(levelname)s] - %(message)s')

Run a single server, always on JST, and this never causes a problem — the log timestamps just read as JST. But once logs from multiple servers (which may not share a timezone) get aggregated for a single timeline, or a JST server's logs get compared against a UTC-based cloud environment's logs during an incident, plain timestamp strings with no explicit timezone can't be reliably lined up against each other.

logging.Formatter exposes a converter attribute that can be swapped to time.gmtime to make asctime UTC-based instead.

import time
_log_fmt = logging.Formatter('%(asctime)s - [%(levelname)s] - %(message)s')
_log_fmt.converter = time.gmtime  # asctime is now UTC-based

Neither choice is inherently correct — what matters is that the basis a given log's timestamps use is stated somewhere, in the code or the runbook, rather than left implicit.

Pitfall 3: WordPress's `post_date` and `post_date_gmt` split

This blog's own publishing workflow has run into exactly this category of bug. WordPress stores a post's timestamp in two separate columns: post_date (local time, in whatever timezone the site is configured for — JST, for this blog) and post_date_gmt (the same instant, expressed in UTC).

What happens if a wp post create call only sets one of the two correctly? This blog hit that in practice: a post's --post_date was correctly set to a past JST time, but --post_date_gmt was left unset (or ended up holding the same value as the JST one). WordPress interpreted that as "this post is scheduled for a time still in the future," silently flipped its status to future, and the page started returning a 404 — even though the intent was to publish immediately.

# safe publish command: set both post_date (JST) and post_date_gmt (UTC) explicitly
wp post create \
  --post_status=publish \
  --post_date='2026-09-15 14:00:00' \
  --post_date_gmt='2026-09-15 05:00:00' \
  ...

The root cause is simple: post_date_gmt is supposed to hold post_date minus nine hours, but if WordPress's default logic or a missing CLI flag lets the JST value get stored there as-is, it ends up nine hours ahead of the real UTC time — which reads as "still in the future." Nine hours happens to be exactly the JST/UTC offset, so whenever a post mysteriously gets treated as nine hours ahead of schedule, this post_date / post_date_gmt mismatch is the first thing worth checking. The fix is just as simple: always set both fields explicitly, nine hours apart, on every create or update call.

Note: WordPress keeps these as two columns because they serve different purposes — post_date is the human-facing time an admin sees in the dashboard, and post_date_gmt is the timezone-independent value plugins and API integrations rely on. The REST API reflects the same split, returning both date (site timezone) and date_gmt (UTC) for every post.

What these three have in common

These three pitfalls look like unrelated technologies on the surface — plain Python datetimes, a logging formatter, a pair of WordPress database columns — but they share the same root cause. Some value's timezone basis simply isn't recoverable from the value itself, and something downstream assumes it is.

Pitfall	Where it shows up	Symptom
Naive datetimes	Python code	Comparing or storing values without knowing which basis each one is in
Local-time log timestamps	`logging.Formatter`	Logs from different servers/environments can't be lined up on a shared timeline
`post_date`/`post_date_gmt` mismatch	WordPress publishing	Post misread as nine hours in the future; status flips to `future`, page 404s

How to avoid it

The fixes all point the same direction — not a clever trick, so much as consistently picking one basis and making sure every value carries it explicitly.

Keep everything internal in UTC, and convert to local time only at the point where a human reads it — sometimes phrased as "UTC in the core, local at the edge." Converting too early, or in more than one place, is exactly how double-conversion and missed-conversion bugs creep in
In Python, avoid producing naive datetime values in the first place; prefer datetime.now(timezone.utc) so the timezone travels with the value instead of living only in the programmer's memory
Where a value's basis genuinely isn't self-evident — logs, external integrations — name it explicitly (a _utc or _jst suffix on a variable, a line in the docs) so the basis is visible without having to trace back through the code
For systems like WordPress that keep the same instant in two separate columns, never write a command that updates just one of them. Every create or update call should set both, together, every time

JST's fixed UTC+9 offset with no DST makes the arithmetic trivial, but that same simplicity breeds a kind of complacency — "it's just nine hours either way." In practice, the failures don't come from getting the arithmetic wrong. They come from losing track of which basis a given value was in to begin with, and that's the thing worth watching for.

Optimistic vs. Pessimistic Locking: Two Ways to Stop Database Updates From Colliding

Susumu Takahashi — Fri, 16 Oct 2026 00:23:36 +0000

When two people or processes update the same piece of data at nearly the same time, one can end up overwriting the other's change without ever knowing it happened. This is the classic "lost update" problem, and it shows up anywhere a database, or any multi-process application, allows concurrent writes. There are two broad strategies for handling it: pessimistic locking and optimistic locking. The names are opposites, and so is the approach each one takes.

The "silent overwrite" problem

Say a table tracks inventory, and two processes, A and B, both read the same row at nearly the same moment. Both see "10 units in stock" and both compute "subtract one, so it should become 9." With no safeguard, whichever update runs last simply writes 9 — even though two separate decrements should have produced 8. One update vanishes without a trace.

There are two ways to prevent that: don't let anyone else touch the data while you're working on it (pessimistic locking), or let everyone touch it, but check for contradictions before committing (optimistic locking).

Pessimistic locking: lock first, then touch the data

Pessimistic locking grabs an exclusive lock the moment it reads a row, and makes every other process wait until it's done. The assumption baked into the name — "someone else is probably going to try to touch this too" — is why you lock it down before doing anything else.

The FileLock class in this project's own core/file_lock.py is a real example. The GUI (site_manager_web.py) and a background maintenance run (maintenance_agent.py) can both try to write the same config file (sites_*.json and similar) at once, so the code takes an exclusive lock before writing and makes the other process wait until it's released.

from core.file_lock import FileLock

with FileLock('sites_default.json', timeout=10):
    # anything else trying to touch this file waits here
    _atomic_write_json('sites_default.json', data)

An earlier article covered how that lock is implemented at the OS level — fcntl on Unix versus msvcrt on Windows. This one is a level up: the design decision to take a lock before writing at all, not the mechanics of how the lock itself works.

On the database side, most RDBMSes offer pessimistic locking through a SELECT ... FOR UPDATE clause.

BEGIN;
SELECT quantity FROM stock WHERE id = 42 FOR UPDATE;
-- any other transaction trying to update this row now blocks here
UPDATE stock SET quantity = quantity - 1 WHERE id = 42;
COMMIT;

Note: a deadlock happens when two transactions each hold a lock the other is waiting for, so neither can proceed. Pessimistic locking reliably prevents lost updates, but getting the lock order wrong can produce exactly this situation. Most RDBMSes detect deadlocks and force one transaction to fail, leaving retry logic to the application.

The downside is that everyone else waits while a lock is held. With long-running operations or heavy concurrent access, that waiting adds up.

Optimistic locking: assume conflicts are rare, check afterward

Optimistic locking takes the opposite view: "two processes updating the same row at once probably won't happen often," so it never locks on read. Instead, it checks at write time whether the row has changed since it was read.

The usual implementation adds a version or updated_at column and includes that value in the update's WHERE clause.

UPDATE stock
SET quantity = 9, version = 6
WHERE id = 42 AND version = 5;

If this affects exactly one row, nobody touched it since it was read, and the update succeeds. If it affects zero rows, the version no longer matches — someone else got there first. The application treats that as a detected conflict: re-read the current value and retry, or tell the user their change collided with someone else's.

Note: "conflict" here means two attempted changes to the same data that can't both be applied. Optimistic locking doesn't prevent conflicts — it detects, at write time, whether one actually occurred.

The same idea shows up on the web. An earlier article on HTTP cache headers covered ETag, which normally validates a cache. Paired with an If-Match header, though, it becomes a form of optimistic locking: "only accept this update if the version I last fetched still matches what's on the server now." A client sends If-Match: "<its last-fetched ETag>" on an update request, and the server rejects the write if the current ETag doesn't match.

WordPress's "post lock" isn't strictly pessimistic locking

WordPress's admin screen has a familiar warning: open a post someone else is already editing, and you'll see "So-and-so is currently editing this post." It's built on the Heartbeat API, which periodically writes and refreshes a lock transient marking who's editing.

But this isn't a hard, database-enforced lock. It's advisory — a notice, not a barrier. If both users ignore it and hit save, wp_update_post() has no built-in conflict detection, so whichever save happens last simply wins. The UI flags that someone else is in there, but nothing at the database level actually prevents a lost update — so saving anyway, warning ignored, is expected behavior rather than a bug.

Comparing the two

Aspect	Pessimistic locking	Optimistic locking
Assumption	Conflicts are common	Conflicts are rare
When it acts	Locks on read	Detects conflicts on write
Effect on others	Others wait while the lock is held	No waiting under normal conditions; retries only on conflict
Fits best	High update frequency, expensive-to-redo failures	Read-heavy workloads with few write collisions
Main risk	Deadlock	Missing retry logic after a detected conflict

Which one to use

When conflicts happen often, or redoing a failed update is expensive (inventory allocation, say, where retrying gets complicated), locking up front is usually easier to reason about. When reads dominate and write collisions are rare, pessimistic locking's constant waiting becomes a drag, and optimistic locking fits better.

This project uses FileLock — pessimistic — for config writes because the GUI and background process rarely collide on the same file, so the occasional wait doesn't matter, while a corrupted partial write (an incomplete JSON file) is worth avoiding outright. The lock is also held only briefly, just long enough to finish one file. Pessimistic locking isn't the right answer everywhere; it comes down to how often conflicts happen, how costly a failed retry is, and whether waiting is acceptable.

Summary

Pessimistic locking locks on read and makes everyone else wait, trading that wait — and some deadlock risk — for guaranteed conflict prevention. Optimistic locking skips the lock and checks at write time whether the version changed, avoiding waiting under normal conditions but requiring retry handling once a conflict is detected. This project's FileLock is a real instance of the former; HTTP's ETag paired with If-Match is a web-native version of the latter. Both answer the same question: what happens when more than one process reaches for the same data at once.

Git Bisect and Blame: Binary-Searching Your Way to "When Did This Break?"

Susumu Takahashi — Thu, 15 Oct 2026 00:24:57 +0000

Last time we looked at what actually happens between git add and git commit — the mechanics of the moment a commit gets created. This time we shift focus to a different kind of question: given a long history of past commits, how do you track down the one that introduced a specific bug? git blame and git bisect both dig into that history, but they're suited to very different situations.

`git blame`: following one line's history directly

Running git blame <file> lists, for every line in that file, the most recent commit that touched it — hash, author, and date included. If you already suspect a particular line is causing a problem, blame tells you exactly when it was introduced and by which commit.

git blame -L 40,60 core/db_backup_diagnostics.py

Narrowing the range with -L keeps the search fast since you don't have to scan the whole file. From there, feeding the commit hash into git show <hash> reveals the full commit message and diff that line was part of. The limitation of blame is that it tells you when a line was written, not whether that line is actually responsible for the bug you're chasing. If you don't yet know which line is at fault, blame isn't the right starting point.

`git bisect`: binary-searching between a known-good point and a known-bad one

git bisect is the tool for when you don't know which commit — or even which file — caused the regression. The idea is simple: mark one commit you know was working ("good") and one you know is currently broken ("bad"). Git then checks out the commit sitting roughly halfway between them. You test that commit and tell Git whether it's still broken or not, and the remaining range gets cut in half again.

Note: binary search means repeatedly checking the midpoint of a range and discarding the half that can't contain the answer. Even with 100 candidates, this narrows things down to one in roughly seven checks (2 to the 7th power is 128).

git bisect start
git bisect bad                      # the current commit (HEAD) is broken
git bisect good v1.6.8               # this tag was known to work
# → Git checks out a commit roughly halfway between the two
# test it, then report the result:
git bisect good   # if it still works
git bisect bad    # if it's broken
# this repeats automatically until one commit remains
git bisect reset  # return to your original branch when done

Even across hundreds of candidate commits, this cuts the number of commits you actually need to check down sharply compared with testing them one by one in order.

Automating it: `git bisect run` hands the verdict to a script

You don't have to eyeball good/bad by hand every time. If you have a script or test that reliably reproduces the bug, pass it to git bisect run <command>, and Git will execute that command at each candidate commit automatically — treating exit code 0 as good and anything else as bad.

git bisect start
git bisect bad HEAD
git bisect good v1.6.8
git bisect run python3 -m unittest tests.test_db_backup_diagnostics

Give it a valid starting good/bad pair, and Git drives the whole search to the culprit commit on its own. The catch is that your test needs to reliably reproduce the exact failure you're chasing. A flaky check (one that sometimes fails for unrelated reasons) breaks the core assumption of binary search — that one side of the range is definitively good and the other definitively bad — and can lead bisect to converge on the wrong commit.

A real example: tracking down a shell-dependent parsing bug

There was a past issue where DB backups reliably failed on hosts using csh-family login shells, such as Sakura Internet's. The cause turned out to be a progress-log output routine added at some point that implicitly assumed a bash-style environment; under csh, the log format came out differently and parsing broke. This is a textbook case for bisect: you know exactly when the symptom appeared (once a csh-environment report came in), but the actual commit responsible could be anywhere across dozens or hundreds of commits further back. With a test that reproduces the csh environment, git bisect run can chase down the offending commit without manual intervention at every step; without one, you'd answer good/bad by hand after testing on that environment each time. Once bisect narrows things to a single commit, git blame (or git show on that commit) is the natural next step to understand what the change was trying to do and how to fix it properly.

When to reach for which

Situation	Command
You already suspect a specific line and want to know when it was written	`git blame`
Something is broken, but you don't know which line or commit caused it	`git bisect`
`bisect` narrowed it to one commit and you want to understand the intent behind it	`git blame` / `git show <commit>`

Once bisect narrows a regression down to a single commit, reading that commit's diff with git show — and tracing the same lines further back with blame if needed — is the natural next step. It helps to think of bisect as narrowing the range and blame as digging into one specific point; they cover different stages of the same investigation.

Summary

git blame tells you exactly when a specific line last changed, but it's no help if you don't yet know which line is at fault. git bisect only needs a known-good and a known-bad commit to binary-search its way to the culprit, and pairing it with a reliable test via git bisect run lets the whole search run unattended. This connects back to last time's point about staging — commits are fixed-in-time snapshots, and it's precisely because of that property that you can binary-search backward through them to find which snapshot introduced the problem.

JWT and Session Tokens Explained: Stateless vs. Stateful Authentication

Susumu Takahashi — Wed, 14 Oct 2026 01:26:26 +0000

Two articles back, we covered cookie+nonce authentication, and last time we looked at how WordPress's login cookie is actually a hybrid: signature verification is fully self-contained, but revocation depends on a server-side list of valid tokens. This time we look at the opposite end of the design spectrum: JWT (JSON Web Token), which aims for authentication that is fully stateless — no server-side token list at all. Comparing it against WordPress's hybrid model makes the trade-off between stateful and stateless authentication much easier to see.

What a JWT actually is: three dot-separated parts

A JWT looks like a single string split into three parts by dots — xxxxx.yyyyy.zzzzz. These correspond to a header, a payload, and a signature. The header names the signing algorithm (such as HS256) and token type; the payload holds "claims" — pieces of data like a user ID, an expiration time, or permissions. The header and payload are each Base64url-encoded and joined with a dot, and the signature is computed over that combined string using the algorithm named in the header.

Note: Base64url is a variant of ordinary Base64 that swaps out characters like +, /, and = for - and _ so the result is safe to embed in URLs and cookies. It's just a character encoding, not encryption — anyone can decode it back to the original string instantly.

A common misconception: "signed" is not "encrypted"

A frequent misunderstanding is assuming the JWT payload is hidden because it's "encrypted." In reality it's only Base64url-encoded — there's no encryption involved at all. Anyone can decode it in a second using browser dev tools or a command line, and read the user ID, permissions, or any other claim inside directly. What a JWT actually guarantees is not confidentiality but integrity: that the content hasn't been tampered with since it was issued. This is the exact same property WordPress's authentication cookie relies on via its HMAC signature, as covered last time. The practical takeaway is the same in both cases: never put a password, API key, or other secret inside a JWT payload.

No database lookup required — genuine statelessness

WordPress's authentication cookie, as we saw last time, checks the HMAC signature and then also has to look up whether the token is still on the list of currently valid tokens stored as user metadata in the database. That lookup is exactly what makes "log out everywhere" possible — but it also means a database query happens on every single request.

JWT is designed to skip that lookup entirely. Whoever needs to verify a token only needs the shared secret key (for HMAC-based signing) or the public key (for asymmetric algorithms like RSA or ECDSA) to recompute the signature and check it matches. No database query, and no round trip back to the issuing server, is required. This is exactly what "stateless" means here, and it's why JWT is popular in distributed systems where multiple microservices need to share the same authentication scheme — each service can verify a token entirely on its own, using only a key it already holds, without querying a central session store.

The trade-off: no way to instantly revoke a single token

This statelessness comes at a clear cost. Once a JWT is issued, it will pass verification anywhere its signature checks out, right up until it expires — there's no equivalent of WordPress's "log out everywhere" for a plain JWT. The very design choice that eliminates the database lookup — not maintaining any server-side list of valid tokens — is also what removes the ability to forcibly invalidate one specific token before it expires.

Real-world compromises: pure statelessness is hard to sustain

Two common approaches address this weakness in practice. The first is to keep the JWT's own expiration very short — a few minutes to maybe an hour — and pair it with a separate, longer-lived "refresh token" that the server tracks and uses to reissue new JWTs periodically. This reintroduces a small amount of server-side state, in the form of managing the refresh token, but the short-lived JWT itself can still be verified statelessly. The second approach is to maintain a server-side blocklist of revoked token IDs (the jti claim) and check every incoming token against it — which, in effect, brings back the same kind of token-list lookup WordPress relies on, giving up most of the statelessness advantage in the process. Between these two compromises, it becomes clear that being fully stateless and being able to revoke instantly are, in principle, difficult to have at the same time.

Which one fits — it depends on the system's shape

In a system like WordPress, where a single central database already sits within reach of every request, the hybrid approach we covered last time makes good sense: the database round trip is already happening anyway, so adding one more lookup for the token list is a small cost for a genuinely useful feature — instant revocation.

In a distributed system made of several independent services, or a mobile app talking to multiple separate backend APIs, having every request check in with one central session store can itself become a bottleneck or a network dependency. That's where JWT's "verify independently with just a key" property becomes the real advantage. Giving up instant per-token revocation in exchange for a short expiration plus a refresh token often makes the overall system easier to operate at that scale.

Summary

A JWT is made of a header, a payload, and a signature; the payload is merely encoded, not encrypted, so it should never carry secrets. Its defining feature is genuine statelessness — verification relies purely on a signature check, with no server-side token list required — which is what makes it cheap to verify across distributed services. The cost is that no single token can be revoked instantly, which is why real deployments lean on short expirations paired with refresh tokens, or a blocklist that partially reintroduces state. Seen next to WordPress's hybrid cookie model from last time, the two designs come into focus as different answers to the same underlying tension: fast, stateless verification versus the ability to revoke access on demand.

CORS Explained: Why Browsers Block Cross-Origin API Requests

Susumu Takahashi — Tue, 13 Oct 2026 01:25:22 +0000

Anyone who has wired up a browser-side call to an API on a different domain has probably hit the red has been blocked by CORS policy message in the console — even though the server responded just fine. The browser is the one refusing to hand the response over. This article walks through the same-origin policy that causes this, and what CORS (Cross-Origin Resource Sharing) actually does to relax it safely.

What "origin" means

Note: an origin is the combination of a URL's scheme (https://), hostname (wpmm.jp), and port. The path (/blog/, etc.) doesn't count. https://wpmm.jp and https://en.wpmm.jp are different origins because the hostname differs; https://wpmm.jp and http://wpmm.jp are different origins too, because the scheme differs.

Browsers enforce a baseline rule called the same-origin policy: JavaScript loaded from one origin generally cannot read the response of a request made to a different origin. This restriction lives in the browser itself — it has nothing to do with server configuration.

Why the restriction exists at all

The reasoning becomes obvious once you imagine a world without it. If the same-origin policy didn't exist, simply opening a malicious page in your browser would let its JavaScript quietly send a request to your bank's site in the background, using the authentication cookies already stored in your browser, and read the response — your account balance, for instance. The browser doesn't stop the request from being sent; what it stops is letting the page's JavaScript read the response that comes back from a different origin. That single restriction closes off a large class of data-theft attacks.

CORS is how a server safely loosens that restriction

Plenty of legitimate use cases need to call an API on a different origin, though. CORS is the mechanism a server uses to explicitly declare "reads from this origin are allowed." When a server includes a header like Access-Control-Allow-Origin: https://example.com in its response, the browser permits JavaScript running on that specific origin to read the response — and only that origin.

The key point is that the decision is made by the browser, not the server. The server is only offering a header; whether the response actually gets handed to the calling JavaScript is enforced client-side. A tool like curl or Postman, which isn't a browser, always sees the full response regardless of any CORS header — the restriction only kicks in for JavaScript running inside a browser.

Preflight requests

For a "simple" GET request, the browser sends the real request first and then decides whether to expose the response based on the headers it gets back. But for a request that isn't considered simple — a POST with Content-Type: application/json, for example — the browser sends an OPTIONS request first, called a preflight, before it ever sends the real one. Only once the server responds to that preflight with headers like Access-Control-Allow-Methods and Access-Control-Allow-Headers does the browser go ahead and send the actual request.

Wildcard `*` vs. a specific origin

Access-Control-Allow-Origin can either allow any origin via the wildcard *, or allow a single specific origin by name. The deciding factor is whether the API's response depends on credentials such as cookies or an Authorization header.

A public, stateless endpoint that returns the same result no matter who calls it can safely use *.
An endpoint whose response is tied to a cookie-based session, and therefore contains something personal to the caller, can't use * — browsers won't allow Access-Control-Allow-Credentials: true to be paired with a wildcard origin. Instead, the server has to maintain an allowlist and match it against the incoming Origin header on each request, echoing back only the origins it trusts.

How our own backend splits this

Two API endpoints behind our landing page happen to illustrate this split directly.

The chatbot API (server/wpmm-web/api/chat.php) checks the incoming Origin header against an explicit allowlist and only echoes it back on a match:

$allowed_origins = [
    'https://wpmm.jp',
    'https://www.wpmm.jp',
    'https://en.wpmm.jp',
];
$origin = $_SERVER['HTTP_ORIGIN'] ?? '';
if (in_array($origin, $allowed_origins, true)) {
    header('Access-Control-Allow-Origin: ' . $origin);
    header('Vary: Origin');
}

Because this endpoint tracks rate limits and conversation logs per session, letting any arbitrary site embed it would open the door to abuse. Restricting the allowed origins to our own landing pages keeps the set of places it can be called from under our control. The Vary: Origin header alongside it is deliberate too — it tells any caching layer (a CDN, or the browser's own cache) that the response body depends on the Origin header's value, so a response approved for one origin never gets served from cache to a request from a different one.

The checkout-session API (server/wpmm-web/api/checkout.php), on the other hand, returns Access-Control-Allow-Origin: *. It only creates a Stripe checkout session and hands back a redirect URL — nothing in that response is tied to the caller's cookies or identity — so there's little reason to restrict which origin can call it.

There's a third pattern worth mentioning too: the "latest posts" section on our landing page (includes/blog_latest.php) doesn't call the blog's REST API from browser JavaScript at all. Instead, the PHP running on the server fetches the REST API itself and renders the result as plain HTML. A server-to-server request like that never goes through a browser, so the same-origin policy and CORS simply don't apply to it. "Restrict which browser origins can call this directly" and "don't let the browser make the call in the first place" are two different answers to the same underlying problem.

Takeaway

CORS is how a server safely relaxes the browser's default same-origin restriction by explicitly declaring which origins it trusts. The browser is the one enforcing the rule; the server is only stating a preference via a header. Whether to use a wildcard or an allowlist comes down to whether the response is tied to credentials. And it's worth remembering that CORS is a browser-specific concept in the first place — routing a call through the server instead of directly from client-side JavaScript sidesteps the whole question.

Environment Variables and .env Files: What Wins When They Conflict?

Susumu Takahashi — Thu, 08 Oct 2026 23:34:06 +0000

When building a Python application, configuration values tend to live in one of three places: real OS environment variables, a .env file, or a hard-coded default in the code itself. These three can conflict, and when a value doesn't seem to be "taking effect," the cause is usually a misunderstanding of which one wins. This article walks through the resolution order between the three, and why it's designed the way it is.

What a `.env` file actually is

Note: a .env file is a plain text file listing KEY=value pairs, one per line. It's used to keep environment-specific or sensitive values — API keys, database connection strings — out of the source code itself. It's almost always excluded from version control via .gitignore.

In Python, the go-to library is python-dotenv. Calling load_dotenv() reads the .env file and populates os.environ with its contents. From that point on, calling code just does os.environ.get('API_KEY') without needing to know or care whether the value came from a real OS-level environment variable or from the .env file.

Three places a value can come from, and their priority

In general, a configuration value can exist at up to three levels:

OS environment variables — values exported in the shell (export API_KEY=...), or injected by CI systems and container runtimes at startup
.env file — values checked into the repository (or kept alongside it) that are loaded only in a developer's local environment
Hard-coded defaults in the code — the last resort, as in os.environ.get('API_KEY', 'default-value')

Most dotenv-style libraries, python-dotenv included, default to a specific rule here: a value that's already set as a real OS environment variable is not overwritten by the .env file. Unless you explicitly pass override=True, load_dotenv() respects whatever is already present in os.environ and simply skips any matching key found in the .env file.

That gives a priority order of: OS environment variable > .env file > hard-coded default.

Why this ordering makes sense

At first glance it might seem more intuitive for the value loaded last (the .env file) to win. But there's a good reason OS environment variables take precedence instead.

The classic case is CI pipelines and containerized deployments. In those environments, secrets management systems — GitHub Actions secrets, a docker run -e flag, and similar mechanisms — inject production-relevant or CI-specific values directly as OS environment variables. If a .env file checked into the repo (typically containing dummy values or a developer's personal local settings) were allowed to silently overwrite those injected values, tests and deployments would end up running against the wrong configuration without any obvious error.

The underlying principle — a value that has already been explicitly and deliberately set should not be silently overwritten by a file loaded later — is a common pattern in configuration resolution design generally. Ordering things so that "the more intentionally a value was set, the higher its priority" lets both cases work correctly at once: a local developer's .env file is used whenever no OS environment variable overrides it, while CI and production environments reliably use whatever the infrastructure layer injected, regardless of what happens to be sitting in the .env file.

A similar pattern in our own codebase: explicit setting > auto-detection > hard-coded fallback

This application doesn't use .env files, but a structurally similar multi-tier fallback shows up in core/log_i18n.py's automatic UI-language detection (get_ui_language()):

# Resolution order (first valid value wins):
#   1. Environment variables LC_ALL / LC_MESSAGES / LANG (POSIX standard)
#   2. Windows API: GetUserDefaultUILanguage
#   3. locale.getlocale() / locale.getdefaultlocale() (legacy fallback)
#   4. If nothing resolves -> 'en' (defaults toward international users)

On top of that, the caller of this function checks for an explicit language setting in settings.json first, and skips the automatic detection entirely if one is present.

Laid out as a priority chain, that's: an explicit user choice (settings.json) > information the OS/shell already exposes (LANG and friends) > a guess from the standard library (the locale module) > a fixed fallback ('en') when nothing else resolves. It's the same underlying idea as the .env priority rule, applied to a different problem: a deliberately configured value should always outrank an automatically detected one, and there should always be a safe, hard-coded value at the very bottom so the system never has no answer at all.

Takeaway

The typical resolution order for configuration values — OS environment variable, then .env file, then hard-coded default — exists specifically to stop a developer's local .env file from accidentally overriding values that CI or container infrastructure deliberately injected. That same idea, "prefer the more intentional value and always keep a safe fallback underneath," generalizes well beyond .env files to configuration resolution in general.

How Python's venv Works — Why It Keeps Projects From Fighting Over the System Python

Susumu Takahashi — Thu, 08 Oct 2026 00:39:18 +0000

Anyone who has worked with Python tooling has run into "virtual environments" (venv) sooner or later. A single command, python3 -m venv .venv, creates a directory that most Python projects treat as a given. What is that directory actually doing, and why has it become such a standard part of the workflow? This post looks at the problem venv solves and how it works under the hood.

The Problem: Projects Sharing One Python Installation

Working on multiple Python projects on the same machine eventually runs into a conflict: one project needs version 2 of a library, another needs version 3 of the same library. Running pip install directly against the system Python installs into one shared site-packages directory for the entire machine, so installing the second project's dependencies overwrites the first project's, and one of them breaks.

Note: site-packages is the directory where third-party libraries installed via pip install actually live. Python looks inside it whenever code does an import.

On some operating systems, the system Python is also used internally by OS-level tooling (package managers, for instance), so carelessly installing or upgrading libraries into that shared location risks affecting the OS itself, not just your own projects. A virtual environment sidesteps this by giving each project its own independent site-packages, rather than everyone sharing one pool.

What Actually Happens Inside a venv

Running python3 -m venv .venv creates a directory roughly structured like this:

.venv/
├── bin/                       # python3/pip executables (symlink or copy)
├── lib/.../site-packages/     # this project's own library directory
├── pyvenv.cfg                 # records where the base system Python lives

The key detail is that .venv/bin/python3 isn't a separate Python implementation — it's the same interpreter as the system Python, either copied or symlinked. What changes is where it looks for libraries. When .venv/bin/python3 starts up, it reads pyvenv.cfg and redirects its site-packages search path to .venv/lib/.../site-packages instead of the system-wide location. Any pip install run through that interpreter installs into this project-local directory, leaving the system Python's environment untouched.

The familiar source .venv/bin/activate command isn't the mechanism that provides this isolation — it's a convenience shell script layered on top. Running it just prepends .venv/bin to the PATH environment variable and sets a VIRTUAL_ENV variable, so that typing python or pip in the terminal afterward resolves to the venv's copies first. The isolation itself doesn't require activation at all: calling .venv/bin/python3 script.py by its full path gets you the same isolated environment, activated or not.

A Real Example: Startup-Time venv Management in `_launcher.sh`

This app's Mac/Linux launch script, _launcher.sh, relies on exactly that direct, activation-free call for a health check:

if [ ! -f ".venv/bin/python3" ]; then
    NEEDS_SETUP=1
elif [ ! -f "$STAMP" ] || [ "$(cat $STAMP)" != "${ARCH}:${PY_VER}:${REQ_HASH}" ]; then
    NEEDS_SETUP=1
elif ! .venv/bin/python3 -c "import sys; sys.exit(0)" >/dev/null 2>&1; then
    NEEDS_SETUP=1
fi

Rather than rebuilding .venv on every launch, the script keeps a stamp file at .venv/.install_stamp containing three values as a single string: the machine architecture (uname -m), the Python version, and a hash of requirements.txt. On the next launch, it compares this composite key against the stored one. If they match, .venv is assumed unchanged and reused as-is — the script just runs source .venv/bin/activate and moves on. If any of the three has changed (a dependency bump shipped in an app update, or the machine changing from Intel to Apple Silicon, for example), .venv is deleted entirely and rebuilt from scratch with python3 -m venv .venv followed by pip install -r requirements.txt.

The line .venv/bin/python3 -c "import sys; sys.exit(0)" looks like it does nothing, but it's a health check confirming the venv's Python binary can actually run. This can fail, for example, after an OS update moves the system Python's location out from under a symlink the venv still points to — in which case a rebuild is triggered as well.

This "don't rebuild unless the requirements.txt hash changes" design carries a hidden assumption worth naming. As covered in our post on pip's version-specifier syntax, this app's own requirements.txt uses >= lower-bound specifiers (like flask>=3.0.0) rather than == exact pins. That means the file's hash can stay identical across two separate pip install runs, while the actual library versions installed can still differ depending on when the install happened. A matching hash guarantees the venv was built from the same requirements.txt, not that its installed contents are byte-for-byte identical every time — a distinction worth keeping in mind.

Summary

A venv solves the problem of multiple projects fighting over one shared Python installation by giving each project its own isolated site-packages. activate is a convenience layer that temporarily rewrites PATH; the actual isolation works by simply calling .venv/bin/python3 directly. This app's launcher script leans on that property, checking for environment drift (architecture, Python version, dependency changes) via a hash-based stamp file instead of rebuilding the environment on every single launch — while still catching the cases where it genuinely needs to.

Image Optimization and WebP Basics — Why WebP Is Smaller, and How Browsers Decide to Use It

Susumu Takahashi — Tue, 06 Oct 2026 23:20:40 +0000

It's often cited that the biggest drag on WordPress page speed isn't code at all — it's images. The same-looking photo can end up dramatically smaller in file size depending on whether it stays as JPEG/PNG or gets converted to WebP. This post looks at why WebP tends to be lighter, how browsers negotiate which format to load, and how WordPress itself has adopted the format over time.

Why WebP Is Smaller: A Different Compression Approach

JPEG, standardized back in 1992, is built on discrete cosine transform (DCT) compression. WebP, introduced by Google in 2010, takes a different route: it repurposes the intra-frame compression techniques from the VP8 video codec for still images. Because it inherits prediction-based encoding refined for video, WebP can often hit a smaller file size than JPEG at a comparable level of visible quality loss.

Note: intra-frame compression means compressing a single video frame using only the information within that frame, without referencing neighboring frames. That's essentially the same problem as compressing one still image, which is why video codec techniques transfer so directly to image formats.

Another advantage of WebP is that it covers multiple use cases under one format. It supports lossy compression for photos, but also lossless compression for things like logos and screenshots, plus alpha-channel transparency (like PNG) and even simple animation (like GIF). Formats that used to require picking JPEG for photos, PNG for transparency, and GIF for animation can now be handled by WebP alone.

How Browsers Decide Which Format to Serve

When WebP was new, browser support was inconsistent, and HTTP content negotiation helped bridge that gap. A browser requesting an image sends a header like Accept: image/webp,image/*,*/*, and a server or CDN can inspect it to decide: if the browser says it understands WebP, serve the lighter WebP version; otherwise, fall back to JPEG or PNG.

Note: content negotiation is the general term for a server returning different content at the same URL depending on what format the client claims to support. The same idea shows up for language (Accept-Language) and compression (Accept-Encoding), not just image formats.

The same idea can be expressed explicitly in HTML. Wrapping a <source type="image/webp" srcset="photo.webp"> element inside a <picture> tag, followed by a regular <img src="photo.jpg"> fallback, lets the browser pick whichever format it understands first — WebP if supported, the JPEG <img> otherwise. This is convenient because the browser handles the decision itself; no server-side negotiation logic is required.

All major browsers today (Chrome, Firefox, Edge, Safari) support WebP, so the "unsupported" branch of that logic rarely gets exercised in practice. Still, some older email-preview renderers and certain image-processing bots don't support it, so keeping a fallback in place remains a reasonable default.

WebP Support in WordPress Core

For a long time, WordPress restricted uploadable image formats to JPEG, PNG, GIF, and a few others — trying to upload a .webp file to the media library used to fail with an error about the file type not being allowed for security reasons. WebP was officially added to the allowed MIME type list (wp_get_mime_types()) starting with WordPress 5.8, after which WebP files could be uploaded directly to the media library.

Later versions of WordPress went a step further: derivative sizes generated from an uploaded JPEG (the various sizes registered via add_image_size(), such as thumbnails) can now be automatically converted to WebP and stored alongside the original. The original JPEG file itself is left untouched, while the smaller sizes used in post listings and featured images become WebP — reducing transferred bytes on the display side while preserving compatibility of the source file. Whether this conversion actually happens depends on the server's image-processing library (GD or Imagick) supporting WebP output, so it isn't guaranteed on every hosting environment.

A Similar Case in Our Own Codebase: Mapping Extensions to MIME Types

This app's white-label reporting feature (available on the STD/BIZ plans) touches WebP in a comparable way. The agency-logo upload endpoint (site_manager_web.py::upload_report_logo) includes .webp in its list of allowed extensions, and the endpoint that serves the logo back for preview (report_logo_preview) maintains a lookup table from extension to MIME type:

mime_map = {'.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
            '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml'}

Similarly, the routine that embeds site screenshots into a report PDF (report_generator.py::_encode_image_b64) determines the correct MIME type from the file extension (mapping webp to image/webp) before encoding the file as a base64 data URI.

Why bother with this lookup table at all? Browsers and PDF renderers decide how to interpret an image based on the actual Content-Type header sent (or the MIME type declared inside a data URI) — not the file extension itself. If a .webp file were mistakenly served with a MIME type like image/png, the browser might fail to render it, or offer a download dialog instead of displaying it inline. Explicitly mapping each extension to its correct MIME type is a small, unglamorous step, but it's the kind of detail that prevents broken image rendering.

Why the OGP Image Generator Still Outputs PNG, Not WebP

On the other hand, this blog's dynamic OGP image generator — ogp-generator.php, covered previously in our Cache-Control vs. ETag post — deliberately outputs PNG rather than WebP. The reason: social media crawlers from platforms like X (formerly Twitter) and Facebook are separate programs from a person's browser, and they don't necessarily track the same level of image-format support as the latest browser releases. Since an OGP image's job is to be read by a social platform's crawler rather than a human's browser, choosing the most broadly compatible format — PNG or JPEG — reduces the risk of a share card failing to render correctly.

Even with the same underlying goal of keeping images small, the right format can differ depending on whether the audience is a general-purpose browser or a social crawler.

Summary

WebP borrows video-codec compression techniques to deliver photos, transparent images, and simple animations in one format, typically at a smaller file size than the JPEG/PNG/GIF combination it replaces. Browsers can negotiate format support through the Accept header or declare it explicitly with the <picture> element, and WordPress core has gradually adopted WebP — first as an upload-allowed format in version 5.8, later with automatic conversion for generated image sizes. Lighter isn't always better, though: when compatibility with a specific consumer (like a social media crawler) matters more than raw file size, sticking with an older, more universally supported format can be the right call.

Cookie and Session Authentication Basics — What Happens Behind a wp-admin Login

Susumu Takahashi — Tue, 06 Oct 2026 00:13:34 +0000

The previous article covered how REST API requests inside wp-admin are protected by a combination of cookies and nonces. This time we go one level deeper: what actually happens when you "log in," and why does entering a password once keep you authenticated across dozens of page loads afterward? We'll also look at how WordPress's approach differs from the more common server-side session model.

What happens the moment you click "Log In"

When you submit the wp-admin login form, wp_signon() first checks the submitted password against the hashed password stored in the database — nothing unusual so far. Once authentication succeeds, wp_set_auth_cookie() issues an authentication cookie to the browser. From then on, the browser automatically attaches this cookie to every subsequent request, so you never have to re-enter your password.

Note: HTTP itself has no concept of "state." The server doesn't remember, at the time of the next request, who logged in during the previous one. The general term for solving this problem — maintaining a logged-in state on top of a stateless protocol — is "session management."

What's actually inside the authentication cookie

WordPress's authentication cookie (stored under a name like wordpress_logged_in_*) is a pipe-delimited string. Roughly speaking, it consists of four parts: the username, an expiration timestamp, a session token, and an HMAC signature. The important detail here is that the username and expiration are stored in something close to plain text inside the cookie itself.

Note: HMAC (Hash-based Message Authentication Code) is a tamper-detection signature computed with a secret key. The same input and key always produce the same output, but a third party who doesn't know the key cannot forge a valid signature.

If a user could freely rewrite the contents of that cookie, they could swap in someone else's username and impersonate them. The HMAC signature at the end prevents exactly that. The server computes this signature using secret strings defined in wp-config.php — AUTH_KEY / AUTH_SALT (and a separate LOGGED_IN_KEY / LOGGED_IN_SALT pair specifically for the login cookie). On every request, the server redoes this same computation and checks whether the result matches the signature in the cookie. Without knowing the secret key, an attacker who tampers with the username or expiration cannot produce a matching signature, so the forgery is caught immediately.

The verification that runs on every single request

Every time a page loads, WordPress runs this check through wp_validate_auth_cookie(). The flow is: split the cookie on the pipe character, confirm the expiration hasn't passed, recompute the expected HMAC from the username, token, and expiration, and compare it against the signature stored in the cookie. If even one of these checks fails, the request is treated as unauthenticated.

The apparent contradiction: "stateless," yet "log out everywhere" works

Based on the description so far, WordPress's authentication scheme looks entirely self-contained — as long as the username, expiration, and signature can be verified, the server doesn't need to look anything up in a database on every request. This has a real advantage: the server doesn't need to hold onto a large volume of session data.

And yet, the WordPress admin dashboard has a "log out everywhere" feature. If the cookie were truly self-contained with nothing on the server side, there would be no way to invalidate an already-issued, cryptographically valid cookie from the outside. The piece that resolves this is the "session token" embedded in the cookie. WordPress separately maintains, per user, a list of currently valid session tokens as user metadata in the database — handled by a class called WP_Session_Tokens. When validating the authentication cookie, WordPress checks not only that the HMAC signature matches, but also that the token inside the cookie still appears in that user's list of valid tokens. Triggering "log out everywhere" clears that list of tokens server-side; even though the signature itself would still verify correctly, the associated token can no longer be found, so all subsequent requests using that cookie are treated as expired.

In other words, WordPress's authentication design is a hybrid of a purely self-contained token and a server-managed, revocable session record. The signature check happens fast and self-contained, while only the part that genuinely needs revocation — the token list — depends on server-side state, getting the benefits of both approaches.

How this compares to the traditional server-side session model

Many web applications take the opposite approach. The cookie handed to the browser contains nothing meaningful at all — just a random session ID — while the actual data (username, permissions, and so on) lives entirely in a server-side lookup table mapping session IDs to user information, held in memory or a database. This means the server must look up that table on every request, but revoking a session is as simple as deleting a single entry from it.

It helps to think of WordPress's authentication cookie as sitting between these two designs. Lightweight data like the username and expiration travels inside the signed cookie itself, keeping verification cheap, while only the part that actually needs revocation logic — which tokens are currently valid — is carved out into server-side user metadata.

Summary

A wp-admin login state is re-verified on every request through an authentication cookie made up of four parts: username, expiration, token, and HMAC signature. Looking only at the signature check, it resembles a fully self-contained token scheme, but it's actually a hybrid combined with a list of valid session tokens stored in user metadata — which is precisely what makes a server-initiated action like "log out everywhere" possible. The nonce verification covered in the previous article on REST API authentication also depends on this login cookie working correctly in the first place; both mechanisms ultimately rest on the same underlying authentication layer.

REST API Authentication: Cookie+Nonce vs. Application Passwords

Susumu Takahashi — Mon, 05 Oct 2026 00:48:52 +0000

WordPress's REST API (covered in an earlier article) mixes two kinds of endpoints: some that anyone can read without authenticating, and others that reject you outright unless you're logged in. Inside wp-admin, the browser is quietly firing off requests to that same API the whole time you're editing — and yet you never re-enter your password for each one. This article looks at the mechanism behind that: cookie+nonce authentication, and a separate mechanism built for a different purpose, Application Passwords.

What authenticates a request inside wp-admin

When you log into WordPress, your browser receives an authentication cookie named wordpress_logged_in_*. From then on, every request your browser sends to that same domain carries this cookie automatically, so the server can identify "who's logged in" just by checking it. When wp-admin's own JavaScript calls the REST API — auto-saving a draft, or the block editor updating a post in the background — it's riding on that same cookie.

Note: CSRF (Cross-Site Request Forgery) is an attack where, while you're logged into a site, a malicious page you happen to open triggers requests to that site using your browser's cookies without your intent — deleting a post or changing a setting, for example. Because browsers attach cookies automatically, a cookie alone can't prove the request was something you actually meant to do.

This is exactly the gap CSRF exploits. Since cookies are sent automatically, visiting a booby-trapped page while logged in would carry the same cookie along with it. If the REST API accepted write requests based on cookie validation alone, simply loading a malicious page while logged in could trigger an unwanted post deletion or account change.

Where the nonce comes in

A nonce closes that gap. Despite the name suggesting "used once," WordPress's nonce is actually a token tied to the current login session, valid for a fixed window (24 hours by default, extendable to roughly 48 hours with rotation), and scoped to a specific action. The server generates one with wp_create_nonce('some-action-name') and embeds it in the wp-admin page's HTML/JS. Write requests to the REST API are expected to carry this value in an X-WP-Nonce header, and the server checks it against the logged-in user with wp_verify_nonce().

A malicious external site has no way to obtain that nonce value — it's only embedded in the wp-admin page itself, which lives on the same origin. So even if an attacker's page manages to reuse your stolen cookie, the nonce check still blocks it. Put simply: the cookie answers "who is this," and the nonce answers "did this person actually intend this action from this page, right now." Both have to check out before a wp-admin REST request goes through.

Where cookie+nonce falls short

This whole design assumes requests originate from the same browser, inside the same wp-admin session. The flip side is that it doesn't work well for programs that never touch a browser — a command-line tool, or a script running on a different server, that wants to call the REST API directly. Cookies are tied to a browser's login session, and there's no natural way for an external program to acquire or maintain one; nonces are similarly short-lived and need to be re-fetched every time a wp-admin page loads.

Application Passwords: a separate door in

Application Passwords, shipped in WordPress core since version 5.6 (2020), answers exactly this need — a way for external programs to call the REST API safely — through a mechanism entirely separate from cookie+nonce. Under the hood it resembles HTTP Basic authentication. From their profile page in wp-admin, a user can generate a new Application Password by naming the application it's for. What comes out is a randomly generated password distinct from the login password; sent in an Authorization: Basic header, it carries the same permissions as the account.

The key differences from cookie+nonce are twofold. First, it doesn't depend on any browser session state — once you have the password, any program can use it immediately. Second, each one can be revoked individually. There's no need to hand your actual login password to an external integration; if you decide to stop using that integration, you revoke just that one Application Password from wp-admin, without touching your login credentials or affecting any other connected tool.

A real case where no authentication is needed at all

Interestingly, the "From the Blog" section on our own LP (en.wpmm.jp/) — built by the blog_latest.php script covered in the earlier article — uses neither of these mechanisms. It only calls /wp/v2/posts, a read-only endpoint for published posts, which is designed to be accessible to anyone without authentication in the first place. REST API authentication only becomes necessary once you go beyond public data — fetching drafts, creating or updating posts, changing settings. Thinking of it in three tiers — anyone can read, only the logged-in user can write, and an external program writes through a dedicated Application Password — makes it straightforward to decide which authentication approach a given task actually needs.

Summary

Requests inside wp-admin combine two checks — a cookie (who's logged in) and a nonce (did this person intend this action, from this page, right now) — to block CSRF while still letting you skip re-entering your password on every request. But because that design leans heavily on browser session state, it doesn't extend naturally to external programs calling the REST API. Application Passwords fill that gap with a separate class of token that can be issued and revoked independently of the login password. The same phrase, "REST API authentication," calls for a different mechanism depending on whether the request originates inside a browser or outside one — worth keeping in mind whenever you're deciding how a piece of code should authenticate.

DEV Community: Susumu Takahashi

The Basics of `$wpdb->prepare()` — Why You Should Never Build SQL Queries With String Concatenation

Why String Concatenation Is Dangerous

What $wpdb->prepare() Actually Solves

Why the Placeholder Type Matters

Where Plain Placeholders Fall Short: LIKE and IN

Why This Theme Never Touches $wpdb At All

Summary

WordPress Hooks Explained: How Plugins and Themes Extend Core Without Editing It

What separates an action from a filter

A filter example: excerpt length and the "read more" marker

An action example: pre-generating an OGP image on save

Why priority exists

Why this means core never has to be edited directly

Summary

Timezone Conversion Pitfalls: Where UTC/JST Bugs Actually Come From

Pitfall 1: values that don't carry their own timezone

Pitfall 2: log timestamps default to local time

Pitfall 3: WordPress's post_date and post_date_gmt split

What these three have in common

How to avoid it

Optimistic vs. Pessimistic Locking: Two Ways to Stop Database Updates From Colliding

The "silent overwrite" problem

Pessimistic locking: lock first, then touch the data

Optimistic locking: assume conflicts are rare, check afterward

WordPress's "post lock" isn't strictly pessimistic locking

Comparing the two

Which one to use

Summary

Git Bisect and Blame: Binary-Searching Your Way to "When Did This Break?"

git blame: following one line's history directly

git bisect: binary-searching between a known-good point and a known-bad one

Automating it: git bisect run hands the verdict to a script

A real example: tracking down a shell-dependent parsing bug

When to reach for which

Summary

JWT and Session Tokens Explained: Stateless vs. Stateful Authentication

What a JWT actually is: three dot-separated parts

A common misconception: "signed" is not "encrypted"

No database lookup required — genuine statelessness

The trade-off: no way to instantly revoke a single token

Real-world compromises: pure statelessness is hard to sustain

Which one fits — it depends on the system's shape

Summary

CORS Explained: Why Browsers Block Cross-Origin API Requests

What "origin" means

Why the restriction exists at all

CORS is how a server safely loosens that restriction

Preflight requests

Wildcard * vs. a specific origin

How our own backend splits this

Takeaway

Environment Variables and .env Files: What Wins When They Conflict?

What a .env file actually is

Three places a value can come from, and their priority

Why this ordering makes sense

A similar pattern in our own codebase: explicit setting > auto-detection > hard-coded fallback

Takeaway

How Python's venv Works — Why It Keeps Projects From Fighting Over the System Python

The Problem: Projects Sharing One Python Installation

What Actually Happens Inside a venv

A Real Example: Startup-Time venv Management in _launcher.sh

Summary

Image Optimization and WebP Basics — Why WebP Is Smaller, and How Browsers Decide to Use It

Why WebP Is Smaller: A Different Compression Approach

How Browsers Decide Which Format to Serve

WebP Support in WordPress Core

A Similar Case in Our Own Codebase: Mapping Extensions to MIME Types

Why the OGP Image Generator Still Outputs PNG, Not WebP

Summary

Cookie and Session Authentication Basics — What Happens Behind a wp-admin Login

What happens the moment you click "Log In"

What's actually inside the authentication cookie

The verification that runs on every single request

The apparent contradiction: "stateless," yet "log out everywhere" works

How this compares to the traditional server-side session model

Summary

REST API Authentication: Cookie+Nonce vs. Application Passwords

What authenticates a request inside wp-admin

Where the nonce comes in

What `$wpdb->prepare()` Actually Solves

Where Plain Placeholders Fall Short: `LIKE` and `IN`

Why This Theme Never Touches `$wpdb` At All

Pitfall 3: WordPress's `post_date` and `post_date_gmt` split

`git blame`: following one line's history directly

`git bisect`: binary-searching between a known-good point and a known-bad one

Automating it: `git bisect run` hands the verdict to a script

Wildcard `*` vs. a specific origin

What a `.env` file actually is

A Real Example: Startup-Time venv Management in `_launcher.sh`