Eventonomy

Developer Guide

The Developer Guide is the technical reference for extending, embedding, and integrating Eventonomy. Every page is written for developers, so if you are configuring events from wp-admin, start with the Getting Started and Admin Settings sections instead.

Authoritative source files: docs/ARCHITECTURE.md, docs/REST-API.md, docs/EXTENDING.md. This guide distills them and cross-references them. When anything here conflicts with those files, the source files win.

This guide has two tracks: Reference (comprehensive API surfaces) and How-to recipes (short, focused examples for common tasks). Start with Reference to understand the system, then use Recipes when you are ready to build.

Track 1: Reference

Deep documentation of every stable extension surface.

Understand the System

Get a clear picture of how Eventonomy is built before you start extending it.

  • Architecture - the seven layers, auto-discovery backbone, data model, and Free/Pro seam.

Extend

Add behavior to the event lifecycle, query system, or REST responses.

  • Hooks & Filters - every evnm_* action and filter, with the arguments each one passes.
  • Extending (Free↔Pro contract) - how to bind contracts, implement interfaces, add a payment gateway, create a notification channel, and work with the Meta API.

Embed

Surface event content on any page, post, sidebar, or page-builder canvas.

  • Blocks & Templates - the nine Free blocks, nine Pro blocks, shortcodes, the shared Interactivity store, and template overrides.

Integrate

Read and write event data from another application, cron job, or headless frontend.

  • REST API Reference - the full eventonomy/v1 endpoint listing with methods, payloads, responses, and permission contracts.
  • Mobile API Contract - what a companion mobile app reads: the app bootstrap block, the viewer-relative event fields, the registration contract, Application Passwords, the ban gate on writes, and what the plugin does not own (CORS, transport, packaging).
  • Calendar Sync Internals (Pro) - the evnm_pro_feeds table, the feed repository and runner, the sync scheduler, the member and admin feed routes, and how to register your own import source.
  • Database Schema - all 15 tables (10 Free, 5 Pro), their columns, the index strategy behind them, and the migration rules.
  • Capabilities & Permissions - the seven capabilities, what they map to, how ownership is resolved, and the REST permission-callback contract.
  • Abilities API - the WordPress 7.0 ability registry, what Eventonomy exposes today (nothing yet), and how to register your own safely.
  • The timezone rule - which zone a date renders in and why: event zone answers "when is this event?", site zone answers "which group is this row in?", and the abbreviation appears only when they differ. Use evnm_event_card_dates().

Operations

Drive and test Eventonomy from the command line.

  • WP-CLI Commands - the full wp eventonomy command surface plus the qa-actions smoke suite.

Track 2: How-to Recipes

Short, task-oriented recipes. Each recipe names the goal, the exact hook or contract, a minimal working snippet, and a "verify it worked" step.