BookAdder Docfile:
Further Customizing BookAdder

BookAdder: Further Customizing

Beyond the essentials you have already set in the customize.php file, there are many aspects of the appearance and operation of BookAdder that you can and, at least in some instances, should customize to your needs and tastes. They are all explained here.

But First!

Please be sure you have read all the preceding BookAdder docfiles, through Tuning Your Search before you plunge into these procedures. You should not be tinkering here till you have a satisfactorily running shop. Please: RTFM!

Also, let me insert right here at the top this important reminder:

What You Should Customize

These are several things that you should at the least review, and in many cases should customize to your own needs. These are they.

Google AdSense

For some extra income for you, BookAdder provides for running Google AdSense ads on most pages. This facility is built in, but obviously you need to set it to display ads with your Google "Publisher Code"; you can also, if you choose (I do not recommend it) change the colors or style or format of the displayed ad block, in the usual ways.

(In the unlikely case that you are not at least familiar with Google's "AdSense" program, you should read Google's AdSense Tour page; it explains the program, and includes links from which you can apply for your own Publisher Code. I strongly recommend the program.)

Basic AdSense Customizing

The file you want to customize is adsense1.php. That file is self-explanatory, but for convenience I reproduce it below.

<!--  This file is HTML code, and NOT php code.  -->

<!-- BOOKADDER: adsense1.php - v. 4.22 -->


<!-- If you are a Google AdSense affiliate, insert your own Publisher Code on the

       google_ad_client =  

     line, or substitute other Google-provided AdSense code.  If you are not a
     Google AdSense subscriber, you can easily sign up with Google by going to:

       https://www.google.com/adsense/?sourceid=aso&subid=us-et-ads
-->


  <font size="1">Sponsored links:</font>
  <br/>
  <center>
   <!--  AdSense  -->

    <script type="text/javascript"><!--
    google_ad_client = "pub-2696651971824184";
    google_ad_width = 728;
    google_ad_height = 90;
    google_ad_format = "728x90_as";
    google_ad_type = "text";
    google_ad_channel ="";
    google_color_border = "DEB887";
    google_color_bg = "DEB887";
    google_color_link = "CC0000";
    google_color_url = "CC0000";
    google_color_text = "000000";
    //--></script>
    <script type="text/javascript"
      src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
    </script>

   <!--  /AdSense  -->
  </center>

I have artificially color-highlighted the critical datum in the AdSense lines: all you need to do is enter your own Google AdSense Publisher Code in place of mine, which is the yellow number above.

If, for some reason, you decide you don't want AdSense ads at all on your BookAdder pages, the process is even simpler: just delete all the lines following the two file-id commented header lines. (Or delete the entire file--but I think it's better to keep a blank "placeholder" so you don't later wonder where it went.) If you delete the AdSense code, or the whole file, I advise first making a backup copy of the original, so that you can change your mind later.

If you opt not to use AdSense then later change your mind, just use your backup copy. If you didn't make one, you can re-download the original BookAdder ZIPfile--or, being clever, you can extract the contents from this docfile! (Do it by taking a copy of what you see on your screen above, not of the actual HTML in this docfile, which is altered so it will display as the file looks in a text editor).

Variant Ad Formats

BookAdder allows you to use different AdSense layouts or formats on different pages. To make a differing layout, copy the file adsense1.php to a new file named, cleverly, adsense2.php, then customize that file to your heart's content. (I strongly recommend getting your entire new AdSense block direct from Google, rather than trying to fiddle the lines in this file.) Farther down in this docfile we will see how to select which adsenseX.php file gets used where. You can have as many as ten different AdSense-insertion files, using the numerals from 0 to 9 (inclusive) in the file names.

To be very exact, if you want a different AdSense layout than the all-text, 4-across format BookAdder defaults to, go to Google's AdSense HTML generator, style it as you like, get the needed code lines, then insert them into the adsenseX.php file of your choice substituting them completely for the lines between the two markers:

   <!--  AdSense  -->


   <!--  /AdSense  -->

Piece o'cake.

Google Analytics

