Filament Crm Sync Laravel Package

Technical Evaluation

Architecture fit

• The package is a Filament plugin wrapping a driver-based CRM sync layer: mapping is declared in code (a SyncsToCrm trait on the Eloquent model, or CrmSync::map() in a service provider), and transport sits behind a driver contract with HubSpot as the first implementation. That is the right shape for a Laravel/Filament codebase — no config UI to maintain, mapping lives in version control, and the driver boundary gives a credible path to Pipedrive/Salesforce later.
• It composes with existing conventions rather than replacing them: queued jobs for bulk, model events for sync-on-save, Filament actions and columns for the operator surface. Low conceptual overhead for a team already on Filament.
• Scope is deliberately one-directional (local → HubSpot). There is no inbound sync, no deletion/archive propagation, and no conflict resolution described. Teams expecting a two-way CRM integration will be disappointed; teams that treat HubSpot as a downstream lead destination will not.

Integration feasibility

• Install is genuinely small: composer require, php artisan migrate, register the plugin on the panel, set CRM_SYNC_HUBSPOT_TOKEN. No external service, no sidecar, no OAuth dance — a HubSpot private-app token is the only credential.
• Field mapping supporting attributes, dot paths and closures covers the realistic cases (relations, computed values, formatting).
• Dedup design is sound in principle: persisted HubSpot ID per record, email-based upsert for contacts, property-based match for companies/deals, and skip-if-unchanged to conserve quota.

Technical risk

