view release on metacpan or  search on metacpan

lib/Lib/Pepper/Simple.pm  view on Meta::CPAN

    # Validate library_path matches
    if($library_path ne $INIT_LIBRARY_PATH) {
        return 0;
    }

    # Validate config_xml matches (strict - must be identical)
    if($config_xml ne $INIT_CONFIG_XML) {
        return 0;
    }

    # Validate license_xml matches
    if($license_xml ne $INIT_LICENSE_XML) {
        return 0;
    }

    return 1;
}

# Class method to check process-wide library status
# Returns hashref with library state information
sub library_status($class) {
    return {
        initialized     => $LIBRARY_INITIALIZED,
        instance_count  => $INSTANCE_COUNT,
        library_path    => $INIT_LIBRARY_PATH,
        instance_ids    => { %INSTANCE_ID_COUNTERS },
    };
}

sub DESTROY($self) {
    # Cleanup instance resources
    if($self->{instance}) {
        eval {
            # Connection cleanup handled by Instance destructor
            undef $self->{instance};
        };
    }

    # ========================================
    # MULTI-INSTANCE SUPPORT: Reference counting
    # ========================================
    # CRITICAL: Only decrement if this instance was actually counted!
    # If constructor failed before incrementing, don't decrement
    return unless $self->{_instance_counted};

    # Decrement the instance counter
    $INSTANCE_COUNT--;

    # ========================================
    # DESIGN DECISION: Never finalize the library
    # ========================================
    # The Pepper C library has a critical limitation: once pepFinalize() is called,
    # pepInitialize() cannot be called again in the same process (returns error -103).
    #
    # SOLUTION: We never call pepFinalize(), keeping the library loaded in memory.
    # This allows creating new instances even after all previous instances are destroyed.
    #
    # Trade-offs:
    #   PRO: Can create instances → destroy all → create new instances ✓
    #   PRO: No -103 errors, can run unlimited test iterations ✓
    #   PRO: Simpler lifecycle management ✓
    #   CON: Library stays in memory until process exit (~few MB)
    #   CON: Cannot reset library state without restarting process
    #
    # Note: Instance-level resources (connections, handles) are still properly cleaned up.
    #       Only the library initialization state persists.

    return;
}

# Internal logging helper - uses reph if available, falls back to STDERR
sub _log($self, @parts) {
    if($self->{reph} && $self->{reph}->can('debuglog')) {
        $self->{reph}->debuglog(@parts);
    } else {
        # Fallback to STDERR if no reph provided
        print STDERR join('', @parts), "\n";
    }
    return;
}

# Default callback if user doesn't provide one
sub _defaultCallback {
    # Silent default callback - user can provide their own for logging/debugging
    return;
}

1;
__END__

=encoding utf8

=head1 NAME

Lib::Pepper::Simple - High-level payment terminal interface

=head1 SYNOPSIS

    use Lib::Pepper::Simple;
    use Lib::Pepper::Constants qw(:all);

    # Initialize connection to terminal
    my $pepper = Lib::Pepper::Simple->new(
        terminal_type    => PEP_TERMINAL_TYPE_GENERIC_ZVT,
        terminal_address => '192.168.1.163:20008',
        license_file     => '/path/to/license.xml',
        config_file      => '/path/to/config.xml',
    );

    # Check terminal status
    my $status = $pepper->checkStatus();
    if($status->{ready_for_transactions}) {
        print "Terminal ready!"\n";
    }

    # Process a payment (100.50 EUR)
    my $payment = $pepper->doPayment(10_050);
    if($payment->{authorized}) {
        print "Payment authorized!"\n";
        print "Trace: $payment->{trace_number}"\n";