Merge pull request #179 from 5pm-HDH/release/1.4.0

Release 1.4.0

CHANGELOG.md

@@ -5,38 +5,103 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
-## [1.4.0 Unreleased]
+## [Unreleased]
 
 ### Added
-- Add get config request ([175](https://github.com/5pm-HDH/churchtools-api/pull/175))
-- Add Address-Property to Appointment ([PR137](https://github.com/5pm-HDH/churchtools-api/pull/137))
-- Add SongStatistic ([PR140](https://github.com/5pm-HDH/churchtools-api/pull/140), [PR164](https://github.com/5pm-HDH/churchtools-api/pull/164))
-- Add multi-factor authentication support ([PR146](https://github.com/5pm-HDH/churchtools-api/pull/146))
+
+### Changed
+
+### Fixed
+
+## [1.4.0]
+
+### Added
+
+**New Requests:**
+- Get config request `ConfigRequest:getConfig()` ([175](https://github.com/5pm-HDH/churchtools-api/pull/175))
+- Get SongStatistic `SongStatisticRequest::all()` ([PR140](https://github.com/5pm-HDH/churchtools-api/pull/140), [PR164](https://github.com/5pm-HDH/churchtools-api/pull/164))
+- Song-Tags (`$song->requestTags()`) and Group-Tags (`$group->requestTags()`) ([PR168](https://github.com/5pm-HDH/churchtools-api/pull/168))
+- Get CombinedAppointment consisting of appointment, booking and event ([PR174](https://github.com/5pm-HDH/churchtools-api/pull/174))
+
+**New Properties:**
+- Add Address-Property on Appointment ([PR137](https://github.com/5pm-HDH/churchtools-api/pull/137))
 - Group-member-fields and DBFields-API ([PR147](https://github.com/5pm-HDH/churchtools-api/issues/147))
-- Pagination Page-Size Option ([PR163](https://github.com/5pm-HDH/churchtools-api/pull/163))
-- DateTime-Getter ([PR167](https://github.com/5pm-HDH/churchtools-api/pull/167))
-- Song-Tags ([PR168](https://github.com/5pm-HDH/churchtools-api/pull/168))
-- CTSession ([PR170](https://github.com/5pm-HDH/churchtools-api/pull/170))
-- CombinedAppointment ([PR174](https://github.com/5pm-HDH/churchtools-api/pull/174))
-- Appointment property for calculated and Base StartDate/EndDate ([PR177](https://github.com/5pm-HDH/churchtools-api/pull/177))
+- All date properties get DateTime-Getter (`$vaccationAbsence->getEndDateAsDateTime()`) ([PR167](https://github.com/5pm-HDH/churchtools-api/pull/167))
+- Appointment property for calculated and base StartDate/EndDate ([PR177](https://github.com/5pm-HDH/churchtools-api/pull/177))
+- Add ImageUrlBanner to GroupInformation data ([PR136](https://github.com/5pm-HDH/churchtools-api/pull/136))
+- Add Image-Property to Appointment ([PR174](https://github.com/5pm-HDH/churchtools-api/pull/174))
+
+**Configuration:**
+- Add HTTP-Log to log http request data ([PR137](https://github.com/5pm-HDH/churchtools-api/pull/137))
+- Pagination Page-Size Option `CTConfig::setPaginationPageSize(400)` ([PR163](https://github.com/5pm-HDH/churchtools-api/pull/163))
+- CTSession to handle multiple ct-instances and login-tokens ([PR170](https://github.com/5pm-HDH/churchtools-api/pull/170))
+
+**Authentication:**
+- Add multi-factor authentication support ([PR146](https://github.com/5pm-HDH/churchtools-api/pull/146))
 
 ### Changed
-- Refactor Imports ([PR165](https://github.com/5pm-HDH/churchtools-api/pull/165))
+
+**Breaking Changes:**
+- Refactor Imports to follow PSR-4 ([PR165](https://github.com/5pm-HDH/churchtools-api/pull/165))
 - Reorganize Codebase ([PR173](https://github.com/5pm-HDH/churchtools-api/pull/173))
-- Authenticate CTClient with session cookie instead of api-key ([PR142](https://github.com/5pm-HDH/churchtools-api/pull/142))
-- GH-Action for integration-tests ([PR143](https://github.com/5pm-HDH/churchtools-api/pull/143), [PR144](https://github.com/5pm-HDH/churchtools-api/pull/144), [PR149](https://github.com/5pm-HDH/churchtools-api/pull/149), [PR153](https://github.com/5pm-HDH/churchtools-api/pull/153))
-- Update Dependencies ([PR154](https://github.com/5pm-HDH/churchtools-api/pull/154))
+
+- Authenticate CT-API-Client with cookie session instead of sending api-key in every request. ([PR142](https://github.com/5pm-HDH/churchtools-api/pull/142))
 - Authenticate with UserId and LoginToken ([PR155](https://github.com/5pm-HDH/churchtools-api/pull/155), [PR156](https://github.com/5pm-HDH/churchtools-api/pull/156), [PR157](https://github.com/5pm-HDH/churchtools-api/pull/157))
-- ChurchTools Release ([PR159](https://github.com/5pm-HDH/churchtools-api/pull/159))
+
+**Intern Changes:**
+- Add integration-test that interact with a reallife churchtools instance ([PR143](https://github.com/5pm-HDH/churchtools-api/pull/143), [PR144](https://github.com/5pm-HDH/churchtools-api/pull/144), [PR149](https://github.com/5pm-HDH/churchtools-api/pull/149), [PR153](https://github.com/5pm-HDH/churchtools-api/pull/153))
+- Update Dependencies ([PR154](https://github.com/5pm-HDH/churchtools-api/pull/154))
+- Update tested CT-Version in Docs ([PR178](https://github.com/5pm-HDH/churchtools-api/pull/178), [PR159](https://github.com/5pm-HDH/churchtools-api/pull/159))
 - Replace Psalm PHP with PHP-Stan ([PR166](https://github.com/5pm-HDH/churchtools-api/pull/166))
 - Upgrade Monolog to v3 ([PR171](https://github.com/5pm-HDH/churchtools-api/pull/171))
 - Upgrade required PHP version from 8.0 to 8.1 ([PR171](https://github.com/5pm-HDH/churchtools-api/pull/171))
-- Add Image-Property to Appointment ([PR174](https://github.com/5pm-HDH/churchtools-api/pull/174))
-- Update CT-Version ([PR178](https://github.com/5pm-HDH/churchtools-api/pull/178))
 
-### Fixed
+## Upgrade Guide - Upgrading from 1.3 to 1.4
 
-- Add ImageUrlBanner to GroupInformation data ([PR136](https://github.com/5pm-HDH/churchtools-api/pull/136))
+For version 1.4 we refactor the complete code base to provide a better overview and split the code in the diffrent churchtools parts (groups, events, calendars, bookings). To migrate your from version 1.3 to 1.4 please check out this upgrade guide:
+
+### High Impact Changes:
+
+**Reorganizce Coadebase and refactor imports ([PR173](https://github.com/5pm-HDH/churchtools-api/pull/173), [PR165](https://github.com/5pm-HDH/churchtools-api/pull/165))**
+
+Please update the imports in your code for each Request and Model. You can make use of your IDE's intellisense or refer to the [documentation](https://github.com/5pm-HDH/churchtools-api#requests-and-models) to find the correct namespaces.
+
+**Upgrade PHP Version to 8.1 and dump support for 8.0 ([PR171](https://github.com/5pm-HDH/churchtools-api/pull/171))**
+
+With security support for PHP 8.0 set to expire on November 26, the focus will shift away from 8.0 in favor of embracing new language features in PHP 8.1. You can find more information about supported PHP versions at https://www.php.net/supported-versions.php.
+
+Update your PHP Version on your system and reinstall the composer dependencies.
+
+### Medium Impact Changes:
+
+**Changed Authentication of CT-Client ([PR142](https://github.com/5pm-HDH/churchtools-api/pull/142))**
+
+The authentication method for the churchtools API has been updated. Previously, the API-token was included in every request. Now, authentication will be based on the provided cookie session, which will significantly improve request speed. To be up to date with the authentication methods please check out the [documentation](https://github.com/5pm-HDH/churchtools-api/blob/master/docs/out/CTConfig.md#2-authentication). As a result of this change, the Config API has also been modified:
+
+- `CTConfig::validateApiKey()` is replaced with `CTConfig::validateAuthentication()`
+- `CTConfig::authWithLoginToken($userId, $loginToken)` now only needs loginToken as parameter, because userId is not required: `CTConfig::authWithLoginToken($loginToken)`.
+- `AuthRequest::retrieveApiToken()` now needs the userId as parameter.
+
+### Low Impact Changes:
+
+**Upgrade Monolog to v3 ([PR171](https://github.com/5pm-HDH/churchtools-api/pull/171))**
+
+We upgraded monolog to v3 to be compatible with Laravel 10. There is now action required.
+
+**Ugrade Guzzle from 7.4 to 7.7 ([PR154](https://github.com/5pm-HDH/churchtools-api/pull/154))**
+
+No action required.
+
+### Contributors:
+
+Special thanks to the dedicated contributors who are the driving force behind this project, advancing it, enhancing its quality, and introducing new features.
+
+- [@stollr](https://github.com/stollr) enhanced the person-api and implemented the capability to update data in churchtools and create new persons.
+- [@devdot](https://github.com/devdot) upgraded Monolog to ensure compatibility with Laravel 10.
+- [@a-schild](https://github.com/a-schild) provided valuable input for the appointment API, included the configuration request, and introduced the CombinedAppointment request.
+- [@BiKi05](https://github.com/BiKi05) provided the inspiration for the song-statistic API and the DateTime cast.
+- [@piridium](https://github.com/piridium) implemented a security fix.
+- [@castilma](https://github.com/castilma) proposed documentation for handling exceptions.
 
 ## [1.3.6] - 2023-04-05
 

README.md

@@ -9,6 +9,9 @@
 The ChurchTools-API Client is a PHP-based wrapper for the ChurchTools API and has been tested with ChurchTools
 version <version>3.102.0</version>.
 
+> [!NOTE]
+> Version 1.4 has been launched, featuring a restructured code base and numerous new features. If you're upgrading from version 1.3 to 1.4, please consult the [Upgrade Guide](https://github.com/5pm-HDH/churchtools-api/blob/master/CHANGELOG.md#upgrade-guide---upgrading-from-13-to-14).
+
 ## Installation
 
 Go to the project-root and install ChurchTools-API via [composer](https://getcomposer.org/):
@@ -256,4 +259,22 @@ information, please refer to this page: [Doc-Generator](/docs/Docs.md)
 
 ## License
 
-This project is licensed under MIT-License feel free to use it or to contribute.
+This project is licensed under MIT-License feel free to use it or to contribute.
+
+## Showcase:
+
+To provide you with an idea of the ChurchTools-API Client's potential uses, here are a few examples. If you're working on a project too, please consider contributing and adding it to this list:
+
+**Administration Tools:**
+- **ChurchTools-CLI** by [@5pm-HDH](https://github.com/5pm-HDH/churchtools-cli): With the ChurchTools-CLI-Tool, you can access data from your ChurchTools application instance directly through a CLI application, using simple commands that are easy to learn. The tool is compatible with cmd on Windows, terminal on Mac, and bash on Linux.
+- **ChurchTools GroupMeetings** by [@a-schild](https://github.com/a-schild/churchtools-groupmeetings): Create ical feed from group meetings
+- **ChurchTools PDF Calendar** by [@a-schild](https://github.com/a-schild/churchtools-pdfcalendar): Generate PDF month calendars from churchtools
+- **ECGPB Member List Administration** by [@stollr](https://github.com/stollr/ecgpb-memberlist): This application is written for the christian church Evangeliums-Christengemeinde e.V. and its main purpose is the administration of its members and to generate a printable member list.
+
+**Wordpress Plugins:**
+
+- **ChurchTools WP Calendarsync** by [@a-schild](https://github.com/a-schild/churchtools-wp-calendarsync): This wordpress plugin does take the events from the churchtools calendar and imports them as events in wordpress.
+- **Wordpress Plugin für ChurchTools Anmeldungen** by [@5pm-HDH](https://github.com/5pm-HDH/wp-plugin-churchtools-anmeldungen): Mit diesem Wordpress-Plugin kannst du das von ChurchTools zur Verfügung gestellte iFrame für die Anmeldungen ersetzen durch einen eigenen Template-basierten Ansatz.
+
+**Other Applications:**
+- **FreeScout Module** by [@churcholution](https://github.com/churcholution/freescout-churchtoolsauth): Login to FreeScout with ChurchTools credentials and manage permissions based on group/role memberships.