View on
MetaCPAN
Chase Whitener > WWW-Shorten-Yourls > WWW::Shorten::Yourls

Download:
WWW-Shorten-Yourls-1.001.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 1.001   Source  

NAME ^

WWW::Shorten::Yourls - Interface to shortening URLs using http://yourls.org

SYNOPSIS ^

The traditional way, using the WWW::Shorten interface:

    use strict;
    use warnings;

    use WWW::Shorten::Yourls;
    # use WWW::Shorten 'Yourls';  # or, this way

    # if you have a config file with your credentials:
    my $short_url = makeashorterlink('http://www.foo.com/some/long/url');
    my $long_url  = makealongerlink($short_url);
    # otherwise
    my $short = makeashorterlink('http://www.foo.com/some/long/url', {
        username => 'username',
        password => 'password',
        server => 'https://yourls.org/yourls-api.php',
        ...
    });

Or, the Object-Oriented way:

    use strict;
    use warnings;
    use Data::Dumper;
    use Try::Tiny qw(try catch);
    use WWW::Shorten::Yourls;

    my $yourls = WWW::Shorten::Yourls->new(
        username => 'username',
        password => 'password',
        signature => 'adflkdga234252lgka',
        server => 'https://yourls.org/yourls-api.php', # default
    );
    try {
        my $res = $yourls->shorten(longUrl => 'http://google.com/');
        say Dumper $res;
        # {
        #    message => "http://google.com/ added to database",
        #    shorturl => "https://yourls.org/4",
        #    status => "success",
        #    statusCode => 200,
        #    title => "Google",
        #    url => {
        #        date => "2017-02-08 02:34:37",
        #        ip => "192.168.0.1",
        #        keyword => 4,
        #        title => "Google",
        #        url => "http://google.com/"
        #    }
        # }
    }
    catch {
        die("Oh, no! $_");
    };

DESCRIPTION ^

A Perl interface to the Yourls.org API.

You can either use the traditional (non-OO) interface provided by WWW::Shorten. Or, you can use the OO interface that provides you with more functionality.

FUNCTIONS ^

In the non-OO form, WWW::Shorten::Yourls makes the following functions available.

makeashorterlink

    my $short_url = makeashorterlink('https://some_long_link.com');
    # OR
    my $short_url = makeashorterlink('https://some_long_link.com', {
        username => 'foo',
        password => 'bar',
        # any other attribute can be set as well.
    });

The function makeashorterlink will call the Yourls Server web site, passing it your long URL and will return the shorter version.

http://yourls.org requires the use of a user account to shorten links.

makealongerlink

    my $long_url = makealongerlink('http://yourls.org/22');
    # OR
    my $long_url = makealongerlink('http://yourls.org/22', {
        username => 'foo',
        password => 'bar',
        # any other attribute can be set as well.
    });

The function makealongerlink does the reverse. makealongerlink will accept as an argument either the full URL or just the identifier.

If anything goes wrong, either function will die.

ATTRIBUTES ^

In the OO form, each WWW::Shorten::Yourls instance makes the following attributes available.

password

    my $password = $yourls->password;
    $yourls = $yourls->password('some_secret'); # method chaining

Gets or sets the password. This is used along with the "username" in WWW::Shorten::Yourls attribute. Credentials are sent to the server upon each and every request.

server

    my $server = $yourls->server;
    $yourls = $yourls->server(
        URI->new('https://yourls.org/yourls-api.php')
    ); # method chaining

Gets or sets the server. This is full and absolute path to the server and yourls-api.php endpoint.

signature

    my $signature = $yourls->signature;
    $signature = $yourls->signature('abcdef123'); # method chaining

Gets or sets the signature. If the signature attribute is set, the "userna,e" in WWW::Shorten::Yourls and "password" in WWW::Shorten::Yourls attributes are ignored on each request and instead the signature is sent. See the Password-less API documentation for more details.

username

    my $username = $yourls->username;
    $yourls = $yourls->username('my_username'); # method chaining

Gets or sets the username. This is used along with the "password" in WWW::Shorten::Yourls attribute. Credentials are sent to the server upon each and every request.

METHODS ^

In the OO form, WWW::Shorten::Yourls makes the following methods available.

new

    my $yourls = WWW::Shorten::Yourls->new(
        username => 'username',
        password => 'password',
        signature => 'adflkdga234252lgka',
        server => 'https://yourls.org/yourls-api.php', # default
    );

The constructor can take any of the attributes above as parameters.

Any or all of the attributes can be set in your configuration file. If you have a configuration file and you pass parameters to new, the parameters passed in will take precedence.

clicks

    my $clicks = $yourls->clicks(shorturl => "https://yourls.org/5");
    say Dumper $clicks;
    # {
    #    link => {
    #        clicks => 0,
    #        ip => "192.168.0.1",
    #        shorturl => "http://yourls.org/5",
    #        timestamp => "2017-02-08 02:37:24",
    #        title => "Google",
    #        url => "http://www.google.com"
    #    },
    #    message => "success",
    #    statusCode => 200
    # }

Get the url-stats or number of clicks for a given URL made shorter using the Yourls API. Returns a hash reference or dies. Make use of Try::Tiny.

expand

    my $long = $yourls->expand(shorturl => "https://yourls.org/5");
    say $long->{longurl};
    # http://www.google.com
    say Dumper $long;
    # {
    #    keyword => 4,
    #    longurl => "http://www.google.com",
    #    message => "success",
    #    shorturl => "http://jupiter/yourls/5",
    #    statusCode => 200,
    #    title => "Google"
    # }

Expand a URL using the Yourls API. Returns a hash reference or dies. Make use of Try::Tiny.

shorten

    my $short = $yourls->shorten(
        url => "http://google.com/", # required.
    );
    say $short->{shorturl};
    # https://yourls.org/4
    say Dumper $short;
    # {
    #    message => "http://google.com/ added to database",
    #    shorturl => "https://yourls.org/4",
    #    status => "success",
    #    statusCode => 200,
    #    title => "Google",
    #    url => {
    #        date => "2017-02-08 02:34:37",
    #        ip => "192.168.0.1",
    #        keyword => 4,
    #        title => "Google",
    #        url => "http://google.com/"
    #    }
    # }

Shorten a URL using the Yourls API. Returns a hash reference or dies. Make use of Try::Tiny.

CONFIG FILES ^

$HOME/.yourls or _yourls on Windows Systems.

You may omit username and password in the constructor if you set them in the .yourls config file on separate lines using the syntax:

  username=username
  password=password
  server=https://yourls.org/yourls-api.php
  signature=foobarbaz123

Set any or all "ATTRIBUTES" in WWW::Shorten::Yourls in your config file in your home directory. Each key=val setting should be on its own line. If any parameters are then passed to the "new" in WWW::Shorten::Yourls constructor, those parameter values will take precedence over these.

AUTHOR ^

Pankaj Jain, <pjain@cpan.org>

CONTRIBUTORS ^

LICENSE AND COPYRIGHT ^

Copyright (c) 2009 Pankaj Jain, All Rights Reserved http://blog.linosx.com.

Copyright (c) 2009 Teknatus Solutions LLC, All Rights Reserved http://www.teknatus.com.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: