<<

NAME

Koha::Patron - Koha Patron Object class

API

Class Methods

new

fixup_cardnumber

Autogenerate next cardnumber from highest value found in database

trim_whitespace

trim whitespace from data which has some non-whitespace in it. Could be moved to Koha::Object if need to be reused

plain_text_password

$patron->plain_text_password( $password );

stores a copy of the unencrypted password in the object for use in code before encrypting for db

store

Patron specific store method to cleanup record and do other necessary things before saving to db

delete

$patron->delete

Delete patron's holds, lists and finally the patron.

Lists owned by the borrower are deleted or ownership is transferred depending on the ListOwnershipUponPatronDeletion pref, but entries from the borrower to other lists are kept.

category

my $patron_category = $patron->category

Return the patron category for this patron

image

library

Returns a Koha::Library object representing the patron's home library.

sms_provider

Returns a Koha::SMS::Provider object representing the patron's SMS provider.

guarantor_relationships

Returns Koha::Patron::Relationships object for this patron's guarantors

Returns the set of relationships for the patrons that are guarantors for this patron.

Note that a guarantor should exist as a patron in Koha; it was not possible to add them without a guarantor_id in the interface for some time. Bug 30472 restricts it on db level.

is_guarantee

Returns true if the patron has a guarantor.

guarantee_relationships

Returns Koha::Patron::Relationships object for this patron's guarantors

Returns the set of relationships for the patrons that are guarantees for this patron.

The method returns Koha::Patron::Relationship objects for the sake of consistency with the guantors method. A guarantee by definition must exist as a patron in Koha.

is_guarantor

Returns true if the patron is a guarantor.

relationships_debt

Returns the amount owed by the patron's guarantors *and* the other guarantees of those guarantors

housebound_profile

Returns the HouseboundProfile associated with this patron.

housebound_role

Returns the HouseboundRole associated with this patron.

siblings

Returns the siblings of this patron.

merge_with

    my $patron = Koha::Patrons->find($id);
    $patron->merge_with( \@patron_ids );

    This subroutine merges a list of patrons into the patron record. This is accomplished by finding
    all related patron ids for the patrons to be merged in other tables and changing the ids to be that
    of the keeper patron.

messaging_preferences

    my $patron = Koha::Patrons->find($id);
    $patron->messaging_preferences();

wants_check_for_previous_checkout

    $wants_check = $patron->wants_check_for_previous_checkout;

Return 1 if Koha needs to perform PrevIssue checking, else 0.

do_check_for_previous_checkout

    $do_check = $patron->do_check_for_previous_checkout($item);

Return 1 if the bib associated with $ITEM has previously been checked out to $PATRON, 0 otherwise.

is_debarred

my $debarment_expiration = $patron->is_debarred;

Returns the date a patron debarment will expire, or undef if the patron is not debarred

is_expired

my $is_expired = $patron->is_expired;

Returns 1 if the patron is expired or 0;

is_active

$patron->is_active({ [ since => $date ], [ days|weeks|months|years => $value ] })

A patron is considered 'active' if the following conditions hold:

    - account did not expire
    - account has not been anonymized
    - enrollment or lastseen within period specified

Note: lastseen is updated for triggers defined in preference TrackLastPatronActivityTriggers. This includes logins, issues, holds, etc.

The period to check is defined by $date or $value in days, weeks or months. You should pass one of those; otherwise an exception is thrown.

password_expired

my $password_expired = $patron->password_expired;

Returns 1 if the patron's password is expired or 0;

is_going_to_expire

my $is_going_to_expire = $patron->is_going_to_expire;

Returns 1 if the patron is going to expired, depending on the NotifyBorrowerDeparture pref or 0

set_password

    $patron->set_password({ password => $plain_text_password [, skip_validation => 1, action => NAME ] });

Set the patron's password.

Allows optional action parameter to change name of action logged (when enabled). Used for reset password.

Exceptions

The passed string is validated against the current password enforcement policy. Validation can be skipped by passing the skip_validation parameter.

Exceptions are thrown if the password is not good enough.

Koha::Exceptions::Password::TooShort
Koha::Exceptions::Password::WhitespaceCharacters
Koha::Exceptions::Password::TooWeak
Koha::Exceptions::Password::Plugin (if a "check password" plugin is enabled)

renew_account

my $new_expiry_date = $patron->renew_account

Extending the subscription to the expiry date.

has_overdues

my $has_overdues = $patron->has_overdues;

Returns the number of patron's overdues

has_restricting_overdues

