> ## Documentation Index
> Fetch the complete documentation index at: https://docs.obvlo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WordPress plugin

> Serve Obvlo guides under your own domain on WordPress. Download the plugin from the portal, upload it, activate it — no web server configuration, provided your server allows .htaccess rewrites.

The Obvlo Microsite plugin serves your guides under your own domain — `yourhotel.com/local-guides/paris` — so the SEO value accrues to your site. It is the same reverse proxy described in [Reverse proxy](/microsite/reverse-proxy), packaged as a plugin. On any server that allows `.htaccess` rewrites — which is most of them, and all the common managed WordPress hosts — there is **no server config to edit, no shell access and no restart**: the plugin sets up its own path and then checks that it really works. Where a server does not allow them, no plugin can serve these URLs, and the [one requirement](#before-you-start-one-server-requirement) below says how to tell.

<Tip>
  If you run WordPress, this is the mode we recommend. You get everything the reverse proxy gives you —
  publishing live within seconds, new pages appearing on their own — without touching a server config
  file. [Deployment modes](/microsite/deployment-modes) compares it against the alternatives.
</Tip>

## Before you start: one server requirement

The plugin needs your server to let `.htaccess` files set up rewrites. On Apache that means two things:
`mod_rewrite` enabled, and `AllowOverride` set to allow it — normally `AllowOverride All`.

<Warning>
  **If `AllowOverride` is `None`, the plugin cannot work.** Apache then never reads `.htaccess` at all,
  so the rule the plugin writes is ignored and your guides return a 404. This is not something the
  plugin, or any WordPress plugin, can work around from inside WordPress — the request is refused before
  PHP ever runs.
</Warning>

**You almost certainly already meet this requirement.** It is the same thing that makes WordPress's
pretty permalinks work, so there is a one-second check: if your posts have URLs like
`yoursite.com/my-post/`, your server allows `.htaccess` rewrites and the plugin will work. If your posts
look like `yoursite.com/?p=123` or `yoursite.com/index.php/my-post/`, they do not — fix that first, and
see [When guide URLs stay unreachable](#when-guide-urls-stay-unreachable).

## Install

<Steps>
  <Step title="Download the plugin from the portal">
    Open your site in the Obvlo portal, go to the **Integration** tab, choose **WordPress plugin** and
    download the archive.

    It arrives **already configured for your site**. There is no org id, site id or origin to type in,
    and nothing to substitute by hand.
  </Step>

  <Step title="Upload and activate">
    In WordPress, go to **Plugins → Add New → Upload Plugin**, choose the `.zip`, install, then
    activate.
  </Step>

  <Step title="Check the settings screen">
    Go to **Settings → Obvlo Microsite**. **Guide URLs reachable** should say *Yes* — the plugin checks
    this by requesting one of your guide URLs, so it is reporting what a visitor would actually get.

    That is the whole installation. You do not need shell access, and nothing outside your own site
    folder is touched.
  </Step>

  <Step title="Visit your guides">
    Open the path the portal generated the plugin for, e.g. `https://yourhotel.com/local-guides/`. Your
    Obvlo content loads on your own domain.
  </Step>
</Steps>

<Note>
  **If your guides return a 404, the settings screen will tell you why.** The row **Guide URLs
  reachable** is checked by actually requesting one, not by guessing — so it reflects what a visitor
  would get. If it says no, use the **Add the rule and re-check** button on that screen.
</Note>

## How the guide path reaches the plugin

Your web server has to hand `/local-guides/paris` to WordPress before the plugin can answer it.
Otherwise the server looks for a file or folder of that name, does not find one, and returns its own 404
without ever loading WordPress.

On most sites WordPress's own rule already does this — it is the same rule that makes your post URLs
work. Where it does not, the plugin adds one line of its own to the `.htaccess` file in your site
folder, claiming **only** your guide path:

```apache theme={null}
# BEGIN Obvlo Microsite
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^local\-guides(/.*)?$ /index.php [L]
</IfModule>
# END Obvlo Microsite
```

Nothing else on your site is affected: your post URLs, your permalink setting and any other rules in
that file are left exactly as they were, and the block is removed again if you deactivate the plugin.

A guide that does not exist gets **your own theme's 404 page**, on your own domain.

## When guide URLs stay unreachable

If **Guide URLs reachable** still says no after the plugin has written its rule, the rule is being
ignored. The plugin has done everything it can from inside WordPress; what is left is a server setting.

**How to confirm it.** Your guide path returns a plain Apache 404 — a small unstyled "Not Found" page —
while `yoursite.com/index.php/local-guides/` reaches WordPress. That combination means PHP and the
plugin are both healthy and only the rewrite is failing.

**On Apache**, ask your host (or run, if you have shell access):

```bash theme={null}
apache2ctl -M | grep rewrite
grep -rn "AllowOverride" /etc/apache2/apache2.conf /etc/apache2/sites-enabled/
```

The fix is `AllowOverride All` on the directory that holds your site, then a reload:

```bash theme={null}
apache2ctl configtest && systemctl reload apache2
```

<Warning>
  **Check the HTTPS site specifically.** `AllowOverride` is set per virtual host, and a common setup has
  it correct on the plain-HTTP site while the HTTPS one — added later by an SSL certificate tool — never
  received it. Because HTTP redirects straight to HTTPS, every real visit uses the site that does *not*
  allow overrides, and the plugin's rule is ignored even though `AllowOverride All` appears in your
  config. Make sure it applies to the `:443` virtual host, not only `:80`.
</Warning>

On **NGINX or IIS** the `.htaccess` file does nothing at all, so the plugin does not write one; your
host needs to route the guide path to WordPress.

If your host will not change any of this, [Reverse proxy](/microsite/reverse-proxy) and
[Embed API](/microsite/embed-api) do not depend on `.htaccess`.

## What your visitors get if Obvlo is unavailable

The plugin serves a cached copy rather than an error, and never lets a slow response affect the rest of
your site.

| Situation                                    | What a visitor gets                                        |
| -------------------------------------------- | ---------------------------------------------------------- |
| Page cached and fresh (under 5 minutes)      | The cached page. No request leaves your server.            |
| Cache stale, Obvlo healthy                   | A freshly fetched page, refreshed during that request.     |
| Obvlo slow (over 4 seconds) or unreachable   | The last known-good copy of that page, kept for 24 hours.  |
| Obvlo failing repeatedly                     | The same, and Obvlo is not called again for a minute.      |
| Never-visited page **and** Obvlo unreachable | A plain "temporarily unavailable" page. Never a PHP error. |

Two of those numbers are deliberate. The request to Obvlo is abandoned after **4 seconds**, so one slow
page cannot occupy a PHP worker long enough to starve the rest of your site. After **3 consecutive
failures** Obvlo is not called again for a minute, so a sustained outage costs microseconds per request
rather than four seconds.

## Diagnosing a page

Every response carries two headers:

```bash theme={null}
curl -sI https://yourhotel.com/local-guides/ | grep -i x-obvlo
```

* `X-Obvlo-Cache` is one of `hit`, `miss`, `stale`, `breaker-open`, `error` or `disabled`.
* `X-Obvlo-Ref` is a short id for the page. Quote it to Obvlo support.

## Changing the mount path

The path is baked into the archive when you download it. If you change the URL on your domain in the
portal, **download the plugin again** and upload the new version — the old archive still carries the old
path.

Alternatively, correct it on the settings screen. Those edits are stored as overrides in WordPress
options and survive a re-upload, so a locally corrected path is not clobbered by a fresh download.

## Updates

Obvlo distributes this plugin, not wordpress.org, so WordPress will never offer you an update for it.

The plugin checks Obvlo once a day and shows an admin notice when a newer version exists, or a warning
when your copy is too old for the current Obvlo service. **Downloading a fresh archive from the portal
is the update.** Your settings survive it.

## Compatibility

|               | Supported                                                                                                                                                                                    |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| WordPress     | 6.0 and later                                                                                                                                                                                |
| PHP           | 7.4 and later, including 8.0–8.4                                                                                                                                                             |
| Multisite     | Yes, per site — activate on the site whose domain serves the guides                                                                                                                          |
| Permalinks    | Any setting except *Plain*                                                                                                                                                                   |
| Outbound HTTP | cURL preferred; PHP streams used if cURL is disabled                                                                                                                                         |
| Object cache  | Redis or Memcached preferred; transients in the database otherwise                                                                                                                           |
| Page caches   | WP Rocket, LiteSpeed, Cloudflare APO and similar are compatible. Obvlo pages carry their own `Cache-Control`, and a stale or error response is sent `no-store` so an outage is never cached. |

## Removing it

Deactivating changes nothing else on your site — it simply stops serving the guides, and the path
returns to WordPress. Deleting the plugin also removes its settings and its cached pages.

## Not on WordPress?

The same archive is available as a generic PHP proxy for a single-server PHP stack, and every other
platform is covered by a configuration file you paste in. See [Reverse proxy](/microsite/reverse-proxy).

## Related pages

* [Deployment modes](/microsite/deployment-modes)
* [Reverse proxy](/microsite/reverse-proxy)
* [Dynamic serving](/microsite/ssr-proxy)
* [Embed API](/microsite/embed-api)
* [Microsite overview](/microsite/overview)