PHPackages                             mosaicora/plugin-core-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. mosaicora/plugin-core-php

ActiveLibrary

mosaicora/plugin-core-php
=========================

Framework-agnostic Mosaicora Open Graph image URL and JSON-LD helpers for PHP.

v1.1.0(1mo ago)01131Apache-2.0PHPPHP ^8.1CI passing

Since Jul 18Pushed 1mo agoCompare

[ Source](https://github.com/Mosaicora/plugin-core-php)[ Packagist](https://packagist.org/packages/mosaicora/plugin-core-php)[ Docs](https://mosaicora.io/integrations/php)[ RSS](/packages/mosaicora-plugin-core-php/feed)WikiDiscussions master Synced 2w ago

READMEChangelog (2)Dependencies (2)Versions (3)Used By (1)

`mosaicora/plugin-core-php`
===========================

[](#mosaicoraplugin-core-php)

Framework-agnostic PHP helpers for Mosaicora Open Graph image URLs and `mosaicora:og` JSON-LD v3 overrides.

Install
-------

[](#install)

```
composer require mosaicora/plugin-core-php
```

The package requires PHP 8.1 or newer and has no runtime dependencies.

Build an Open Graph image URL
-----------------------------

[](#build-an-open-graph-image-url)

```
use Mosaicora\PluginCore\OgImageUrl;
use Mosaicora\PluginCore\OgImageUrlOptions;

$imageUrl = OgImageUrl::build(new OgImageUrlOptions(
    siteId: '321cac22d2103fb1660c50bd',
    pageHref: 'https://example.com/products/view',
));
```

The output is deterministic: it normalizes duplicate and trailing path slashes, keeps readable UTF-8 paths, ignores fragments, filters default tracking/control parameters, and percent-encodes the sorted remaining page query into the CDN path before `.jpg`. The CDN ignores query parameters after `.jpg` for source page lookup.

The home page produces `https://cdn.mosaicora.io/s/{siteId}.jpg` nested paths remain below `/s/{siteId}`. Pass `baseOrigin` to use a different CDN origin.

### Refreshing social image URLs

[](#refreshing-social-image-urls)

Social networks can retain a link preview after their first crawl. A new image URL helps them retrieve a new asset when they re-scrape page metadata, but it does not force them to re-scrape.

Use an explicit release or content revision when one is available:

```
$imageUrl = OgImageUrl::build(new OgImageUrlOptions(
    siteId: '321cac22d2103fb1660c50bd',
    pageHref: 'https://example.com/products/view',
    cacheVersion: 'release-2026-07',
));
```

Or opt in to a UTC schedule with `cacheBuster`: `daily`, `weekly`, `monthly`, or a positive duration such as `15m`, `6h`, or `7d`. `cacheVersion` takes precedence over `cacheBuster` and replaces any existing `v` parameter. Keep the default stable URL unless your content genuinely needs rotation. `monthly` is a good production default for most pages. The reserved `v` token remains after `.jpg` and is cache-only.

Add a v3 JSON-LD override
-------------------------

[](#add-a-v3-json-ld-override)

Keep existing Schema.org data and add only values Mosaicora should use exactly:

```
use Mosaicora\PluginCore\MosaicoraOgJsonLd;
use Mosaicora\PluginCore\MosaicoraOgJsonLdOptions;
use Mosaicora\PluginCore\MosaicoraOgOverride;

$jsonLd = MosaicoraOgJsonLd::build(new MosaicoraOgJsonLdOptions(
    schemaType: 'Product',
    name: 'Example product',
    offers: [
        '@type' => 'Offer',
        'price' => '49',
        'priceCurrency' => 'USD',
    ],
    mosaicoraOg: new MosaicoraOgOverride(
        templateId: '6a36446a0021410e8044',
        semanticValues: [
            'content.title' => 'Example product',
            'content.description' => 'A polished preview for every product page.',
            'product.price' => '$49',
            'product.features' => ['Fast setup', 'Consistent previews'],
        ],
    ),
));

$serialized = MosaicoraOgJsonLd::serialize($jsonLd);
```

`serialize()` removes null values recursively and escapes `