# RobArt Update Guard — User Manual

**Version 0.0.1** · A Rob Art | Illustration WordPress plugin · [robsnow.eu](https://robsnow.eu)

---

## Contents

- [Introduction](#introduction)
- [How it works](#how-it-works)
- [Getting started](#getting-started)
- [The Report](#the-report)
- [Reading a finding](#reading-a-finding)
- [Severity](#severity)
- [Appearance exposure](#appearance-exposure)
- [The Lexicon](#the-lexicon)
- [What it covers — and what it can't](#what-it-covers--and-what-it-cant)
- [Privacy](#privacy)
- [FAQ](#faq)
- [Support](#support)

---

## Introduction

Every WordPress release quietly retires a few things — a function, a class, a core file, an action or filter. Nothing is removed the day it is deprecated, so a plugin that still calls a retired function keeps working for a while. Then a later release finally drops it, and something breaks — often with no error a site owner can see, just a button that no longer does anything.

**RobArt Update Guard tells you, before that happens, exactly which of your installed plugins still lean on something WordPress has retired — with the file, the line, and what to use instead.**

It is built for anyone who runs WordPress with third-party plugins and wants to know where the risk is before clicking *Update*: site owners, freelancers handing a site to a client, and agencies maintaining many installs.

## How it works

WordPress marks its own retirements directly in its source code. When core deprecates a function it writes, in that function:

```php
_deprecated_function( __FUNCTION__, '5.5.0', 'add_allowed_options()' );
```

That one line carries all three facts a report needs: **what** was retired, **when** (the version), and **what to use instead**. Update Guard reads those markings from the copy of WordPress already installed on your site, builds an index of everything retired, then walks the PHP of your installed plugins looking for anything that still calls one.

Because the answer comes from your own WordPress install, it is as authoritative as your site itself — no changelog parsing, no external service, no guesswork, and no AI.

## Getting started

1. Install and activate **RobArt Update Guard**.
2. Open the **Update Guard** menu in the WordPress admin sidebar. It opens on the **Report** screen.
3. Click **Run a scan**. On a large site the scan reads every plugin file, so it takes a few seconds.
4. Read the results. A green "Nothing to fix" means no installed plugin calls anything WordPress has retired.

The result is cached for a day, so revisiting the screen is instant. Click **Scan again** any time — for example after updating a plugin — to refresh it.

## The Report

The Report is the main screen. After a scan it shows a strip of figures at the top:

| Figure | Meaning |
|---|---|
| **Retired things known** | How many functions, classes, core files and hooks the index found retired in your WordPress version. |
| **Plugin files read** | How many PHP files across your installed plugins were scanned. |
| **Plugins affected** | How many plugins still call something retired. |
| **Calls to fix** | The total number of individual calls found. |

Below the figures, either a green **Nothing to fix** card, or one card per affected plugin listing each finding.

## Reading a finding

Each finding tells you everything needed to act on it:

- **Kind** — function, class, core file, hook, or jQuery method.
- **The name** — e.g. `get_page_by_title()`.
- **When it was retired** — the WordPress version that deprecated it.
- **Use instead** — the replacement WordPress names, when it names one. Where core names no direct replacement, the finding says so.
- **Locations** — the exact file and line number of every call, so you can go straight to it.

## Severity

Findings are shaded by how long ago the thing was retired, because age is a rough proxy for urgency — the longer something has been deprecated, the closer it is to being removed for good:

- **Recent** — retired in a current or very recent release. Low pressure, but worth noting.
- **Ageing** — retired several releases back.
- **Old** — retired long ago and overdue for removal. Fix these first.

Severity is a guide to ordering your work, not a verdict — a "recent" finding in a plugin you depend on may still deserve attention before an "old" one in a plugin you are about to remove.

## Appearance exposure

The **Appearance** screen answers a different question: *what might look different after an update, even though nothing broke?*

WordPress can restyle its own admin at any release — version 7.0 changed input sizes, button shapes and the accent colour. Nothing is removed and no plugin stops working, but a plugin whose look leans on core's styling will change appearance along with it. This screen lists where your plugins lean on core styling, so you know which admin screens to glance at after an update rather than clicking through every one.

Nothing on this screen is a fault. Using core's classes is how a plugin looks like part of WordPress. The screen can't tell you whether anything actually looks wrong — only your eyes can — it tells you *where to look*.

## The Lexicon

The **Lexicon** is a reference: everything your WordPress version has retired, newest first, with what replaced each one, grouped by the release that retired it. Use the search box to check a single name. The functions section is marked **Checked by the Report** — those are exactly what the Report scans your plugins against.

The Lexicon is a reference, not a list of problems. Nothing here means anything is wrong with your site; it simply documents what WordPress itself considers retired.

## What it covers — and what it can't

Update Guard is deliberately honest about its edges. A clean report means nothing *named here* is a problem — it does not by itself mean an update is completely safe.

**It covers, reliably and with exact line numbers:**

- Retired **functions**
- Retired **classes**
- Retired **core files**
- Retired **actions and filters**

**It does not cover:**

- **Class methods.** Core retires around a hundred, many with everyday names like `reset()` or `render()`. Telling a retired method from an unrelated one with the same name needs to know each object's type; guessing there would fill the report with things that are not problems, so it is left out on purpose.
- **Same-name behaviour changes.** When a function keeps its name but changes what it does, no reading of the code can reveal it — and this is the commonest cause of a plugin breaking on update. Update Guard cannot see it.
- **jQuery held in plain variables.** For jQuery it reports only calls whose receiver is visibly jQuery — `$(…)`, `jQuery(…)`, or a `$`-prefixed variable. A jQuery object stored in a plainly named variable is invisible to it. This misses some real problems on purpose: the removed jQuery names are ordinary words like `load` and `error`, and matching them loosely would bury the real findings in noise.
- **Minified and bundled files.** A line number inside a built bundle points at nothing you can edit, and a bundled library is not yours to change, so these are skipped.
- **Block-editor API changes and plugin-to-plugin conflicts**, which are outside what static reading can see.

Third-party libraries inside plugins (`vendor/`, `node_modules/`) are skipped too — they are not the plugin author's to fix and would dominate the results.

## Privacy

Everything is read from the copy of WordPress and the plugins already on your site. **No code leaves your server, nothing is fetched from the network, and no AI is involved.** Update Guard bundles no third-party libraries. Scan results are stored in a WordPress transient on your own site and cleared when the plugin is deactivated.

## FAQ

**Does a clean report mean it is safe to update?**
It means nothing your plugins call has been *retired*. It cannot promise an update is safe, because a function can change what it does while keeping its name — the commonest cause of breakage, and something no code reader can detect. Treat a clean report as "no known retirements," not "guaranteed safe."

**Why didn't it flag a method I know is deprecated?**
Class methods are excluded on purpose. Many share everyday names, and distinguishing a retired one from an unrelated method needs runtime type information a static scan doesn't have. Flagging them would produce more noise than signal.

**Will it slow my site down?**
No. Nothing runs on the front end. A scan only happens when you click the button, and the result is cached.

**Does it change any of my files?**
No. Update Guard only reads. It never edits a plugin, and it makes no changes for you — it points you to the file and line so you can decide.

**How often should I scan?**
Whenever you're about to update WordPress or a plugin, and after updating one, so the report reflects the current code.

## Support

Documentation, guides and support at [robsnow.eu](https://robsnow.eu/plugins-wordpress-development/robart-update-guard/).

Found a bug? [Open a support thread](https://wordpress.org/support/plugin/robart-update-guard/) on WordPress.org.
