Documentation

Autodiscover
in package

Exchange Web Services Autodiscover implementation

This class supports POX (Plain Old XML), which is deprecated but functional in Exchange 2010. It may make sense for you to combine your Autodiscovery efforts with a SOAP Autodiscover request as well.

USAGE:

(after any auto-loading class incantation)

$ews = EWSAutodiscover::getEWS($email, $password);

-- OR --

If there are issues with your cURL installation that require you to specify a path to a valid Certificate Authority, you can configure that manually.

$auto = new EWSAutodiscover($email, $password); $auto->setCAInfo('/path/to/your/cacert.pem'); $ews = $auto->newEWS();

Tags
link
http://technet.microsoft.com/en-us/library/bb332063(EXCHG.80).aspx
link
https://www.testexchangeconnectivity.com/
todo

This class is quite large; it should be refactored into smaller classes.

SuppressWarnings

(PHPMD.CyclomaticComplexity)

SuppressWarnings

(PHPMD.ExcessiveClassComplexity)

SuppressWarnings

(PHPMD.NPathComplexity)

Table of Contents

Constants

AUTODISCOVER_PATH  = '/autodiscover/autodiscover.xml'
The path appended to the various schemes and hostnames used during autodiscovery.
AUTODISCOVERED_VIA_RESPONSE_REDIRECT  = 14
Server was discovered using the HTTP redirect method.
AUTODISCOVERED_VIA_SRV_RECORD  = 13
Server was discovered using the DNS SRV redirect method.
AUTODISCOVERED_VIA_SUBDOMAIN  = 11
Server was discovered using the subdomain method.
AUTODISCOVERED_VIA_TLD  = 10
Server was discovered using the TLD method.
AUTODISCOVERED_VIA_UNAUTHENTICATED_GET  = 12
Server was discovered using the unauthenticated GET method.

Properties

$connection_timeout  : int
The value in seconds to use for Autodiscover host connection timeouts.
$discovered  : mixed
A successful, non-error and non-redirect parsed Autodiscover response will be stored here.
$error  : mixed
Information about an Autodiscover Response containing an error will be stored here.
$last_curl_errno  : int
The cURL error code associated with the most recent cURL request.
$last_curl_error  : string
Human-readable description of the most recent cURL error.
$last_info  : array<string|int, mixed>
The output of curl_info() relating to the most recent cURL request.
$last_response  : string
The body of the last response.
$last_response_headers  : array<string|int, mixed>
An associative array of response headers that resulted from the last request. Keys are lowercased for easy checking.
$redirect  : mixed
Information about an Autodiscover Response with a redirect will be retained here.
$cainfo  : string
The path to a specific Certificate Authority file. Get one and use it for full Autodiscovery compliance.
$capath  : string
The Certificate Authority path. Should point to a directory containing one or more certificates to use in SSL verification.
$email  : string
The email address to attempt autodiscovery against.
$password  : string
The password to present during autodiscovery.
$requestxml  : string
The Autodiscover XML request. Since it's used repeatedly, it's cached in this property to avoid redundant re-generation.
$skip_ssl_verification  : bool
Skip SSL verification. Bad idea, and violates the strict Autodiscover protocol. But, here in case you have no other option.
$tld  : string
The top-level domain name, extracted from the provided email address.
$username  : string
The Exchange username to use during authentication. If unspecified, the provided email address will be used as the username.

Methods

__construct()  : mixed
Constructor for the EWSAutodiscover class.
discover()  : int
Execute the full discovery chain of events in the correct sequence until a valid response is received, or all methods have failed.
discoveredSettings()  : mixed
Return the settings discovered from the Autodiscover process.
doNTLMPost()  : bool
Perform the NTLM authenticated post against one of the chosen endpoints.
getAutodiscoverRequest()  : string
Return the generated Autodiscover XML request body.
getEWS()  : mixed
Static method may fail if there are issues surrounding SSL certificates.
newEWS()  : mixed
Method to return a new Client object, auto-configured with the proper hostname.
parseServerVersion()  : string|bool
Parse the hex ServerVersion value and return a valid Client::VERSION_* constant.
readHeaders()  : int
Utility function to pick headers off of the incoming cURL response.
reset()  : self
Reset the response-related structures. Called before making a new request.
responseToArray()  : array<string|int, mixed>
Utility function to parse XML payloads from the response into easier to manage associative arrays.
setCAInfo()  : self
Set the path to the file to be used by CURLOPT_CAINFO.
setCAPath()  : self
Set the path to the file to be used by CURLOPT_CAPATH.
setConnectionTimeout()  : self
Set a connection timeout for the POST methods.
skipSSLVerification()  : self
Toggle skipping of SSL verification in cURL requests.
trySRVRecord()  : int|bool
Attempt to retrieve the autodiscover host from an SRV DNS record.
trySubdomain()  : int|bool
Perform an NTLM authenticated HTTPS POST to the 'autodiscover' subdomain of the email address' TLD.
trySubdomainUnauthenticatedGet()  : int|bool
Perform an unauthenticated HTTP GET in an attempt to get redirected via 302 to the correct location to perform the HTTPS POST.
tryTLD()  : int|bool
Perform an NTLM authenticated HTTPS POST to the top-level domain of the email address.
nodeToArray()  : mixed
Recursive method for parsing DOM nodes.
parseAutodiscoverResponse()  : bool|array<string|int, mixed>
Parse the Autoresponse Payload, particularly to determine if an additional request is necessary.
parseVersion2007()  : string
Parses the version of an Exchange 2007 server.
parseVersion2010()  : string
Parses the version of an Exchange 2010 server.
parseVersion2013()  : string
Parses the version of an Exchange 2013 server.
parseVersion2016()  : string
Parses the version of an Exchange 2016 server.
setTLD()  : bool
Set the top-level domain to be used with autodiscover attempts based on the provided email address.
tryViaUrl()  : bool
Attempts an autodiscover via a URL.