my $has_restricting_overdues = $patron->has_restricting_overdues({ issue_branchcode => $branchcode });

Returns true if patron has overdues that would result in debarment.

update_lastseen

  $patron->update_lastseen('activity');

Updates the lastseen field, limited to one update per day, whenever the activity passed is listed in TrackLastPatronActivityTriggers.

The method should be called upon successful completion of the activity.

move_to_deleted

my $is_moved = $patron->move_to_deleted;

Move a patron to the deletedborrowers table. This can be done before deleting a patron, to make sure the data are not completely deleted.

can_request_article

    if ( $patron->can_request_article( $library->id ) ) { ... }

Returns true if the patron can request articles. As limits apply for the patron on the same day, those completed the same day are considered as current.

A library_id can be passed as parameter, falling back to userenv if absent.

article_request_fee

    my $fee = $patron->article_request_fee(
        {
          [ library_id => $library->id, ]
        }
    );

Returns the fee to be charged to the patron when it places an article request.

A library_id can be passed as parameter, falling back to userenv if absent.

add_article_request_fee_if_needed

    my $fee = $patron->add_article_request_fee_if_needed(
        {
          [ item_id    => $item->id,
            library_id => $library->id, ]
        }
    );

If an article request fee needs to be charged, it adds a debit to the patron's account.

Returns the fee line.

A library_id can be passed as parameter, falling back to userenv if absent.

article_requests

    my $article_requests = $patron->article_requests;

Returns the patron article requests.

add_enrolment_fee_if_needed

my $enrolment_fee = $patron->add_enrolment_fee_if_needed($renewal);

Add enrolment fee for a patron if needed.

$renewal - boolean denoting whether this is an account renewal or not

checkouts

my $checkouts = $patron->checkouts

pending_checkouts

my $pending_checkouts = $patron->pending_checkouts

This method will return the same as $self->checkouts, but with a prefetch on items, biblio and biblioitems.

It has been introduced to replaced the C4::Members::GetPendingIssues subroutine

It should not be used directly, prefer to access fields you need instead of retrieving all these fields in one go.

old_checkouts

my $old_checkouts = $patron->old_checkouts

overdues

my $overdue_items = $patron->overdues

Return the overdue items

restrictions

  my $restrictions = $patron->restrictions;

Returns the patron restrictions.

get_routing_lists

my $routinglists = $patron->get_routing_lists

Returns the routing lists a patron is subscribed to.

get_age

    my $age = $patron->get_age

Return the age of the patron

is_valid_age

my $is_valid = $patron->is_valid_age

Return 1 if patron's age is between allowed limits, returns 0 if it's not.

account

my $account = $patron->account

holds

my $holds = $patron->holds

Return all the holds placed by this patron

old_holds

my $old_holds = $patron->old_holds

Return all the historical holds for this patron

curbside_pickups

my $curbside_pickups = $patron->curbside_pickups;

Return all the curbside pickups for this patron

bookings

  my $bookings = $item->bookings();

Returns the bookings for this patron.

return_claims

my $return_claims = $patron->return_claims

notice_email_address

    my $email = $patron->notice_email_address;

Return the email address of patron used for notices. Returns the empty string if no email address.

first_valid_email_address

my $first_valid_email_address = $patron->first_valid_email_address

Return the first valid email address for a patron. For now, the order is defined as email, emailpro, B_email. Returns the empty string if the borrower has no email addresses.

get_club_enrollments

get_enrollable_clubs

get_lists_with_patron

    my @lists = $patron->get_lists_with_patron;

FIXME: This method returns a DBIC resultset instead of a Koha::Objects-based iterator.

account_locked

my $is_locked = $patron->account_locked

Return true if the patron has reached the maximum number of login attempts (see pref FailedLoginAttempts). If login_attempts is < 0, this is interpreted as an administrative lockout (independent of FailedLoginAttempts; see also Koha::Patron->lock). Otherwise return false. If the pref is not set (empty string, null or 0), the feature is considered as disabled.

can_see_patron_infos

my $can_see = $patron->can_see_patron_infos( $patron );

Return true if the patron (usually the logged in user) can see the patron's infos for a given patron

can_see_patrons_from

my $can_see = $patron->can_see_patrons_from( $branchcode );

Return true if the patron (usually the logged in user) can see the patron's infos from a given library

can_edit_items_from

    my $can_edit = $patron->can_edit_items_from( $branchcode );

Return true if the Koha::Patron can edit items from the given branchcode

