path: root/README.rst

*********************************
bdrem - Birthday reminder by mail
*********************************
Birthday reminder that sends out e-mails.

It can also generate ASCII tables on your console, iCalendar files
and normal HTML pages.

.. contents::

========
Features
========

Data sources
============
- Any SQL database.

  - Multiple date fields per record supported.
- An LDAP server with ``evolutionPerson`` records
- `Birthday reminder <http://cweiske.de/birthday3.htm>`_ files (``.bdf``)
- CSV files

Output formats
==============
- ASCII table
- HTML
- Email (text + HTML parts)
- iCalendar


=====
Usage
=====

Command line
============
After configuration_, you can test and use *bdrem* via command line::

    $ bdrem
    -----------------------------------------------------------
    Days  Age  Name                  Event      Date        Day
    -----------------------------------------------------------
       0   32  Foo Bar               Birthday   20.03.1982  Do
       1   33  Andrea Milestone      Birthday   21.03.1981  Fr
       7   32  Hugh Success          Birthday   27.03.1982  Do
      12       Welt                  Scherztag  01.04.????  Di

Help
----
To find out about all supported command line options, use ``--help``::

    Usage:
      ./bin/bdrem.php [options]
      ./bin/bdrem.php [options] <command> [options]

    Options:
      -n NUM, --next=NUM                Show NUM days after date
      -p NUM, --prev=NUM                Show NUM days before date
      -r renderer, --renderer=renderer  Output mode
      --list-renderer                   lists valid choices for option renderer
      -e, --stoponempty                 Output nothing when list is empty
      -d date, --date=date              Date to show events for
      -c FILE, --config=FILE            Path to configuration file
      --debug                           Development helper (mail)
      --no-color                        Do not output ANSI color codes
      -h, --help                        show this help message and exit
      -v, --version                     show the program version and exit

    Commands:
      readme  Show README.rst file
      config  Extract configuration file


E-Mail
======
To send birthday reminder e-mails, use the ``mail`` renderer::

    $ bdrem --renderer=mail

If you only want an email if there is a birthday, use ``--stoponempty``::

    $ bdrem --renderer=mail --stoponempty

Make sure your config file contains ``$mail_from`` and ``$mail_to`` settings.


iCalendar
=========
Exporting birthday events into an ``.ics`` file is easy::

   $ bdrem --renderer=ical > birthdays.ics

It is possible to access the calendar via HTTP, too::

    http://example.org/bdrem/?renderer=ical

You can subscribe to it in your calendar or email application.
Integration has been tested with Thunderbird's Lightning__ and Claws Mail's
vCalendar__ plugin.

__ https://addons.mozilla.org/en-US/thunderbird/addon/lightning/
__ http://www.claws-mail.org/plugin.php?plugin=vcalendar


HTML page
=========
Simply point your web browser to the ``.phar`` file, or ``index.php``.
You will get a colorful HTML table:

.. image:: docs/html.png



=============
Configuration
=============
Copy ``data/bdrem.config.php.dist`` to ``data/bdrem.config.php`` and
adjust it to your liking.

When running the ``.phar``, extract the configuration file first::

    $ php dist/bdrem-0.1.0.phar config > bdrem-0.1.0.phar.config.php


Birthday file
=============
If you have a ``.bdf`` file from `birthday reminder`__ or `birthday reminder 3`__,
you can use it with *bdrem*.

Configure your source as follows::

    $source = array('Bdf', '/path/to/birthday.bdf');

__ http://cweiske.de/birthday.htm
__ http://cweiske.de/birthday3.htm


CSV file
========
Comma separated value files can be used with bdrem.
They should at least contain a column with the name, and one with the date.

Simple configuration if you use the default settings::

    $source = array(
        'Csv',
        '/path/to/file.csv'
    );

Complex configuration::

    $source = array(
        'Csv',
        array(
            'filename' => '/path/to/file.csv',
            'columns' => array(
                'name'  => 0,
                'event' => 1,
                'date'  => 2
            ),
            'firstLineIsHeader' => true,
            'defaultEvent' => 'Birthday',
            'separator' => ',',
        )
    );

Configuration options
---------------------
``columns``
  Determines the position of the name, event and date columns.
  ``0`` is the first column.
  You can use ``false`` to disable a column; helpful if there is no
  ``event`` column.

  Default:

  ``array('name' => 0, 'event' => 1, 'date' => 2)``

``defaultEvent``
  Text to use as event if there is no event column.

  Defaults to ``Birthday``

``firstLineIsHeader``
  If the first line in the CSV is column header data

  Defaults to ``true``

``separator``
  How columns are separated.

  Defaults to ``,``


LDAP server
===========
*bdrem* can read birthdays and other events from persons in an LDAP server.
It is known to work fine with ``evolutionPerson`` objects.
Attributes ``birthDate`` and ``anniversary`` are read.

Configure it as follows::

    $source = array(
        'Ldap',
        array(
            'host'   => 'ldap.example.org',
            'basedn' => 'ou=adressbuch,dc=example,dc=org',
            'binddn' => 'cn=FIXME,ou=users,dc=example,dc=org',
            'bindpw' => 'FIXME'
        )
    );


SQL database
============
Events can be fetched from any SQL database supported by PHP's
PDO extension - MySQL, SQLite, PostgreSQL and so on.

You may configure every little detail of your database::

    $source = array(
        'Sql',
        array(
            'dsn' => 'mysql:dbname=bdrem;host=127.0.0.1',
            'user' => 'FIXME',
            'password' => 'FIXME',
            'table' => 'contacts',
            'fields' => array(
                'date' => array(
                    //column name => event title
                    'c_birthday' => 'Birthday'
                ),
                //column with name, or array with column names
                'name' => array('c_name'),
                //sprintf-compatible name formatting instruction
                'nameFormat' => '%s',
            )
        )
    );


MS SQL server
-------------
Configure the date format in ``/etc/freetds/locales.conf``::

    [default]
        date format = %Y-%m-%d

Also set the charset to UTF-8 in ``/etc/freetds/freetds.conf``::

    [global]
        # TDS protocol version
        tds version = 8.0
        client charset = UTF-8

Restart Apache afterwards.

Use ``dblib`` in the DSN::

    dblib:host=192.168.1.1;dbname=Databasename


============
Dependencies
============
- PHP 5.3 or higher
- PDO
- PEAR packages:

  - `Console_Color2 <https://pear.php.net/package/Console_Color2>`_
  - `Console_CommandLine <https://pear.php.net/package/Console_CommandLine>`_
  - `Console_Table <https://pear.php.net/package/Console_Table>`_
  - `Mail_mime <https://pear.php.net/package/Mail_mime>`_
  - `Net_LDAP2 <https://pear.php.net/package/Net_LDAP2>`_


Note that the ``.phar`` file already includes all dependencies;
you do not need to install anything.

When running from a git checkout, install the dependencies with composer::

  $ composer install


=======
License
=======
``bdrem`` is licensed under the `AGPL v3`__ or later.

__ http://www.gnu.org/licenses/agpl.html


========
Homepage
========
Web site
   http://cweiske.de/bdrem.htm

Source code
   http://git.cweiske.de/bdrem.git

   Mirror: https://github.com/cweiske/bdrem


======
Author
======
Written by Christian Weiske, cweiske@cweiske.de