Laravel Sabre Laravel Package

Getting Started

• Upgrading from 1.x: read MIGRATION.md before touching composer. Bump to ^2.0, then grep the codebase for the three removed symbols: LaravelSabre::getNodes(), LaravelSabre::getPlugins(), and LaravelSabre\Exception\InvalidStateException. Any test, debug command, or health check that introspected the node tree or plugin stack through the static getters will fatal — replace it with the patterns in the migration guide (typically asserting against a real DAV request instead of the internals).
• Fresh install: composer require monicahq/laravel-sabre, publish the config (config/laravelsabre.php) for the DAV path, storage location and default plugin list. Then register your node tree and authentication callback in a service provider — this is the whole integration surface for most apps.
• First use case: stand up a read-only DAV endpoint for a single collection. Point a client (macOS Finder "Connect to Server", Cyberduck, or curl -X PROPFIND) at /dav and confirm a 207 Multi-Status. Getting a 401 first is normal and actually the fastest way to prove your auth callback is wired.
• Don't type-hint the internals. LaravelSabre\Sabre\Server and LaravelSabre\Sabre\Sapi are now internal. If you injected, subclassed, or mocked them, that's unsupported in 2.x — build against the public facade/config and the HTTP contract instead.

Implementation Patterns

• Node tree per principal. The common shape is a root collection → per-user principal → calendar/addressbook home → collections, with the principal resolved from the authenticated Laravel user. Cache the tree construction per request, not per application boot; nodes are frequently user-scoped and must not leak between requests (especially under Octane).
• Auth via Laravel guards. Resolve the DAV principal inside your auth callback using Auth::guard(...)->user(), returning the principal URI (e.g. principals/users/{id}). Remember DAV clients send HTTP Basic credentials on every request — they are not session-based, so guard/session middleware won't help you here.
• Plugins before behaviour. Order matters: the auth plugin must be registered before anything that resolves principals, and ACL/browser plugins after. Keep a dev-only browser plugin (Sabre\DAV\Browser\Plugin) behind an environment check so you can explore the tree in a browser without shipping it.
• New in 2.0 — test through the router. Because the adapter now runs on a framework-native request pipeline, integration tests no longer need to fake a SAPI. Use Laravel's HTTP test helpers with a real DAV verb (PROPFIND, REPORT, PUT) and a Basic auth header, and assert on status codes and XML bodies. This is the intended replacement for the deleted getNodes()/getPlugins() assertions.
• Middleware is now the extension point. Route-level middleware (tenant resolution, rate limiting, request logging) applies to DAV traffic the way it does to any other route. Prefer middleware or a decorator over patching the adapter when you need cross-cutting behaviour.
• Backends: filesystem backends are fine for prototypes and local dev; for anything with concurrency, use a PDO/DB backend so PUT/DELETE semantics and locking survive multiple workers.

Gotchas and Tips

• InvalidStateException is gone. Code that caught it to detect "server not configured yet" needs a different signal; treat misconfiguration as a boot-time failure rather than a runtime catch.
• Exclude the DAV route from CSRF and session middleware. DAV verbs arrive without tokens; a stock web middleware group will silently break clients with 419s. Use a dedicated route group.
• Base URI and trailing slashes. The configured path becomes the Sabre base URI; mismatches (trailing slash, generated absolute URLs behind a proxy) produce principals whose hrefs don't resolve, and clients fail in confusing ways. Set trusted proxies so hrefs are scheme/host-correct.
• Content-Type drives parsing. PROPFIND/REPORT with a body but no application/xml content type often yields an empty multistatus rather than an error — a classic "it works in Cyberduck, not in my client" cause.
• Storage permissions and dotfiles. Filesystem backends fail with 500s (not 403s) when storage/ isn't writable by the web user; also check that your .gitignore/deploy excludes the DAV data directory from asset syncs.
• Octane/queue workers: never hold node or plugin instances in singletons — rebuild per request, and verify state doesn't bleed across requests in a long-lived worker.
• Debugging: the browser plugin plus curl -u user:pass -X PROPFIND -H 'Content-Type: application/xml' --data @body.xml will diagnose most issues faster than logs; enable Sabre's own debug output only in local environments since it echoes request bodies.
• Extension points that survived: custom node classes, custom plugins, custom backends, and your auth callback. Anything reaching into Sabre\Server/Sapi did not survive — reimplement those hooks as middleware or plugins.