add LICENSE file
[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, 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