API Documentation
\
Horde
ManageSieve
Exception

\HordeManageSieve

This class implements the ManageSieve protocol (RFC 5804).

Summary

Methods
Properties
Constants
__construct()
setLogger()
connect()
disconnect()
login()
listScripts()
getActive()
setActive()
getScript()
installScript()
removeScript()
hasSpace()
getExtensions()
hasExtension()
getAuthMechs()
hasAuthMech()
$supportedAuthMethods
$supportedSASLAuthMethods
STATE_DISCONNECTED
STATE_NON_AUTHENTICATED
STATE_AUTHENTICATED
AUTH_AUTOMATIC
AUTH_DIGESTMD5
AUTH_CRAMMD5
AUTH_LOGIN
AUTH_PLAIN
AUTH_EXTERNAL
_handleConnectAndLogin()
_cmdAuthenticate()
_authPLAIN()
_authLOGIN()
_authCRAMMD5()
_authDigestMD5()
_authEXTERNAL()
_cmdDeleteScript()
_cmdGetScript()
_cmdSetActive()
_cmdListScripts()
_cmdPutScript()
_cmdLogout()
_cmdCapability()
_parseCapability()
_sendCmd()
_sendStringResponse()
_recvLn()
_recvBytes()
_doCmd()
_getBestAuthMethod()
_checkConnected()
_checkAuthenticated()
_escape()
_debug()
$_sock
$_params
$_state
$_logger
$_maxReferralCount
N/A
No private methods found
No private properties found
N/A

Constants

STATE_DISCONNECTED

STATE_DISCONNECTED

Client is disconnected.

STATE_NON_AUTHENTICATED

STATE_NON_AUTHENTICATED

Client is connected but not authenticated.

STATE_AUTHENTICATED

STATE_AUTHENTICATED

Client is authenticated.

AUTH_AUTOMATIC

AUTH_AUTOMATIC

Authentication with the best available method.

AUTH_DIGESTMD5

AUTH_DIGESTMD5

DIGEST-MD5 authentication.

AUTH_CRAMMD5

AUTH_CRAMMD5

CRAM-MD5 authentication.

AUTH_LOGIN

AUTH_LOGIN

LOGIN authentication.

AUTH_PLAIN

AUTH_PLAIN

PLAIN authentication.

AUTH_EXTERNAL

AUTH_EXTERNAL

EXTERNAL authentication.

Properties

$supportedAuthMethods

$supportedAuthMethods : array

The authentication methods this class supports.

Can be overwritten if having problems with certain methods.

Type

array

$supportedSASLAuthMethods

$supportedSASLAuthMethods : array

SASL authentication methods that require Auth_SASL.

Type

array

$_sock

$_sock : \Horde\Socket\Client

The socket client.

Type

\Horde\Socket\Client

$_params

$_params : array

Parameters and connection information.

Type

array

$_state

$_state : integer

Current state of the connection.

One of the STATE_* constants.

Type

integer

$_logger

$_logger : string|array

Logging handler.

Type

string|array

$_maxReferralCount

$_maxReferralCount : array

Maximum number of referral loops

Type

array

Methods

__construct()

__construct(array  $params = array())

Constructor.

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

Parameters

array $params

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().

Throws

\Horde\ManageSieve\Exception

setLogger()

setLogger(object  $logger)

Passes a logger for debug logging.

Parameters

object $logger

A log handler, must implement debug().

connect()

connect(string  $host = null, string  $port = null, array  $context = null, boolean  $secure = null)

Handles connecting to the server and checks the response validity.

Defaults from the constructor are used for missing parameters.

Parameters

string $host

Hostname of server.
string $port

Port of server.
array $context

List of options to pass to stream_context_create().
boolean $secure

Security layer requested. @see __construct().

Throws

\Horde\ManageSieve\Exception

disconnect()

disconnect(boolean  $sendLogoutCMD = true)

Disconnect from the Sieve server.

Parameters

boolean $sendLogoutCMD

Whether to send LOGOUT command before disconnecting.

