dbiCal v3.0.5 copyright (c) 2011 Kjell-Inge Gustafsson, kigkonsult kigkonsult.se/dbiCal ical@kigkonsult.se dbiCal is a PHP database back end solution storing (multiple) iCal calendars in a database, using pear MDB2 as database API and iCalcreator as the calendar information API. dbiCal may very well fit as a caldav calendar database back end. The package supports - insert calendar(-s) into database - fetching information about stored calendars in the database - fetch calendar (instance) from database - delete calendar instance(-s) in database dbiCal supports ALL calendar information, timezone, event, todo, journal and freebusy components with all properties, including x-properties. Empty properties are not supported. Multiple instances of a calendar (file) (with separate insert datetimes) are supported. Also metadata, ex. user/calendar references or user/calendar preferences, may be stored for each calendar instance. Using the PHP PEAR MDB2 package, dbiCal supports the following RDBMS: MySQL/MySQLi, PostgreSQL, Oracle, Frontbase (unmaintained), Querysim, Interbase/Firebird, MSSQL, SQLite. Depending on the underlying RDBMS (and MDB2), transactions are supported. The PHP PEAR LOG usage is optional. dbiCal is also shipped with a simple web admin page, offering ability to upload, insert, examine (file), inspect (db), removal and compare of calendar files and db content. dbIcal is implemented as a 'public' class file, dbiCal.class.php and 'inner' calendar/component/property/table DAOs (data access objects) doing the hard work. iCalcreator is used as calendar (file) API, download at 'http://kigkonsult.se/downloads/index.php#icalcreator'. Developing environment is PHP 5.3.3, mysqli driver and MySQL 5.1.47. Please notify back if using other database (engines). To get a proper understanding of iCal, calendar, components and properties, explore RFC2445 / RFC5545, download from 'http://kigkonsult.se/downloads#rfc2445' or 'http://kigkonsult.se/downloads#rfc5545'. DEPENDENCIES ============ iCalcreator-2.10.23 (or later) 'http://kigkonsult.se/downloads/index.php#icalcreator'. MDB2 'http://pear.php.net' LOG, optional 'http://pear.php.net' FILES ===== cache directory, used when comparing disc and db files calendars directory, calendar file storage (proposal) docs/LGPL.txt licence docs/README.txt this file includes directory, dbiCal DAO and iCalcreator class files includes/encoded directory, dbiCal DAO and iCalcreator encoded class files includes/images directory, dbiCal images sql directory, (MySQL) sql create script dbiCal_admin.php dbiCal web admin page INSTALL ======= Unpack to any directory - add this directory to your include-path - or unpack to your application-(include)-directory Add "require_once [directory/][dbiCal/][includes/][encoded/]dbIcal.class.php;" to your php-script. Please examine the enclosed 'dbiCal_admin.php' scripts for using example. Download iCalcreator package and place iCalcreator class files in the same directory as dbiCal or your application-(include)-directory. Add "require_once [directory/][dbiCal/][includes/][encoded/]iCalcreator.class.php;" to your php-script. Please examine the enclosed 'dbiCal_admin.php' script for using example. If using byte encoded class files ('Boost performance' below) and using the admin interface (below), use the 'include/encoded' directory and set '$encoded' to 'TRUE' (if using the admin interface). The 'date_default_timezone' may need to be set to fit your (local) timezone in 'iCalcreator.class.php' or reset after the 'require iCalcreator.class.php' command. In order to create a proper MDB2 DSN (data source name), please examine 'http://pear.php.net/manual/en/package.database.mdb2.intro-dsn.php'. As defined in 'dbiCal_admin.php': 'mysqli://dbiCal:dbiCal@localhost/dbiCal2' ://:@/ If setting up and configure logging, please examine 'http://www.indelible.org/php/Log/guide.html' for details and the enclosed 'dbiCal_admin.php' script for using example. If using the admin interface, place 'dbiCal_admin.php' under your web server document root, edit the 'init and defines' and 'PHP includes' sections (especially directories and log settings) and open the page in a web browser. How to create a MySQL database: Open a MySQL database interface like phpMyAdmin and create a new database, make note of database server name/IP, database name, user and password. Select the new database, import and execute the dbiCal.sql (in the sql directory). The character set in the sql script (default UTF8) may need to be altered to fit. DESCRIPTION =========== - - - - - - - - - - - - To create a new dbiCal instance: - - - - - - - - - - - - dbiCal( db_conn [, log] ) db_conn = pear MDB2 connection instance log = pear Log instance, optional - - - - - - - - - - - - The dbiCal class offer four API methods: - - - - - - - - - - - - dbiCal->getCalendars( [(array) selectOptions] ) selectOptions = associative array ( 'calendar_id' => (int) value , 'filename' => (string) value, , 'date' => (string) date (YYYY-mm-dd) *[, x-property (string) key => (string) value / empty ] *[, metadata (string) key => (string) value / empty ] ) An empty array or no array at all selects all calendars in the database. Any set 'calendar_id' overrides all other criteria. Multiple criteria are combined by the AND condition, (* multiple x-property select criteria are combined by the OR condition as well as metadata criteria). Setting only x-property and/or metadata KEY (and empty VALUEs) selects matching calendars with the specific key set (regardless of value). X-property and metadata key uses database type VARCHAR(255) and value TEXT (in MySQL 2+(2^16)). Returns an array of data for existing calendar instances in the database matching the criteria in array selectOptions, each matching calendar is presented by an associative sub-array( 'calendar_id' => (int) value , 'filename' => (string) value, , 'filesize' => (int) value, , 'create_date' => (string) db insert date value [, (string) x-property key => (string) value ] [, 'metadata' => array( *[(string) key=>(string) value )] ) Default sort order is descending 'calendar_id' (also array key), ex. when searching on 'filename' and multiple instances occur, the higest 'calendar_id' (=latest insert) is placed "first" in array. Returns an empty array if no matching criteria Returns FALSE if database error occurs (details in log file). - - - - - - - - - - - - dbiCal->delete( (array) selectOptions ) selectOptions, see above. Deletes all calendars that matches criteria in selectOptions, an empty array or no array at all, deletes all. Returns FALSE if database error occurs (details in log file), otherwise always TRUE, even if no delete is done. - - - - - - - - - - - dbiCal->insert( (object) calendar [, (array) metadata ] ) calendar = iCalcreator calendar object metadata = arbitrary (string) key / (string) value associative array, like user/calendar reference (ex. 'customerId'=1234) or any user/calendar preference metadata key uses database type VARCHAR(255) and metadata value type TEXT (in MySQL 2+(2^16)). Returns calendar database id (success) or FALSE (database error, details in log file). - - - - - - - - - - - dbiCal->select( (int) calendar_id [, (array) config] ) Selects calendar with argument database id Config is a iCalcreator calendar config array, please examine 'http://kigkonsult.se/iCalcreator/docs/using.html#Calendar_configuration_functions'. Returns iCalcreator calendar instance (success) or FALSE (not found or database error, details in log file). Setting argument 'unique_id' in array config will override any existent (stored) calendar unique_id (and set component UID, if missing), please examine 'http://kigkonsult.se/iCalcreator/docs/using.html#Unique_id'. - - - - - - - - - - - The web admin page presents a menu with six tabs: 'config' shows dbiCal admin configuration offer ability to change (session) log level 'db status' show inserted file instance(-s) in the database and offer ability to remove calendar instance from database compare disc file and database calendar instance (contents) (*) download calendar instance as file from database 'Files' display files in the 'calendars' directory and offer ability to insert calendar file (instance) into database inspect calendar file in the directory remove calendar file from the directory upload calendar file into the directory 'file compare' shows result from a 'compare' operation 'test Select' offer ability for 'ad hoc' database searches and displays the result offer the same functionality for matching results as the 'db status' tab 'Inspect Log' display (opt.) log file offer the ability to examine and clear the log file and change (session) log level (*) The web interface are using iCalcreator sort() before insert, disc file and database content may differ at compare, due to component (re-)sorted order and also iCalcreator (component) property order. The admin web interface originates from a dbiCal test interface. If you want to use test calendar files, download tiCalFile package, 'http://kigkonsult.se/downloads/index.php#tiCalFile'. The package create test iCal file(-s) with configurable events; start date, number of events, recurrence etc. - - - - - - - - - - - For creating (used as dbiCal input) and utilize (dbiCal output) iCalcreator objects, please examine 'http://kigkonsult.se/iCalcreator/docs/using.html' for use and coding issues. Also useful are RFC2445 Internet Calendaring and Scheduling Core Object Specification (iCalendar) RFC2446 iCalendar Transport-Independent Interoperability Protocol (iTIP) Scheduling Events, BusyTime, To-dos and Journal Entries RFC5545 Internet Calendaring and Scheduling Core Object Specification (iCalendar), Obsoletes: RFC2445. RFC5546 iCalendar Transport-Independent Interoperability Protocol (iTIP) Obsoletes: RFC2446 Download the rfc's at 'http://kigkonsult.se/downloads/index.php#rfc' SUPPORT ======= Use 'kigkonsult.se/contact/index.php' page for queries, improvement/development issues or professional support and development. Please note that paid support or consulting service has the highest priority. Our services are available for support and designing and developing iCalcreator, dbiCal etc. customizations, adaptations and other PHP/MySQL solutions with a special focus on software utility and reliability, supported through our iterative acquire/design/transition process modell. Donate ====== You can show your appreciation for our free software, and can support future development by making a donation to the kigkonsult project dbiCal. Make a donation of any size at 'http://kigkonsult.se/contact/index.php#Donate'. Thanks in advance! Boost performance ================= To really boost performance, kigkonsult can now offer PHP (4 and 5) packages (dbiCal, iCalcreator etc) in byte coded files, using ionCube (http://www.ioncube.com/?xp=SRLGBR) encoder. Encoded files use a platform independent file format, and can be run on any platform for which ionCube supply a (free) Loader. Currently supported platforms are Windows (e.g. NT, XP, W2K), Intel Linux, FreeBSD, NetBSD, OpenBSD, OS X, and Sparc Solaris. Visit 'http://kigkonsult.se/contact/index.php#Boost' for information and/or purchase. COPYRIGHT & LICENCE =================== COPYRIGHT dbiCal v3.0.5 copyright (c) 2011 Kjell-Inge Gustafsson, kigkonsult kigkonsult.se/dbiCal ical@kigkonsult.se LICENCE This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA