
#                                      Copyright 2024 WebPros International, LLC
#                                                           All rights reserved.
# copyright@cpanel.net                                         http://cpanel.net
# This code is subject to the cPanel license. Unauthorized copying is prohibited.

package Whostmgr::360Monitoring::Agent::Plugins::Roles::Installable;

use v5.36;
use Whostmgr::360Monitoring::Moo;
use Types::Common qw(Bool);
use Moo::Role;

requires qw(
  install
  uninstall
  is_installable
  is_installed
);

around 'install' => sub ( $orig, $self, $force = 0 ) {
    if ($force) {
        return $orig->($self);
    }
    else {
        return !!1            if $self->is_installed;
        return $orig->($self) if $self->is_installable;
        return !!0;
    }
};

sub install_and_enable ( $self, $force = 0 ) {
    my $status = $self->install($force);
    $status && $self->enabled( !!1 );
    $status;
}

sub uninstall_and_disable ( $self, $force = 0 ) {
    my $status = $self->uninstall($force);
    $status && $self->enabled( !!0 );
    $status;
}

1;

__END__

=head1 NAME

Whostmgr::360Monitoring::Agent::Plugins::Roles::Installable - A Moo::Role governing individual plugin installation/uninstallation.

=head1 DESCRIPTION

A role that requires you to imlement C<install>, C<uninstall>,
C<is_installed>, and C<is_installable>.

=head1 Things you must implement

Implementing this role requires a private implementation of the following methods.
B<Note you should only call them by their public names (without the "_").>

=over 8

=item install

How to install the plugin, regardless of any checks as to whether or not we
support the install. Used in C<install> and to provide C<install_and_enable>.

The user must implement `sub install {}`. The behavior of this function they
implemnt is modified by the role such that its invocation is augmented in the
following way.

=over 6

=item * Will shortcut and return true if the plugin is already installed. Or it
will trigger an install if C<supported_install> is true.

=item * A new parameter is also available to disable this augmentation `force`,
supplied as the first argument.

=back

=item uninstall

How to uninstall the plugin. Used in C<uninstall> and to provide
C<uninstall_and_disable>.

=item is_installed

Determines whether or not something is already already installed. Used
internally be C<install>.

=item supported_install

Only useful on plugins that are B<NOT> universally installable. Seemed like a
better name than C<is_installable> when we already have C<is_installed>. If
your plugin is defined everywhere, simply define a sub by this name and have it
return C<!!1>.

=back

=head1 METHODS

After implementing the above, you have the following methods available.

=over 8

=item install_and_enable

Sets the plugin to enabled. You'll still have to call the writer manually if
you want to flush the ini.

=head2 ARGUMENTS

=over

=item $force - Optional, Defaults to 0

If provided will force the install, otherwise the install only happens when the is_installable check returns true.

=back

=item uninstall_and_disable

Sets the plugin to NOT enabled. You'll still have to call the writer manually
if you want to flush the ini.

=head2 ARGUMENTS

=over

=item $force - Optional, Defaults to 0

If provided will force the uninstall, otherwise the uninstall only happens when the is_installable check returns true.

=back

=back
