Skip to content
On this page

JSON-LD

Modern web applications needs to provide the websites informations in structure way for search engines, therefore you can use luya\web\JsonLd. The inheritation and full documentation about the schema itself is available under https://schema.org.

Basic usage

Every JSON-LD property starts within a given type like Person the base of every type is Thing. The following list highlights the most common used types:

NameUsage
luya\web\jsonld\ThingThis is the base object for every JSON-LD object.
luya\web\jsonld\PersonAuthors for serveral things like blog post, comments or used when having text about a person.
luya\web\jsonld\BlogPostingUsed for Blog posts or news articles.
luya\web\jsonld\OrganizationProvides information about an organization such as a school, NGO, corporation, club, etc.
luya\web\jsonld\CreativeWorkProviding informations about a given work.
luya\web\jsonld\PlaceDescribes location, for example to provide the company location.
luya\web\jsonld\ImageObjectUsed for images or galleries.
luya\web\jsonld\CommentCould be used for user comments.
luya\web\jsonld\ContactPointE-Mail, Telephone or address.
luya\web\jsonld\OfferProviding an estore offer.
php
JsonLd::person()
   ->setGivenName('Albert')
   ->setFamilyName('Einstein')
   ->setBirthPlace('Ulm, Germany');

Keep in mind that a lot of objects require a certain sub object. This makes it more complex to build and understand, but also provides the possibility for the nesting which are required by the schema defintions. For example the BlogPosting publisher requires an Organisation object and the organisation logo requires an ImageObject object:

php
$logo = (new ImageObject())
    ->setUrl(new UrlValue('https://example.com/johndoe.jpg'));

$organisation = (new Organization())
    ->setName('John Doe')
    ->setLogo($logo);
        
JsonLd::blogPosting()
    ->setPublisher($organisation)

Currently we do not have all possible types implemented but you can always register them by yourself by calling luya\web\JsonLd::addGraph() with an array which contains the defintions:

php
luya\web\JsonLd::addGraph([
    "url" => "https://heartbeat.gmbh/blog/2018/5-jahre-heartbeat-aarau",
    "@type" => "BlogPosting",
|);

Value Types

Some properties require a given type of value, therefore we have Value objects. Some methods can require those objects in order to make sure the correct value is passed to the properties, otherwise you could enter values which are not valid for the given key.

An example for a value object with an URL to a given image:

php
$image = (new ImageObject())
    ->setUrl(new UrlValue('https://example.com/johndoe.jpg'));

The value object will then parse the input correctly for the given schema property.

NameUsage
luya\web\jsonld\DateTimeValueUsed for timestamps with time.
luya\web\jsonld\DateValueUsed for date values.
luya\web\jsonld\DurationValueTime periods as duration.
luya\web\jsonld\UrlValueUsed for paths to images or websites (links).
luya\web\jsonld\TextValueUsed when objects needs to get shorten or encode the text values is required.

Advanced usage

An example for providing structured JSON-LD for a blog with LUYA CMS module:

php
$current = Yii::$app->menu->current;

// register general thing information about the current page
JsonLd::thing()
    ->setName($current->title)
    ->setDescription($current->description)
    ->setUrl(new UrlValue($current->absoluteLink))
    
// author
$author = (new Person())
    ->setName($current->userCreated->firstname . " " . $current->userCreated->lastname);
    
// about
$about = (new Thing())
    ->setDescription($current->title);
    
// company logo definition
$companyLogo = (new ImageObject())
    ->setUrl(new UrlValue('https://example.com/company-logo.jpg'));
    
// publisher
$publisher = (new Organization())
    ->setName('My company')
    ->setLogo($companyLogo);
    
// register the blog post
JsonLd::blogPosting()
    ->setAbout($about)
    ->setAuthor($author)
    ->setPublisher($publisher)
    ->setDateCreated(new DateTimeValue($current->dateCreated))
    ->setDateModified(new DateTimeValue($current->dateUpdated))
    ->setDatePublished(new DateTimeValue($current->dateCreated))
    ->setHeadline(new TextValue($current->description))
    ->setUrl(new UrlValue($current->absoluteLink));