PHPackages                             craigk5n/php-icalendar-core - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. craigk5n/php-icalendar-core

ActiveLibrary[Parsing & Serialization](/categories/parsing)

craigk5n/php-icalendar-core
===========================

RFC 5545 compliant PHP library for iCalendar parsing and writing

1.1.4(2mo ago)1432↓50%[1 PRs](https://github.com/craigk5n/php-icalendar-core/pulls)MITPHPPHP >=8.2CI passing

Since Feb 9Pushed 2mo agoCompare

[ Source](https://github.com/craigk5n/php-icalendar-core)[ Packagist](https://packagist.org/packages/craigk5n/php-icalendar-core)[ Docs](https://github.com/craigk5n/php-icalendar-core)[ RSS](/packages/craigk5n-php-icalendar-core/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (7)Versions (8)Used By (0)

PHP iCalendar Core
==================

[](#php-icalendar-core)

[![CI](https://github.com/craigk5n/php-icalendar-core/actions/workflows/ci.yml/badge.svg)](https://github.com/craigk5n/php-icalendar-core/actions/workflows/ci.yml)[![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![PHP Version](https://camo.githubusercontent.com/d840cef9807c8f76051ad687841d67f4d830c84e0d83236968e53124ef6742d5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e322d3838393242462e737667)](https://www.php.net/)[![PHPStan Level 9](https://camo.githubusercontent.com/1bc07920f0d36e55c17e1d38b1caa132cc605f51a82b388c962870b9a747b898/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d6c6576656c253230392d627269676874677265656e2e737667)](https://phpstan.org/)[![Documentation](https://camo.githubusercontent.com/6dfb1e3718252ee864de53a8ee883568f1f8e27c6c561dc725dc01e85047579e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f63732d4465657057696b692d626c75652e737667)](https://deepwiki.com/craigk5n/php-icalendar-core)

This library provides robust parsing and writing capabilities for the iCalendar (RFC 5545) format. It aims for high compatibility with RFC specifications while offering flexible parsing modes and supporting standardized extensions for richer data.

Features
--------

[](#features)

- **RFC 5545 Compliant**: Adheres to the iCalendar standard for data representation.
- **Parser & Writer**: Full support for reading and writing iCalendar data.
- **Component & Property Support**: Handles various iCalendar components (VEVENT, VTODO, VCALENDAR, etc.) and properties.
- **Recurrence Rule (RRULE) Handling**: Advanced support for parsing and generating recurrence rules.
- **Timezone Support**: Correctly parses and handles timezone information.
- **Rich Text Descriptions (RFC 9073)**: Supports the `STYLED-DESCRIPTION` property for HTML or URI-based rich text descriptions, enhancing event details. This includes parsing `STYLED-DESCRIPTION` and handling backward compatibility with the plain `DESCRIPTION` property (omitting it unless `DERIVED=TRUE`). Writing also respects this rule.
- **Extensibility**: Designed to be extensible for custom component or property types.
- **Memory Efficiency**: Utilizes generators and streaming where possible for handling large files. Performance benchmarks are calibrated for execution without code coverage overhead.

Strict vs. Lenient Parsing Modes
--------------------------------

[](#strict-vs-lenient-parsing-modes)

This library supports two parsing modes to accommodate varying `.ics` file compliance:

### Strict Mode (`Parser::STRICT`)

[](#strict-mode-parserstrict)

- **Behavior**: In strict mode, the parser rigorously enforces RFC 5545 compliance. Any deviation from the standard, such as malformed date/time values, unexpected component types, or syntax errors, will result in a `ParseException` being thrown immediately. This mode also enforces strict handling of extensions like `STYLED-DESCRIPTION` and its interaction with `DESCRIPTION`.
- **Use Case**: Ideal for validating compliant `.ics` files or when strict adherence to the standard is paramount. It acts as a robust syntax checker for iCalendar data.

### Lenient Mode (`Parser::LENIENT`)

[](#lenient-mode-parserlenient)

- **Behavior**: In lenient mode, the parser prioritizes data import by attempting to process `.ics` files even with non-compliant structures.
    - Instead of throwing exceptions for certain violations (specifically related to **dates**, **times**, and the **`SUMMARY` property**), the parser will collect warnings.
    - These warnings can be retrieved using the `getWarnings()` method after parsing is complete.
    - The parser attempts to handle known extensions like `STYLED-DESCRIPTION` gracefully, collecting warnings for any non-critical deviations.
- **Use Case**: Useful for importing data from `.ics` files that may not perfectly adhere to the RFC, allowing for maximum data recovery.

### Choosing a Mode

[](#choosing-a-mode)

Clients can select the parsing mode by passing a constant to the `Parser` constructor:

```
use Icalendar\Parser\Parser;

// Strict mode (default)
$parserStrict = new Parser(Parser::STRICT);
$calendarStrict = $parserStrict->parse($icsData);

// Lenient mode
$parserLenient = new Parser(Parser::LENIENT);
$calendarLenient = $parserLenient->parse($icsData);

// Access warnings collected in lenient mode
$warnings = $parserLenient->getWarnings(); // Note: getErrors() is an alias for getWarnings() for backward compatibility
```

Installation
------------

[](#installation)

Requires PHP 8.2+ and no external production dependencies.

```
# Assuming you have Composer installed
composer require craigk5n/php-icalendar-core
```

Usage
-----

[](#usage)

### Parsing

[](#parsing)

```
use Icalendar\Parser\Parser;
use Icalendar\Exception\ParseException;
use Icalendar\Validation\ErrorSeverity; // For checking warning severity if needed

$icsData = file_get_contents('path/to/your/calendar.ics');

// Use Parser::LENIENT to collect warnings for non-compliant data
$parser = new Parser(Parser::LENIENT);
try {
    $calendar = $parser->parse($icsData);

    // Process the calendar object...
    // e.g., $events = $calendar->getComponents('VEVENT');

    // Check for warnings if in lenient mode
    if ($parser->getMode() === Parser::LENIENT) {
        $warnings = $parser->getWarnings(); // getErrors() is an alias for backward compatibility
        if (!empty($warnings)) {
            echo "Parsing completed with warnings:\n";
            foreach ($warnings as $warning) {
                // Example: check if it's a warning
                if ($warning->getSeverity() === ErrorSeverity::WARNING) {
                    echo "- Warning (Code: {$warning->getCode()}): {$warning->getMessage()} (Property: {$warning->getProperty()}) [Line {$warning->getLineNumber()}]\n";
                } else {
                    echo "- Error (Code: {$warning->getCode()}): {$warning->getMessage()} (Property: {$warning->getProperty()}) [Line {$warning->getLineNumber()}]\n";
                }
            }
        }
    }

} catch (ParseException $e) {
    echo "Parsing failed: " . $e->getMessage() . "\n";
}
```

### `STYLED-DESCRIPTION` Support (RFC 9073)

[](#styled-description-support-rfc-9073)

The library now supports the `STYLED-DESCRIPTION` property introduced in RFC 9073, which allows for rich text descriptions (e.g., HTML) or URI references.

- **Parsing:** `STYLED-DESCRIPTION` is parsed and stored. When `STYLED-DESCRIPTION` is present, plain `DESCRIPTION` properties that are not marked `DERIVED=TRUE` are ignored during parsing to adhere to RFC 9073's backward compatibility rules.
- **Writing:** `STYLED-DESCRIPTION` properties are correctly serialized. When writing a component that includes `STYLED-DESCRIPTION`, any plain `DESCRIPTION` properties without `DERIVED=TRUE` will be omitted from the output.

### Writing

[](#writing)

```
use Icalendar\Writer\Writer;
use Icalendar\Component\VCalendar;

// Assume $calendar is a VCalendar object populated with data
$writer = new Writer();
$icsString = $writer->write($calendar);

file_put_contents('output.ics', $icsString);
```

Documentation
-------------

[](#documentation)

- **[Full Documentation (DeepWiki)](https://deepwiki.com/craigk5n/php-icalendar-core)** — Auto-generated wiki covering architecture, parsing, writing, recurrence rules, and API reference.
- [PRD.md](PRD.md) — Product requirements and RFC 5545 compliance details.
- [STATUS.md](STATUS.md) — Detailed task tracking and implementation status.

Contributing
------------

[](#contributing)

Please refer to the `CONTRIBUTING.md` file.

AI Assistance Disclosure
------------------------

[](#ai-assistance-disclosure)

This project was developed with the assistance of generative AI tools (Claude Code by Anthropic, OpenCode, and Google Gemini) for tasks such as:

- Structuring the initial PRD and task breakdown
- Generating code skeletons, design patterns, and documentation drafts
- Suggesting test cases and edge-case handling
- Refining explanations, README content, and commit messages

**All AI-generated output has been carefully reviewed, edited, tested, and validated by the human maintainer (Craig Knudsen) for correctness, security, RFC 5545 compliance, and project goals.** No AI-generated code was merged without human understanding and modification.

The final codebase, architecture decisions, and quality assurance remain the responsibility of the human author. This approach accelerated development while preserving full ownership and accountability.

License
-------

[](#license)

This project is licensed under the MIT License - see the `LICENSE` file for details.

###  Health Score

43

—

FairBetter than 91% of packages

Maintenance84

Actively maintained with recent releases

Popularity19

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 91.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

6

Last Release

81d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/cc27447511cb3df84395414395777744612c0660347a7962c80e139d4ff858c7?d=identicon)[craigk5n](/maintainers/craigk5n)

---

Top Contributors

[![craigk5n](https://avatars.githubusercontent.com/u/5342249?v=4)](https://github.com/craigk5n "craigk5n (54 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (5 commits)")

---

Tags

parserwriteriCalendaricsrfc5545calendar

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Psalm

Type Coverage Yes

### Embed Badge

![Health badge](/badges/craigk5n-php-icalendar-core/health.svg)

```
[![Health](https://phpackages.com/badges/craigk5n-php-icalendar-core/health.svg)](https://phpackages.com/packages/craigk5n-php-icalendar-core)
```

###  Alternatives

[nikic/php-parser

A PHP parser written in PHP

17.4k902.6M1.8k](/packages/nikic-php-parser)[doctrine/lexer

PHP Doctrine Lexer parser library that can be used in Top-Down, Recursive Descent Parsers.

11.2k910.8M118](/packages/doctrine-lexer)[masterminds/html5

An HTML5 parser and serializer.

1.8k242.8M229](/packages/masterminds-html5)[matomo/device-detector

The Universal Device Detection library, that parses User Agents and detects devices (desktop, tablet, mobile, tv, cars, console, etc.), clients (browsers, media players, mobile apps, feed readers, libraries, etc), operating systems, devices, brands and models.

3.5k23.5M111](/packages/matomo-device-detector)[eluceo/ical

The eluceo/iCal package offers an abstraction layer for creating iCalendars. You can easily create iCal files by using PHP objects instead of typing your \*.ics file by hand. The output will follow RFC 5545 as best as possible.

1.2k17.5M47](/packages/eluceo-ical)[sabre/vobject

The VObject library for PHP allows you to easily parse and manipulate iCalendar and vCard objects

59723.5M41](/packages/sabre-vobject)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)