Checkin in Joomla

1. The Basics

1.1 What is the Check-in Component?

The Check-in component (com_checkin) is Joomla's built-in administrator tool for releasing edit locks on database rows. It has shipped with Joomla core since version 1.6.

What it does in short:

• It scans every database table whose name starts with your configured prefix.
• It lists the tables that have checked_out and checked_out_time columns and at least one locked row.
• It clears the lock by resetting both columns to their default value or NULL.

Think of it as the force-eject button for stuck records. It is not the way records normally get unlocked - saving a record does that. Check-in only cleans up what saving missed.

1.2 The Library Book Analogy

It helps to think of every editable record as a library book:

• Opening the edit form = borrowing the book. Your name goes on the slip.
• Clicking Save or Cancel = returning the book. The slip is cleared.
• Closing the browser mid-edit = walking out with the book. The slip stays in your name, nobody else can borrow it.
• Global Check-in = the librarian walks the shelves and clears every slip whose borrower has clearly forgotten to come back.

1.3 What is a Check-out, Really?

When you open an article (or category, module, menu item) for editing, Joomla writes a row-level "borrow slip":

UPDATE #__content
   SET checked_out      = 42,                   -- your user id
       checked_out_time = '2026-05-27 14:23:00' -- now
 WHERE id = 1234;

While those columns are filled in, anyone else who opens the row sees a warning and cannot save. When you click Save & Close or Cancel, Joomla performs the matching check-in:

UPDATE #__content
   SET checked_out      = NULL,
       checked_out_time = NULL
 WHERE id = 1234;

The lock is gone, the next editor can open the row. This is the happy path. com_checkin only matters when this cycle breaks.

1.4 Where Do I Find It?

In the Joomla 6 backend the path is:

System → Maintenance → Global Check-in

The component lives at administrator/components/com_checkin/. There is no frontend folder - by design. There is no menu item type and no API endpoint either. It is a Super User tool.

3. When the Lock Gets Stuck

The check-in step is skipped when something interrupts the editor:

• The browser tab is closed without clicking Save or Cancel.
• The user's session expires while the edit form is open.
• The browser crashes, the laptop sleeps, the wifi drops mid-save.
• A PHP fatal error throws before the controller reaches checkin().
• A second tab opens the same article - the first tab's check-in fires, then closing the second tab leaves the row locked from the second check-out.

The result is the same in every case: a row marked as checked out by a user who is no longer editing it. That is when Global Check-in earns its place in the toolbar.

5. The Editor Experience

5.1 The Lock Icon in List Views

Open Content → Articles. Each row shows a small lock icon next to its title when checked_out is set:

• Hover the icon - tooltip with the locking user's name and the time of check-out.
• Click the icon - if you have the right ACL on the row, it checks the row in immediately.
• Without permission - the click does nothing, the row stays locked.

This per-row check-in is the fast path. Editors rarely need to open Global Check-in. They just click the lock icon on the article list.

5.2 The Lock Warning on the Edit Form

If Editor B opens an article that Editor A is editing, B sees a yellow notice at the top of the form. B can still view the data, but the Save button is disabled. B's options are:

1. Close the tab and come back later.
2. Ask A to save and close.
3. Ask a Super User (or click the lock icon if allowed) to release the lock.

5.3 Per-row vs Global - Pick the Smallest Tool

7. The Underlying API

7.1 Why Not Real Database Locks?

Joomla deliberately does not use SELECT ... FOR UPDATE or table locks for editor concurrency. The reasons:

• Edit sessions outlive DB connections. Databases are optimized for short transactions, not long human editing sessions. A real row lock held while an editor stares at a form for 20 minutes would exhaust the connection pool. Joomla therefore stores the lock as metadata in the row itself.
• Cross-engine portability. Joomla targets MySQL, MariaDB, PostgreSQL, and SQL Server. Lock semantics differ across all four. Advisory columns work the same everywhere. This keeps Joomla portable and predictable.
• No deadlocks. Two columns cannot deadlock. Two real DB locks racing for the same row can.
• Cluster-safe. The lock state is the database row, so every web node sees the same answer. File-based or in-memory locks would fail in a load-balanced setup.
• Visible to humans. SELECT * FROM #__content WHERE checked_out IS NOT NULL is something a developer can actually run. It's human-readable and easy to debug as administrators can inspect locks directly.

7.2 Table::checkOut()

Every Joomla table that supports locking extends Joomla\CMS\Table\Table, which provides:

public function checkOut($userId, $pk = null): bool

The method dispatches a "before" event, updates the row's checked_out and checked_out_time columns, and dispatches an "after" event. The checked_out integer is the user id, not a session id. Joomla can show who holds the lock, by name, in the warning message.

7.3 Table::checkIn()

The mirror method clears the columns:

public function checkIn($pk = null): bool

checkIn() is called by:

• AdminModel::checkin() - the backend Save and Cancel buttons.
• Table::store() - the regular save path. Saving a record always checks it in.
• Table::delete() - before deletion, to release any lock first.

A successful save is therefore the normal way locks are released. The Check-in component only sweeps up the leftovers.

7.4 Table::isCheckedOut() and Session Metadata

