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