Ibexa Imagemap Bundle Laravel Package

Getting Started

• Install with composer require <vendor>/<package>:^2.0 and confirm your app meets the new major-version requirements (PHP, Laravel, and Ibexa 5.0+). v2.0.0 explicitly adds Ibexa 5.0+ support, so validate your Ibexa instance version before upgrading.
• Look first at the package's service provider, config file, and README upgrade notes. Publish the config (php artisan vendor:publish) and set connection values (Ibexa host, repository/user, siteaccess, credentials) in .env rather than committing them.
• In Laravel 10/11 the provider is usually auto-discovered; if not, register it in bootstrap/providers.php or config/app.php.
• First use case: fetch a single content item by ID or location ID and render its fields in a Blade view or a small JSON route. This validates auth, siteaccess resolution, and field mapping in one pass. Use php artisan tinker or a temporary route to confirm connectivity before building features.

Implementation Patterns

• Wrap the package client in your own repository/service class and bind it in the container. Inject that abstraction into controllers and jobs instead of calling package facades directly; this keeps upgrade surface small when the package changes.
• Use a read-through cache for content lookups, keyed by content ID + language + version. Ibexa content is versioned and multilingual, so a naive cache key will serve stale or wrong-language data.
• For writes (create/update/publish), dispatch queued jobs rather than doing remote calls in the request cycle. Ibexa operations can be slow and may fail transiently; jobs give you retries and backoff.
• Map Ibexa content types to local Eloquent models or DTOs at the boundary. Don't leak package response objects into Blade views or API resources; normalize them early.
• Sync content via scheduled commands (php artisan schedule:run) or event listeners where the package exposes them. Keep an idempotent upsert path so re-runs are safe.
• Testing: fake the client/service in unit tests, and keep a small contract/integration suite that runs against a disposable Ibexa container or fixture responses. Assert field mapping and error handling, not just happy-path calls.
• For API endpoints, add a thin caching + pagination layer; Ibexa location queries can return large result sets, so constrain limits and use cursor-style pagination where supported.

Gotchas and Tips

• v2.0.0 is a major release. Even though the notes only advertise Ibexa 5.0+ support, treat it as potentially breaking: review the changelog/upgrade guide, diff config keys, and check minimum PHP/Laravel versions before merging. Pin ^2.0 and test the upgrade in a branch.
• Compatibility is now gated on Ibexa 5.0+. If you still run an older Ibexa version, stay on the v1 line or verify backward compatibility yourself; don't assume the new major works against older installations.
• Auth and siteaccess errors often surface as generic 401/403 or empty results. Log the resolved endpoint, siteaccess, and user context on failure; most "missing content" bugs are siteaccess or permission mismatches.
• Watch cache invalidation across languages and content versions. A publish in one language can leave other language caches stale; invalidate by content ID family, not by single cache key.
• Remote calls in request handlers are a common performance trap. Add timeouts, retries with backoff, and circuit-breaker-style fallbacks so an Ibexa outage doesn't take down your Laravel app.
• Extension points to prefer: container bindings for the client, custom service providers for decorators, package events/listeners for side effects, and macros/query scopes if offered. Avoid editing vendor code; fork or decorate instead.
• Debugging tip: capture the raw package response (redacting credentials) in a log channel during development. Field-mapping issues are much easier to diagnose from the payload than from a rendered view.
• Keep the package's config under version control with safe defaults and override secrets via env. Document the Ibexa version your app targets so future major upgrades are predictable.