Ldap Orm Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require carnegielearning/ldap-orm-bundle
   

   Add to AppKernel.php:

   new CarnegieLearning\LdapOrmBundle\CarnegieLearningLdapOrmBundle(),
   

2. Configure LDAP Connection Add to config.yml:

   carnegie_ldap_orm:
       connections:
           default:
               host: 'ldap.example.com'
               port: 389
               use_ssl: false
               username: 'cn=admin,dc=example,dc=com'
               password: 'admin_password'
               base_dn: 'dc=example,dc=com'
   

3. First Use Case: Querying Users Define an entity extending LdapEntity (e.g., User):

   namespace App\Entity;
   
   use CarnegieLearning\LdapOrmBundle\Entity\LdapEntity;
   
   class User extends LdapEntity
   {
       protected $objectClass = 'inetOrgPerson';
   }
   

   Query in a controller/service:

   $users = $this->get('carnegie_ldap_orm.manager')->getRepository('App\Entity\User')->findAll();
   

Implementation Patterns

Common Workflows

1. Entity Mapping Extend LdapEntity for each LDAP object class (e.g., Group, OrganizationalUnit):

   class Group extends LdapEntity
   {
       protected $objectClass = 'groupOfNames';
       protected $fields = ['cn', 'member'];
   }
   

2. Repository Operations Use Repository::findBy() with LDAP attributes:

   $repo = $this->get('carnegie_ldap_orm.manager')->getRepository('App\Entity\User');
   $users = $repo->findBy(['cn' => 'John Doe']);
   

3. Complex Filtering Leverage filterByComplex() for advanced queries:

   $filter = $repo->filterByComplex()
       ->where('ou', '=', 'Users')
       ->andWhere('objectClass', '=', 'inetOrgPerson')
       ->getFilter();
   $results = $repo->findByCustomFilter($filter);
   

4. CRUD Operations

   • Create: Use create() and save():

     $user = new User();
     $user->setDn('cn=New User,ou=Users');
     $user->setCn('New User');
     $manager->save($user);
     

   • Update: Modify fields and call save().
   • Delete: Use remove():

     $manager->remove($user);
     

5. Bulk Operations Iterate over results with findAll() or findBy():

   foreach ($users as $user) {
       $user->setMail($user->getMail() . '@newdomain.com');
       $manager->save($user);
   }
   

Integration Tips

• Symfony Forms: Bind LDAP entities to forms using Symfony\Component\Form\Extension\Core\Type\FormType.
• Security: Use LDAP entities in Symfony’s security system (e.g., UserProviderInterface).
• Caching: Cache frequent queries with Symfony’s cache component:

  $cache = $this->get('cache.app');
  $key = 'ldap_users_' . md5('ou=Users');
  $users = $cache->get($key, function() use ($repo) {
      return $repo->findBy(['ou' => 'Users']);
  });
  

Gotchas and Tips

Pitfalls

1. Connection Issues

   • Symptom: Queries hang or return empty results.
   • Fix: Verify LDAP server credentials, firewall rules, and network connectivity. Use ldapsearch to test manually:

     ldapsearch -x -H ldap://ldap.example.com -D "cn=admin,dc=example,dc=com" -w admin_password -b "dc=example,dc=com"
     

2. Attribute Mapping

   • Symptom: Fields return null or incorrect values.
   • Fix: Ensure $fields in your entity matches LDAP attributes (case-sensitive). Use getLdapAttributes() to debug:

     $user = $repo->findOneBy(['cn' => 'Test']);
     var_dump($user->getLdapAttributes());
     

3. Object Class Conflicts

   • Symptom: Entities fail to save with "structural object class" errors.
   • Fix: Specify the correct $objectClass in your entity. For example, inetOrgPerson requires top, person, and organizationalPerson.

4. Performance with Large Datasets

   • Symptom: Slow queries on large directories.
   • Fix: Use findBy() with specific filters instead of findAll(). Paginate results:

     $paginator = $this->get('knp_paginator');
     $results = $paginator->paginate(
         $repo->findBy(['ou' => 'Users']),
         $pageNumber,
         50
     );
     

5. Schema Differences

   • Symptom: Entities work in one environment but fail in another.
   • Fix: LDAP schemas vary by server. Use getLdapConnection()->getSchemaManager() to inspect available object classes and attributes.

Debugging Tips

• Enable LDAP Debugging Configure the connection to log queries:

  carnegie_ldap_orm:
      connections:
          default:
              debug: true
  

  Check logs for raw LDAP queries.

• Use var_dump() or dd() Inspect entities and attributes:

  dd($user->getLdapAttributes());
  

• Test with Simple Queries Start with basic findOneBy() calls before complex filters.

Extension Points

1. Custom Filters Extend Repository::filterByComplex() for reusable logic:

   class UserRepository extends \CarnegieLearning\LdapOrmBundle\Repository\Repository
   {
       public function findActiveUsers()
       {
           $filter = $this->filterByComplex()
               ->where('objectClass', '=', 'inetOrgPerson')
               ->andWhere('mail', '!=', null)
               ->getFilter();
           return $this->findByCustomFilter($filter);
       }
   }
   

2. Event Listeners Hook into LDAP operations via Symfony events (e.g., ldap.pre_save):

   $eventDispatcher->addListener('ldap.pre_save', function(LdapEvent $event) {
       if ($event->getEntity() instanceof User) {
           $event->getEntity()->setModifiedAt(new \DateTime());
       }
   });
   

3. Custom Entity Managers Override the default manager to add logic:

   class CustomLdapManager extends \CarnegieLearning\LdapOrmBundle\Manager\Manager
   {
       public function findByDn($dn)
       {
           return $this->findOneBy(['dn' => $dn]);
       }
   }
   

   Register as a service in services.yml:

   services:
       carnegie_ldap_orm.manager.custom:
           class: App\Manager\CustomLdapManager
           arguments: ['@carnegie_ldap_orm.connection.default']
   

4. Post-Processing Use LdapEntity::postLoad() to transform data:

   class User extends LdapEntity
   {
       public function postLoad()
       {
           $this->fullName = $this->getGivenName() . ' ' . $this->getSn();
       }
   }