PrePAN

Sign in to PrePAN

Web::Mention An implementation of the Webmention protocol, as defined by the W3C and the IndieWeb community.

Good

Synopsis

 use Web::Mention;
 use Try::Tiny;
 use v5.22;

 # Define a simple handler that, given a web-request object, determines
 # whether it contains a webmention, and reacts to it if so.
 sub find_webmention ( $ ) {

    # $request is an object that provides a 'param' method, such as
    # Catalyst::Request or Mojo::Message::Request.
    my ( $request ) = @_;

    my $wm;
    try {
        $wm = Web::Mention->new_from_request ( $request )
    }
    catch {
        say "Oops, this wasn't a webmention at all: $_";
    };
    return unless $wm;

    if ( $wm->is_verified ) {
        my $author = $wm->author;
        my $name;
        if ( $author ) {
            $name = $author->name;
        }
        else {
            $name = 'somebody';
        }

        my $source = $wm->original_source;
        my $target = $wm->target;

        if ( $wm->is_like ) {
            say "Hooray, $name likes $target!";
        }
        elsif ( $wm->is_repost ) {
            say "Gadzooks, over at $source, $name reposted $target!";
        }
        elsif ( $wm->is_reply ) {
            say "Hmm, over at $source, $name said this about $target:";
            say $wm->content;
        }
        else {
            say "I'll be darned, $name mentioned $target at $source!";
        }
    }
    else {
       say "What the heck, this so-called 'webmention' doesn't actually "
             . "mention its target URL. The nerve!";
    }
 }

 # Manually buidling a webmention:

 my $wm = Web::Mention->new(
    source => $url_of_the_thing_that_got_mentioned,
    target => $url_of_the_thing_that_did_the_mentioning
 );

 # Sending a webmention:
 # ...watch this space.

Description

This set of modules implements Webmention, according to its W3C-defined spec as well as related best practices developed by the IndieWeb community.

About Webmention

Webmention provides a standard way for one website to inform another that someone, somewhere on the web, has published a reference to a URL under the receiver's domain. This notification travels through very short and simple HTTP POST messages that merely identify the two URLs involved: the source of the mention, and its target. The receiver of a webmention can, at its own leisure, request the HTML document found at the source URL in order to verify the mention, and also to learn more about its author and content via any Microformats2 metadata it may contain. The receiver may then proceed to do something interesting with this fetched and parsed data, such as display hyperlinked information about the mention and its author underneath its own, original content.

For example, a response published on Blog A to an article on Magazine B could result in A sending a webmention to B. (There is implied consent here, since the article on B has a <link> tag in its HTML that explicitly invites webmentions, providing an endpoint URI for them.) It would then become B's responsibility to confirm that the webpage at A really does mention the URL of B's aticle. B may then wish to represent the mention on its own site, however it deems appropriate.

About these modules

An object of the main Web::Mention class represents a single webmention instance, probably created from an incoming HTTP request, as shown in the synopsis. The object's verify() method (and, indeed, its is_verified attribute) will do the hard work of fetching the source URL's document, verifying the presence of the target URL, and parsing any Microformats2 metdata it finds in order to infer author information. The latter goes into a Web::Mention::Author object, and taken all together this should give the receiver enough information to react in some appropriate way to the mention.

This module requires Web::Microformats2, another proposed CPAN module of mine with its own PrePAN page.

Near-future versions of this module will assist with creating and sending webmentions. But receiving is the harder part (and arguably the more rewarding part as well) so I wanted to get it done first. This ended up being a depth-first adventure that resulted in my creating all of Web::Microformats2 before I could come back and finish this module, and so here we are.

Regarding the name

I'd like to hear opinions on the name. Giving it a top-level namespace of "Web" seemed natural, for the same arguments I made in Web::Microformats2's case, and then following up the way I did seemed inevitable. But is splitting the word up this way too "cute"? Or, more to the point, will it make it harder to find in CPAN searches?

Certainly "Web::Webmention" is too ugly to live, but I could be talked into e.g. "Net::Webmention" or "HTTP::Webmention" or something. Absent any argument to the contrary, I do like both the directness and the subtle humor of "Web::Mention" the best.

Comments

Please sign up to post a review.