Skip to main content

Marking text

A Pushery\AiContentMarking\MarkedText holds a plain text and the Marking that says how it came about. Create one where the text comes back from the model:

use Pushery\AiContentMarking\MarkedText;

$description = MarkedText::generated($modelOutput);
$returns = MarkedText::edited($rewrittenPolicy, generator: 'Support Desk', at: now(), model: 'example-writer', operator: 'Example Ltd');

generated() uses the term trainedAlgorithmicMedia, edited() the term compositeWithTrainedAlgorithmicMedia. The generator, the moment, the model and the operator are optional, and each ends up in the JSON form as a field of its own: the generator names the system that produced the text, the model the model behind it, and the operator the company that runs the system. For any other term, build the marking yourself:

use Pushery\AiContentMarking\DigitalSourceType;
use Pushery\AiContentMarking\MarkedText;
use Pushery\AiContentMarking\Marking;

$text = new MarkedText($proofread, new Marking(DigitalSourceType::AlgorithmicallyEnhanced));

In a page​

html() returns the escaped text inside a span that carries the marking as schema.org microdata. Wrap it in whatever element the page needs:

<h2>{{ $product->name }}</h2>
<p>{{ $description->html() }}</p>

The text becomes the text of a CreativeWork item, and a link element inside the item names the term:

<span itemscope itemtype="https://schema.org/CreativeWork">
<link itemprop="digitalSourceType" href="https://schema.org/TrainedAlgorithmicMediaDigitalSource">
<span itemprop="text">A linen shirt with a relaxed fit.</span>
</span>

The term travels in a link because microdata reads a URL value only from href. For the two terms schema.org has no member for, humanEdits and digitalCreation, the href is the IPTC URI of the term.

The marked paragraph looks exactly like one without a marking. Only its source differs:

The same paragraph rendered twice, once without a marking and once through MarkedText::html(). Both read "A linen shirt with a relaxed fit." and look the same. Under each, its HTML source shows that only the second carries the microdata, with the link element highlighted.

As a plain string​

A MarkedText is the plain text wherever a string is expected, and Blade's {{ }} escapes it like any other string. Nothing marks itself, so a text used where no markup may go stays intact:

<title>{{ $description }}</title>
<meta name="description" content="{{ $description }}">

In JSON​

toArray() and json_encode() give the text beside the values of its marking:

{
"text": "Returns take fourteen days.",
"marking": {
"version": 1,
"digital_source_type": "compositeWithTrainedAlgorithmicMedia",
"digital_source_type_uri": "http://cv.iptc.org/newscodes/digitalsourcetype/compositeWithTrainedAlgorithmicMedia",
"generator": "Support Desk",
"model": "example-writer",
"operator": "Example Ltd",
"generated_at": "2026-10-14T21:00:00+00:00"
}
}

Return the MarkedText from an API resource where the marking should reach the client, and the plain string where the client expects one. A Marking serializes on its own to the inner object.

version is the version of this shape. It rises when a field changes its meaning or leaves the shape, not when one is added, so a client can tell a shape it does not know from a value that is only missing. A marking stored before the field existed reads back with the model and the operator as null. The mail header field and the XMP of an image carry the term, the generator and the moment, not the model or the operator.

In the header section of a response​

A client that reads a response before its body, such as one that streams the answer, finds the marking in the response's header section as well. HttpMarking::headers() gives the field:

use Pushery\AiContentMarking\Http\HttpMarking;

return response()->json($answer, 200, HttpMarking::headers($answer->marking));
Digital-Source-Type: http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia; generator="Support Desk"

A client that reads the response sees the field before the body:

A JSON response with generated text, as a client reads it. The Digital-Source-Type field stands highlighted among the response's header fields and names the IPTC term and the generator Support Desk. The body below, indented as a client shows it, carries the text and its marking.

It is the field a mail carries, with the same value: the term's IPTC URI, and the generator and the moment as parameters. A response sends its header section before its body, so set the field from what is known when the response starts. Where a fallback can still change the model, leave the model out of the marking. The marking in the body stays the record of the content.

Rich HTML​

A text that already is HTML, such as a description your application stores as sanitized rich text, goes through Marking::wrap(). It puts the HTML into a div that carries the marking, and it does not escape it:

{{ $marking->wrap(new \Illuminate\Support\HtmlString($sanitizedDescription)) }}

Pass only HTML that is safe to render. A plain text belongs in MarkedText::html(), which escapes it.

Storing a marking with a model​

Marking is castable. Name it in the casts of a model with a JSON column, and the column stores exactly what toArray() writes:

use Illuminate\Database\Eloquent\Model;
use Pushery\AiContentMarking\MarkedText;
use Pushery\AiContentMarking\Marking;

final class Product extends Model
{
protected function casts(): array
{
return ['description_marking' => Marking::class];
}

public function markedDescription(): MarkedText|string
{
return $this->description_marking === null
? $this->description
: new MarkedText($this->description, $this->description_marking);
}
}

A column can stay null for a text nobody generated. Storing anything but a Marking or null throws an InvalidArgumentException, and so does reading a column that holds no stored marking. The cast reads the JSON as your database hands it back, so a PostgreSQL jsonb column, which reorders the keys, works the same as a MySQL json or a SQLite text column.