The check that decides whether to show the warning is more subtle than people think. The isCheckedOut() method consults the #__session table when session tracking is on:

if (Factory::getApplication()->get('session_metadata', true)) {
    // SELECT COUNT(userid) FROM #__session WHERE userid = $against
    // If 0 → the row is treated as not-checked-out,
    //         even though the columns are still filled in
}

What this means in practice:

• With session_metadata = true (the default): once the locking user's session ends, the row behaves as unlocked. The next editor can open and save it, even though the columns still look "locked".
• With session_metadata = false: the predicate trusts the columns blindly. Stale locks then really do block other editors until Global Check-in clears them.

Common myth: "Joomla never auto-releases stale locks". Reality: with the default settings, the behaviour already adapts when sessions expire. Global Check-in and the scheduled task tidy up the columns afterwards.

The toggle lives at System → Global Configuration → System → Session Settings → Track Session Metadata.

7.5 The Four Table Events

Developers can hook into the lock lifecycle through four per-row events:

7.6 The Component-level onAfterCheckin Event

Global Check-in fires its own event after each table is processed. The event class is Joomla\CMS\Event\Checkin\AfterCheckinEvent (Joomla 5.0 and later). A typical subscriber:

public function onAfterCheckin(AfterCheckinEvent $event): void
{
    $table = $event->getTableName();
    Log::add("Global check-in cleared locks in {$table}", Log::INFO, 'audit');
}

This is useful for compliance trails - you want to know who released locks in bulk and when. Note that the event fires once per table, not once per row.

9. Permissions and ACL

9.1 The Two Actions

Check-in's ACL is configured at System → Global Configuration → Permissions → Check-in:

By default only Super Users inherit both. You can give a Site Manager group access by allowing Manage on com_checkin.

9.2 The Per-row Permission Is Different

Releasing a single row via the lock icon in a list view is governed by the component that owns the row, not by com_checkin. To click-to-unlock an article, you need the right permission on com_content, not on com_checkin.

A user with com_checkin Manage can do a bulk check-in but might not be allowed to click the lock icon on a single article. The two paths use two different permissions.

9.3 Suggested Role Matrix

Global Check-in is a maintenance privilege, while single-row check-in is a content-management privilege.

11. Multi-server, API, and Headless

11.1 Load-balanced Clusters

Because the lock state lives entirely in the database, Joomla check-in works correctly in clustered hosting without any extra effort:

• Editor A opens a row on web node A - checked_out is written to the shared database.
• Editor B's request hits web node B - the same row is loaded, and the lock is visible.
• Either node can perform the check-in. Both see the result immediately.

No sticky sessions are required for the lock itself.

11.2 The Web Services API

Joomla 4 and later ship a JSON API at /api/index.php/v1/. The same AdminModel code powers the API endpoints and the backend forms, so:

• A PATCH on an article performs check-out, save, check-in internally.
• An API client that reads an article does not lock it.
• An API client that opens an article for editing should call the explicit check-out endpoint, then save, and expect the auto check-in.

The lock is advisory. A raw PATCH that ignores check-out will succeed and may overwrite an in-progress backend edit. If you build a headless editor on top of the API, you are responsible for calling check-out before showing the form, surfacing the lock state in your UI, and calling check-in when the user navigates away.

11.3 CLI Scripts and Direct SQL

The lock is enforced by Joomla's PHP code, not by the database itself. This means:

• CLI scripts that call Table::store() directly bypass the lock check unless they explicitly call isCheckedOut() first.
• Maintenance scripts that run raw UPDATE statements bypass it entirely.
• Third-party migrators may not respect locks. Be careful running them while editors are active.

If your CLI script writes to a table that supports check-in, do the courtesy of checking out and checking back in around the write.

13. Best Practices and Cheat Sheet

If you only remember a few things from this article, remember these:

• Check-in is not the primary unlock path - saving a record is. The component exists for when saving never happens.
• Pick the smallest tool that solves the problem: lock icon, then Global Check-in, then the scheduled task.
• Enable plg_task_globalcheckin on multi-editor production sites with a sensible delay (2 hours is a good start).
• The convention is two columns: checked_out and checked_out_time. Any table that has them participates automatically.
• The lock is advisory. Raw SQL or careless CLI scripts can bypass it.
• With session_metadata = true (the default), expired sessions already behave as unlocked in the UI - Global Check-in just tidies the columns.
• Subscribe to onAfterCheckin if you need an audit trail.

Cheat Sheet

UNLOCK ONE ROW       Click the lock icon in the list view
UNLOCK MANY ROWS     System → Maintenance → Global Check-in
AUTO-RELEASE         Enable plg_task_globalcheckin, set delay = 2
SUPPORT IT IN MINE   Add checked_out + checked_out_time columns
                     Extend Table and AdminModel
AUDIT WHO RELEASED   Subscribe to onAfterCheckin
REFUSE A CHECK-IN    Subscribe to onTableBeforeCheckin
FIND ALL LOCK TABLES INFORMATION_SCHEMA.COLUMNS WHERE COLUMN_NAME = 'checked_out'
DIAGNOSE A LOCK      SELECT a.*, u.name FROM <table> a JOIN #__users u ON u.id = a.checked_out