Pumukit Ldap Bundle Laravel Package

Getting Started

The package is small and Pumukit-specific, so treat it as an integration layer rather than a standalone LDAP library. Your first job is confirming compatibility, not learning an API.

Minimal steps:

1. Verify the Pumukit version. This bundle is tightly coupled to the Pumukit core (User entity, security firewall conventions, config tree). Open composer.json and read the require / provide sections — match them against your pumukit/pumukit version before touching anything else.
2. Install via Composer: composer require teltek/pumukit-ldap-bundle.
3. Register the bundle in app/AppKernel.php (or config/bundles.php on newer Symfony) — it must load after the Pumukit core bundles so its compiler passes and service decorators can hook in.
4. Enable the PHP LDAP extension in every environment (web + CLI workers). php -m | grep ldap should return ldap. There is no pure-PHP fallback in this bundle.
5. Look first at DependencyInjection/Configuration.php in the vendor tree. That file is the authoritative list of config keys — the README is thin and frequently behind the code. Read the config tree before writing any YAML.
6. Look second at the security integration. Find the user provider / authenticator service definition in Resources/config/services.xml. That tells you exactly which firewall key it expects to be wired into.

First concrete use case — authenticate against LDAP while keeping Pumukit’s own session/User persistence:

# config/config.yml (or config/packages/pumukit_ldap.yaml)
pumukit_ldap:
    server:
        host: ldap.example.org
        port: 389          # 636 for LDAPS
        # bind credentials as required by your directory
    # attribute mapping, base DN, filter — see Configuration.php for exact keys

Then point a firewall at the bundle’s provider rather than the default pumukit one, and confirm on a staging server that a known LDAP login lands on the Pumukit dashboard with the correct local user (or creates one, if auto-provisioning is on).

Implementation Patterns

1. Authenticate-then-provision. The typical flow: user presents credentials → bundle binds to LDAP → on success, a Pumukit User is looked up by username, and created or updated on the fly. Use this to seed Pumukit users from your directory so nobody maintains parallel accounts. Keep provisioning idempotent — the bundle may call it on every login.

2. Metadata-first filling. This is the bundle’s named selling point. After a successful bind, read directory attributes (cn, mail, telephoneNumber, o/ou, custom schema attrs) and copy them into the Pumukit Person/User fields. The pattern is a service that takes the LDAP entry array and maps it to your entity fields — keep the mapping explicit in config or a small mapper class, because attribute names differ wildly across directories (OpenLDAP vs. Active Directory vs. eDirectory).

3. Decorate, don’t fork. If the bundle’s mapper doesn’t cover your attributes, register a compiler pass or use service decoration to wrap the bundle’s mapper/provider. Vendor-editing is the wrong path given how sparsely maintained this package is — decorate and keep your code in src/.

4. Environment-split config. Define the LDAP host/port/base DN per environment in parameters.yml / .env. Use a local OpenLDAP container (e.g., osixia/openldap) for dev/test so you never accidentally point a debug build at production AD.

5. Sync as a command, not just on login. For existing users or when metadata drifts, write a Symfony console command that iterates local users and refreshes their attributes from LDAP. Wrap it in a cron. This is usually where most of the day-to-day business value is realized — login-time filling only helps new sessions.

6. Firewall integration. Wire the bundle as an additional authenticator on your Pumukit firewall (or a dedicated ldap firewall for admin tools) rather than a full replacement, so local fallback accounts remain usable while you validate the LDAP path.

7. Test with a known-good ldapsearch first. Before debugging the bundle, confirm the connection works outside Symfony: ldapsearch -H ldap://host -D 'binddn' -w pass -b 'base' '(uid=test)'. If that fails, the bundle will fail the same way — save yourself the round trips.

Gotchas and Tips

• PHP LDAP extension is a hard dependency. Missing ext-ldap surfaces as cryptic “Unable to connect” errors rather than an install-time failure. Add "ext-ldap": "*" to your own composer.json to fail fast.
• Version coupling with Pumukit core. The bundle’s service definitions reference Pumukit internals. A minor Pumukit upgrade can silently break the config tree or the User construction. Pin pumukit/pumukit and this bundle together, and re-run integration tests after every Pumukit bump.
• Low maintenance signal. One star, no dependents — assume the README is stale and the config keys may differ from documentation. Always read DependencyInjection/Configuration.php. Keep an eye on the repository’s open issues before relying on edge-case features.
• LDAP filter syntax is a quiet footgun. Unescaped input in filters (e.g., a username containing * or parentheses) can broaden matches. Escape user-supplied values with ldap_escape($value, '', LDAP_ESCAPE_FILTER) before building the search filter.
• TLS vs. LDAPS. Port 389 with StartTLS and port 636 with LDAPS behave differently in PHP’s ldap_* functions and in the bundle’s config. Many AD servers require one specific path — test both, and remember certificate trust is a system-level concern (/etc/ldap/ldap.conf, or TLS_REQCERT), not something the bundle manages.
• Active Directory quirks. AD returns memberOf as a multi-valued attribute and paged results for large searches; some LDAP libraries handle paging automatically, some don't. If group-based authorization is expected, verify the attribute is actually populated before writing logic against it.
• Attribute case sensitivity. LDAP attribute names are case-insensitive on the wire but the bundle’s mapping config may not be. Match the exact case shown by ldapsearch output to avoid silent “attribute not found” mapping misses.
• Bind account hygiene. If the bundle uses a service account for the initial bind (common in AD), put the password in an environment variable or secrets manager, not config.yml. Rotate it independently of application deploys.
• Timeouts and failure modes. A down LDAP server should degrade to local login, not 500 the login page. Check how the bundle handles a failed connection (it typically throws) and wrap or catch at the firewall level so your admin fallback still works.
• Debugging tip: enable LDAP protocol logging at the PHP level (ldap_set_option($ds, LDAP_OPT_DEBUG_LEVEL, 7)) in a throwaway script, not in the bundle — it dumps raw wire traffic to stderr and is unusable in production logs.
• Extension point: the mapper and user provider are the two services you’ll realistically override. If you find yourself wanting to override anything else, reassess — the package is too small and too sparsely maintained to be a stable extension base, and you may be better served by a thin custom authenticator using symfony/ldap directly, keeping this bundle only for the Pumukit-side provisioning glue.