File Coverage

blib/lib/Module/CheckLatestVersion.pm

Criterion	Covered	Total	%
statement	20	52	38.4
branch	0	22	0.0
condition	0	25	0.0
subroutine	7	8	87.5
pod	1	1	100.0
total	28	108	25.9

package Module::CheckLatestVersion;

use 5.010001;
use strict;
use warnings;
use Log::ger;
use Log::ger::Format::MultilevelLog (); # for scan prereqs
use Log::ger::Format 'MultilevelLog';

use Exporter qw(import);

our $AUTHORITY = 'cpan:PERLANCAR'; # AUTHORITY
our $DATE = '2026-04-14'; # DATE
our $DIST = 'Module-CheckLatestVersion'; # DIST
our $VERSION = '0.009'; # VERSION

## no critic: Modules::ProhibitAutomaticExportation
our @EXPORT = qw(check_latest_version);

sub check_latest_version {
    my $opts = ref $_[0] eq 'HASH' ? {%{ shift()} } : {};
    my $mod = shift; $mod = caller() unless $mod;
    $opts->{die} //= $ENV{PERL_MODULE_CHECKLATESTVERSION_OPT_DIE};
    $opts->{log_level} //= 'debug';
    $opts->{do_check} //= 0 if
        $ENV{HARNESS_ACTIVE} ||
        $ENV{RELEASE_TESTING} ||
        $ENV{AUTOMATED_TESTING} ||
        $ENV{PERL_MODULE_CHECKLATESTVERSION_SKIP};

    if (defined($opts->{do_check}) && !$opts->{do_check}) {
        log('debug', "Skipping checking version of module $mod ...");
        return;
    }

    require Cache::File::Simple;
    my $cachekey = __PACKAGE__ . '|' . $mod;
    log($opts->{log_level}, "Checking version of module $mod from cache ...");
    my $res = Cache::File::Simple::cache($cachekey);
    unless ($res) {
        # cache miss
        log($opts->{log_level}, "Checking version of module $mod (cache miss) ...");
        require Module::CheckVersion;
        $res = Module::CheckVersion::check_module_version(module => $mod);
    }

    if ($res->[0] != 200) {
        warn "Cannot check latest version of module $mod: $res->[0] - $res->[1]";
        return;
    }

    if ($res->[2]{is_latest_version}) {
        log($opts->{log_level}, "Module $mod (installed version: $res->[2]{installed_version}) is latest version ($res->[2]{latest_version})");
        # cache only positive result AND when version is defined
        if (defined($res->[2]{installed_version}) && defined($res->[2]{latest_version})) {
            log($opts->{log_level}, "Caching version check result ...");
            Cache::File::Simple::cache($cachekey, $res);
        }
    } else {
        my $msg = "Module $mod (installed version: " .
            (defined($res->[2]{installed_version}) ? $res->[2]{installed_version} : "undef") .
            ") is not the latest version (" .
            (defined($res->[2]{latest_version}) ? $res->[2]{latest_version} : "undef") .
            ").";
        if ($opts->{die} && defined $res->[2]{latest_version}) {
            $msg .= " Please update to the latest version first.";
            die $msg;
        } else {
            $msg .= " Please consider updating to the latest version.";
            warn $msg;
        }
    }
}

1;
# ABSTRACT: Warn/die when a module is not the latest version

__END__