BILLING PLUGINS
------------------------------------------------------------------------

phpaga gives you the ability to write your own custom billing plugins 
which decide how totals and subtotals are calculated when you generate
PDF bills to send to your clients.  PHPAGA comes pre-installed with
the necessary plugins to calculate taxes for the Italian government, 
and a very simple plugin, which returns the total, not including any 
taxes.  You can use these files as a reference implementation of what
a billing plugin should look like.  If you happen to write your own 
generalized plugin (say for example, one that calculates US taxes), feel
free to contribute it back to PHPAGA.


BILLING PLUGIN MINI-HOWTO
------------------------------------------------------------------------

Billing methods can be created as plugins. The plugin file can be freely
named and must be installed under the directory lib/bill/

The billing method function in the plugin ALWAYS has to be called:

phpaga_bill_calculate

and accept the following parameters:
(-> in |  <- out)

-> float startsum    # The startsum from which to calculate the bill
-> int   currency-ID # ID of the currency to be used
<- real  endsum      # The full sum that is to be paid
<- array details     # Array containing the full calculation with
                     #   description and amounts
-> float expensesum  # Amount of expenses (optional)

The "details" array has to be of the following structure:

details[]["text"]
details[]["amount"]

Please refer to the sample files shipped with phpaga (to be found under
lib/bill/); you can use one of them as a base for your personalized
billing method.

When a user selects a billing method, the corresponding file will be 
included, and the function will be called (with the necessary 
parameters).

This should provide a standard interface with which users can create
their own plugins that create their bills exactly the way they (or their
legislation) needs them.

As of phpaga 0.3, billing method plugins can be installed/uninstalled
from within phpaga. The files are not physically installed or removed, 
but the database entries can be managed from the administrator's
interface.

------------------------------------------------------------------------
$Id: README.BILLING_PLUGINS 891 2007-11-06 19:55:28Z florian $