Throws

\Horde\ManageSieve\Exception

login()

login(string  $user = null, string  $password = null, string  $authmethod = null, string  $euser = null)

Logs into server.

Defaults from the constructor are used for missing parameters.

Parameters

string $user

Login username.
string $password

Login password.
string $authmethod

Type of login method to use.
string $euser

Effective UID (perform on behalf of $euser).

Throws

\Horde\ManageSieve\Exception

listScripts()

listScripts() : array

Returns an indexed array of scripts currently on the server.

Returns

array —

Indexed array of scriptnames.

getActive()

getActive() : string

Returns the active script.

Returns

string —

The active scriptname.

setActive()

setActive(string  $scriptname)

Sets the active script.

Parameters

string $scriptname

The name of the script to be set as active.

Throws

\Horde\ManageSieve\Exception

getScript()

getScript(string  $scriptname) : string

Retrieves a script.

Parameters

string $scriptname

The name of the script to be retrieved.

Throws

\Horde\ManageSieve\Exception

Returns

string —

The script.

installScript()

installScript(string  $scriptname, string  $script, boolean  $makeactive = false)

Adds a script to the server.

Parameters

string $scriptname

Name of the script.
string $script

The script content.
boolean $makeactive

Whether to make this the active script.

Throws

\Horde\ManageSieve\Exception

removeScript()

removeScript(string  $scriptname)

Removes a script from the server.

Parameters

string $scriptname

Name of the script.

Throws

\Horde\ManageSieve\Exception

hasSpace()

hasSpace(string  $scriptname, integer  $size) : boolean

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

Parameters

string $scriptname

The name of the script to mark as active.
integer $size

The size of the script.

Throws

\Horde\ManageSieve\Exception

Returns

boolean —

True if there is space.

getExtensions()

getExtensions() : array

Returns the list of extensions the server supports.

Throws

\Horde\ManageSieve\Exception

Returns

array —

List of extensions.

hasExtension()

hasExtension(string  $extension) : boolean

Returns whether the server supports an extension.

Parameters

string $extension

The extension to check.

Throws

\Horde\ManageSieve\Exception

Returns

boolean —

Whether the extension is supported.

getAuthMechs()

getAuthMechs() : array

Returns the list of authentication methods the server supports.

Throws

\Horde\ManageSieve\Exception

Returns

array —

List of authentication methods.

hasAuthMech()

hasAuthMech(string  $method) : boolean

Returns whether the server supports an authentication method.

Parameters

string $method

The method to check.

Throws

\Horde\ManageSieve\Exception

Returns

boolean —

Whether the method is supported.

_handleConnectAndLogin()

_handleConnectAndLogin()

Connects to the server and logs in.

Throws

\Horde\ManageSieve\Exception

_cmdAuthenticate()

_cmdAuthenticate(string  $uid, string  $pwd, string  $authmethod = null, string  $euser = '')

Handles the authentication using any known method.

Parameters

string $uid

The userid to authenticate as.
string $pwd

The password to authenticate with.
string $authmethod

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

The effective uid to authenticate as.

Throws

\Horde\ManageSieve\Exception

_authPLAIN()

_authPLAIN(string  $user, string  $pass, string  $euser)

Authenticates the user using the PLAIN method.

Parameters

string $user

The userid to authenticate as.
string $pass

The password to authenticate with.
string $euser

The effective uid to authenticate as.

Throws

\Horde\ManageSieve\Exception

_authLOGIN()

_authLOGIN(string  $user, string  $pass, string  $euser)

Authenticates the user using the LOGIN method.

Parameters

string $user

The userid to authenticate as.
string $pass

The password to authenticate with.
string $euser

The effective uid to authenticate as. Not used.

Throws

\Horde\ManageSieve\Exception

_authCRAMMD5()

_authCRAMMD5(string  $user, string  $pass, string  $euser)

Authenticates the user using the CRAM-MD5 method.

Parameters

string $user

The userid to authenticate as.
string $pass

