Documentation

Client
in package

This class implements the ManageSieve protocol (RFC 5804).

Tags
author

Richard Heyes richard@phpguru.org

author

Damian Fernandez Sosa damlists@cnba.uba.ar

author

Anish Mistry amistry@am-productions.biz

author

Jan Schneider jan@horde.org

copyright

2002-2003 Richard Heyes

copyright

2006-2008 Anish Mistry

copyright

2009-2017 Horde LLC

license

http://www.horde.org/licenses/bsd BSD

link

RFC 5804 A Protocol for Remotely Managing Sieve Scripts

Table of Contents

AUTH_AUTOMATIC  = 0
Authentication with the best available method.
AUTH_CRAMMD5  = 'CRAM-MD5'
CRAM-MD5 authentication.
AUTH_DIGESTMD5  = 'DIGEST-MD5'
DIGEST-MD5 authentication.
AUTH_EXTERNAL  = 'EXTERNAL'
EXTERNAL authentication.
AUTH_LOGIN  = 'LOGIN'
LOGIN authentication.
AUTH_PLAIN  = 'PLAIN'
PLAIN authentication.
STATE_AUTHENTICATED  = 3
Client is authenticated.
STATE_DISCONNECTED  = 1
Client is disconnected.
STATE_NON_AUTHENTICATED  = 2
Client is connected but not authenticated.
$supportedAuthMethods  : array<string|int, mixed>
The authentication methods this class supports.
$supportedSASLAuthMethods  : array<string|int, mixed>
SASL authentication methods that require Auth_SASL.
$_logger  : string|array<string|int, mixed>
Logging handler.
$_maxReferralCount  : array<string|int, mixed>
Maximum number of referral loops
$_params  : array<string|int, mixed>
Parameters and connection information.
$_sock  : Client
The socket client.
$_state  : int
Current state of the connection.
__construct()  : mixed
Constructor.
connect()  : mixed
Handles connecting to the server and checks the response validity.
disconnect()  : mixed
Disconnect from the Sieve server.
getActive()  : string
Returns the active script.
getAuthMechs()  : array<string|int, mixed>
Returns the list of authentication methods the server supports.
getExtensions()  : array<string|int, mixed>
Returns the list of extensions the server supports.
getScript()  : string
Retrieves a script.
hasAuthMech()  : bool
Returns whether the server supports an authentication method.
hasExtension()  : bool
Returns whether the server supports an extension.
hasSpace()  : bool
Checks if the server has space to store the script by the server.
installScript()  : mixed
Adds a script to the server.
listScripts()  : array<string|int, mixed>
Returns an indexed array of scripts currently on the server.
login()  : mixed
Logs into server.
removeScript()  : mixed
Removes a script from the server.
setActive()  : mixed
Sets the active script.
setLogger()  : mixed
Passes a logger for debug logging.
_authCRAMMD5()  : mixed
Authenticates the user using the CRAM-MD5 method.
_authDigestMD5()  : mixed
Authenticates the user using the DIGEST-MD5 method.
_authEXTERNAL()  : mixed
Authenticates the user using the EXTERNAL method.
_authLOGIN()  : mixed
Authenticates the user using the LOGIN method.
_authPLAIN()  : mixed
Authenticates the user using the PLAIN method.
_checkAuthenticated()  : mixed
Asserts that the client is in authenticated state.
_checkConnected()  : mixed
Asserts that the client is in disconnected state.
_cmdAuthenticate()  : mixed
Handles the authentication using any known method.
_cmdCapability()  : mixed
Sends the CAPABILITY command
_cmdDeleteScript()  : mixed
Removes a script from the server.
_cmdGetScript()  : string
Retrieves the contents of the named script.
_cmdListScripts()  : array<string|int, mixed>
Returns the list of scripts on the server.
_cmdLogout()  : mixed
Logs out of the server and terminates the connection.
_cmdPutScript()  : mixed
Adds a script to the server.
_cmdSetActive()  : mixed
Sets the active script, i.e. the one that gets run on new mail by the server.
_debug()  : mixed
Write debug text to the current log handler.
_doCmd()  : string
Send a command and retrieves a response from the server.
_escape()  : string
Converts strings into RFC's quoted-string or literal-c2s form.
_getBestAuthMethod()  : string
Returns the name of the best authentication method that the server has advertised.
_handleConnectAndLogin()  : mixed
Connects to the server and logs in.
_parseCapability()  : mixed
Parses the response from the CAPABILITY command and stores the result in $_capability.
_recvBytes()  : string
Receives a number of bytes from the server.
_recvLn()  : string
Receives a single line from the server.
_sendCmd()  : mixed
Sends a command to the server
_sendStringResponse()  : mixed
Sends a string response to the server.