Constants

AUTODISCOVER_PATH

The path appended to the various schemes and hostnames used during autodiscovery.

public string AUTODISCOVER_PATH = '/autodiscover/autodiscover.xml'

AUTODISCOVERED_VIA_RESPONSE_REDIRECT

Server was discovered using the HTTP redirect method.

public int AUTODISCOVERED_VIA_RESPONSE_REDIRECT = 14
Tags
todo

We do not currently support this.

AUTODISCOVERED_VIA_SRV_RECORD

Server was discovered using the DNS SRV redirect method.

public int AUTODISCOVERED_VIA_SRV_RECORD = 13

AUTODISCOVERED_VIA_SUBDOMAIN

Server was discovered using the subdomain method.

public int AUTODISCOVERED_VIA_SUBDOMAIN = 11

AUTODISCOVERED_VIA_TLD

Server was discovered using the TLD method.

public int AUTODISCOVERED_VIA_TLD = 10

AUTODISCOVERED_VIA_UNAUTHENTICATED_GET

Server was discovered using the unauthenticated GET method.

public int AUTODISCOVERED_VIA_UNAUTHENTICATED_GET = 12

Properties

$connection_timeout

The value in seconds to use for Autodiscover host connection timeouts.

public int $connection_timeout = 2

Default connection timeout is 2 seconds, so that unresponsive methods can be bypassed quickly.

$discovered

A successful, non-error and non-redirect parsed Autodiscover response will be stored here.

public mixed $discovered = null

$error

Information about an Autodiscover Response containing an error will be stored here.

public mixed $error = false

$last_curl_errno

The cURL error code associated with the most recent cURL request.

public int $last_curl_errno

$last_curl_error

Human-readable description of the most recent cURL error.

public string $last_curl_error

$last_info

The output of curl_info() relating to the most recent cURL request.

public array<string|int, mixed> $last_info

$last_response

The body of the last response.

public string $last_response

$last_response_headers

An associative array of response headers that resulted from the last request. Keys are lowercased for easy checking.

public array<string|int, mixed> $last_response_headers

$redirect

Information about an Autodiscover Response with a redirect will be retained here.

public mixed $redirect = false

$capath

The Certificate Authority path. Should point to a directory containing one or more certificates to use in SSL verification.

protected string $capath

$email

The email address to attempt autodiscovery against.

protected string $email

$password

The password to present during autodiscovery.

protected string $password

$requestxml

The Autodiscover XML request. Since it's used repeatedly, it's cached in this property to avoid redundant re-generation.

protected string $requestxml

$skip_ssl_verification

Skip SSL verification. Bad idea, and violates the strict Autodiscover protocol. But, here in case you have no other option.

protected bool $skip_ssl_verification = false

Defaults to FALSE.

$tld

The top-level domain name, extracted from the provided email address.

protected string $tld

$username

The Exchange username to use during authentication. If unspecified, the provided email address will be used as the username.

protected string $username

Methods

__construct()

Constructor for the EWSAutodiscover class.

public __construct(string $email, string $password[, string $username = null ]) : mixed
Parameters
$email : string
$password : string
$username : string = null

If left blank, the email provided will be used.

discover()

Execute the full discovery chain of events in the correct sequence until a valid response is received, or all methods have failed.

public discover() : int
Tags
throws
RuntimeException

When all autodiscovery methods fail.

Return values
int —

One of the AUTODISCOVERED_VIA_* constants.

discoveredSettings()

Return the settings discovered from the Autodiscover process.

public discoveredSettings() : mixed

NULL indicates discovery has not completed (or been attempted) FALSE indicates discovery was not successful. Check for errors or redirects. An array will be returned with discovered settings on success.

doNTLMPost()

Perform the NTLM authenticated post against one of the chosen endpoints.

public doNTLMPost(string $url[, int $timeout = 6 ]) : bool
Parameters
$url : string

URL to try posting to.

$timeout : int = 6

Number of seconds before the request should timeout.

Return values
bool

getAutodiscoverRequest()

Return the generated Autodiscover XML request body.

public getAutodiscoverRequest() : string
Tags
suppress

PhanTypeMismatchArgumentInternal

Return values
string

