README.rst

   1 *********************************
   2 bdrem - Birthday reminder by mail
   3 *********************************
   4 Birthday reminder that sends out e-mails.
   5
   6 It can also generate ASCII tables on your console, iCalendar files
   7 and normal HTML pages.
   8
   9 .. contents::
  10
  11 ========
  12 Features
  13 ========
  14
  15 Data sources
  16 ============
  17 - Any SQL database.
  18
  19   - Multiple date fields per record supported.
  20 - An LDAP server
  21 - `Birthday reminder <http://cweiske.de/birthday3.htm>`_ files (``.bdf``)
  22
  23 Output formats
  24 ==============
  25 - ASCII table
  26 - HTML
  27 - Email (text + HTML parts)
  28 - iCalendar
  29
  30
  31 =====
  32 Usage
  33 =====
  34
  35 Command line
  36 ============
  37 After configuration_, you can test and use *bdrem* via command line::
  38
  39     $ bdrem
  40     -----------------------------------------------------------
  41     Days  Age  Name                  Event      Date        Day
  42     -----------------------------------------------------------
  43        0   32  Foo Bar               Birthday   20.03.1982  Do
  44        1   33  Andrea Milestone      Birthday   21.03.1981  Fr
  45        7   32  Hugh Success          Birthday   27.03.1982  Do
  46       12       Welt                  Scherztag  01.04.????  Di
  47
  48 Help
  49 ----
  50 To find out about all supported command line options, use ``--help``::
  51
  52     Usage:
  53       ./bin/bdrem.php [options]
  54       ./bin/bdrem.php [options] <command> [options]
  55
  56     Options:
  57       -n NUM, --next=NUM                Show NUM days after date
  58       -p NUM, --prev=NUM                Show NUM days before date
  59       -r renderer, --renderer=renderer  Output mode
  60       --list-renderer                   lists valid choices for option renderer
  61       -e, --stoponempty                 Output nothing when list is empty
  62       -d date, --date=date              Date to show events for
  63       -c FILE, --config=FILE            Path to configuration file
  64       -h, --help                        show this help message and exit
  65       -v, --version                     show the program version and exit
  66
  67     Commands:
  68       readme  Show README.rst file
  69       config  Extract configuration file
  70
  71
  72 E-Mail
  73 ======
  74 To send birthday reminder e-mails, use the ``mail`` renderer::
  75
  76     $ bdrem --renderer=mail
  77
  78 If you only want an email if there is a birthday, use ``--stoponempty``::
  79
  80     $ bdrem --renderer=mail --stoponempty
  81
  82 Make sure your config file contains ``$mail_from`` and ``$mail_to`` settings.
  83
  84
  85 iCalendar
  86 =========
  87 Exporting birthday events into an ``.ics`` file is easy::
  88
  89    $ bdrem --renderer=ical > birthdays.ics
  90
  91 It is possible to access the calendar via HTTP, too::
  92
  93     http://example.org/bdrem/?renderer=ical
  94
  95 You can subscribe to it in your calendar or email application.
  96 Integration has been tested with Thunderbird's Lightning__ and Claws Mail's
  97 vCalendar__ plugin.
  98
  99 __ https://addons.mozilla.org/en-US/thunderbird/addon/lightning/
 100 __ http://www.claws-mail.org/plugin.php?plugin=vcalendar
 101
 102
 103 HTML page
 104 =========
 105 Simply point your web browser to the ``.phar`` file, or ``index.php``.
 106 You will get a colorful HTML table:
 107
 108 .. image:: docs/html.png
 109
 110
 111
 112 =============
 113 Configuration
 114 =============
 115 Copy ``data/bdrem.config.php.dist`` to ``data/bdrem.config.php`` and
 116 adjust it to your liking.
 117
 118 When running the ``.phar``, extract the configuration file first::
 119
 120     $ php dist/bdrem-0.1.0.phar config > bdrem-0.1.0.phar.config.php
 121
 122
 123 Birthday file
 124 =============
 125 If you have a ``.bdf`` file from `birthday reminder`__ or `birthday reminder 3`__,
 126 you can use it with *bdrem*.
 127
 128 Configure your source as follows::
 129
 130     $source = array('Bdf', '/path/to/birthday.bdf');
 131
 132 __ http://cweiske.de/birthday.htm
 133 __ http://cweiske.de/birthday3.htm
 134
 135
 136 LDAP server
 137 ===========
 138 *bdrem* can read birthdays and other events from persons in an LDAP server.
 139 It is known to work fine with ``evolutionPerson`` objects.
 140 Attributes ``birthDate`` and ``anniversary`` are read.
 141
 142 Configure it as follows::
 143
 144     $source = array(
 145         'Ldap',
 146         array(
 147             'host'   => 'ldap.example.org',
 148             'basedn' => 'ou=adressbuch,dc=example,dc=org',
 149             'binddn' => 'cn=FIXME,ou=users,dc=example,dc=org',
 150             'bindpw' => 'FIXME'
 151         )
 152     );
 153
 154
 155 SQL database
 156 ============
 157 Events can be fetched from any SQL database supported by PHP's
 158 PDO extension - MySQL, SQLite, PostgreSQL and so on.
 159
 160 You may configure every little detail of your database::
 161
 162     $source = array(
 163         'Sql',
 164         array(
 165             'dsn' => 'mysql:dbname=bdrem;host=127.0.0.1',
 166             'user' => 'FIXME',
 167             'password' => 'FIXME',
 168             'table' => 'contacts',
 169             'fields' => array(
 170                 'date' => array(
 171                     //column name => event title
 172                     'c_birthday' => 'Birthday'
 173                 ),
 174                 //column with name, or array with column names
 175                 'name' => array('c_name'),
 176                 //sprintf-compatible name formatting instruction
 177                 'nameFormat' => '%s',
 178             )
 179         )
 180     );
 181
 182
 183 MS SQL server
 184 -------------
 185 Configure the date format in ``/etc/freetds/locales.conf``::
 186
 187     [default]
 188         date format = %Y-%m-%d
 189
 190 Also set the charset to UTF-8 in ``/etc/freetds/freetds.conf``::
 191
 192     [global]
 193         # TDS protocol version
 194         tds version = 8.0
 195         client charset = UTF-8
 196
 197 Restart Apache afterwards.
 198
 199 Use ``dblib`` in the DSN::
 200
 201     dblib:host=192.168.1.1;dbname=Databasename
 202
 203
 204 ============
 205 Dependencies
 206 ============
 207 - PHP 5.3 or higher
 208 - PDO
 209 - PEAR packages:
 210
 211   - `Console_Color2 <https://pear.php.net/package/Console_Color2>`_
 212   - `Console_CommandLine <https://pear.php.net/package/Console_CommandLine>`_
 213   - `Console_Table <https://pear.php.net/package/Console_Table>`_
 214   - `Mail_mime <https://pear.php.net/package/Mail_mime>`_
 215   - `Net_LDAP2 <https://pear.php.net/package/Net_LDAP2>`_
 216
 217
 218 =======
 219 License
 220 =======
 221 ``bdrem`` is licensed under the `AGPL v3`__ or later.
 222
 223 __ http://www.gnu.org/licenses/agpl.html
 224
 225
 226 ========
 227 Homepage
 228 ========
 229 Web site
 230    http://cweiske.de/bdrem.htm
 231
 232 Source code
 233    http://git.cweiske.de/bdrem.git
 234
 235    Mirror: https://github.com/cweiske/bdrem
 236
 237
 238 ======
 239 Author
 240 ======
 241 Written by Christian Weiske, cweiske@cweiske.de