Constants

AUTH_AUTOMATIC

Authentication with the best available method.

public mixed AUTH_AUTOMATIC = 0

AUTH_CRAMMD5

CRAM-MD5 authentication.

public mixed AUTH_CRAMMD5 = 'CRAM-MD5'

AUTH_DIGESTMD5

DIGEST-MD5 authentication.

public mixed AUTH_DIGESTMD5 = 'DIGEST-MD5'

AUTH_EXTERNAL

EXTERNAL authentication.

public mixed AUTH_EXTERNAL = 'EXTERNAL'

AUTH_LOGIN

LOGIN authentication.

public mixed AUTH_LOGIN = 'LOGIN'

AUTH_PLAIN

PLAIN authentication.

public mixed AUTH_PLAIN = 'PLAIN'

STATE_AUTHENTICATED

Client is authenticated.

public mixed STATE_AUTHENTICATED = 3

STATE_DISCONNECTED

Client is disconnected.

public mixed STATE_DISCONNECTED = 1

STATE_NON_AUTHENTICATED

Client is connected but not authenticated.

public mixed STATE_NON_AUTHENTICATED = 2

Properties

$supportedAuthMethods

The authentication methods this class supports.

public array<string|int, mixed> $supportedAuthMethods = array(self::AUTH_DIGESTMD5, self::AUTH_CRAMMD5, self::AUTH_EXTERNAL, self::AUTH_PLAIN, self::AUTH_LOGIN)

Can be overwritten if having problems with certain methods.

$supportedSASLAuthMethods

SASL authentication methods that require Auth_SASL.

public array<string|int, mixed> $supportedSASLAuthMethods = array(self::AUTH_DIGESTMD5, self::AUTH_CRAMMD5)

$_logger

Logging handler.

protected string|array<string|int, mixed> $_logger

$_maxReferralCount

Maximum number of referral loops

protected array<string|int, mixed> $_maxReferralCount = 15

$_params

Parameters and connection information.

protected array<string|int, mixed> $_params

$_sock

The socket client.

protected Client $_sock

$_state

Current state of the connection.

protected int $_state = self::STATE_DISCONNECTED

One of the STATE_* constants.

Methods

__construct()

Constructor.

public __construct([array<string|int, mixed> $params = array() ]) : mixed

If username and password are provided connects to the server and logs in too.

Parameters
$params : array<string|int, mixed> = array()

A hash of connection parameters:

  • host: Hostname of server (DEFAULT: localhost). Optionally prefixed with protocol scheme.
  • port: Port of server (DEFAULT: 4190).
  • user: Login username (optional).
  • password: Login password (optional).
  • authmethod: Type of login to perform (see $supportedAuthMethods) (DEFAULT: AUTH_AUTOMATIC).
  • euser: Effective user. If authenticating as an administrator, login as this user.
  • bypassauth: Skip the authentication phase. Useful if passing an already open socket.
  • secure: Security layer requested. One of:
    • true: (TLS if available/necessary) [DEFAULT]
    • false: (No encryption)
    • 'ssl': (Auto-detect SSL version)
    • 'sslv2': (Force SSL version 3)
    • 'sslv3': (Force SSL version 2)
    • 'tls': (TLS; started via protocol-level negotation over unencrypted channel)
    • 'tlsv1': (TLS version 1.x connection)
  • context: Additional options for stream_context_create().
  • logger: A log handler, must implement debug().
Tags
throws
Exception
Return values
mixed —

connect()

Handles connecting to the server and checks the response validity.

public connect([string $host = null ][, string $port = null ][, array<string|int, mixed> $context = null ][, bool $secure = null ]) : mixed

Defaults from the constructor are used for missing parameters.

Parameters
$host : string = null

Hostname of server.

$port : string = null

Port of server.

$context : array<string|int, mixed> = null

List of options to pass to stream_context_create().

$secure : bool = null

Security layer requested. @see __construct().

Tags
throws
Exception
Return values
mixed —

disconnect()

Disconnect from the Sieve server.

public disconnect([bool $sendLogoutCMD = true ]) : mixed
Parameters
$sendLogoutCMD : bool = true

Whether to send LOGOUT command before disconnecting.

Tags
throws
Exception
Return values
mixed —

getActive()

