Laravel Integrations Laravel Package

Getting Started

Install the package with Composer, publish/run any package migrations, and review the provider contract or base provider class first. The core day-to-day object is an integration record that stores provider configuration, encrypted credentials, optional metadata, and health state.

A good first use case is connecting one external provider: create an integration, assign credentials through the package’s cast/Data class, perform a request through the provider, and let the package record request health. Version 6.5.1 is a bugfix release with no documented breaking changes; upgrade if you have integrations with credentialDataClass() or metadataDataClass() and have seen unnecessary writes or lock contention.

Implementation Patterns

• Define providers around the package’s provider contract/base class, and return Data classes from credentialDataClass() and metadataDataClass() when you want typed access to encrypted credentials and JSON metadata.
• Assign and read credentials through the model/cast rather than raw attributes. With 6.5.1, assigning equivalent credentials or reading them through a Data class should no longer mark the column dirty.
• Treat credentials as write-only secrets in application code: compare Data objects or decoded values, never ciphertext.
• Use metadata for provider-specific non-secret configuration. The updated cast compares decoded JSON and ignores whitespace/key-order differences introduced by JSON columns.
• Rely on the package’s request flow to call recordSuccess() and update health. Avoid manually rewriting integration rows after requests unless you have a specific health/state update to make.
• In tests, assert dirty state explicitly after reads and saves: isDirty('credentials') and isDirty('metadata') should be false when values are unchanged.
• During key rotation, expect credentials decryptable only by APP_PREVIOUS_KEYS to be treated as changed on the first save, then re-encrypted with the current APP_KEY. Subsequent saves should not rewrite them.

Gotchas and Tips

• Upgrade to 6.5.1 if you observed high write volume or lock wait timeouts on integration rows. Before this release, reading credentials/metadata through Data classes could make Eloquent consider those columns changed and rewrite them on every save, including after recordSuccess().
• Do not compare encrypted credential columns directly. Encryption is non-deterministic; the same plaintext produces different ciphertexts.
• Do not compare raw JSON column strings. MySQL and similar databases may reorder keys or change whitespace; the 6.5.1 cast normalizes this comparison.
• If you see an unexpected credential write after rotation, verify whether the row was encrypted with an APP_PREVIOUS_KEYS key. One rewrite is expected to move it under the current APP_KEY.
• Use query logging or model events when debugging unexpected updates. Check isDirty() after reading $integration->credentials or $integration->metadata to confirm the cast is behaving as expected.
• Keep provider Data classes stable and comparable. The cast can only suppress false changes when the decoded values are actually equivalent.
• The main extension points are the provider’s Data class hooks and the credential/metadata casts. If you customize casting or persistence, preserve the package’s decoded-value comparison behavior.