Json Ld Laravel Package

Getting Started

Begin by installing via Composer: composer require ml/json-ld. After autoloading, the fastest path to value is using the static JsonLD API—start with JsonLD::expand() to normalize any JSON-LD input (e.g., expanding Schema.org microdata for SEO validation), or JsonLD::compact() with a reusable context (e.g., @context for schema.org) to standardize output. Use the online playground to experiment with transformations before coding. A common first task: embed structured data in Blade templates by compacting internal data into schema.org-compliant JSON-LD using JsonLD::toString(JsonLD::compact($data, $context), true).

Implementation Patterns

Leverage the procedural JsonLD facade for core pipeline operations in controllers or services:

• SEO & Rich Snippets: In a controller, generate <script type="application/ld+json"> blocks by compacting product/order/event data using JsonLD::compact($document, $schemaContext).
• Data Interoperability: Use JsonLD::frame() to extract specific subsets (e.g., author-only views) from complex JSON-LD APIs, or JsonLD::flatten() to normalize graph structures before storage.
• RDF Integration: Convert to/from RDF quads with JsonLD::toRdf() and NQuads for interoperability with graph databases (e.g., Blazegraph, RDF4J) via Laravel queued jobs.
• Node-level mutation: When modifying semantic relationships (e.g., adding cross-references in a knowledge graph), use JsonLD::getDocument() → $doc->getGraph()->getNode($id) → $node->addPropertyValue() → $graph->toJsonLd(). Note: Reserve this for low-volume, graph-intensive tasks due to experimental status.

Gotchas and Tips

• Array vs Document: JsonLD::expand() always returns an array of graphs—even with one document—so use reset($expanded) to get the top-level graph.
• Context handling: Remote contexts (HTTP(S)) require network access and fail silently if unreachable; cache them manually via ['@context' => include 'context.jsonld'] or inject via Laravel config.
• Blank nodes: IDs like _:b0 are regenerated per operation—never rely on them for state persistence; assign stable @ids early.
• Memory/CPU: Large documents (>5MB) risk OOM; profile with memory_get_usage() and consider chunking or async processing in Laravel queues.
• Debugging: Always inspect intermediate results with JsonLD::toString($value, true) (pretty-print enabled).
• Dependencies: Ensure ext-json and ml/iri (auto-required) are installed; missing ext-json causes silent failures—add a health check in AppServiceProvider.
• Experimental OOP: Avoid node mutation in production unless thoroughly tested—round-trip serialization may lose property order or blank node references.