Returns the active script.

public getActive() : string
Return values
string —

The active scriptname.

getAuthMechs()

Returns the list of authentication methods the server supports.

public getAuthMechs() : array<string|int, mixed>
Tags
throws
Exception
Return values
array<string|int, mixed> —

List of authentication methods.

getExtensions()

Returns the list of extensions the server supports.

public getExtensions() : array<string|int, mixed>
Tags
throws
Exception
Return values
array<string|int, mixed> —

List of extensions.

getScript()

Retrieves a script.

public getScript(string $scriptname) : string
Parameters
$scriptname : string

The name of the script to be retrieved.

Tags
throws
Exception
Return values
string —

The script.

hasAuthMech()

Returns whether the server supports an authentication method.

public hasAuthMech(string $method) : bool
Parameters
$method : string

The method to check.

Tags
throws
Exception
Return values
bool —

Whether the method is supported.

hasExtension()

Returns whether the server supports an extension.

public hasExtension(string $extension) : bool
Parameters
$extension : string

The extension to check.

Tags
throws
Exception
Return values
bool —

Whether the extension is supported.

hasSpace()

Checks if the server has space to store the script by the server.

public hasSpace(string $scriptname, int $size) : bool
Parameters
$scriptname : string

The name of the script to mark as active.

$size : int

The size of the script.

Tags
throws
Exception
Return values
bool —

True if there is space.

installScript()

Adds a script to the server.

public installScript(string $scriptname, string $script[, bool $makeactive = false ]) : mixed
Parameters
$scriptname : string

Name of the script.

$script : string

The script content.

$makeactive : bool = false

Whether to make this the active script.

Tags
throws
Exception
Return values
mixed —

listScripts()

Returns an indexed array of scripts currently on the server.

public listScripts() : array<string|int, mixed>
Return values
array<string|int, mixed> —

Indexed array of scriptnames.

login()

Logs into server.

public login([string $user = null ][, string $password = null ][, string $authmethod = null ][, string $euser = null ]) : mixed

Defaults from the constructor are used for missing parameters.

Parameters
$user : string = null

Login username.

$password : string = null

Login password.

$authmethod : string = null

Type of login method to use.

$euser : string = null

Effective UID (perform on behalf of $euser).

Tags
throws
Exception
Return values
mixed —

removeScript()

Removes a script from the server.

public removeScript(string $scriptname) : mixed
Parameters
$scriptname : string

Name of the script.

Tags
throws
Exception
Return values
mixed —

setActive()

Sets the active script.

public setActive(string $scriptname) : mixed
Parameters
$scriptname : string

The name of the script to be set as active.

Tags
throws
Exception
Return values
mixed —

setLogger()

Passes a logger for debug logging.

public setLogger(object $logger) : mixed
Parameters
$logger : object

A log handler, must implement debug().

Return values
mixed —

_authCRAMMD5()

Authenticates the user using the CRAM-MD5 method.

protected _authCRAMMD5(string $user, string $pass, string $euser) : mixed
Parameters
$user : string

The userid to authenticate as.

$pass : string

The password to authenticate with.

$euser : string

The effective uid to authenticate as. Not used.

Tags
throws
Exception
Return values
mixed —

_authDigestMD5()

Authenticates the user using the DIGEST-MD5 method.

protected _authDigestMD5(string $user, string $pass, string $euser) : mixed
Parameters
$user : string

The userid to authenticate as.

$pass : string

The password to authenticate with.

$euser : string

The effective uid to authenticate as.

Tags
throws
Exception
Return values
mixed —

_authEXTERNAL()

Authenticates the user using the EXTERNAL method.

protected _authEXTERNAL(string $user, string $pass, string $euser) : mixed
Parameters
$user : string

The userid to authenticate as.

$pass : string

The password to authenticate with.

$euser : string

The effective uid to authenticate as.

Tags
throws
Exception
Return values
mixed —

_authLOGIN()

Authenticates the user using the LOGIN method.

protected _authLOGIN(string $user, string $pass, string $euser) : mixed
Parameters
$user : string

The userid to authenticate as.

$pass : string

The password to authenticate with.

$euser : string

The effective uid to authenticate as. Not used.

Tags
throws
Exception
Return values
mixed —

_authPLAIN()

Authenticates the user using the PLAIN method.

protected _authPLAIN(string $user, string $pass, string $euser) : mixed
Parameters
$user : string

The userid to authenticate as.

$pass : string

The password to authenticate with.

$euser : string

