Install
This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.
Install straight from GitHub with WP-CLI:
wp plugin install https://github.com/sw-wordpress/sw-cloudcalendar/archive/refs/heads/master.zipShows appointments from Google Calendar, Microsoft 365 and ICS feeds on your WordPress site, read-only. Events are copied to your site in the background and displayed as a list, cards or a month grid via shortcode or block.
Features
- Three calendar sources — Google Calendar, Microsoft 365 (Exchange Online) and any ICS feed.
- Background synchronisation — Page views never contact the calendar providers.
- Your own layout — Visual and HTML template editor with presets and live preview.
- Visibility per calendar — Public, logged-in users or selected roles; protected calendars never end up in cached pages.
- Protected attachments — Optionally stored locally and delivered only by WordPress after an access check.
Languages
English, German.
Usage
- Open Calendar → Connections, click Add connection and choose ICS, Google or Microsoft 365. For Google and Microsoft 365 click Authorise after saving (provider setup).
- Open Calendar → Sources, click Create source, choose the calendar and Visibility, then Create as draft.
- Edit the source, set Status to Active and save. The first synchronisation runs in the background.
- Open Calendar → Views, click Create view, pick sources and Display mode, then Copy shortcode
(e.g.
[sw_calendar id="12"]) or add the block Calendar (SW CloudCalendar). More examples: docs/setup.md.
Configuration
Requirements
PHP 8.2+ with sodium, mbstring, JSON and XML (fileinfo recommended, GD or Imagick for image previews), WordPress 6.5+, MySQL 8.0+ or MariaDB 10.6+ (InnoDB), single site or multisite.
Settings
Global options (HTML cache, default time zone, API rate limit, cron mode, storage quota, logging, data removal) are under Calendar → Settings; health checks under Calendar → Diagnostics.
Recommended wp-config.php constants (details: docs/setup.md):
// Key for stored credentials. Default: derived from the WordPress salts (warning in Diagnostics).
define( 'SW_CALENDAR_ENCRYPTION_KEY', '…' );
// Previous key during key rotation. Default: none.
define( 'SW_CALENDAR_ENCRYPTION_KEY_PREVIOUS', '…' );
// Attachment storage OUTSIDE the web root. Default: random folder below uploads/,
// used only if it is proven not to be publicly reachable; otherwise attachment sync stays blocked.
define( 'SW_CALENDAR_PRIVATE_STORAGE_PATH', '/var/lib/wordpress-private/sw-cloudcalendar' );
// Maximum synchronisation window in days per direction. Default: 1095.
define( 'SW_CALENDAR_MAX_WINDOW_DAYS', 1095 );
SW_CALENDAR_AUTOLOADER and SW_CALENDAR_TEST_SAVEPOINTS are for the test environment only.
Background tasks
Every 5 minutes WP-Cron checks which sources are due (default: every 6 hours per source); a daily job cleans up
logs and files. On sites with little traffic or with DISABLE_WP_CRON, set Cron mode to
System cron (WP-CLI) and add * * * * * cd /path/to/wordpress && wp sw-cloudcalendar queue run.
All WP-CLI commands: docs/setup.md.
Integrations
- Google Calendar — OAuth or API key; Drive files as attachments.
- Microsoft 365 — Delegated OAuth with your own Entra ID app registration.
- ICS feeds — Any iCalendar URL, optionally with an Authorization header.
Deactivation and removal
Deactivating keeps all data and only stops the scheduled tasks. Deleting the plugin also keeps everything unless
Delete all data on uninstall is enabled under Calendar → Settings; then all tables, options, the plugin's
own folder below uploads/ and Google tokens (revoked) are removed. A folder set via
SW_CALENDAR_PRIVATE_STORAGE_PATH is never deleted. On multisite, removal only covers the main site.
Troubleshooting
| Problem | Solution |
|---|---|
| Events are not updated. | With DISABLE_WP_CRON, switch to System cron (WP-CLI) and set up the cron job; see Calendar → Diagnostics. |
| Attachments are not synchronised. | The fallback folder below uploads/ is publicly reachable (often Nginx). Set SW_CALENDAR_PRIVATE_STORAGE_PATH. |
| Google asks to Re-authorise every 7 days. | The Google app is in "Testing" mode; publish it or use "Internal" with Google Workspace. |
| A protected calendar only shows "Loading calendar…". | Protected views are loaded with JavaScript; make sure scripts are not blocked. |
Built with AI
This plugin was implemented with AI assistance. Why it exists and how AI is used: sw-wordpress manifest.
AI agents must follow the project rules before changing code:
- Rules and mandatory coverage: AGENTS.md, docs/CODE-STYLE.md
- Plan and specification: PLAN.md, docs/SPECIFICATIONS.md, docs/CALENDAR_PLUGIN_CONCEPT.md
- Decisions and open points: docs/decisions.md, further docs in docs/
- README structure: README-STANDARD.md
Local plugin sources
Other WordPress plugins can provide calendars directly without copying events. Registration API, schema, permissions and examples: Local sources. ChurchTools Suite supplies its adapter externally.
Development
Requirements: PHP 8.2+, Composer, Node.js 22.22.2+ (Node 22 line) with npm, Make, MariaDB (test database), GNU gettext (translations) and Docker for the release build.
composer install
make build # admin SPA (apps/admin) -> assets/admin/
bin/test-db.sh start # private MariaDB on 127.0.0.1:33078
(cd tests/wp && composer install) # WordPress test environment
composer check # cs, cs:wp, PHPStan and PHPUnit (unit + integration)
composer test:wp # WordPress integration tests
composer test:performance # 2000 events/month; JSON report (tests/Performance)
bin/i18n.sh check # translations complete and up to date
(cd apps/admin && npm run typecheck && npm run lint && npm test)
bin/build-zip.sh # release ZIP in dist/
Every change needs tests; line coverage must stay above 80 % for PHP and JavaScript/TypeScript. Details: docs/development.md, docs/testing.md (incl. browser tests), docs/sonarqube.md. GitHub Actions run all checks on every push.
License
GPL-2.0-or-later — see LICENSE. Provided by Stefan Warnat.
Bundled third-party components (license texts in the linked repositories; the release package does not include copies):
- PHP, isolated in
vendor-prefixed/of the release build:- sabre/vobject — BSD-3-Clause
- sabre/xml — BSD-3-Clause
- sabre/uri — BSD-3-Clause
- JavaScript, bundled in
assets/admin/:- Vue — MIT
- Vue Router — MIT
- Pinia — MIT
- Vue I18n (incl. @intlify packages) — MIT
- Quasar — MIT
- CodeMirror 6 (incl. @lezer, style-mod, w3c-keyname, crelt, find-cluster-break) — MIT
- Fonts, bundled in
assets/admin/assets/:- Inter — OFL-1.1
- JetBrains Mono — OFL-1.1
- Material Icons Round (via @quasar/extras) — Apache-2.0