libraries_where_can_edit_items

    my $libraries = $patron->libraries_where_can_edit_items;

Return the list of branchcodes(!) of libraries the patron is allowed to items for. The branchcodes are arbitrarily returned sorted. We are supposing here that the object is related to the logged in patron (use of C4::Context::only_my_library)

An empty array means no restriction, the user can edit any item.

libraries_where_can_see_patrons

  my $libraries = $patron->libraries_where_can_see_patrons;

Return the list of branchcodes(!) of libraries the patron is allowed to see other patron's infos.

The branchcodes are arbitrarily returned sorted.

We are supposing here that the object is related to the logged in patron (use of C4::Context::only_my_library)

An empty array means no restriction, the patron can see patron's infos from any libraries.

can_see_things_from

    my $can_see = $patron->can_see_things_from(
        {
            branchcode    => $branchcode,
            permission    => $permission,
            subpermission => $subpermission,
            group_feature => $group_feature
        }
    );

Return true if the Koha::Patron can perform some action, as described by a permission, subpermission, group_feature combination, at the passed library.

can_log_into

my $can_log_into = $patron->can_log_into( $library );

Given a Koha::Library object, it returns a boolean representing the fact the patron can log into a the library.

libraries_where_can_see_things

    my $libraries = $patron->libraries_where_can_see_things(
        {
            permission    => $permission,
            subpermission => $subpermission,
            group_feature => $group_feature
        }
    );

Returns a list of libraries where this user is allowed to perform an action, as defined by a permission, subpermission, group_feature combination.

We account for `IndependentBranches` and permission/subpermission assignments before looking into library group allowances.

We are assuming here that the object is related to the logged in librarian (use of C4::Context::only_my_library)

An empty array means no restriction, the thing can see thing's infos from any libraries.

has_permission

my $permission = $patron->has_permission($required);

See C4::Auth::haspermission for details of syntax for $required

is_superlibrarian

  my $is_superlibrarian = $patron->is_superlibrarian;

Return true if the patron is a superlibrarian.

is_adult

my $is_adult = $patron->is_adult

Return true if the patron has a category with a type Adult (A), Organization (I) or Staff (S)

is_child

my $is_child = $patron->is_child

Return true if the patron has a category with a type Child (C)

has_valid_userid

my $patron = Koha::Patrons->find(42); $patron->userid( $new_userid ); my $has_a_valid_userid = $patron->has_valid_userid

my $patron = Koha::Patron->new( $params ); my $has_a_valid_userid = $patron->has_valid_userid

Return true if the current userid of this patron is valid/unique, otherwise false.

Note that this should be done in $self->store instead and raise an exception if needed.

generate_userid

    $patron->generate_userid;

    If you do not have a plugin for generating a userid, we will call
    the internal method here that returns firstname.surname[.number],
    where number is an optional suffix to make the userid unique.
    (Its behavior has not been changed on bug 32426.)

    If you have plugin(s), the first valid response will be used.
    A plugin is assumed to return a valid userid as suggestion, but not
    assumed to save it already.
    Does not fallback to internal (you could arrange for that in your plugin).
    Clears userid when there are no valid plugin responses.

add_extended_attribute

extended_attributes

Return object of Koha::Patron::Attributes type with all attributes set for this patron

Or setter FIXME

messages

    my $messages = $patron->messages;

Return the message attached to the patron.

lock

    Koha::Patrons->find($id)->lock({ expire => 1, remove => 1 });

    Lock and optionally expire a patron account.
    Remove holds and article requests if remove flag set.
    In order to distinguish from locking by entering a wrong password, let's
    call this an administrative lockout.

anonymize

    Koha::Patrons->find($id)->anonymize;

    Anonymize or clear borrower fields. Fields in BorrowerMandatoryField
    are randomized, other personal data is cleared too.
    Patrons with issues are skipped.

add_guarantor

    my $relationship = $patron->add_guarantor(
        {
            borrowernumber => $borrowernumber,
            relationships  => $relationship,
        }
    );

    Adds a new guarantor to a patron.

get_extended_attribute

my $attribute_value = $patron->get_extended_attribute( $code );

Return the attribute for the code passed in parameter.

It not exist it returns undef

Note that this will not work for repeatable attribute types.

