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 with ``evolutionPerson`` records
  21 - `Birthday reminder <http://cweiske.de/birthday3.htm>`_ files (``.bdf``)
  22 - CSV files
  23 - A directory of .vcf vCard files
  24
  25
  26 Output formats
  27 ==============
  28 - ASCII table
  29 - HTML
  30 - Email (text + HTML parts)
  31 - iCalendar
  32
  33
  34 =====
  35 Usage
  36 =====
  37
  38 Command line
  39 ============
  40 After configuration_, you can test and use *bdrem* via command line::
  41
  42     $ bdrem
  43     -----------------------------------------------------------
  44     Days  Age  Name                  Event      Date        Day
  45     -----------------------------------------------------------
  46        0   32  Foo Bar               Birthday   20.03.1982  Do
  47        1   33  Andrea Milestone      Birthday   21.03.1981  Fr
  48        7   32  Hugh Success          Birthday   27.03.1982  Do
  49       12       Welt                  Scherztag  01.04.????  Di
  50
  51 Help
  52 ----
  53 To find out about all supported command line options, use ``--help``::
  54
  55     Usage:
  56       ./bin/bdrem.php [options]
  57       ./bin/bdrem.php [options] <command> [options]
  58
  59     Options:
  60       -n NUM, --next=NUM                Show NUM days after date
  61       -p NUM, --prev=NUM                Show NUM days before date
  62       -r renderer, --renderer=renderer  Output mode
  63       --list-renderer                   lists valid choices for option renderer
  64       -e, --stoponempty                 Output nothing when list is empty
  65       -d date, --date=date              Date to show events for
  66       -c FILE, --config=FILE            Path to configuration file
  67       --debug                           Development helper (mail)
  68       --no-color                        Do not output ANSI color codes
  69       -h, --help                        show this help message and exit
  70       -v, --version                     show the program version and exit
  71
  72     Commands:
  73       readme  Show README.rst file
  74       config  Extract configuration file
  75
  76
  77 E-Mail
  78 ======
  79 To send birthday reminder e-mails, use the ``mail`` renderer::
  80
  81     $ bdrem --renderer=mail
  82
  83 If you only want an email if there is a birthday, use ``--stoponempty``::
  84
  85     $ bdrem --renderer=mail --stoponempty
  86
  87 Make sure your config file contains ``$mail_from`` and ``$mail_to`` settings.
  88
  89
  90 iCalendar
  91 =========
  92 Exporting birthday events into an ``.ics`` file is easy::
  93
  94    $ bdrem --renderer=ical > birthdays.ics
  95
  96 It is possible to access the calendar via HTTP, too::
  97
  98     http://example.org/bdrem/?renderer=ical
  99
 100 You can subscribe to it in your calendar or email application.
 101 Integration has been tested with Thunderbird's Lightning__ and Claws Mail's
 102 vCalendar__ plugin.
 103
 104 __ https://addons.mozilla.org/en-US/thunderbird/addon/lightning/
 105 __ http://www.claws-mail.org/plugin.php?plugin=vcalendar
 106
 107
 108 HTML page
 109 =========
 110 Simply point your web browser to the ``.phar`` file, or ``index.php``.
 111 You will get a colorful HTML table:
 112
 113 .. image:: docs/html.png
 114
 115
 116
 117 =============
 118 Configuration
 119 =============
 120 Copy ``data/bdrem.config.php.dist`` to ``data/bdrem.config.php`` and
 121 adjust it to your liking.
 122
 123 When running the ``.phar``, extract the configuration file first::
 124
 125     $ php dist/bdrem-0.1.0.phar config > bdrem-0.1.0.phar.config.php
 126
 127
 128 Birthday file
 129 =============
 130 If you have a ``.bdf`` file from `birthday reminder`__ or `birthday reminder 3`__,
 131 you can use it with *bdrem*.
 132
 133 Configure your source as follows::
 134
 135     $source = array('Bdf', '/path/to/birthday.bdf');
 136
 137 __ http://cweiske.de/birthday.htm
 138 __ http://cweiske.de/birthday3.htm
 139
 140
 141 CSV file
 142 ========
 143 Comma separated value files can be used with bdrem.
 144 They should at least contain a column with the name, and one with the date.
 145
 146 Simple configuration if you use the default settings::
 147
 148     $source = array(
 149         'Csv',
 150         '/path/to/file.csv'
 151     );
 152
 153 Complex configuration::
 154
 155     $source = array(
 156         'Csv',
 157         array(
 158             'filename' => '/path/to/file.csv',
 159             'columns' => array(
 160                 'name'  => 0,
 161                 'event' => 1,
 162                 'date'  => 2
 163             ),
 164             'firstLineIsHeader' => true,
 165             'defaultEvent' => 'Birthday',
 166             'separator' => ',',
 167         )
 168     );
 169
 170 Configuration options
 171 ---------------------
 172 ``columns``
 173   Determines the position of the name, event and date columns.
 174   ``0`` is the first column.
 175   You can use ``false`` to disable a column; helpful if there is no
 176   ``event`` column.
 177
 178   Default:
 179
 180   ``array('name' => 0, 'event' => 1, 'date' => 2)``
 181
 182 ``defaultEvent``
 183   Text to use as event if there is no event column.
 184
 185   Defaults to ``Birthday``
 186
 187 ``firstLineIsHeader``
 188   If the first line in the CSV is column header data
 189
 190   Defaults to ``true``
 191
 192 ``separator``
 193   How columns are separated.
 194
 195   Defaults to ``,``
 196
 197
 198 LDAP server
 199 ===========
 200 *bdrem* can read birthdays and other events from persons in an LDAP server.
 201 It is known to work fine with ``evolutionPerson`` objects.
 202 Attributes ``birthDate`` and ``anniversary`` are read.
 203
 204 Configure it as follows::
 205
 206     $source = array(
 207         'Ldap',
 208         array(
 209             'host'   => 'ldap.example.org',
 210             'basedn' => 'ou=adressbuch,dc=example,dc=org',
 211             'binddn' => 'cn=FIXME,ou=users,dc=example,dc=org',
 212             'bindpw' => 'FIXME'
 213         )
 214     );
 215
 216
 217 SQL database
 218 ============
 219 Events can be fetched from any SQL database supported by PHP's
 220 PDO extension - MySQL, SQLite, PostgreSQL and so on.
 221
 222 You may configure every little detail of your database::
 223
 224     $source = array(
 225         'Sql',
 226         array(
 227             'dsn' => 'mysql:dbname=bdrem;host=127.0.0.1',
 228             'user' => 'FIXME',
 229             'password' => 'FIXME',
 230             'table' => 'contacts',
 231             'fields' => array(
 232                 'date' => array(
 233                     //column name => event title
 234                     'c_birthday' => 'Birthday'
 235                 ),
 236                 //column with name, or array with column names
 237                 'name' => array('c_name'),
 238                 //sprintf-compatible name formatting instruction
 239                 'nameFormat' => '%s',
 240             )
 241         )
 242     );
 243
 244
 245 MS SQL server
 246 -------------
 247 Configure the date format in ``/etc/freetds/locales.conf``::
 248
 249     [default]
 250         date format = %Y-%m-%d
 251
 252 Also set the charset to UTF-8 in ``/etc/freetds/freetds.conf``::
 253
 254     [global]
 255         # TDS protocol version
 256         tds version = 8.0
 257         client charset = UTF-8
 258
 259 Restart Apache afterwards.
 260
 261 Use ``dblib`` in the DSN::
 262
 263     dblib:host=192.168.1.1;dbname=Databasename
 264
 265
 266 ============
 267 Dependencies
 268 ============
 269 - PHP 5.3 or higher
 270 - PDO
 271 - PEAR packages:
 272
 273   - `Console_Color2 <https://pear.php.net/package/Console_Color2>`_
 274   - `Console_CommandLine <https://pear.php.net/package/Console_CommandLine>`_
 275   - `Console_Table <https://pear.php.net/package/Console_Table>`_
 276   - `Mail_mime <https://pear.php.net/package/Mail_mime>`_
 277   - `Net_LDAP2 <https://pear.php.net/package/Net_LDAP2>`_
 278
 279
 280 Note that the ``.phar`` file already includes all dependencies;
 281 you do not need to install anything.
 282
 283 When running from a git checkout, install the dependencies with composer::
 284
 285   $ composer install
 286
 287
 288 =======
 289 License
 290 =======
 291 ``bdrem`` is licensed under the `AGPL v3`__ or later.
 292
 293 __ http://www.gnu.org/licenses/agpl.html
 294
 295
 296 ========
 297 Homepage
 298 ========
 299 Web site
 300    http://cweiske.de/bdrem.htm
 301
 302 Source code
 303    http://git.cweiske.de/bdrem.git
 304
 305    Mirror: https://github.com/cweiske/bdrem
 306
 307
 308 ======
 309 Author
 310 ======
 311 Written by Christian Weiske, cweiske@cweiske.de