Webmasters are well advised to take advantage of the wonderful information available through the Google Analytics program. If you do use Google Analytics, the BookAdder package provides a convenient module wherewith you can easily insert your Analytics code in the proper place on every page of BookAdder for which it would be needed. Just drop the Google-provided code into the file appropriately named ganalytics.php; as supplied, that file is blank except for a header line. Simply drop the code right below that line:

   <!--  Google Analytics Code  -->

Digitalpoint Co-op Ads

If you are a member of the Digitalpoint Cooperative Ad Network and want those ads to run on some or all of your BookAdder pages, that's provided for. Note that unlike the case with AdSense, BookAdder defaults to not displaying Co-op ads: you have to customize to get them.

The process is extremely simple: you edit the file coopads.php by changing the word NO to YES. Here's what that file looks like, with the key word here artificially highlighted in yellow:

<?php

//  BOOKADDER: coopads.php - v. 4.22 


//  This defaults to NOT running Co-op ads.

//  To enable running Digitalpoint Co-op Ad Network ads, change the NO entry below to YES

$runcoopads='NO';

// Your Ad Network file MUST match that given below for ads to work.

// Try to keep to the latest Co-op network scripts: below is the latest as of March 2, 2009 2:01 pm (PST).

// Check current status at:  http://www.digitalpoint.com/tools/ad-network/setup.php?type=99

$networkfile='ad_network_183.php';


?>

Note what it says there about keeping current (they key datum is here artificially highlighted in red): that part is your responsibility as a Co-op member.

The display is as a micro-table with five ads shown side by side on a lightly tinted background. The actual processing is done in BookAdder file runcoopads.php, which reads coopads.php before proceeding, or not proceeding. If you are using Co-op ads, and feel you have the PHP and HTML expertise, and want to change the default display, you can try editing runcoopads.php--but I'd suggest saving a backup copy of the original in case something goes wrong with your edits. The part you'd want in that file is under the commented heading  //     Display ads:

Note that I neither recommend nor disrecommend the Digitalpoint Network. But if you are a member, you have the facility to place Network ads on all of your tens of thousands of new pages. By default, the ads will appear down at the very bottom of each page; but you can change that, as will be seen later, when we come to customizing those pages.

The "Roll Your Own" Module

