{"id":36251499,"url":"https://github.com/5pm-hdh/churchtools-api","last_synced_at":"2026-01-11T07:00:15.299Z","repository":{"id":37718346,"uuid":"352940488","full_name":"5pm-HDH/churchtools-api","owner":"5pm-HDH","description":"The Churchtools-API Client is a wrapper for the churchtools-api written in PHP.","archived":false,"fork":false,"pushed_at":"2025-02-18T07:40:51.000Z","size":1030,"stargazers_count":24,"open_issues_count":15,"forks_count":10,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-12-03T02:30:14.649Z","etag":null,"topics":["api","api-client","churchtools","churchtools-api","churchtools-client","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/5pm-HDH.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-30T09:16:16.000Z","updated_at":"2025-11-03T18:32:45.000Z","dependencies_parsed_at":"2023-02-14T16:16:52.488Z","dependency_job_id":"475a2b8b-e3f0-43ae-914c-5e842d1a5b67","html_url":"https://github.com/5pm-HDH/churchtools-api","commit_stats":{"total_commits":325,"total_committers":6,"mean_commits":"54.166666666666664","dds":"0.10769230769230764","last_synced_commit":"ab8c5f64da4a58a053430ed97b5763e23dfd0a44"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/5pm-HDH/churchtools-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5pm-HDH%2Fchurchtools-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5pm-HDH%2Fchurchtools-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5pm-HDH%2Fchurchtools-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5pm-HDH%2Fchurchtools-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/5pm-HDH","download_url":"https://codeload.github.com/5pm-HDH/churchtools-api/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5pm-HDH%2Fchurchtools-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28296941,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T04:44:51.577Z","status":"ssl_error","status_checked_at":"2026-01-11T04:44:44.232Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-client","churchtools","churchtools-api","churchtools-client","php"],"created_at":"2026-01-11T07:00:13.070Z","updated_at":"2026-01-11T07:00:15.187Z","avatar_url":"https://github.com/5pm-HDH.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ChurchTools-API Client\n\n![static-code-analysis workflow](https://github.com/5pm-HDH/churchtools-api/actions/workflows/static-code-analysis.yml/badge.svg)\n\n![unit-test workflow](https://github.com/5pm-HDH/churchtools-api/actions/workflows/unit-tests.yml/badge.svg)\n\n![integarion-test workflow](https://github.com/5pm-HDH/churchtools-api/actions/workflows/integration-tests.yml/badge.svg)\n\nThe ChurchTools-API Client is a PHP-based wrapper for the ChurchTools API and has been tested with ChurchTools\nversion \u003cversion\u003e3.104.3\u003c/version\u003e.\n\n\u003e [!NOTE]\n\u003e Version 2 has been launched, featuring a restructured code base and numerous new features. If you're upgrading from version 1 to 2, please consult the [Upgrade Guide](https://github.com/5pm-HDH/churchtools-api/blob/master/CHANGELOG.md#upgrade-guide---upgrading-from-v1-to-v2).\n\n## Installation\n\nGo to the project-root and install ChurchTools-API via [composer](https://getcomposer.org/):\n\n```\ncomposer require 5pm-hdh/churchtools-api\n```\n\nLoad all dependency packages into the PHP project using the following code:\n\n```php\n\u003c?php\n\ninclude_once 'vendor/autoload.php';\n```\n\n## Usage\n\nBefore you can start to request data from the API you need to **configure the CT-Client (ChurchTools client)** with\nthe `CTConfig`-interface:\n\n```php\nuse \\CTApi\\CTConfig;\n\n    //set the url of your ChurchTools application api\n    //important! ApiUrl must end with Top-Level-Domain. No paths allowed!\nCTConfig::setApiUrl(\"https://example.church.tools\");\n\n    //authenticates the application and load the api-key into the config\nCTConfig::authWithCredentials(\n    \"example.email@gmx.de\",\n    \"myPassword1234\"\n);\n\n// Multi-factor authentication:\nCTConfig::authWithCredentials(\n    \"example.email@gmx.de\",\n    \"myPassword1234\",\n    \"291521\"\n);\n```\n\nFor more information visit the [CTConfig documentation](/docs/out/CTConfig.md)\nFrom now on all features of the ChurchTools-API are available.\n\n### Requests and Models\n\nThe whole ChurchTools-API client is build on top of the Requests and Models. Requests provide an interface to specify your api call by adding filtering, pagination and sorting. Models represent the data, that the Requests retrieve. More informations can be found in the documentation: \n\n* [Requests](/docs/out/Requests.md)\n* [Models](/docs/out/Models.md)\n\nAll APIs with examples:\n\n* [Person-API](/docs/out/PersonAPI.md)\n* [Group-API](/docs/out/GroupAPI.md)\n* [Calendar-API](/docs/out/CalendarAPI.md)\n* [Resource- and Bookings-API](/docs/out/ResourceAPI.md)\n* [PublicGroup-API](/docs/out/PublicGroupAPI.md)\n* [Event-API](/docs/out/EventAPI.md)\n* [Song-API](/docs/out/SongAPI.md)\n* [Service-API](/docs/out/ServiceAPI.md)\n* [Absence-API](/docs/out/AbsenceAPI.md)\n* [Wiki-API](/docs/out/WikiAPI.md)\n* [Permission-API](/docs/out/PermissionAPI.md)\n* [File-API](/docs/out/FileAPI.md)\n* [Search-API](/docs/out/SearchAPI.md)\n* [DB-Fields](/docs/out/DBFields.md)\n* [Tags-API](/docs/out/TagsAPI.md)\n\nThe following brief examples demonstrate the capabilities of the ChurchTools-API client and provide a general overview\nof its potential uses:\n\n#### Example: Person-API\n\n```php\nuse CTApi\\Models\\Groups\\Person\\PersonRequest;\n\n$myself = PersonRequest::whoami();\necho \"Hello \".$myself-\u003egetLastName() . $myself-\u003egetFirstName();\n\n// Retrieve all Persons\n$allPersons = PersonRequest::all();\n\n// Filter Data with Where-Clause\n$teenager = PersonRequest::where('birthday_before', '2007-01-01')\n                    -\u003ewhere('birthday_after', '2003-01-01')\n                    -\u003eorderBy('birthday')\n                    -\u003eget();\n                    \nforeach($teenager as $teenPerson){\n    echo \"Hello Teenager with E-Mail: \".$teenPerson-\u003egetEmail();\n}\n\n// Get specific Person\n$personA = PersonRequest::find(21);     // returns \"null\" if id is invalid\n$personB = PersonRequest::findOrFail(22); // throws exception if id is invalid\n```\n\n#### Example: Event-API\n\n```php\nuse CTApi\\Models\\Events\\Event\\EventAgendaRequest;use CTApi\\Models\\Events\\Event\\EventRequest;\n\n// Retrieve all events\n$allEvents = EventRequest::all();\n\n// Get specific Event\n$event = EventRequest::find(21);     // returns \"null\" if id is invalid\n$event = EventRequest::findOrFail(22); // throws exception if id is invalid\n\n// Filter events in period\n$christmasServices = EventRequest::where('from', '2020-12-24')\n                    -\u003ewhere('to', '2020-12-26')\n                    -\u003eorderBy('id')\n                    -\u003eget();\n  \n$christmasService = $christmasServices[0];\n  \n// get the Agenda with event id...\n$eventId = $christmasServices-\u003egetId();\n$agenda = EventAgendaRequest::fromEvent($eventId)-\u003eget();\n\n// ...or direct on event-Model\n$agenda = $event-\u003erequestAgenda();\n\n// Use Songs-API\n$songsOnChristmas = $agenda-\u003egetSongs();\n\nforeach($songsOnChristmas as $song){\n    echo $song-\u003egetTitle() . \" - (Key: \" .$song-\u003egetKey() . \")\";\n}\n```\n\n#### Example: Wiki-API\n\n```php\nuse CTApi\\Models\\Wiki\\WikiCategory\\WikiCategoryRequest;\n\n$wikiCategory = WikiCategoryRequest::find(21);\n\n$rootNodeWiki = $wikiCategory-\u003erequestWikiPageTree();\n\necho \"\u003ch1\u003eTable of content:\u003c/h1\u003e\";\necho \"\u003cul class='first-level'\u003e\";\n    // First Level\nforeach($rootNodeWiki-\u003egetChildNodes() as $node){\n    echo \"\u003cli\u003e\";\n    echo $node-\u003egetWikiPage()-\u003egetTitle();\n    \n    echo \"\u003cul class='second-level'\u003e\";\n    foreach($node-\u003egetChildNodes() as $nodeSecondLevel){\n        echo \"\u003cli\u003e\";\n        echo $nodeSecondLevel-\u003egetWikiPage()-\u003egetTitle();\n        echo \"\u003c/li\u003e\";\n    }   \n    echo \"\u003c/ul\u003e\";\n    \n    echo \"\u003c/li\u003e\";\n\n}\necho \"\u003c/ul\u003e\";\n```\n\nResult:\n\n```html\n\u003ch1\u003eTable of content:\u003c/h1\u003e\n\u003cul class=\"first-level\"\u003e\n    \u003cli\u003e\n        Instruments\n        \u003cul class=\"second-level\"\u003e\n            \u003cli\u003ePiano\u003c/li\u003e\n            \u003cli\u003eGuitar\u003c/li\u003e\n        \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n        Chordsheets\n    \u003c/li\u003e\n    \u003cli\u003e\n        Groups\n        \u003cul class=\"second-level\"\u003e\n            \u003cli\u003eWorship-Teams\u003c/li\u003e\n            \u003cli\u003eService-Teams\u003c/li\u003e\n        \u003c/ul\u003e\n    \u003c/li\u003e\n\u003c/ul\u003e\n```\n\n## Support / Contribute\n\nWe welcome your support and contributions to this project.\n\n### CTLog - Logging Request\n\nThe CTLog provides a facade to log Informations. By default it logs all important infos, warnings and errors in the\nlog-file: `churchtools-api.log`. The creation of a logfile can be enabled and disabled with the method:\n\n```php\nuse CTApi\\CTLog;\n\nCTLog::enableFileLog( false ); //disable logfile\nCTLog::enableFileLog(); // enable logfile\n```\n\nBy default, the console will display all logs of Error, Critical, Alert, and Emergency levels. If you wish to display\nadditional log levels on the console, you may use the CTConfig-Debug option or set it directly in the CTLog facade:\n\n```php\nCTConfig::enableDebug();\n\n//or use CTLog facade\n\nCTLog::setConsoleLogLevelDebug();\nCTLog::enableConsoleLog();\n```\n\nTo log a message, use the getLog-method:\n\n```php\nuse CTApi\\CTLog;\n\nCTLog::getLog()-\u003edebug(\"Hello World!\");\nCTLog::getLog()-\u003eerror(\"Error accourd here!\");\n```\n\nFurther information on [CTLog-Page](/docs/out/CTLog.md):\n\n### Error-Handling\n\nThe API-Wrapper provides custom exceptions. More on this page: [Error-Handling](/docs/out/ErrorHandling.md)\n\n### Unit- and Integration-Tests\n\nTo access the unit tests, navigate to the \"tests/unit\" directory. You may use the standard PHPUnit\\Framework\\TestCase to\ntest small sections of code, or use TestCaseHttpMocked to simulate an HTTP request.\n\nFor integration tests, requests are sent directly to a ChurchTools instance. The \"integration-test-data.json\" file\ncontains all available test data scenarios. All integration tests are automatically executed via Github Actions.\n\n### Doc-Generator\n\nThe Doc-Generator parses all documentation files and runs the PHP code examples to verify their validity. For additional\ninformation, please refer to this page: [Doc-Generator](/docs/Docs.md)\n\n## License\n\nThis project is licensed under MIT-License feel free to use it or to contribute.\n\n## Showcase:\n\nTo 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:\n\n**Administration Tools:**\n- **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.\n- **ChurchTools GroupMeetings** by [@a-schild](https://github.com/a-schild/churchtools-groupmeetings): Create ical feed from group meetings\n- **ChurchTools PDF Calendar** by [@a-schild](https://github.com/a-schild/churchtools-pdfcalendar): Generate PDF month calendars from churchtools\n- **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.\n\n**Wordpress Plugins:**\n\n- **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.\n- **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.\n\n**Other Applications:**\n- **FreeScout Module** by [@churcholution](https://github.com/churcholution/freescout-churchtoolsauth): Login to FreeScout with ChurchTools credentials and manage permissions based on group/role memberships.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5pm-hdh%2Fchurchtools-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F5pm-hdh%2Fchurchtools-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5pm-hdh%2Fchurchtools-api/lists"}