The password to authenticate with.
string $euser

The effective uid to authenticate as. Not used.

Throws

\Horde\ManageSieve\Exception

_authDigestMD5()

_authDigestMD5(string  $user, string  $pass, string  $euser)

Authenticates the user using the DIGEST-MD5 method.

Parameters

string $user

The userid to authenticate as.
string $pass

The password to authenticate with.
string $euser

The effective uid to authenticate as.

Throws

\Horde\ManageSieve\Exception

_authEXTERNAL()

_authEXTERNAL(string  $user, string  $pass, string  $euser)

Authenticates the user using the EXTERNAL method.

Parameters

string $user

The userid to authenticate as.
string $pass

The password to authenticate with.
string $euser

The effective uid to authenticate as.

Throws

\Horde\ManageSieve\Exception

_cmdDeleteScript()

_cmdDeleteScript(string  $scriptname)

Removes a script from the server.

Parameters

string $scriptname

Name of the script to delete.

Throws

\Horde\ManageSieve\Exception

_cmdGetScript()

_cmdGetScript(string  $scriptname) : string

Retrieves the contents of the named script.

Parameters

string $scriptname

Name of the script to retrieve.

Throws

\Horde\ManageSieve\Exception

Returns

string —

The script.

_cmdSetActive()

_cmdSetActive(string  $scriptname)

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

Parameters

string $scriptname

The name of the script to mark as active.

Throws

\Horde\ManageSieve\Exception

_cmdListScripts()

_cmdListScripts() : array

Returns the list of scripts on the server.

Throws

\Horde\ManageSieve\Exception

Returns

array —

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

_cmdPutScript()

_cmdPutScript(string  $scriptname, string  $scriptdata)

Adds a script to the server.

Parameters

string $scriptname

Name of the new script.
string $scriptdata

The new script.

Throws

\Horde\ManageSieve\Exception

_cmdLogout()

_cmdLogout(boolean  $sendLogoutCMD = true)

Logs out of the server and terminates the connection.

Parameters

boolean $sendLogoutCMD

Whether to send LOGOUT command before disconnecting.

Throws

\Horde\ManageSieve\Exception

_cmdCapability()

_cmdCapability()

Sends the CAPABILITY command

Throws

\Horde\ManageSieve\Exception

_parseCapability()

_parseCapability(string  $data)

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

Parameters

string $data

The response from the capability command.

_sendCmd()

_sendCmd(string  $cmd)

Sends a command to the server

Parameters

string $cmd

The command to send.

_sendStringResponse()

_sendStringResponse(string  $str)

Sends a string response to the server.

Parameters

string $str

The string to send.

_recvLn()

_recvLn() : string

Receives a single line from the server.

Returns

string —

The server response line.

_recvBytes()

_recvBytes(integer  $length) : string

Receives a number of bytes from the server.

Parameters

integer $length

Number of bytes to read.

Returns

string —

The server response.

_doCmd()

_doCmd(string  $cmd = '', boolean  $auth = false) : string

Send a command and retrieves a response from the server.

Parameters

string $cmd

The command to send.
boolean $auth

Whether this is an authentication command.

Throws

\Horde\ManageSieve\Exception

if a NO response.

Returns

string —

Reponse string if an OK response.

_getBestAuthMethod()

_getBestAuthMethod(string  $authmethod = null) : string

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

Parameters

string $authmethod

Only consider this method as available.

Throws

\Horde\ManageSieve\Exception

Returns

string —

The name of the best supported authentication method.

_checkConnected()

_checkConnected()

Asserts that the client is in disconnected state.

Throws

\Horde\ManageSieve\Exception

_checkAuthenticated()

_checkAuthenticated()

Asserts that the client is in authenticated state.

Throws

\Horde\ManageSieve\Exception

_escape()

_escape(string  $string) : string

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

Parameters

string $string

The string to convert.

Returns

string —

Result string.

_debug()

_debug(string  $message)

Write debug text to the current log handler.

Parameters

string $message

Debug message text.