This is a sort of "catchall" module that allows you to insert anything else you like onto the bottoms of your BookAdder-generated files. As a default, I have built into it the following display, which includes a Firefox-info button. The display that the default rollyourown.php module presents is this (note that the background color is not set by the module but is whatever the page uses--I have used this page's own background color for clarity and simplicity, and--to set it off--I have provided it a border that is not part of what the module displays):

Personally, I think that is a nice addition to your pages, and it is what I use myself. The actual module as supplied in BookAdder looks like roughly this (the display below collapses line indentations in the real file and may have false extra line breaks owing to the width of your browser screen):

But remember: the point of calling this module "Roll Your Own is that you can put whatever you want into it: it is just a convenient "carrier" for any HTML (or PHP) you would like to have appear somewhere on some or all of your BookAdder pages that visitors will see. You can add to what's there, change what's there, or remove it all and have nothing there. It's all up to you.

Border and Background Colors

The BookAdder file looknfeel.php controls certain elements of the, yes, "look and feel" of the generated pages. That file is, again, self-descriptive, and I won't bother to reproduce it here. More important is that you don't have to experiment with "live" pages while playing trial-and-error for colors and styles. You can use the included tool showstyle.php to see most of the effects at work before you cut them in. (I say "most" because the tool does not help much in text and table-border size evaluation, because its display is a miniaturized mock-up meant for seeing what color settings control what, and how different values would look.)

Using showstyle.php, you can experiment with any values you like to see--roughly, anyway--how they would look, but without actually changing your real bookshop pages. When (or perhaps just if) you find a combination you like better than the defaults (but which can include any of the individual default values), you can then implement it instantly with a single click. And if you screwed up, or just got tangled up trying things, you can revert the bookshop to its defaults with another single click and, if you like, start over (or just leave it at the defaults).

When you call up showstyle.php, it will show you this display (the display below is not functional):

I'd like to think that page is self-explanatory, but a few notes anyway. Color values are all in the HTML-standard six-character format; you need supply only the six hex characters--the script handles the formatting (leading # sign and so on). If the This color: sample seems blank, the color is white (ffffff), and thus invisible on the page's white background.

As to font faces, I recommend against anything but serif, which I think looks far and away better than sans-serif (but if you believe all that @#%$!&* about "readability" that some lard-brains write about web pages, help yourself). To avoid the many errors possible when trying to specify a "font family" more exactly than serif/sans-serif, the choice is restricted to those two: let your visitors' browsers do the rest as they prefer.

For style elements where true size matters (such as the border between text block and page background, or the type size on individual-book pages), you are much better off to look over real package pages before making decisions and changes; the "pseudo-pages" shown on showstyles.php are just to let you know what effects are in place at the moment.

To re-iterate an important point: when you just click the Use the new values button, the values displayed in the entry boxes are applied only to the display page of showstyles.php. To make them "stick" for your actual bookshop pages, you need to click the little checkbox labelled Actually apply these values?, then click the Use the new values button. That way, you can try and re-try and re-re-try experimental values till the cows come home without affecting your actual pages, then, if and when you find a new combination you like, apply it all at once.

And, as noted in the red box at the bottom of the display, you can always make an emergency restore to the default values with a single click of the Revert to the original default values button.

(You can also manually edit the file looknfeel.php, which is copiously annotated internally. But if you upload a modified copy--as opposed to editing live on line--be sure to run reperm.php at once, to correctly permission the re-uploaded file copy.

Enhancing Your Bookshop Front Page

I feel that it is a good idea to "personalize" your bookshop's "front page" by adding in a few recommendations of particular books related to your site's theme, so that that page looks like something you yourself really made with some time and care. I have facilitated your doing that with a module called recommendedbooks.php. That module is just an HTML template that you fill in with your selections. It looks roughly like this (the display below collapses line indentations in the real file and may have false extra line breaks owing to the width of your browser screen):

As it is supplied, with--as the notes put it--useless (to you) but illustrative sample material, it would make a display like this (the horizontal rules are not part of the display, but are here to set that display off from the actual content of this docfile):

Small, tidy, pleasing, and suggestive of personal attention. To make use of this module, you need to do three simple things, all described within the module itself:

1. change the entry RUNME:NO to RUNME:YES;
2. change the introductory sentence as appropriate for your site; and,
3. three, customize the actual individual entries.

(If you want some number of recommendations other than three, just add or subtract as you please in the HTML; I feel three is the minimum you should use and perhaps five the maximum--but it's your site and your page.)

Presumably you know enough about your site's topic to choose some appropriate books, but if that is not so, the matter is simple:

• go to Amazon's books "Advanced Search" page;
• fill in the Subject: text entry box with words related to your site's theme (this is not like your BookAdder search phrase--here you want to be as narrowly focussed as possible, since you only need a very few titles to be returned);
• at the Sort Results by: dropdown box, select Bestselling (normally the default) as the sort criterion;
• click the Search now: button.

Look over the first few results--take a little time, and review the page for each, taking care to look at the reader reviews--and select three to five to use. For each, get the data you'll need--

• the ASIN number (if necessary, extract it from your browser's URL bar)
• the title (you don't have to use all of a long title, just what most people would call the book)
• the author
• the binding
• the Amazon sale price

--and fill them in at the appropriate places in the HTML (which should be obvious), then compose or "borrow" a short descriptive sentence, following the models already in the module.

Before uploading, load the edited raw module into your browser as a local (on your computer) file and make sure it looks right and that all the links work correctly (ignore the junk text at the top--that won't show when the module is in actual use). It's all easier to do than to tell about.

When you're satisfied with the edited module (don't forget to set RUNME: to YES), just upload it, then run reperm.php and you're done. The front-page script will automatically detect it and display it in an appropriate place on the page. But do check that your revised bookshop front page now looks as you expected.

What You Can Also Customize

The various pages your visitors see in your bookshop have, besides the actual listings that vary from day to day, text messages of lesser or greater length. My own feeling is that it is as well to leave those as you get them, but if you feel a need, you can certainly edit any of them as you please. Each is basically just an HTML file, with a .htm extension. But, because all these "raw" .htm files are each actually input to a php script that uses them, you need to know what parts you must leave alone for the php scripts to work correctly. Basically, that would be any line in a BookAdder .htm file that has the structure of an HTML "comment", that is, looks like this:

<!-- COUNTOFBOOKS : inserts count of titles available -->

You can move such lines around, but keep in mind that most or all signify the place in the final output page where the php script will insert some datum or data, so consider the effect on page appearance of any such move. If, for example, you just moved the line shown above to elsewhere in its file, you'd get a mighty bizarre effect, both where you put it and where it was supposed to be.

Also be aware that certain "magic words" in these raw .htm files are picked up and modified by the php script that generates the corresponding page--so don't worry about references to "widgets" or SITENAME or BOOKADDER or any like strange-looking things. Look long and carefully at the actual pages as delivered to your browser before considering making any changes in the underlying .htm files.

For those pages containing the dropin-control line--

<!-- ADSENSEDROPIN #1 : inserts a particular Google AdSense insert here -->

--you can change the numeral after the # sign to anything from 0 to 9. That numeral controls which adsenseX.php module is used as the source for the AdSense ads placed on the page at that point. Make sure that if you do change the numeral, a corresponding adsenseX.php module does exist! You can move this line with relative freedom, or even insert copies of it for extra AdSense ads--but I do not recommend either change. The ads are all in reasonable places, and too many of them badly clutter any page. (In fact, I would recommend against moving any of the dropin lines, but you can if you insist).

The files we have been discussing, and the pages each controls, are these:

bookshop.htm hold.htm booksearch.htm usedbooks.htm amazonmessage.htm

your bookshop "front page" the 27 title-listing pages the Amazon new-books search page the Abebooks used-books search page the "Amazon message" you have to carry

Amazon-Related Customization

There are a few BookAdder files that tell the scripts certain things about Amazon's current ways of doing things. I try to update those as I discover any changes Amazon makes, but if you find some yourself and don't want to wait, you can directly modify the files yourself. (But please let me know of any such changes you find.) There are three such files, and I will display them all here, so you can see what I'm talking about.

nonbooks.php

This defines what BookAdder considers to be "ringers" (as opposed to "real" books), based on certain terms found in either the Binding data field (labelled medium below) or the actual Title field. If you have a different opinion, feel free to delete or add to these entries as you think it appropriate--it will change the selection of titles you offer.

medium accessory
medium audio
medium board book
medium calendar
medium cards
medium cassette
medium cd
medium digital
medium kindle
medium looseleaf
medium map
medium maps
medium notebook
medium pop-up
medium poster
medium rag book
medium sheet music
medium specialty
medium stationery


title adapted
title book & charm
title download
title abridged
title audio
title blank book
title board book
title calendar
title cassette
title cd rom
title cd-rom
title coloring
title colouring
title comics
title comic book
title big comic
title disney
title jigsaw
title locked diary
title Lernmaterialien
title mp3
title multi media
title multi-media
title playscript
title pop up
title pop-up
title postcard
title tatoos
title tattoos
title vhs tape
title vocal

unavails.php

This defines what BookAdder understands Amazon to be classing as books not immediately buyable new from Amazon. As with the previous file, if you think you want or need different criteria, go for it (but be sure you understand that these are the exact phrases Amazon uses in the XML datafiles it returns to ECS queries).

limited availability
out of print
out of stock
seller usually dispatches
special order
not currently available
this item is not stocked or has been discontinued
this title is currently not available
this item is currently not available
we are currently unable to offer this title

avails.php

This is a much more complicated file than the two prior simple text lists. This is a PHP script that attempts to translate "availability" and "Binding" messages supplied by the Amazon divisions in places where English is not the native tongue. (If you're wondering why an international business does not supply language-independent codes instead of or in addition to changing, arbitrary, language-specific text strings, so are an awful lot of other people.) If some of the characters below seem bizarre, your browser's current font may not be able to display them--they are non-ASCII "accented" or other non-standard characters (such as Japanese double-byte codes).

<?php

//  BOOKADDER: avails.php - v. 4.22 


  //  Translate Availabilities:
  function transavail($avail)
  {
    //   NOTE!  Within divisions, order is crucial!
    global $in,$br;
    if ($in=='us' or $in=='uk' or $in=='ca')
    {
      $avail=str_replace('dispatched within','ships in',$avail);
      if (strpos($avail,'Not yet published')!==FALSE) $avail='Not yet available, but you can preorder it';
      if (strpos($avail,'Not yet released')!==FALSE) $avail='Not yet available, but you can preorder it';
    }
  
    if ($in=='de')
    {
      $avail=str_replace('bei Amazon ',NULL,$avail);  // note trailing space
      $avail=str_replace('Gewöhnlich versandfertig','Usually ships',$avail);
      $avail=str_replace('Versandfertig','Usually ships',$avail);
      $avail=str_replace(' bis ',' to ',$avail);
      $avail=str_replace('Stunden','hours',$avail);
      $avail=str_replace('Tagen','days',$avail);
      $avail=str_replace('Wochen','weeks',$avail);
      $avail=str_replace('Monaten','months',$avail);
      if (stristr($avail,'Der Artikel ist bald')!==FALSE) $avail='In stock soon: order now';
      if (stristr($avail,'Noch nicht erschienen')!==FALSE) $avail='Not yet available, but you can preorder it';
      if (stristr($avail,'jetzt gebraucht vorbestellen')!==FALSE) $avail='Not currently available';
    }
  
    if ($in=='fr')
    {
      $avail=str_replace('Habituellement expédié sous','Usually ships in',$avail);
      $avail=str_replace(' à ',' to ',$avail);
      $avail=str_replace('24 h','24 hours',$avail);
      if (stristr($avail,'Disponible en stock.')!==FALSE) $avail='In stock soon: order now';
      if (stristr($avail,'s aujourd\'hui')!==FALSE) $avail='Not yet available, but you can preorder it';
      if (stristr($avail,'actuellement indisponible')!==FALSE) $avail='Not currently available';
      $avail=str_replace('jours','days',$avail);
      $avail=str_replace('semaines','weeks',$avail);
      $avail=str_replace('mois','months',$avail);  // apparently singular & plural identical
    }

    if ($in=='jp')
    {
      if ($avail==='間もなく入荷します。ご注文はお早めに。商品はご注文いただいた順番にお届けします。') $avail='In stock soon: order now';
      if ($avail==='近日発売　予約可') $avail='Not yet available, but you can preorder it';
      $avail=str_replace('通常','Usually ships in ',$avail);
      $avail=str_replace('～',' to ',$avail);
      $avail=str_replace('時間以内に発送',' hours',$avail);
      $avail=str_replace('日以内に発送',' days',$avail);
      $avail=str_replace('週間以内に発送',' weeks',$avail);
    }

    return $avail;
  }


  //  Translate Media:
  function transmedia($media)
  {
    global $in,$br;

    if ($in=='us' or $in=='uk' or $in=='ca')
    {
      $media=str_replace('School & Library Binding','Library Binding',$media);
      $media=str_replace('Loose Leaf','Looseleaf',$media);
      $media=str_replace('Mass Market Paperback','Mass-Market Paperback',$media);
      $media=str_replace('Misc. Supplies','Specialty Item',$media);
      $media=str_replace('Perfect','"Perfect" Binding',$media);
      $media=str_replace('Perfect Paperback','"Perfect" Binding',$media);
      $media=str_replace('Audio CD','CD',$media);
    }

    if ($in=='de')
    {
      $media=str_replace('Bibliothekseinband','Library Binding',$media);
      $media=str_replace('Broschiert','"Perfect" Binding',$media);
      $media=str_replace('Gebundene Ausgabe','Hardcover',$media);
      $media=str_replace('Hörkassette','Audio Cassette',$media);
      $media=str_replace('Kalendar','Calendar',$media);
      $media=str_replace('Landkarte','Map',$media);
      $media=str_replace('Ledereinband','Leather Bound',$media);
      $media=str_replace('Musiknoten','Sheet Music',$media);
      $media=str_replace('Papeterie','Stationery',$media);
      $media=str_replace('Pappband','Board Book',$media);
      $media=str_replace('Ringeinband','Ring-bound',$media);
      $media=str_replace('Sondereinband','Turtleback',$media);
      $media=str_replace('Sonstiges Zubehör','Specialty Item',$media);
      $media=str_replace('Spielkarten','Cards',$media);
      $media=str_replace('Spiralbuch','Spiral-bound',$media);
      $media=str_replace('Taschenbuch','Mass-Market Paperback',$media);
      $media=str_replace('Unbekannter Einband','Unknown Binding',$media);
      $media=str_replace('Zubehör','Accessory',$media);
    }

    if ($in=='fr')
    { 
      $media=str_replace('Accessoire','Accessory',$media);
      $media=str_replace('Belle reliure','Library Binding',$media);
      $media=str_replace('Broché','Paperback',$media);
      $media=str_replace('Cahier','Notebook',$media);
      $media=str_replace('Calendrier','Calendar',$media);
      $media=str_replace('Carte','Map',$media);
      $media=str_replace('Cartes','Maps',$media);
      $media=str_replace('Cartonné','Board Book',$media);
      $media=str_replace('Cassette audio','Audio Cassette',$media);
      $media=str_replace('CD audio','CD',$media);
      $media=str_replace('Feuillets mobiles','Looseleaf',$media);
      $media=str_replace('Fournitures diverses','Specialty Item',$media);
      $media=str_replace('Papeterie','Stationery',$media);
      $media=str_replace('Poche','Paperback',$media);  // seem not to distinguish trade & M/M
      $media=str_replace('Relié','Hardcover',$media);
      $media=str_replace('Reliure cuir','Leather Bound',$media);
      $media=str_replace('Reliure inconnue','Unknown binding',$media);
      $media=str_replace('Spirales','Spiral-bound',$media);
     }

    if ($in=='jp')
    {
      $media=str_replace('カセット','Audio Cassette',$media);
      $media=str_replace('ボードブック','Board book',$media);
      $media=str_replace('カレンダー','Calendar',$media);
      $media=str_replace('カード','Cards',$media);
      $media=str_replace('ハードカバー','Hardcover',$media);
      $media=str_replace('マスマーケット','Mass Market Paperback',$media);
      $media=str_replace('ペーパーバック','Paperback',$media);
      $media=str_replace('タートルバック','Turtleback',$media);
      $media=str_replace('－','Unknown Binding',$media);
      $media=str_replace('付属品','Accessory',$media);
      $media=str_replace('図書館','Library Binding',$media);
      $media=str_replace('地図','Map',$media);
      $media=str_replace('学校','Library Binding',$media);
      $media=str_replace('用品','Specialty Item',$media);
      $media=str_replace('リング製本','Ring-bound',$media);
      $media=str_replace('革装本','Leather Bound',$media);
    }

    return $media;
  }


?>

I would most strenuously recommend you not tinker with this file unless you are absolutely, positively, 110% sure you know exactly what you're doing and why.

BookAdder-Operation Customization

Finally, there are a few matters related to what we might call the "internal workings" of BookAdder that you might want to customize. We'll look at these individually.

Spammer-Attack Timeouts

Each publicly accessible Bookshop-generated web page has built into it a protection against your site being crippled by spammer attacks. Mind, most of the time these aren't "attacks" in the sense that the entity is seeking to harm your site: the harm is a side effect of their activity. Most of these slimeballs are "email harvesters"; their bots go from site to site reading each and every page looking for email addresses they can "harvest" to use as, or sell to, email spammers. That is detestable in principle, but where it really hurts you is in the hit rate. Civilized, "well-behaved" internet robots do not normally fetch pages from any one site more often than about every 5 or 6 seconds; indeed, many honor the Crawl-delay: directive in robots.txt files (as you presumably set it at BookAdder installation time). Spammers just go for the pages as fast as the server will deliver them, which of course means that they are stressing the server to the max, in what often amounts (if only as a side effect) to a "denial of service" attack.

Traditional attempts to defeat such scum rely on hopeless methods: identifying particular offenders by IP Address, then blocking that address somewhere. These slimeballs change IP Addresses a deal more often than they change their underwear, so any such list, whether generated locally or obtained from anti-spam groups on the internet, is always ludicrously behindhand, in addition to which it requires perpetual fiddling with block list files.

A while ago, some really clever chap, whose name I have lost, devised a wonderfully neat little PHP script that handles the problem in real time. In essence, it keeps track of how long it's been since a given visitor last took a page from the site, and builds a cumulative "score" recoding that visitor's average file-hit rate. If the value gets too high, that visitor is blocked out for some period (with an HTTP 503 header and appropriate message page returned); the visitor will not be allowed back in till its attempted hit rate is again civilized.

(Every so often, even the best-behaved searchbots seem to forget themselves and fall to over-fast hit rates; since the blockage is always temporary, you need not worry that Google or Yahoo or MSN will not be able to find your pages.)

The BookAdder module that implements this protection is timer.php. What you can modify there if you feel a need to are the three parameters that control exactly how the timer works. Those parameters appear right at the top of the file, which--right below them--includes an explanatory summary of just how it operates. That top part of the file altogether looks like this:

<?php

//  BOOKADDER: timer.php - v. 4.22 


  // CONTROL PARAMETERS:

  $itime=5;          // minimum *average* number of seconds between one-visitor visits

  $imaxvisit=12;     // maximum visits allowed in ($itime x $imaxvisit seconds, e.g. 5 x 12 = 60 seconds)

  $ipenalty=10;      // minutes before visitor is allowed back

  $logging='yes';     // controls whether a log of attackers will be kept



/*

Notes...

    * $itime is the minimum number of seconds between visits _on average_ over 
      $itime*$imaxvisit seconds.  So, in the example, a visitor isn't blocked if 
      it visits the script multiple times in the first 5 seconds, as long as 
      it doesn't visit more than 60 times within 300 seconds (5 minutes).

    * If the limit is reached, $ipenalty is the number of minutes a visitor has to 
      wait before being allowed back. 


An MD5 hash is made of each visitor's IP address, and the last 3 hex digits of that hash 
are used to generate one of a possible 4,096 filenames.  If it is a new visitor, or a visitor
who hasn't been seen for a while, the timestamp of the file is set to the then-current time; 
otherwise, it must be a recent visitor, and the time stamp is increased by $itime. 

If the visitor starts loading the timer script more rapidly than $itime seconds per visit,
the time stamp on the IP-hashed filename will be increasing faster than the actual time is 
increasing.  If the time stamp gets too far ahead of the current time, the visitor is branded 
a bad visitor and the penalty is applied by increasing the time stamp on its file even 
further.

4,096 separate hash files is enough that it's very unlikely you'll get two visitors at exactly 
the same time with the same hash, but not so many that you need to keep tidying up the files.

(Even if you do get more than one visitor with the same hash file at the same time, it's 
no great disaster: they'll just approach the throttle limit a little faster, which in most 
cases won't matter, as the limits are quite generous.)

Note: This will NOT neatly stop a bot from taking more than X files in Y seconds; its
action depends on the difference between the allowed and the actual rate.  Bots taking
only a bit more than allowed can run for quite some time--only really fast ones will be
stopped quickly.  But that is acceptable behavior: the worse they offend, the faster
they're stopped; the less they offend, the longer they have.

This script assumes that there are two subdirectories off whatever directory it itself is
housed in: /logs and /trapfiles

The use of logs is self-evident; the use of trapfiles is as home to the transient files
used as timers.  There is nothing magic about that arrangement, and you can change it in
the script below if you take care with what you are doing.  But there must be *some* home
for the generated logs and timer files.

(The logging is not essential, and you can eliminate it if you like.)

*/

You should absolutely, positively not edit anything but logging, or the numerical values of the three parameters--and I'd advise against even that. They are set for rather reasonable values; be sure you understand their interactions before trying to tweak them.

Note that, as it says above, this module generates a log. If your site is popular, and attackers thus frequent, that log can fill up pretty fast. It much behooves you to either check (and discard) it regularly, or to disable logging altogether. To disable logging, change the parameter yes to no (or to anything that doesn't start with a y). If you do keep logging in place, expect the log entries to look something like this (which would all be on one long line in the log, but is here broken up to fit the page width, and is artificially color-highlighted):

The first part of the line, colored yellow above, is the "user agent" value that the visitor reported. With spammers, that is often forged, but for bots that are from places that are not actual spammer scum but merely wildly inept, you can often get real identifications. The middle part of the line, colored red above, is the actual IP Address of the attacker; the words "Deny From" are there to make it easy for those who want to use these log entries to build more permanent denial tables, something I think not worth the effort. The final data, in white above, are the date and exact time, to the second, of the attack that triggered the log entry (which, remember, will be far from the attacker's first hit at your site). Mostly useless in the real world, but there if you want it for anything.

"Free Pass" Access

There is a little module called freepasses.php in which you can enter IP Addresses, one to a line, and any address in that file will be ignored by the attack timer. That allows you to, for example, specify one or more other IP addresses (the IP address of the server BookAdder resides on is always given a free pass) that equate to "you", so you can hit up your own site if you somehow need to on occasion without tripping the attack timer. Or you could list some legitimate, important searchbots (say, Google's) to always allow them in, even when they're behaving badly to your server. It's all up to you. here's what that file looks like by default:

(That's the IP Address of the site you got this package from, in case you ever need me to work with you on some problem and I need to hit a few files; I can't imagine such a need ever arising, but it's harmless to leave that address in.)

Password Control

The issue of BookAdder-files access via a password is discussed more fully in the BookAdder docfile Security-Related Concerns. There are pros and cons. But as to the mere mechanics, you use the script makepw.php to make one. (If you don't explicitly make one, there is no password control applied.)

When you call that script, the screen you get looks like this:

That is largely self-explanatory, but a few further words may be in order. It refers to "changing" the password even though the first time you use it there is no actual password set; in effect, "no password" is a Null password. The password you get is stored in a new file 4me.php; but even if that file is compromised, no loss, because the entries are 32-byte "md5 hashes" of your actual password. BookAdder takes the password you supply when you want access and md5-hashes it, then compares that with the stored hash, so even if a stranger knows the hash he/she/it can't get in because md5 hashes are not "encoding--they're strictly one way: source to hash; a made hash cannot be reversed back to its source. The phrase you use can range from a single letter to the Constitution of the United States: the hash is always 32 characters long. The criteria are as the page states: short phrases are often easily guessed, while long ones are a pain in the elbow to type in every time you want to run any BookAdder script.

You should read the fuller discussion, but the essence is that this is not a high-security protection against skilled hackers: it is a simple block to stop casually curious visitors from fooling with your stuff. Don't rely on such means as forbidding your server from delivering a directory listing: anyone who wants to look up and download BookAdder will know as well as you what the scripts are named and what they do. My advice is to not make a password till you are pretty sure you have finished up all your installation, setup, customizing, whatever, and set the thing to go off by itself nightly. Then make a password, using some short but cryptic private reference (something like--but not--your aunt's telephone number with her last name instead of the area code).

Once you have made a password, you'll need it to run any runnable php file in BookAdder (some .php files are not runnable php, but are so named to keep them from being casually read by strangers). That includes the password-make/change file itself. You are, however, never really "locked out" since all you have to do if you forget your password is erase that 4me.php file and you again have no password. Doesn't that make insecurity? Sure. I said this was only to discourage casual fooling around and modest malice, not industrial-strength attacks. Anyone who gets sufficient access to your site files to erase one isn't going to be stopped by modest measures--he/she/it is already into you deep.

Moving On

BookAdder Documentation Files Available

They are:

• About BookAdder - a useful overview of what BookAdder does, how, and why
• Installing BookAdder - getting BookAdder initially set up and functioning
• Installation Problems - causes and cures for snags encountered when installing
• Tuning Your Search - how to easily optimize your search phrase
• Further Customizing BookAdder - this file
• Security-Related Concerns - understanding the hows and whys of several related matters
• Upgrading - how to proceed if you have an earlier version installed
• BookAdder Files List - the purpose of every file in BookAdder: worth reading for tips'n'tricks

What to Read Next

Since we ended up discussing security, perhaps it's time to look at the Security-Related Concerns docfile.