Calendar Bundle Laravel Package

Getting Started

• First, calibrate expectations. This is not a Laravel package. It is a Symfony bundle and a read-only subtree split of the Enhavo CMS monorepo. There is no service provider, no facade, no config/calendar.php, and no package discovery. composer require enhavo/calendar-bundle inside a Laravel app gives you nothing to call.
• Decide which of two realities you are in before writing code:
  1. You are not on Enhavo → do not install. Treat this repo as a design reference and source of truth for how an event/calendar domain is modeled, nothing more.
  2. You are deliberately running Enhavo (Symfony) behind or alongside Laravel → install as part of the full CMS (composer require enhavo/enhavo and enable the bundle via the main CMS config), not standalone.
• Where to look first. Not this repo — go to enhavo/enhavo. On the split, read, in order: DependencyInjection/ (services and config tree), Resources/config/ (routes, Doctrine mappings, admin metadata), Model/ or Entity/ (the actual event data model), Form/, Controller/, and Resources/views/. That is the fastest way to learn the real API surface, because there is no standalone documentation.
• A sensible first use case is one of:
  • Inside Enhavo: expose the bundle's calendar/event model through an Enhavo admin resource so editors can create, edit, and list date-bound content, then render upcoming events on the front end.
  • From Laravel: stand up a minimal Enhavo sandbox, create a handful of events in the admin, and expose them over a JSON endpoint that your Laravel app consumes via Http::get(). This is the realistic "day-to-day" pattern for a Laravel developer and the only integration path that does not require rewriting the bundle.
• Budget for source reading, not docs. The README is a stub. Expect to spend days, not hours, mapping the model, config keys, and admin wiring before you can confidently integrate.

Implementation Patterns

• Headless CMS pattern (recommended for Laravel). Run Enhavo as a separate Symfony service. Expose calendar events through a small read-only controller or API endpoint in that service, then consume it from Laravel behind a repository or client class:

  // app/Services/Calendar/EnhavoCalendarClient.php
  class EnhavoCalendarClient
  {
      public function upcoming(): Collection
      {
          return Http::baseUrl(config('services.enhavo.url'))
              ->retry(2, 200)
              ->get('/api/events/upcoming')
              ->throw()
              ->collect('data');
      }
  }
  

  Wrap the HTTP call in Cache::remember() keyed on date range so public calendar pages do not hammer the CMS. Bind the client as a singleton in a service provider; this is the only "Laravel integration" that actually exists.
• Domain-model mirroring. If you decide to reimplement events natively in Laravel, copy the bundle's field naming and semantics to keep future migration open. Read Model/ first, then create an Eloquent model with matching column names (startDate, endDate, title, text, and whatever recurrence fields the bundle defines). Keep the mapping in a doc comment so a future move to Enhavo is a schema rename, not a redesign.
• Native Laravel path for the calendar UI. For anything front-end-facing, do not try to surface Enhavo's admin UI. Model events in Eloquent, expose them via a JSON endpoint, and render with FullCalendar or similar on the client. The bundle is an admin-side content manager, not a presentation layer.
• Event-driven side effects in Laravel. If events drive notifications or sync (reminders, external calendar push), use Laravel's scheduler plus queued jobs against your mirrored model. Do not attempt to reuse the bundle's Doctrine lifecycle subscribers from Laravel — they depend on an ORM and container that do not exist in your app.
• If you are genuinely inside Enhavo (Symfony). Use the Enhavo resource/admin pattern: define the resource metadata, form type, and routing, and let the admin UI handle CRUD. Customize presentation by overriding templates under templates/bundles/EnhavoCalendarBundle/. Change behavior by decorating services or overriding definitions — never by editing vendor files.
• Version pinning as a pattern. Whatever you do, pin the exact commit or tag you integrated against, record it in your deployment notes, and diff the split against the upstream tag before any upgrade. Subtree splits can lag; assume they do.

Gotchas and Tips

• The read-only split is not a support channel. Issues, PRs, and releases live in enhavo/enhavo. If you file a bug against this repo, nothing happens. Any patch you need must go upstream, or live in a private fork you maintain and rebase against the monorepo.
• Transitive weight is enormous. Composer resolves the full Enhavo CMS, not a thin calendar library. This inflates your dependency graph, attack surface, and upgrade blast radius for what is nominally one feature. Audit composer why before committing.
• Security advisories may not surface. Advisories are typically filed against the monorepo package name. If your scanner only watches enhavo/calendar-bundle, you can miss CVEs in the transitive CMS. Add the main package to your scan list explicitly.
• No documented semver policy on the split. The published version can lag or diverge from upstream tags. Before every upgrade, verify the split commit matches the upstream tag you intend to run.
• No Laravel integration seam at all. No service provider, no facade, no config publish, no Artisan commands, no middleware. Any plan that assumes config('calendar.*') or Calendar::events() is wrong. The only Laravel-side seam is HTTP.
• Recurrence and timezone handling are unverified. The description mentions "flexible data structures" but there are zero tests, zero docs, and zero dependents to corroborate. If you need recurrence, iCal/CalDAV interop, or multi-timezone correctness, benchmark the bundle's behavior in a sandbox before betting on it — or use a purpose-built library (eluceo/ical, sabre/vobject, rlanvin/php-rrule) instead.
• Config quirks. Configuration is a Symfony config tree defined in DependencyInjection/Configuration.php, not a Laravel config file. If you are integrating against the Enhavo service, read that file to see every knob — there may be none you need, and there may be required ones you would otherwise miss.
• Debugging. Inside Enhavo, use the Symfony profiler and bin/console debug:container / debug:router to discover what the bundle actually registers. Across the HTTP boundary, log request/response payloads and enable Http::retry() with backoff; the Enhavo service is a single point of failure for every calendar page in Laravel, so surface its errors distinctly rather than swallowing them into empty collections.
• Extension points that actually exist. Template overrides (templates/bundles/EnhavoCalendarBundle/), service decoration, and Doctrine entity extension (mapped subclass or additional fields on your own entity). There is no event/hook API for Laravel-style extension, and no plugin contract exposed on the split.
• If you adopt it, name an owner. Single-digit stars, zero dependents, and single-vendor stewardship mean the operational risk sits entirely with the Enhavo maintainers. Assign one engineer to track upstream activity and release cadence, write a private-fork policy, and define the trigger that would force you off the dependency.