Ldaprecord Laravel Package

Product Decisions This Supports

Build vs. buy for directory integration. LdapRecord turns Active Directory and OpenLDAP into something that looks and feels like Eloquent: models, attribute casts, relationships, a fluent query builder, pagination. For a Laravel product where the directory is already the source of truth for employees, that makes "build on an MIT library" a credible alternative to a commercial IAM contract or hand-rolled ldap_* wrappers in a service class. The decision it unblocks is concrete: identity stays in our codebase, with no per-seat licensing and no vendor-owned schema.

Whether self-service password management ships this quarter. v4.1.0 adds OpenLDAP Argon2 support and a first-class User::changePassword() method. That converts "let users reset their own directory password" from an open-ended spike into a scoped backlog item with a known API. The adjacent allow_insecure_password_changes config and TLS state tracking (v3.6.x) mean the security trade-off becomes an explicit, documented product decision rather than an implementation accident.

Whether automated directory writes are safe to enable. The v4.1.1 release is effectively a readiness gate for joiner/mover/leaver automation: password arguments are now redacted from exception traces (evidence for a "no secrets in logs" control), and detaching a relationship no longer deletes a populated group. Paired with the fix that preserves pending changes when removing attributes, we can approve automated mutations and state our compensating controls in design review instead of parking the feature behind manual ops indefinitely.

Architecture fork: permissions as directory queries vs. a mirrored copy in SQL. whereMemberOf, OU traversal, global scopes, and correct relationship model matching let us express authorization as a live directory query rather than building and reconciling a shadow org chart. The v4.1.1 fix that includes search bases and controls in query cache keys is what makes that choice defensible — a stale cache key returning the wrong group is a security defect, not a performance nit.

Legacy modernization sequencing. Base-DN {base} substitution now works during create and rename (insertAndGetDn, renameAndGetDn), attributes re-synchronize after immediate replacement, refresh() returns false for missing entries instead of throwing, and morphIntoOrFail() handles subclass conversions. Collectively these make porting legacy directory scripts into the Laravel app a tractable backlog item — which is the input to "can we retire the legacy tooling this fiscal year, or do we budget a rewrite?"

Platform currency and upgrade sequencing. Laravel 11/12/13 support landed on both the v3 and v4 branches, with a documented upgrade guide for the v4 migration. That means "stay on a current Laravel LTS" is not blocked by our LDAP layer, and the v4 migration can be scheduled independently of the framework upgrade.

Delivery risk reduction through testability. DirectoryFake, authentication events, logging hooks, and the Ldap::DEBUG_* constants let us exercise auth and provisioning flows in CI without a live domain controller. That shortens the spec-to-shipped loop on every identity feature and removes a standing infra dependency from QA.

Feature bets gated on this one adoption decision: employee portal login against AD, group-driven role assignment, joiner/mover/leaver provisioning across OUs, compliance reporting over lastLoginTime / accountStatus, and self-service profile and password changes.

When to Consider This Package

Adopt when most of these hold:

• The product is PHP/Laravel, and LDAP or Active Directory is already — or is slated to become — the source of truth for authentication or employee identity.
• You need read and write directory operations: provisioning, group membership, attribute updates, password changes. Not just a yes/no bind check.
• Your team already reasons in Eloquent. The ActiveRecord models, casts, and fluent builder eliminate a large amount of bespoke attribute-mapping code.
• You want the directory layer unit-testable in CI (DirectoryFake) and observable in production (events, logging, debug constants).
• MIT licensing and self-hosting are acceptable, and you are willing to own LDAP schema, base-DN, and connection configuration in-house.
• You are on a supported Laravel/PHP version — v4 tracks current Laravel releases, and v3 remains patched if you need a longer runway.

Look elsewhere when any of these hold:

• You need federation, not directory binding. SAML, OIDC, SCIM, MFA orchestration, consent, and app catalogues belong to an IdP (Entra ID, Okta, Keycloak). LdapRecord authenticates against a directory; it does not replace an identity provider.
• You need governance features. Access reviews, attestation campaigns, SoD policy, approval workflows, and audit-grade reporting are out of scope — you would build them on top, and should budget for that explicitly.
• You need a vendor SLA. This is a community-maintained, largely single-maintainer library at ~581 stars. That is fine for a well-understood integration with a competent team, but it is a supply-chain risk worth naming in the risk register — pin versions, keep the upgrade guide in your runbook, and be prepared to fork.
• The directory is not your identity source of truth. If HR or an IdP is authoritative and LDAP is just a downstream replica, writing to LDAP from the app is the wrong layer.
• Your workload is bulk directory sync at high volume. Paging and chunking are solid (and got materially better in v4.1.1), but scheduled full-population syncs at six-figure entry counts are usually better served by dedicated sync tooling with the ORM used for reads and targeted writes.
• The stack is not PHP. The core is plain PHP and usable outside Laravel, but the auth integration, fakes, and events — the parts that make it cheap — are Laravel-shaped.

How to Pitch It (Stakeholders)

For executives: We have a recurring, expensive dependency on directory integration — every identity feature (login, roles from groups, onboarding/offboarding, password reset, access reporting) currently requires bespoke LDAP plumbing or a commercial IAM line item. LdapRecord is a mature, MIT-licensed Laravel package that provides that layer as a first-class ORM. It removes per-seat licensing from the identity roadmap, lets us keep identity logic in our own codebase, and — because it is testable without a live domain controller — shortens delivery on every one of those features. The ask is an adoption decision, not a large build.

For engineering: This is the Laravel-native way to talk to AD and OpenLDAP. Models and a fluent query builder instead of hand-written filters; attribute casts; multiple connections, SSL/TLS, and failover; built-in user resolution and authentication guards; relationships including group membership. It is testable in CI via DirectoryFake, observable via auth events and logging, and debuggable via the Ldap::DEBUG_* constants. The current release (v4.1.1) closed the specific defects that would otherwise make automated writes and cached permission queries risky — credential redaction in traces, safe relationship detachment, correct cache keys, and reliable paging/chunking behavior. It supports Laravel 11–13 on both v3 and v4 branches, with a documented upgrade path.

What we are explicitly not buying: an IdP. No SAML/OIDC federation, no MFA orchestration, no access-review or attestation tooling. We should position this as the directory-access layer beneath our identity strategy, and make the "no vendor SLA, single-maintainer library" risk visible alongside the cost avoidance — pinned versions, upgrade discipline, and a documented fork path.