Ldaptools Bundle Laravel Package

Getting Started

• Recognize the scope first: this is a Symfony bundle, not a Laravel package. As a Laravel developer, leverage it only when you are working in a Symfony codebase; in Laravel you would use the underlying ldaptools/ldaptools library directly or a Laravel-specific LDAP package.
• Install with Composer and register the bundle in config/bundles.php if Flex does not do it automatically:

  composer require ldaptools/ldaptools-bundle
  

• Look first at the README, then DependencyInjection/Configuration.php and the bundle service definitions. Those files tell you the exact config keys, service IDs, and autowiring aliases for your installed version.
• Create a minimal config in config/packages/ldap_tools.yaml with at least one domain, server list, base DN, and bind credentials sourced from environment variables:

  ldap_tools:
      domains:
          corp:
              domain_name: corp.example.com
              servers:
                  - dc1.corp.example.com
                  - dc2.corp.example.com
              base_dn: dc=corp,dc=example,dc=com
              admin_username: '%env(LDAP_BIND_USER)%'
              admin_password: '%env(LDAP_BIND_PASSWORD)%'
  

• First use case: query a user by sAMAccountName or uid and dump the result. Inject the bundle’s LDAP manager service, or fetch it from the container while confirming the exact alias:

  use LdapTools\LdapManager;
  
  public function __construct(private LdapManager $ldap) {}
  
  public function lookup(string $username): void
  {
      $user = $this->ldap->getRepository('user')->findOneByUsername($username);
      dump($user);
  }
  

• If the service is not autowirable in your version, use the configured service ID from the bundle’s Resources/config/services.xml or services.yaml and alias it explicitly in your app.

Implementation Patterns

• Wrap LDAP access in a small application service such as LdapUserDirectory instead of calling LdapManager from controllers. This keeps bind credentials, domain selection, error handling, and attribute mapping in one place.
• Use repositories for common read operations and the query builder for filters:

  $query = $this->ldap->buildLdapQuery()
      ->from('user')
      ->where(['department' => 'Engineering'])
      ->select(['username', 'email', 'displayName']);
  

• For writes, map LDAP objects explicitly: create/modify/delete through LdapObject instances or repository methods, and keep a dedicated mapper between your domain model and LDAP attributes.
• For authentication, prefer the bundle’s Symfony Security integration if it matches your Symfony version. If it does not, implement a custom user provider that binds a user, searches by login attribute, maps groups to roles, and refreshes user data on each login.
• Use one domain config per directory you touch, e.g. corp and partners. Avoid letting a single service silently switch domains based on request input; inject or select the domain explicitly.
• Put LDAP credentials in environment variables or Symfony Secrets. Restrict the bind account to the minimum search bases and operations required.
• For large directories, implement paged searches and limit selected attributes. Avoid findAll-style calls on broad bases such as dc=example,dc=com.
• In Laravel-only contexts, skip the bundle. Use ldaptools/ldaptools behind a Laravel service provider or choose a maintained Laravel LDAP package; the bundle’s value is Symfony DI, configuration, and Security integration.

Gotchas and Tips

• Symfony compatibility is the biggest risk. Check the bundle’s composer.json constraints before installing. A 48-star bundle with zero dependents may not support current Symfony versions; pin versions or be prepared to fork.
• Maintenance risk. Review recent commit activity and open issues. If the bundle is stale, isolate it behind your own service so you can swap to symfony/ldap or another library later.
• Escape LDAP filters. Never interpolate raw user input into filters. Use the query builder or the library’s escaping helpers; otherwise you get broken queries or LDAP injection.
• AD-specific attributes need care. objectGUID and objectSid are binary; memberOf may be absent if you do not query it; sAMAccountName, userPrincipalName, and distinguishedName behave differently from OpenLDAP attributes.
• Connection and TLS issues are common. Validate CA certificates, set timeouts, and test failover across domain controllers. Do not disable certificate validation as a shortcut.
• Bind carefully. Use the admin bind for searches and a user bind only for authentication. Avoid rebinding the shared connection as an end user and then serving that connection to another request.
• Clear Symfony cache after config changes. Changes under ldap_tools often will not take effect until bin/console cache:clear.
• Debug with ldapsearch first. Compare the exact filter, base DN, and bind DN outside Symfony. Then inspect the bundle config and enable logging for the LdapTools connection.
• Catch specific exceptions. Handle connection, query, and authentication exceptions separately; do not let LDAP outages cascade into unhandled 500s across the app.
• Test with mocks and a disposable directory. Mock LdapManager and repositories for unit tests, and use an OpenLDAP or AD container for integration tests of filters, paging, and group mapping.