From d27826ab65ad0a5c952e0f9568a79ddf7d340018 Mon Sep 17 00:00:00 2001 From: Markus Poerschke Date: Sun, 4 Apr 2021 23:56:29 +0200 Subject: [PATCH] Update README and write upgrade guide for v2 (#234) --- CHANGELOG.md | 31 +++++++++++------------ README.md | 4 +-- UPGRADE.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++----- 3 files changed, 82 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index af59853b..10fdc912 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -174,22 +174,21 @@ Please check the [upgrade guide](UPGRADE.md) on how to upgrade from version `0.* - **Breaking Change:** Changed signature of the `Event::setOrganizer` method. Now there is is only one parameter that must be an instance of `Property\Organizer`. - Updated install section in README.md [#54](https://github.com/markuspoerschke/iCal/pull/53) -[unreleased]: https://github.com/markuspoerschke/iCal/compare/0.16.1...2.x -[0.16.0]: https://github.com/markuspoerschke/iCal/compare/0.15.1...0.16.0 -[0.15.1]: https://github.com/markuspoerschke/iCal/compare/0.15.0...0.15.1 -[0.15.0]: https://github.com/markuspoerschke/iCal/compare/0.14.0...0.15.0 -[0.14.0]: https://github.com/markuspoerschke/iCal/compare/0.13.0...0.14.0 -[0.13.0]: https://github.com/markuspoerschke/iCal/compare/0.12.1...0.13.0 -[0.12.1]: https://github.com/markuspoerschke/iCal/compare/0.12.0...0.12.1 -[0.12.0]: https://github.com/markuspoerschke/iCal/compare/0.11.0...0.12.0 -[0.11.5]: https://github.com/markuspoerschke/iCal/compare/0.11.4...0.11.5 -[0.11.4]: https://github.com/markuspoerschke/iCal/compare/0.11.3...0.11.4 -[0.11.3]: https://github.com/markuspoerschke/iCal/compare/0.11.2...0.11.3 -[0.11.2]: https://github.com/markuspoerschke/iCal/compare/0.11.1...0.11.2 -[0.11.1]: https://github.com/markuspoerschke/iCal/compare/0.11.0...0.11.1 -[0.11.0]: https://github.com/markuspoerschke/iCal/compare/0.10.1...0.11.0 -[0.10.1]: https://github.com/markuspoerschke/iCal/compare/0.10.0...0.10.1 -[0.10.0]: https://github.com/markuspoerschke/iCal/compare/0.9.0...0.10.0 [0.9.0]: https://github.com/markuspoerschke/iCal/compare/0.8.0...0.9.0 +[0.10.0]: https://github.com/markuspoerschke/iCal/compare/0.9.0...0.10.0 +[0.10.1]: https://github.com/markuspoerschke/iCal/compare/0.10.0...0.10.1 +[0.11.0]: https://github.com/markuspoerschke/iCal/compare/0.10.1...0.11.0 +[0.11.1]: https://github.com/markuspoerschke/iCal/compare/0.11.0...0.11.1 +[0.11.2]: https://github.com/markuspoerschke/iCal/compare/0.11.1...0.11.2 +[0.11.3]: https://github.com/markuspoerschke/iCal/compare/0.11.2...0.11.3 +[0.11.4]: https://github.com/markuspoerschke/iCal/compare/0.11.3...0.11.4 +[0.11.5]: https://github.com/markuspoerschke/iCal/compare/0.11.4...0.11.5 +[0.12.0]: https://github.com/markuspoerschke/iCal/compare/0.11.0...0.12.0 +[0.12.1]: https://github.com/markuspoerschke/iCal/compare/0.12.0...0.12.1 +[0.13.0]: https://github.com/markuspoerschke/iCal/compare/0.12.1...0.13.0 +[0.14.0]: https://github.com/markuspoerschke/iCal/compare/0.13.0...0.14.0 +[0.15.0]: https://github.com/markuspoerschke/iCal/compare/0.14.0...0.15.0 +[0.15.1]: https://github.com/markuspoerschke/iCal/compare/0.15.0...0.15.1 +[0.16.0]: https://github.com/markuspoerschke/iCal/compare/0.15.1...0.16.0 [unreleased]: https://github.com/markuspoerschke/iCal/compare/2.0.0...HEAD [2.0.0]: https://github.com/markuspoerschke/iCal/compare/0.16.0...2.0.0 diff --git a/README.md b/README.md index 3dfcc797..c3c8b648 100644 --- a/README.md +++ b/README.md @@ -29,9 +29,9 @@ If you just start using this package, you should install version 2. | Version | PHP Version | | ------- | ----------- | +| 2.\* | 7.4 - 8.0 | +| 0.16.\* | 7.0 - 7.4 | | 0.11.\* | 5.3.0 - 7.4 | -| 0.15.\* | 7.0 - 7.4 | -| 2.\* | 7.4 only | ## Documentation diff --git a/UPGRADE.md b/UPGRADE.md index 9c3f9d0c..3e098855 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -1,9 +1,68 @@ -# v0.8.0 -> v0.9.0 +# Upgrade from `0.16.*` to `2.0` -- The signature of the `Event::setOrganizer` method was changed: - Now there is is only one parameter that must be an instance of `Property\Organizer`. +The fundamental change in version 2 two is the separation between presentation and domain layers. -# v0.7.0 -> v0.8.0 +This library was created with the goal that the user should know as little as possible about the iCal standard and +still be able to create usable iCal files. -- The signature of the `Event::setOrganizer` method was changed: Now there are - two parameters name and email instead of an already formatted string. +## Example Upgrade + +Given you have the following Code from version `0.16.*`: + +```php +$vEvent = new \Eluceo\iCal\Component\Event(); + +$vEvent + ->setDtStart(new \DateTime('2012-12-24')) + ->setDtEnd(new \DateTime('2012-12-24')) + ->setNoTime(true) + ->setSummary('Christmas') +; + +$vCalendar = new \Eluceo\iCal\Component\Calendar('www.example.com'); +$vCalendar->addComponent($vEvent); + +header('Content-Type: text/calendar; charset=utf-8'); +header('Content-Disposition: attachment; filename="cal.ics"'); + +echo $vCalendar->render(); +``` + +The code will be structured very similar. In version `0.16.*`, the event could be sent to output directly. +In contrast, in version 2, the domain object must first be passed to a factory that creates the iCal presentation. + +The above code will look like the following after upgrading to version 2. + +```php +// 1. Create Event domain entity +$event = (new Eluceo\iCal\Domain\Entity\Event()) + ->setSummary('Christmas Eve') + ->setDescription('Lorem Ipsum Dolor...') + ->setOccurrence( + new Eluceo\iCal\Domain\ValueObject\SingleDay( + new Eluceo\iCal\Domain\ValueObject\Date( + \DateTimeImmutable::createFromFormat('Y-m-d', '2012-12-24') + ) + ) + ); + +// 2. Create Calendar domain entity +$calendar = new Eluceo\iCal\Domain\Entity\Calendar([$event]); + +// 3. Transform domain entity into an iCalendar component +$componentFactory = new Eluceo\iCal\Presentation\Factory\CalendarFactory(); +$calendarComponent = $componentFactory->createCalendar($calendar); + +// 4. Set headers +header('Content-Type: text/calendar; charset=utf-8'); +header('Content-Disposition: attachment; filename="cal.ics"'); + +// 5. Output +echo $calendarComponent; +``` + +## Documentation + +In version 0.16.x the documentation consisted mainly of example files. +For version 2, a completely new documentation was created, which deals with all properties of the domain objects. +The documentation can be found here: https://ical.poerschke.nrw