• Primary risk: zero live-account validation. The release explicitly states it has never run against a real HubSpot account. All evidence is fixtures, a locally written mock (hubspot-mock.php with shapes taken from HubSpot's API reference), and browser checks against that mock. This validates the package's own logic and UI, not HubSpot's actual behaviour: scope enforcement, property validation, picklist/required-field errors, association API semantics, batch limits, and real 429/Retry-After timing are all unproven.
• Quota and rate-limit exposure. HubSpot enforces per-app and per-account limits and tier-based daily caps. The package rate-limits jobs and backs off on 429, but the actual request budget per record (one call per record? associations as extra calls? batch endpoints?) is not stated, so capacity planning is guesswork until measured.
• Idempotency under retry. If a create succeeds at HubSpot but the job fails before persisting the returned ID, a retry may duplicate a company or deal (contacts are protected by email upsert; companies/deals matched on a chosen property are only as safe as that property's uniqueness).
• Single-maintainer, independent project at v1.0.0. No support SLA, no deprecation policy, PHPStan at level 5 rather than max, and 54 package-level tests. Reasonable for a v1, but it is a dependency you may end up owning.
• Data governance. Contact and deal data (PII) egresses to a third party. Token handling is described as never logged or shown, and errors masked — good — but masked errors also impede diagnosis, so server-side logging behaviour needs verification.
• Key questions to put to the maintainer/vendor:
  1. Which HubSpot API version is pinned, and what is the upgrade policy when HubSpot deprecates it?
  2. Exact private-app scopes required, and behaviour when a scope is missing?
  3. Per-record API call count, and whether batch endpoints are used for bulk and backfill?
  4. What invalidates "unchanged" — a hash of mapped output? Does it account for relation changes?
  5. Behaviour when a HubSpot record is deleted or merged, or the contact's email changes locally?
  6. Is sync-on-save always queued, or can it block the request?
  7. Multi-portal/multi-tenant support, and per-tenant token storage?
  8. Handling of soft-deleted local models, mass updates, and withoutEvents() writes?

Integration Approach

Stack fit

• Supported matrix is PHP 8.2–8.5 × Laravel 12/13 × Filament 4/5 — a current, forward-looking baseline. Teams still on Laravel 10/11 or Filament 3 are excluded; that is a deliberate floor, not an oversight, but it should be checked against your fleet before committing.
• Requires a working queue with retry/backoff semantics; a Redis/Horizon setup is the natural fit given the rate-limit and observability needs.

Migration path

• Add the package, run the migration, then confirm the schema it creates (sync-state table and/or HubSpot ID column) against your data-retention and backup conventions before applying to production.
• Treat existing records as a backfill project: enable the trait or mapping, but do not let sync on save fire retroactively. Write a chunked backfill that enqueues pre-existing records in controlled batches.
• Roll out behind a feature flag per model class so mapping mistakes cannot cascade across all entities at once.

Compatibility

• Verify the plugin registration call against both Filament 4 and 5 in your own panel provider — the release verifies both, but panel-provider APIs are the most common source of Filament major-version friction.
• Filament upgrades are the recurring compatibility cost; pin the package minor version and re-run your pilot checks on each Filament major.

Sequencing

1. Create a dedicated HubSpot sandbox portal and a least-privilege private app; record the scopes used.
2. Map one low-risk model first — companies — and validate upsert, dedup and skip-if-unchanged against the live API.
3. Add contacts with the contact→company association; confirm ordering (related record synced first) behaves under partial failure.
4. Add deals with deal→contact; confirm match-property uniqueness holds in your data.
5. Enable the manual row/page action for a pilot team; keep bulk queued.
6. Run the backfill in throttled chunks, watching 429 behaviour and quota consumption.
7. Enable sync-on-save last, and only for models where write-path latency is acceptable.
8. Hand over with a runbook covering token rotation, mapping changes, and stuck-job recovery.

Operational Impact

Maintenance

• Low code footprint but a real ongoing obligation: track HubSpot API changelog and deprecations, re-validate on each Filament major, and be prepared to fork or replace the driver if the project stalls. Budget a small recurring allowance rather than a one-off integration cost.

Support

• The in-panel surface is a genuine support asset: connection test, mapping check, sync log, retry, and per-record status column turn most "it didn't sync" tickets into self-service.
• Masked errors are correct for UI but will send engineers to server logs; make sure job failure logging captures the HubSpot response body (with token redacted) or triage will be painful.

Scaling

• Throughput is bounded by HubSpot quotas and worker concurrency, not by the package. Backfills and bulk actions must be chunked; association syncing can multiply call volume (a page of 50 contacts each needing a company association is not 50 calls).
• Sync-on-save puts CRM availability in the path of ordinary writes unless it is queued — verify and, if necessary, disable it for high-traffic models.

Failure modes to plan for

• Token expired/revoked or private app deleted → all syncs fail silently from the user's perspective; the connection test is the detector, so surface it in monitoring, not just the admin page.
• Missing or newly required HubSpot property values → per-record validation failures; expect mapping drift as the HubSpot portal evolves.
• 429 storms during backfill → jobs back off correctly in theory, but live Retry-After behaviour is unverified; cap concurrency conservatively at first.
• Partial success on create-then-crash → duplicate companies/deals; enforce a genuinely unique match property and reconcile manually during the pilot.
• Email change or HubSpot-side merge → duplicate contacts or stale stored IDs; needs a periodic reconciliation pass you will have to build.
• Local deletes leave orphans in HubSpot; no propagation is described, so decide whether that matters for your data policy.

Ramp-up

• For a Filament-fluent developer: roughly half a day to map and validate a first model in a sandbox. The real lead time is non-technical — obtaining a HubSpot private-app token and agreeing scopes with whoever owns the HubSpot account, plus a data-protection review for PII egress.
• Operations needs a short runbook (token rotation, queue failure triage, backfill procedure); without it, the first 429 incident will consume a support cycle.

Recommendation

• Treat v1.0.0 as feature-complete but not production-proven against HubSpot. Run a time-boxed pilot against a live sandbox portal on a single low-risk model with a unique match property before enabling bulk or sync-on-save. If the pilot surfaces association or rate-limit issues, you will have found them at low cost; if it passes, the package is a reasonable, well-shaped fit for a Filament-based Laravel stack, with the caveat that you are adopting an independently maintained dependency and should pin versions and retain the option to fork the driver.