A Fluent Builder For Schema.org Types And ld+json Generator
spatie/schema-org
provides a fluent builder for all Schema.org types and their properties. The code in src
is generated from Schema.org's RFDa standards file, so it provides objects and methods for the entire core vocabulary. The classes and methods are also fully documented as a quick reference.
use Spatie\SchemaOrg\Schema;
$localBusiness = Schema::localBusiness()
->name('Spatie')
->email('info@spatie.be')
->contactPoint(Schema::contactPoint()->areaServed('Worldwide'));
$localBusiness->toScript();
<script type="application/ld+json">
{
"@context": "http:\/\/schema.org",
"@type": "LocalBusiness",
"name": "Spatie",
"email": "info@spatie.be",
"contactPoint": {
"@type": "ContactPoint",
"areaServed": "Worldwide"
}
}
</script>
Installation
You can install the package via composer:
composer require spatie/schema-org
Usage
All types can be instantiated though the Spatie\SchemaOrg\Schema
factory class, or with the new
keyword.
$localBusiness = Schema::localBusiness()->name('Spatie');
// Is equivalent to:
$localBusiness = new LocalBusiness();
$localBusiness->name('Spatie');
All types also accept arrays of the expected data type, for example
sameAs
accepts a string or an array of strings.
Types can be converted to an array or rendered to a script.
$localBusiness->toArray();
$localBusiness->toScript();
echo $localBusiness; // Same output as `toScript()`
There's no full API documentation for types and properties. You can refer to the source or to the schema.org website.
If you don't want to break the chain of a large schema object, you can use the if
method to conditionally modify the schema.
use Spatie\SchemaOrg\LocalBusiness;
use Spatie\SchemaOrg\Schema;
$business = ['name' => 'Spatie'];
$localBusiness = Schema::localBusiness()
->name($business['name'])
->if(isset($business['email']), function (LocalBusiness $schema) {
$schema->email($business['email']);
});
I recommended double checking your structured data with Google's structured data testing tool
Advanced Usage
If you'd need to set a custom property, you can use the setProperty
method.
$localBusiness->setProperty('foo', 'bar');
If you'd need to retrieve a property, you can use the getProperty
method. You can optionally pass in a second parameter to provide a default value.
$localBusiness->getProperty('name'); // 'Spatie'
$localBusiness->getProperty('bar'); // null
$localBusiness->getProperty('bar', 'baz'); // 'baz'
All properties can be retrieved as an array with the getProperties
method.
$localBusiness->getProperties(); // ['name' => 'Spatie', ...]
Multiple properties can be set at once using the addProperties
method.
$localBusiness->addProperties(['name' => 'value', 'foo' => 'bar']);
Context and type can be retrieved with the getContext
and getType
methods.
$localBusiness->getContext(); // 'http://schema.org'
$localBusiness->getType(); // 'LocalBusiness'
Known Issues
Type Inheritance
The spec rdfa document that's used to generate this code uses single inheritance for the types. However, the spec on http://schema.org uses multiple inheritance in some cases. Read the docs and use Google's structured data testing tool to ensure you're on the right track!
For example, according to the rdfa, a LocalBusiness
inherits properties from Organization
. However, if you visit the spec page on Schema.org, it inherits properties from Organization
and Place
. The current solution is by manually specifying properties on the item, as described above in advanced usage.
Schema::localBusiness()
// `address` is part of `Organization`, so the method exists
->address(/* ... */)
// `openingHoursSpecification` is part of `Place`, so we need to manually add it
->setProperty('openingHoursSpecification', /* ... */);
Other Minor Issues
- Some docblocks have some formatting issues (PR's welcome!)
- The
Float
type isn't available since it's a reserved keyword in PHP - The
Physician
type isn't available since it extends a type from thehealth
extension spec
Changelog
Please see CHANGELOG for more information what has changed recently.
Testing
$ composer test
Contributing
Please see CONTRIBUTING for details.
Security
If you discover any security related issues, please email freek@spatie.be instead of using the issue tracker.
Postcardware
You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.
Our address is: Spatie, Samberstraat 69D, 2060 Antwerp, Belgium.
We publish all received postcards on our company website.
Credits
Support us
Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.
Does your business depend on our contributions? Reach out and support us on Patreon. All pledges will be dedicated to allocating workforce on maintenance and new awesome stuff.
License
The MIT License (MIT). Please see License File for more information.