Down the Rabbit Hole: Making cardnumber field in Koha longer than 16 characters limit

Making the cardnumber field bigger e.g. for Nigerian student matriculation numbers that overshoot Koha’s 16-char limit

Yesterday Mr. Adigun Samuel Akinwale from Osun, Nigeria, asked for help for his following question:

“How can one increase the character length of the library card number in Koha. It had been fix for 20 characters and was not like that before. In Nigeria most institution use student matric number for the library card in which some are more than 20 characters I try to report it in Bugzilla but it is give some difficulty in reporting. Please what can be a quick fix.”

Here’s keeping our promise to him, but first let’s get the legalese out of the way.

DISCLAIMER Please be aware that if you follow these instructions, either correctly OR incorrectly, you may end up breaking your Koha installation and/or damaging your data. If that happens, do not expect us to help you fix the mess in any way. If you at all use these instructions, you understand that you are on your own and is entirely responsible for your own safety.

Phew! With that out of our way, let’s looks at Mr. Akinwale’s problem. Koha for quite some time has maintained the cardnumber field in the borrowers table in the database as VARCHAR(16)[1]. For most users around the world, 16 characters is a large enough limit for a card number. But there are exceptions e.g. like this use-case from Nigeria.

A look at the new patron entry module of Koha will show (see screenshot above) that by default it will accept a card number that is minimum 1 and maximum 16 characters long.


Explanation : This is where the minimum 1 character requirement for the cardnumber comes from – the BorrowerMandatoryField patron system preference.

If you try to enter a card number larger than 16 characters like Mr. Akinwale, you will be halted in your tracks, thanks to the maxlength attribute of the text field with it’s value set to 16, even though field’s size attribute is set to 20.

Now, if you try to be smart and use the debugger / Firebug to dynamically manipulate the DOM and increase the maxlength to say 24, you will find out when attempting to save the new patron record that Koha will have none of it as you can see below 😉


Finding the source of the hard-coded value

We of course can not store a larger number in a field smaller than itself. So our first pit stop will be an ALTER TABLE SQL statement to increase the field size to 24.

ALTER TABLE `borrowers` CHANGE `cardnumber` `cardnumber` VARCHAR(24)

As we’ll find out, changing the column cardnumber size, while part of the solution, is *not* the final answer. Changing the field size in the database does not change the maxlength attribute and it won’t still allow us to enter anything larger than 16 character.

Digging for the source, it will take us to the following files: first the template file – as located at the directory intranet-tmpl/prog/en/modules/members. This is where the html generation happens. The template itself is called by the Perl script – intranet/cgi-bin/members/ . So far, there is nothing to show what is setting our cardnumber to a maximum length of 16. But we’ll get there soon. The calls the functions (aka sub routines) stored in Perl module, specifically in our case – a particular sub-routine – C4::Members::get_cardnumber_length().

sub get_cardnumber_length {
    my ( $min, $max ) = ( 0, 16 ); # borrowers.cardnumber is a nullable varchar(16)
    $min = 1 if C4::Context->preference('BorrowerMandatoryField') =~ /cardnumber/;
    if ( my $cardnumber_length = C4::Context->preference('CardnumberLength') ) {
        # Is integer and length match
        if ( $cardnumber_length =~ m|^\d+$| ) {
            $min = $max = $cardnumber_length
                if $cardnumber_length >= $min
                    and $cardnumber_length <= $max;
        # Else assuming it is a range
        elsif ( $cardnumber_length =~ m|(\d*),(\d*)| ) {
            $min = $1 if $1 and $min < $1;
            $max = $2 if $2 and $max > $2;

    return ( $min, $max );

This is here the hard-coded value is set my ( $min, $max ) = ( 0, 16 );. Changing it to my ( $min, $max ) = ( 0, 24 ); to match the width of the cardnumber column which we changed in an earlier step, is the answer. As we refresh the “Add patron” page, we will now find that the maxlength attribute of the cardnumber entry field has been changed to 24! Problem solved!


While this small hack solves Mr. Akinwale’s problem, it comes with the following baggage:

  1. It is a hard-coded solution that does not solve the actual problem, rather merely shifts the goal post.
  2. You have to ensure that both the cardnumber field’s column width and the change in the get_cardnumber_length() sub-routine are exactly the same value.
  3. This is not an Koha community approved patch. So every time you upgrade your Koha, you will have to re-do the hard coding

The real risk here is accidentally modifying or deleting something unintentional and breaking your Koha, since handles patron management functions. So, if you are to follow this example, it is strongly suggested that you first make a backup of the and keep in safe. If things go wrong you can simply replace the changed file with the original from the backup. All said and done, these changes should preferably be made only by someone who can understand the code.

P.S. “Down the rabbit hole” is a metaphor for an entry into the unknown; the use comes from “Alice’s Adventures in Wonderland” by Lewis Carroll (real name Charles Lutwidge Dodgson)