getEWS()

Static method may fail if there are issues surrounding SSL certificates.

public static getEWS(string $email, string $password[, string $username = null ]) : mixed

In such cases, set up the object as needed, and then call newEWS().

Parameters
$email : string
$password : string
$username : string = null

If left blank, the email provided will be used.

newEWS()

Method to return a new Client object, auto-configured with the proper hostname.

public newEWS() : mixed
Return values
mixed —

Client object on success, FALSE on failure.

parseServerVersion()

Parse the hex ServerVersion value and return a valid Client::VERSION_* constant.

public parseServerVersion(string $version_hex) : string|bool
Parameters
$version_hex : string

Hexadecimal version string.

Tags
link
http://msdn.microsoft.com/en-us/library/bb204122(v=exchg.140).aspx
link
http://blogs.msdn.com/b/pcreehan/archive/2009/09/21/parsing-serverversion-when-an-int-is-really-5-ints.aspx
link
http://office.microsoft.com/en-us/outlook-help/determine-the-version-of-microsoft-exchange-server-my-account-connects-to-HA001191800.aspx
Return values
string|bool —

A known version constant, or FALSE if it could not be determined.

readHeaders()

Utility function to pick headers off of the incoming cURL response.

public readHeaders(resource $_ch, string $str) : int

Used with CURLOPT_HEADERFUNCTION.

Parameters
$_ch : resource

cURL handle.

$str : string

Header string to read.

Tags
todo

Determine if we can remove $_ch here.

SuppressWarnings

(PHPMD.UnusedFormalParameter)

Return values
int —

Bytes read.

reset()

Reset the response-related structures. Called before making a new request.

public reset() : self
Return values
self

responseToArray()

Utility function to parse XML payloads from the response into easier to manage associative arrays.

public responseToArray(string $xml) : array<string|int, mixed>
Parameters
$xml : string

XML to parse.

Return values
array<string|int, mixed>

setCAInfo()

Set the path to the file to be used by CURLOPT_CAINFO.

public setCAInfo(string $path) : self
Parameters
$path : string

Path to a certificate file such as cacert.pem

Return values
self

setCAPath()

Set the path to the file to be used by CURLOPT_CAPATH.

public setCAPath(string $path) : self
Parameters
$path : string

Path to a directory containing one or more CA certificates.

Return values
self

setConnectionTimeout()

Set a connection timeout for the POST methods.

public setConnectionTimeout(int $seconds) : self
Parameters
$seconds : int

Seconds to wait for a connection.

Return values
self

skipSSLVerification()

Toggle skipping of SSL verification in cURL requests.

public skipSSLVerification([bool $skip = true ]) : self
Parameters
$skip : bool = true

Whether or not to skip SSL certificate verification.

Tags
SuppressWarnings

(PHPMD.BooleanArgumentFlag)

Return values
self

trySubdomain()

Perform an NTLM authenticated HTTPS POST to the 'autodiscover' subdomain of the email address' TLD.

public trySubdomain() : int|bool
Return values
int|bool —

One of the AUTODISCOVERED_VIA_* constants or false on failure.

trySubdomainUnauthenticatedGet()

Perform an unauthenticated HTTP GET in an attempt to get redirected via 302 to the correct location to perform the HTTPS POST.

public trySubdomainUnauthenticatedGet() : int|bool
Return values
int|bool —

One of the AUTODISCOVERED_VIA_* constants or false on failure.

tryTLD()

Perform an NTLM authenticated HTTPS POST to the top-level domain of the email address.

public tryTLD() : int|bool
Return values
int|bool —

One of the AUTODISCOVERED_VIA_* constants or false on failure.

parseAutodiscoverResponse()

Parse the Autoresponse Payload, particularly to determine if an additional request is necessary.

protected parseAutodiscoverResponse() : bool|array<string|int, mixed>
Return values
bool|array<string|int, mixed> —

FALSE if response isn't XML or parsed response array.

parseVersion2007()

Parses the version of an Exchange 2007 server.

protected parseVersion2007(int $minorversion) : string
Parameters
$minorversion : int

Minor server version.

Return values
string —

Server version.

parseVersion2010()

Parses the version of an Exchange 2010 server.

protected parseVersion2010(int $minorversion) : string
Parameters
$minorversion : int

Minor server version.

Return values
string —

Server version.

parseVersion2013()

Parses the version of an Exchange 2013 server.

protected parseVersion2013(int $majorbuild) : string
Parameters
$majorbuild : int

Major build version.

Return values
string —

Server version.

parseVersion2016()

Parses the version of an Exchange 2016 server.

protected parseVersion2016() : string
Return values
string —

Server version.

setTLD()

Set the top-level domain to be used with autodiscover attempts based on the provided email address.

protected setTLD() : bool
Return values
bool

tryViaUrl()

Attempts an autodiscover via a URL.

protected tryViaUrl(string $url[, int $timeout = 6 ]) : bool
Parameters
$url : string

Url to attempt an autodiscover.

$timeout : int = 6

Number of seconds before the request should timeout.

Return values
bool 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results