NAME

Web::Mention - Implementation of the IndieWeb Webmention protocol

SYNOPSIS

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

 # Building a webmention from an incoming web request:

 my $wm;
 try {
     # $request can be any object that provides a 'param' method, such as
     # Catalyst::Request or Mojo::Message::Request.
     $wm = Web::Mention->new_from_request ( $request )
 }
 catch {
     say "Oops, this wasn't a webmention at all: $_";
 };

 if ( $wm && $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 "This webmention doesn't actually mention its target URL, "
        . "so it is not verified.";
 }

 # Manually buidling and sending a webmention:

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

 my $success = $wm->send;
 if ( $success ) {
     say "Webmention sent successfully!";
 }
 else {
     say "The webmention wasn't sent successfully.";
     say "Here's the response we got back..."
     say $wm->response;
 }

DESCRIPTION

This class implements the Webmention protocol, as defined by the W3C and the IndieWeb community. (See: https://indieweb.org/Webmention)

An object of this class represents a single webmention, with target and source URLs. It can verify itself, determining whether or not the document found at the source URL does indeed mention the target URL. It can also use the Indieweb authorship algorithm to identify and describe the author of source document, if possible.

METHODS

Class Methods

new

 $wm = Web::Mention->new( source => $source_url, target => $target_url );

Basic constructor. The source and target URLs are both required arguments. Either one can either be a URI object, or a valid URL string.

Per the Webmention protocol, the source URL represents the location of the document that made the mention described here, and target describes the location of the document that got mentioned. The two arguments cannot refer to the same URL (disregarding the #fragment part of either, if present).

new_from_request

 $wm = Web::Mention->new_from_request( $request_object );

Convenience constructor that looks into the given web-request object for source and target parameters, and attempts to build a new Web::Mention object out of them.

The object must provide a param( $param_name ) method that returns the value of the named HTTP parameter. So it could be a Catalyst::Request object or a Mojo::Message::Request object, for example.

Throws an exception if the given argument doesn't meet this requirement, or if it does but does not define both required HTTP parameters.

Object Methods

author

 $author = $wm->author;

A Web::Mention::Author object representing the author of this webmention's source document, if we're able to determine it. If not, this returns undef.

content

 $content = $wm->content;

The content of this webmention, if its source document exists and defines its content using Microformats2. If not, then it returns the content of the source document's <title> element, if it has one.

CAUTION: Spec-compliant implementation of this method is incomplete, and its API may change in near-future updates to this module.

endpoint

 my $uri = $wm->endpoint;

Attempts to determine the webmention endpoint URL of this webmention's target. On success, returns a URI object. On failure, returns undef.

(If the endpoint is set to localhost or a loopback IP, will return undef and also emit a warning, because that's terribly rude behavior on the target's part.)

is_verified

 $bool = $wm->is_verified;

Returns 1 if the webmention's source document actually does seem to mention the target URL. Otherwise returns 0.

The first time this is called on a given webmention object, it will try to fetch the source document at its designated URL. If it cannot fetch the document on this first attempt, this method returns 0.

original_source

 $original_url = $wm->original_source;

If the document fetched from the source URL seems to point at yet another URL as its original source, then this returns that URL. If not, this has the same return value as source().

(It makes this determination based on the possible presence a u-url property in an h-entry found within the source document.)

response

 my $response = $wm->response;

Returns the HTTP::Response object representing the response received by this webmention instance during its most recent attempt to send itself.

Returns undef if this webmention instance hasn't tried to send itself.

send

 my $bool = $wm->send;

Attempts to send an HTTP-request representation of this webmention to its target's designated webmention endpoint. This involves querying the target URL to discover said endpoint's URL (via the endpoint object method), and then sending the actual webmention request via HTTP to that endpoint.

If that whole process goes through successfully and the endpoint returns a success response (meaning that it has acknowledged the webmention, and most likely queued it for later processing), then this method returns true. Otherwise, it returns false.

source

 $source_url = $wm->source;

Returns the webmention's source URL, as a URI object.

source_html

 $html = $wm->source_html;

The HTML of the document fetched from the source URL. If nothing got fetched successfully, returns undef.

source_mf2_document

 $mf2_doc = $wm->source_mf2_document;

The Web::Microformats2::Document object that resulted from parsing the source document for Microformats2 metadata. If no such result, returns undef.

target

 $target_url = $wm->target;

Returns the webmention's target URL, as a URI object.

type

 $type = $wm->type;

The type of webmention this is. One of:

• mention (default)

• reply

• like

• repost

• quotation

NOTES AND BUGS

This software is alpha; its author is still determining how it wants to work, and its interface might change dramatically.

Implementation of the content-fetching method is incomplete.

SUPPORT

To file issues or submit pull requests, please see this module's repository on GitHub.

The author also welcomes any direct questions about this module via email.

AUTHOR

Jason McIntosh (jmac@jmac.org)

CONTRIBUTORS

• Mohammad S Anwar (mohammad.anwar@yahoo.com)

COPYRIGHT AND LICENSE

This software is Copyright (c) 2018 by Jason McIntosh.

This is free software, licensed under:

  The MIT (X11) License

cpanm Web::Mention

perl -MCPAN -e shell
install Web::Mention