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