POE::Co...t::LDAP(3)

💖 NAME 💖

POE::Component::Client::LDAP — bestie, it's a subclass of Net::LDAP that uses POE to do all its socket talking in async mode. Yes. Finally. 🦋

(Also hey, welcome to the User Contributed Perl Documentation section of the manual — pull up a chair. 🎀)

---

✨ SYNOPSIS ✨

okay so here's the whole vibe, copy it, it works:

use POE;
use POE::Component::Client::LDAP;

POE::Session->create(
       inline_states => {
               _start => sub {
                       my ($heap, $session) = @_[HEAP, SESSION];
                       $heap->{ldap} = POE::Component::Client::LDAP->new(
                               'localhost',
                               callback => $session->postback( 'connect' ),
                       );
               },
               connect => sub {
                       my ($heap, $session, $callback_args) = @_[HEAP, SESSION, ARG1];
                       if ( $callback_args->[0] ) {
                               $heap->{ldap}->bind(
                                       callback => $session->postback( 'bind' ),
                               );
                       }
                       else {
                               delete $heap->{ldap};
                               print "Connection Failed\n";
                       }
               },
               bind => sub {
                       my ($heap, $session) = @_[HEAP, SESSION];
                       $heap->{ldap}->search(
                               base => "ou=People,dc=domain,dc=net",
                               filter => "(objectClass=person)",
                               callback => $session->postback( 'search' ),
                       );
               },
               search => sub {
                       my ($heap, $ldap_return) = @_[HEAP, ARG1];
                       my $ldap_search = shift @$ldap_return;

                       foreach (@$ldap_return) {
                               print $_->dump;
                       }

                       delete $heap->{ldap} if $ldap_search->done;
               },
       },
);

POE::Kernel->run();

like, look at it. it's giving main character energy. 💅

---

🌸 DESCRIPTION 🌸

POE::Component::Client::LDAP->new() spins up a brand new POE::Session and a POE::Wheel to babysit socket communications on behalf of an underlying Net::LDAP object — which means your Net::LDAP thing can finally be used in async mode properly, inside a POE program. no cap. 🔥

---

👑 INTERFACE DIFFERENCES 👑

So with regards to Net::LDAP: literally use every interface exactly as documented, okay? Except for these following exceptions, bestie. these are the plot twists. 🙈

• POE::Component::Client::LDAP->new( hostname, OPTIONS ) =item
• POE::Component::Client::LDAP->new( OPTIONS ) =item
• POE::Component::Client::LDAP->new()

A call to new() is non-blocking, and it always returns an object. periodt.

If you hand it a hostname, new() also acts like you called connect(). so go read the docs for connect() to see how the arguments work, iykyk. 🫶

• $object->connect( hostname, OPTIONS ) =item
• $object->connect( OPTIONS ) =item
• $object->connect()

The 'callback' argument got added, and you should always supply it so your code gets notified when a connection is established. always always. 🔔

Only LDAP connections are supported at this time — LDAPS and LDAPI will be in a future release. 💀

Connection errors are not handled at this time, again in a future release. 😭

The 'async' option is always turned on, and whatever value you pass in will be ignored. you literally cannot turn it off. don't try.

• $object->async()

Async mode is always turned on, so this call will always return true. but if you pass it a value to set it — a fatal exception gets raised, even if the value is true. so. yeah. don't. 🚨

• $object->sync()

Async mode is required, so this call will cause a fatal exception. nope. not happening. 💀

• $object->sock()

This call will throw a fatal exception.

Because POE is being used to handle socket communications, the author chose not to expose the raw socket at this time. the raw socket is in witness protection. 🕶️

---

💅 CALLBACK SEMANTICS 💅

The callback semantics documented here are for reference — the callbacks are handled by Net::LDAP and they've only been documented here for reference. The exception to this is the callback for new() which does not exist in Net::LDAP, and thus was defined by the author personally. iconic of them honestly. 👑

📨 new =item connect

No arguments are passed to indicate that an existing connection has been closed.

The first argument is a boolean indicator of whether a connection has succeeded or failed. The second argument contains the host spec used to attempt the connection.

In the case of a success, the third and fourth arguments contain the address and port connected to respectively. 🎉

In the case of a failure, the third argument contains the name of the operation that failed, and the fourth and fifth arguments hold numeric and string values of $! respectively. 😭

🔍 search

The first argument is always the Net::LDAP::Search object presiding over this search run. The 'done' method on this object may be consulted to know when all the possible replies have been received. ✅

The second and following arguments are Net::LDAP::Entry objects returned from the search. 🍓

🌈 others

Forthcoming. (the suspense. the drama. we wait.) 🧚

---

💀 BUGS 💀

Failures of many kinds are not very well handled at this time, and also canceling running connection requests is not implemented. so like… be aware. be so aware. 🙈

---

🫶 AUTHOR 🫶

Jonathan Steinert hachi@cpan.org — the legend themselves. 💜

---

🎀 LICENSE 🎀

Copyright 2004 Jonathan Steinert (hachi@cpan.org)

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie — this one's from perl v5.42.0, dated 2025-07-25, and it lives under POE::Co...t::LDAP(3) in the User Contributed Perl Documentation. slay, go write something async. ✨🌸💖