Reference

Image Endpoint

URL

GET /og-image/{resource_type}/{resource_id}?site_id={siteId}
Parameter Values
resource_type site, item, item_set, media, page, search, blog_post
resource_id The numeric ID of the resource. For site this is the site ID; for search the module uses the site ID and adds the query as q.
site_id Optional query parameter. Selects the site whose title, tagline, logo and template override are used. Public pages always include it.

The endpoint is public; no login is required. It is registered outside the site namespace, so the same URL serves every site.

Response

Case Response
Image generated or served from cache 200, Content-Type: image/png, Cache-Control: public, max-age=86400, X-OG-Image: OgImages/1.0
Generation disabled, or the resource type is not enabled in settings 200 with a 1x1 transparent PNG and the same headers
The resource does not exist (its title resolves to empty) 404 with an empty body
GD is not available 200 with a 1x1 transparent PNG

The X-OG-Image header is a quick way to confirm that a response came from this module rather than a proxy or a theme.

Meta tags injected into pages

On a covered public page the module adds these tags through the headMeta() view helper:

<meta property="og:image" content="https://example.org/og-image/item/42?site_id=1">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:type" content="image/png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:image" content="https://example.org/og-image/item/42?site_id=1">
<meta property="og:title" content="Item title">
<meta property="og:description" content="Item description">

og:title and og:description are omitted when the value is empty. The width and height tags always report 1200 x 630 even when a template uses a different canvas size.

The image URL is absolute (force_canonical), built from the request's scheme and host.

Theme integration

  • Your theme's layout must print $this->headMeta() in <head>. The default theme does. Without it no tags appear.
  • Tags are set with setProperty / setName, which replace any existing headMeta entry with the same property or name. A theme or module that sets og:image earlier in the render is overridden; one that sets it later wins.
  • Tags are only injected when the request is a site request, the module is enabled, and the resource type is enabled in settings.
  • The listener keys on the controller and action: item, item set, media and page show actions, every action of the site index controller, the cross-site search controller, and the Blog module's post show action.

Cache keys

Generated files are stored as {cache_dir}/{resource_type}/{resource_id}.png, or {resource_id}_s{siteId}.png when site_id is present. Non-alphanumeric characters in the ID are stripped from the file name. See Cache Management.

Admin AJAX endpoints

Used by the template editor and the site settings section; they require the same role as template management.

Method and path Purpose
GET /admin/og-images/preview-vars?resource_type=item&resource_id=42[&site_id=1] Returns { "ok": true, "vars": { ... } } with the resolved variables for the live preview.
GET /admin/og-images/random-resource?resource_type=item Returns { "ok": true, "id": "17" } for a random resource of that type (not supported for search).
POST /admin/og-images/site-settings Saves per-site overrides; fields site_id and template_{type}.
GET /admin/og-images/flush-cache[?type=item] Flushes all cached images, or one type. Returns JSON when called with X-Requested-With: XMLHttpRequest.
Log in for Support