Maybe you certainly not want to use this method, it is actually only used for SHOW_BARCODE (which should be a real patron's attribute (not extended)

set_default_messaging_preferences

    $patron->set_default_messaging_preferences

Sets default messaging preferences on patron.

See Koha::Patron::MessagePreference(s) for more documentation, especially on thrown exceptions.

is_accessible

    if ( $patron->is_accessible({ user => $logged_in_user }) ) { ... }

This overloaded method validates whether the current Koha::Patron object can be accessed by the logged in user.

Returns 0 if the user parameter is missing.

unredact_list

This method returns the list of database fields that should be visible, even for restricted users, for both API and UI output purposes

to_api

    my $json = $patron->to_api;

Overloaded method that returns a JSON representation of the Koha::Patron object, suitable for API output.

to_api_mapping

This method returns the mapping for representing a Koha::Patron object on the API.

strings_map

Returns a map of column name to string representations including the string.

queue_notice

    Koha::Patrons->queue_notice({ letter_params => $letter_params, message_name => 'DUE'});
    Koha::Patrons->queue_notice({ letter_params => $letter_params, message_transports => \@message_transports });
    Koha::Patrons->queue_notice({ letter_params => $letter_params, message_transports => \@message_transports, test_mode => 1 });

    Queue messages to a patron. Can pass a message that is part of the message_attributes
    table or supply the transport to use.

    If passed a message name we retrieve the patrons preferences for transports
    Otherwise we use the supplied transport. In the case of email or sms we fall back to print if
    we have no address/number for sending

    $letter_params is a hashref of the values to be passed to GetPreparedLetter

    test_mode will only report which notices would be sent, but nothing will be queued

safe_to_delete

    my $result = $patron->safe_to_delete;
    if ( $result eq 'has_guarantees' ) { ... }
    elsif ( $result ) { ... }
    else { # cannot delete }

This method tells if the Koha:Patron object can be deleted. Possible return values

'ok'
'has_checkouts'
'has_debt'
'has_guarantees'
'is_anonymous_patron'
'is_protected'

recalls

    my $recalls = $patron->recalls;

Return the patron's recalls.

account_balance

    my $balance = $patron->account_balance

Return the patron's account balance

notify_library_of_registration

$patron->notify_library_of_registration( $email_patron_registrations );

Send patron registration email to library if EmailPatronRegistrations system preference is enabled.

has_messaging_preference

my $bool = $patron->has_messaging_preference({ message_name => $message_name, # A value from message_attributes.message_name message_transport_type => $message_transport_type, # email, sms, phone, itiva, etc... wants_digest => $wants_digest, # 1 if you are looking for the digest version, don't pass if you just want either });

can_patron_change_staff_only_lists

$patron->can_patron_change_staff_only_lists;

Return 1 if a patron has 'Superlibrarian' or 'Catalogue' permission. Otherwise, return 0.

can_patron_change_permitted_staff_lists

$patron->can_patron_change_permitted_staff_lists;

Return 1 if a patron has 'Superlibrarian' or 'Catalogue' and 'edit_public_list_contents' permissions. Otherwise, return 0.

encode_secret

  $patron->encode_secret($secret32);

Secret (TwoFactorAuth expects it in base32 format) is encrypted. You still need to call ->store.

decoded_secret

  my $secret32 = $patron->decoded_secret;

Decode the patron secret. We expect to get back a base32 string, but this is not checked here. Caller of encode_secret is responsible for that.

virtualshelves

    my $shelves = $patron->virtualshelves;

get_savings

    my $savings = $patron->get_savings;

Use the replacement price of patron's old and current issues to calculate how much they have 'saved' by using the library.

alert_subscriptions

    my $subscriptions = $patron->alert_subscriptions;

Return a Koha::Subscriptions object containing subscriptions for which the patron has subscribed to email alerts.

consent

    my $consent = $patron->consent(TYPE);

    Returns the first consent of type TYPE (there should be only one) or a new instance
    of Koha::Patron::Consent.

can_checkout

my $patron_borrowing_status = $patron->can_checkout( { patron => $patron } );

This method determines whether a patron is able to borrow based on various parameters. - Restrictions - Expiry - Charges

If any blockers are found, these are returned in a hash

is_patron_inside_charge_limits

my $patron_charge_limits = $patron->is_patron_inside_charge_limits( { patron => $patron } );

Checks the current account balance for a patron and any guarantors/guarantees and compares it with any charge limits in place Takes into account patron category level charge limits in the first instance and defaults to global sysprefs if not set

Internal methods

_type

AUTHORS

Kyle M Hall <kyle@bywatersolutions.com> Alex Sassmannshausen <alex.sassmannshausen@ptfs-europe.com> Martin Renvoize <martin.renvoize@ptfs-europe.com>

<<