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