The effective uid to authenticate as.

Tags
throws
Exception
Return values
mixed —

_checkAuthenticated()

Asserts that the client is in authenticated state.

protected _checkAuthenticated() : mixed
Tags
throws
Exception
Return values
mixed —

_checkConnected()

Asserts that the client is in disconnected state.

protected _checkConnected() : mixed
Tags
throws
Exception
Return values
mixed —

_cmdAuthenticate()

Handles the authentication using any known method.

protected _cmdAuthenticate(string $uid, string $pwd[, string $authmethod = null ][, string $euser = '' ]) : mixed
Parameters
$uid : string

The userid to authenticate as.

$pwd : string

The password to authenticate with.

$authmethod : string = null

The method to use. If empty, the class chooses the best (strongest) available method.

$euser : string = ''

The effective uid to authenticate as.

Tags
throws
Exception
Return values
mixed —

_cmdCapability()

Sends the CAPABILITY command

protected _cmdCapability() : mixed
Tags
throws
Exception
Return values
mixed —

_cmdDeleteScript()

Removes a script from the server.

protected _cmdDeleteScript(string $scriptname) : mixed
Parameters
$scriptname : string

Name of the script to delete.

Tags
throws
Exception
Return values
mixed —

_cmdGetScript()

Retrieves the contents of the named script.

protected _cmdGetScript(string $scriptname) : string
Parameters
$scriptname : string

Name of the script to retrieve.

Tags
throws
Exception
Return values
string —

The script.

_cmdListScripts()

Returns the list of scripts on the server.

protected _cmdListScripts() : array<string|int, mixed>
Tags
throws
Exception
Return values
array<string|int, mixed> —

An array with the list of scripts in the first element and the active script in the second element.

_cmdLogout()

Logs out of the server and terminates the connection.

protected _cmdLogout([bool $sendLogoutCMD = true ]) : mixed
Parameters
$sendLogoutCMD : bool = true

Whether to send LOGOUT command before disconnecting.

Tags
throws
Exception
Return values
mixed —

_cmdPutScript()

Adds a script to the server.

protected _cmdPutScript(string $scriptname, string $scriptdata) : mixed
Parameters
$scriptname : string

Name of the new script.

$scriptdata : string

The new script.

Tags
throws
Exception
Return values
mixed —

_cmdSetActive()

Sets the active script, i.e. the one that gets run on new mail by the server.

protected _cmdSetActive(string $scriptname) : mixed
Parameters
$scriptname : string

The name of the script to mark as active.

Tags
throws
Exception
Return values
mixed —

_debug()

Write debug text to the current log handler.

protected _debug(string $message) : mixed
Parameters
$message : string

Debug message text.

Return values
mixed —

_doCmd()

Send a command and retrieves a response from the server.

protected _doCmd([string $cmd = '' ][, bool $auth = false ]) : string
Parameters
$cmd : string = ''

The command to send.

$auth : bool = false

Whether this is an authentication command.

Tags
throws
Exception

if a NO response.

Return values
string —

Reponse string if an OK response.

_escape()

Converts strings into RFC's quoted-string or literal-c2s form.

protected _escape(string $string) : string
Parameters
$string : string

The string to convert.

Return values
string —

Result string.

_getBestAuthMethod()

Returns the name of the best authentication method that the server has advertised.

protected _getBestAuthMethod([string $authmethod = null ]) : string
Parameters
$authmethod : string = null

Only consider this method as available.

Tags
throws
Exception
Return values
string —

The name of the best supported authentication method.

_handleConnectAndLogin()

Connects to the server and logs in.

protected _handleConnectAndLogin() : mixed
Tags
throws
Exception
Return values
mixed —

_parseCapability()

Parses the response from the CAPABILITY command and stores the result in $_capability.

protected _parseCapability(string $data) : mixed
Parameters
$data : string

The response from the capability command.

Return values
mixed —

_recvBytes()

Receives a number of bytes from the server.

protected _recvBytes(int $length) : string
Parameters
$length : int

Number of bytes to read.

Return values
string —

The server response.

_recvLn()

Receives a single line from the server.

protected _recvLn() : string
Return values
string —

The server response line.

_sendCmd()

Sends a command to the server

protected _sendCmd(string $cmd) : mixed
Parameters
$cmd : string

The command to send.

Return values
mixed —

_sendStringResponse()

Sends a string response to the server.

protected _sendStringResponse(string $str) : mixed
Parameters
$str : string

The string to send.

Return values
mixed —

Search results