Using LDAPS protocol question

[shark2k]

Hello,

I am trying to update my connection to use LDAPS but I am confused about something in the documentation (https://ldaprecord.com/docs/core/v4/configuration) under the TLS & STARTTLS section.
This is a connection to a Windows AD instance (and my code is running on Windows Server using IIS).

There is this code snippet on that page

$config = [
    // ...
    'use_tls' => false,      // Uses ldaps:// protocol (port 636)
    'use_starttls' => false, // Uses ldap:// with STARTTLS upgrade (port 389)
];

The way I am reading this, it makes it seem like if you set 'use_tls' to false, that enables using ldaps:// protocol.
However, a few lines under that, there is an info dialog that states "Only one can be set to true. You must choose either or."
That makes me think that setting one of those to true should turn it on.
Clarification on that would be helpful (though I did set use_tls to true and I believe it was trying to use ldaps:// protocol, though that leads me to my next question).

My bigger question is, how would I go about verifying that I am connecting to the AD using ldaps://?
Part of this is to confirm that I am, but the other part is to confirm if the one error I hit after trying to enable it for one script is because of the secure connection.

When I set use_tls to true for my one script, I retrieved the following error:

[27-Mar-2026 15:36:17 America/New_York] PHP Fatal error:  Uncaught ErrorException: ldap_search(): Search: Operations error in properTopLevel\vendor\directorytree\ldaprecord\src\Ldap.php:207
Stack trace:
#0 [internal function]: LdapRecord\Ldap->LdapRecord\{closure}()
#1 properTopLevel\vendor\directorytree\ldaprecord\src\Ldap.php(207): ldap_search()
#2 properTopLevel\vendor\directorytree\ldaprecord\src\HandlesConnection.php(184): LdapRecord\Ldap->LdapRecord\{closure}()
#3 properTopLevel\vendor\directorytree\ldaprecord\src\Ldap.php(197): LdapRecord\Ldap->executeFailableOperation()
#4 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(585): LdapRecord\Ldap->search()
#5 properTopLevel\vendor\directorytree\ldaprecord\src\Connection.php(350): LdapRecord\Query\Builder->LdapRecord\Query\{closure}()
#6 properTopLevel\vendor\directorytree\ldaprecord\src\Connection.php(418): LdapRecord\Connection->runOperationCallback()
#7 properTopLevel\vendor\directorytree\ldaprecord\src\Connection.php(400): LdapRecord\Connection->retry()
#8 properTopLevel\vendor\directorytree\ldaprecord\src\Connection.php(310): LdapRecord\Connection->tryAgainIfCausedByLostConnection()
#9 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(574): LdapRecord\Connection->run()
#10 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(362): LdapRecord\Query\Builder->run()
#11 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(560): LdapRecord\Query\Builder->LdapRecord\Query\{closure}()
#12 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(364): LdapRecord\Query\Builder->getCachedResponse()
#13 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(201): LdapRecord\Query\Builder->query()
#14 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(218): LdapRecord\Query\Builder->LdapRecord\Query\{closure}()
#15 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(200): LdapRecord\Query\Builder->onceWithColumns()
#16 properTopLevel\computerLogonCheck.php(162): LdapRecord\Query\Builder->get()
#17 {main}

Next LdapRecord\LdapRecordException: ldap_search(): Search: Operations error in properTopLevel\vendor\directorytree\ldaprecord\src\LdapRecordException.php:19
Stack trace:
#0 properTopLevel\vendor\directorytree\ldaprecord\src\HandlesConnection.php(197): LdapRecord\LdapRecordException::withDetailedError()
#1 properTopLevel\vendor\directorytree\ldaprecord\src\Ldap.php(197): LdapRecord\Ldap->executeFailableOperation()
#2 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(585): LdapRecord\Ldap->search()
#3 properTopLevel\vendor\directorytree\ldaprecord\src\Connection.php(350): LdapRecord\Query\Builder->LdapRecord\Query\{closure}()
#4 properTopLevel\vendor\directorytree\ldaprecord\src\Connection.php(418): LdapRecord\Connection->runOperationCallback()
#5 properTopLevel\vendor\directorytree\ldaprecord\src\Connection.php(400): LdapRecord\Connection->retry()
#6 properTopLevel\vendor\directorytree\ldaprecord\src\Connection.php(310): LdapRecord\Connection->tryAgainIfCausedByLostConnection()
#7 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(574): LdapRecord\Connection->run()
#8 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(362): LdapRecord\Query\Builder->run()
#9 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(560): LdapRecord\Query\Builder->LdapRecord\Query\{closure}()
#10 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(364): LdapRecord\Query\Builder->getCachedResponse()
#11 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(201): LdapRecord\Query\Builder->query()
#12 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(218): LdapRecord\Query\Builder->LdapRecord\Query\{closure}()
#13 properTopLevel\vendor\directorytree\ldaprecord\src\Query\Builder.php(200): LdapRecord\Query\Builder->onceWithColumns()
#14 properTopLevel\computerLogonCheck.php(162): LdapRecord\Query\Builder->get()
#15 {main}
  thrown in properTopLevel\vendor\directorytree\ldaprecord\src\LdapRecordException.php on line 19

I am using 2 connections in this script and immediately after I set the use_tls to false for the one connection, I received the same error as above but at a different line which used the 2nd connection. Once I set use_tls to false for that connection, the script was able to successfully run.

The line that is causing the error from above is:

$computers = Computer::on('ou-US')->orderBy('name')->get();

The line that causes the error when the first connection is set to use_tls false:

$employeeInfo = User::on('ou-FR')->findBy('samaccountname', $username);

So one is trying to get computer info and the other is trying to get user info.

The connection information is a such (with use_tls being uncommented when I received the above error):

$connection = new Connection([
		'hosts' => [
			'valid.host',
		],
		//'use_tls' => true,
		'base_dn' => 'valid-base_dn,
		'username' => 'valid_username',
		'password' => 'valid_password'
	]);

And my "connect" section is:

try {
		//$connection->connect();
		Container::addConnection($connection, 'ou-US');
		Container::setDefaultConnection('ou-US');
		//echo 'Successfully connected';
	} catch (\LdapRecord\Auth\BindException $e) {
		$error = $e->getDetailedError();
		
		echo $error->getErrorCode().'<br />';
		echo $error->getErrorMessage().'<br />';
		echo $error->getDiagnosticMessage().'<br />';
	}

I had a different script I was using for testing and that seemed to work, but I could not figure out how to get some kind of output somewhere to confirm I was connecting using the ldaps:// protocol.

So I guess I have 2 or 3 questions in this.

1. Clarification of the section in the documentation
2. How one would go about confirming they are connecting using ldaps:// protocol?
3. If I am connecting via ldaps:// protocol, why does my code at least in the one script fail when doing that but succeed when not secure?

As I have said in past questions I have opened, I really do appreciate this library and all the work you have put into.
Also, while I might be getting slightly better with programming, it is not my day job so forgive me if I need extra clarification.

Thanks,
Shark2k

[shreyanshjain1]

You are reading the docs correctly that the example snippet is a little confusing, but the bullet points below it clarify the real behavior:

• use_tls => true = connect using ldaps:// (default port 636)
• use_starttls => true = connect using ldap:// on 389 and then upgrade with STARTTLS
• only one of those should be true at a time

So if your goal is LDAPS, then use_tls should be set to true, not false.

For confirming whether you are really using LDAPS:

1. Make sure use_tls => true
2. Do not prepend ldaps:// to hosts; the docs say to use the config option instead
3. Check whether the connection is going to port 636
4. If possible, test the server with another LDAP client against the same host/port/cert path to confirm the server accepts LDAPS from that machine

About the ldap_search(): Search: Operations error:

That usually suggests the connection/bind may have succeeded far enough to reach the server, but the server is rejecting the operation afterward because something about the secure setup or bind context is not right.

A few practical things I would verify:

• the AD server actually supports LDAPS on 636
• the certificate on the domain controller is valid/trusted by the Windows server running PHP/IIS
• the PHP LDAP/OpenLDAP layer on that machine trusts the issuing CA
• both of your configured connections are using the correct TLS setting consistently
• the bind account / base DN / search scope are still valid on both connections

Since both connections started failing when TLS was mixed between them, I would also avoid testing with one secure and one non-secure connection in the same script until the baseline works cleanly. I would first get one connection working with use_tls => true, confirm it queries successfully, then apply the same pattern to the second connection.

So in short:

• Q1: for LDAPS, set use_tls to true
• Q2: verify by checking that the connection is using port 636 and that the LDAPS handshake succeeds
• Q3: the search error is more likely a server/certificate/bind/query-context issue after enabling LDAPS, not evidence that use_tls itself should be false

If it helps, I’d test one connection first with the smallest possible query and verify that exact host can bind and search over LDAPS before reintroducing the second connection.

If this helps, feel free to mark it as the answer so others can find it faster.