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