properly generate full-day ical events
[bdrem.git] / 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 You can subscribe to it in your calendar or email application.
95 Integration has been tested with Thunderbird's Lightning__ and Claws Mail's
96 vCalendar__ plugin.
97
98 __ https://addons.mozilla.org/en-US/thunderbird/addon/lightning/
99 __ http://www.claws-mail.org/plugin.php?plugin=vcalendar
100
101
102 HTML page
103 =========
104 Simply point your web browser to the ``.phar`` file, or ``index.php``.
105 You will get a colorful HTML table:
106
107 .. image:: docs/html.png
108
109
110
111 =============
112 Configuration
113 =============
114 Copy ``data/bdrem.config.php.dist`` to ``data/bdrem.config.php`` and
115 adjust it to your liking.
116
117 When running the ``.phar``, extract the configuration file first::
118
119     $ php dist/bdrem-0.1.0.phar config > bdrem-0.1.0.phar.config.php
120
121
122 Birthday file
123 =============
124 If you have a ``.bdf`` file from `birthday reminder`__ or `birthday reminder 3`__,
125 you can use it with *bdrem*.
126
127 Configure your source as follows::
128
129     $source = array('Bdf', '/path/to/birthday.bdf');
130
131 __ http://cweiske.de/birthday.htm 
132 __ http://cweiske.de/birthday3.htm 
133
134
135 LDAP server
136 ===========
137 *bdrem* can read birthdays and other events from persons in an LDAP server.
138 It is known to work fine with ``evolutionPerson`` objects.
139 Attributes ``birthDate`` and ``anniversary`` are read.
140
141 Configure it as follows::
142
143     $source = array(
144         'Ldap',
145         array(
146             'host'   => 'ldap.example.org',
147             'basedn' => 'ou=adressbuch,dc=example,dc=org',
148             'binddn' => 'cn=FIXME,ou=users,dc=example,dc=org',
149             'bindpw' => 'FIXME'
150         )
151     );
152
153
154 SQL database
155 ============
156 Events can be fetched from any SQL database supported by PHP's
157 PDO extension - MySQL, SQLite, PostgreSQL and so on.
158
159 You may configure every little detail of your database::
160
161     $source = array(
162         'Sql',
163         array(
164             'dsn' => 'mysql:dbname=bdrem;host=127.0.0.1',
165             'user' => 'FIXME',
166             'password' => 'FIXME',
167             'table' => 'contacts',
168             'fields' => array(
169                 'date' => array(
170                     //column name => event title
171                     'c_birthday' => 'Birthday'
172                 ),
173                 //column with name, or array with column names
174                 'name' => array('c_name'),
175                 //sprintf-compatible name formatting instruction
176                 'nameFormat' => '%s',
177             )
178         )
179     );
180
181
182 MS SQL server
183 -------------
184 Configure the date format in ``/etc/freetds/locales.conf``::
185
186     [default]
187         date format = %Y-%m-%d
188
189 Also set the charset to UTF-8 in ``/etc/freetds/freetds.conf``::
190
191     [global]
192         # TDS protocol version
193         tds version = 8.0
194         client charset = UTF-8
195
196 Restart Apache afterwards.
197
198 Use ``dblib`` in the DSN::
199
200     dblib:host=192.168.1.1;dbname=Databasename
201
202
203 ============
204 Dependencies
205 ============
206 - PHP 5.3 or higher
207 - PDO
208 - PEAR packages:
209
210   - `Console_Color2 <https://pear.php.net/package/Console_Color2>`_
211   - `Console_CommandLine <https://pear.php.net/package/Console_CommandLine>`_
212   - `Console_Table <https://pear.php.net/package/Console_Table>`_
213   - `Mail_mime <https://pear.php.net/package/Mail_mime>`_
214   - `Net_LDAP2 <https://pear.php.net/package/Net_LDAP2>`_
215
216
217 =======
218 License
219 =======
220 ``bdrem`` is licensed under the `AGPL v3`__ or later.
221
222 __ http://www.gnu.org/licenses/agpl.html
223
224
225 ========
226 Homepage
227 ========
228 Web site
229    http://cweiske.de/bdrem.htm
230
231 Source code
232    http://git.cweiske.de/bdrem.git
233
234    Mirror: https://github.com/cweiske/bdrem
235
236
237 ======
238 Author
239 ======
240 Written by Christian Weiske, cweiske@cweiske.de