README

Open Graph protocol enhances information associated with a webpage through key-value pairs included as <meta> elements in your HTML. This additional data is consumed by social sharing sites, populating a story preview for shared links and referenced objects in the social graph.

This project includes tools to validate and sanitize inputs before generating Open Graph protocol markup on your webpages. This project standardizes outputs for easy indexing by consuming agents. We also let you consume remote pages and attempt to parse the Open Graph tags there of.

Consuming agents

Facebook

Facebook indexes Open Graph protocol markup found on pages shared in a member's social news feed. This markup also enhances social news feed stories generated by the Like button social plugin and Facebook Share.

Open Graph protocol markup turns webpages into objects within the Facebook social graph, increasing search exposure and uniquely classifying your site and story type within the social news feed.

The Facebook Object Debugger displays a Facebook interpretation of your site's Open Graph protocol content.

mixi Check

Mixi indexes Open Graph protocol markup in its mixi Check social sharing service.

Google+ Snippet

Google indexes Open Graph protocol markup to populate a Google+ activity post.

Structure

The Application includes a number of core objects in the Open Graph protocol. They are all located under the OpenGraph namespace.

Objects:

OpenGraph\Objects\Article
OpenGraph\Objects\Book
OpenGraph\Objects\Profile
OpenGraph\Objects\Video

Media:

OpenGraph\Media\Audio
OpenGraph\Media\Image
OpenGraph\Media\Video

Core Open Graph protocol

Support for structured properties for image, video, and audio objects.

<?php
$image = new OpenGraph\Media\Image();
$image->setURL( 'http://example.com/image.jpg' );
$image->setSecureURL( 'https://example.com/image.jpg' );
$image->setType( 'image/jpeg' );
$image->setWidth( 400 );
$image->setHeight( 300 );

$video = new OpenGraph\Media\Video();
$video->setURL( 'http://example.com/video.swf' );
$video->setSecureURL( 'https://example.com/video.swf' );
$video->setType( OpenGraphProtocolVideo::extension_to_media_type( pathinfo( parse_url( $video->getURL(), PHP_URL_PATH ), PATHINFO_EXTENSION ) ) );
$video->setWidth( 500 );
$video->setHeight( 400 );

$audio = new OpenGraph\Media\Audio();
$audio->setURL( 'http://example.com/audio.mp3' );
$audio->setSecureURL( 'https://example.com/audio.mp3' );
$audio->setType('audio/mpeg');
?>

Declare a new OpenGraphProtocol object and set some properties. Add structured media objects.

<?php
$ogp = new OpenGraph\Manager();
$ogp->setLocale( 'en_US' );
$ogp->setSiteName( 'Happy place' );
$ogp->setTitle( 'Hello world' );
$ogp->setDescription( 'We make the world happy.' );
$ogp->setType( 'website' );
$ogp->setURL( 'http://example.com/' );
$ogp->setDeterminer( 'the' );
$ogp->addImage($image);
$ogp->addAudio($audio);
$ogp->addVideo($video);
?>

Output your OpenGraphProtocol object as HTML <meta> elements. Default configuration uses the property attribute from RDFa. Change to name if you prefer HTML specification compliance and consuming agents support the name attribute as a property fallback.

<?php
$ogp->toHTML();
?>

Global objects

Build global objects and attributes. Set time values using either an ISO 8601 formatted string or a DateTime object. DateTimes will be converted to the UTC timezone before output for consistency.

<?php
$article = new OpenGraph\Objects\Article();
$article->setPublishedTime( '2011-11-03T01:23:45Z' );
$article->setModifiedTime( new DateTime( 'now', new DateTimeZone( 'America/Los_Angeles' ) ) );
$article->setExpirationTime( '2011-12-31T23:59:59+00:00' );
$article->setSection( 'Front page' );
$article->addTag( 'weather' );
$article->addTag( 'football' );
$article->addAuthor( 'http://example.com/author.html' );
?>

Convert a global object to <meta> elements just as you would with OpenGraphProtocol.

<?php
$article->toHTML();
?>

Combined

A common use case might be storing Open Graph protocol objects in a Controller for use by your web application. You can add each object to an array and later iterate through the array for <head prefix=""> and <meta> outputs.

<?php
$ogp_objects = array( $ogp, $article );
$prefix = '';
$meta = '';
foreach ( $ogp_objects as $ogp_object ) {
    $prefix .= $ogp_object::PREFIX . ': ' . $ogp_object::NS . ' ';
    $meta .= $ogp_object->toHTML() . PHP_EOL;
}
?>
<head prefix="<?php echo rtrim( $prefix,' ' ); ?>">
<?php echo rtrim( $meta, PHP_EOL ); ?>
</head>

Fetching

Commonly used in applications, fetching the contents of a remote page to get the Open Graph information can be a tedious task. Often time, you will have to get a webpage, write some regex to get the IMGs from it and MAYBE it'll work. Let us fix that.

<?php
// also shown in test.php

// Include Composer Autoloader
include 'vendor/autoload.php';

$fetch = new OpenGraph\Fetcher('http://www.cnn.com/2013/08/15/opinion/bergen-zawahiri-egypt/index.html?hpt=hp_t1');
var_dump($fetch->getKeys());
?>

That'll give you something that looks like this:

array (size=6)
  'description' => string 'Ayman al-Zawahiri, who has warned against Islamist parties taking part in elections, is emerging as a stronger leader than predicted' (length=132)
  'title' => string 'Al Qaeda leader's 'I told you so' on Egypt' (length=42)
  'type' => string 'article' (length=7)
  'url' => string 'http://www.cnn.com/2013/08/15/opinion/bergen-zawahiri-egypt/index.html' (length=70)
  'site_name' => string 'CNN' (length=3)
  'image' => string 'http://i2.cdn.turner.com/cnn/dam/assets/130815122452-08-egypt-0815-story-top.jpg' (length=80)

We're looking for ways to improve it still (find an image in the page's contents if og:image isn't specified). Stay tuned.

srtfisher / open-graph-protocol-tools

Maintainers

Details