Interfaces

General

A class can implement a set of capabilities — herein called a contract — through what is called an interface. An interface is a set of method declarations and constants. Note that the methods are only declared, not defined; that is, an interface defines a type consisting of abstract methods, where those methods are implemented by client classes as they see fit. An interface allows unrelated classes to implement the same facilities with the same names and types without requiring those classes to share a common base class.

An interface can extend one or more other interfaces, in which case, it inherits all members from its base interface(s).

Interface Declarations

Syntax

interface-declaration:
   interface   name   interface-base-clauseopt   {   interface-member-declarationsopt   }

interface-base-clause:
   extends   qualified-name
   interface-base-clause   ,   qualified-name

Constraints

An interface must not be derived directly or indirectly from itself.

Every qualified-name must name an interface type.

Semantics

An interface-declaration defines a contract that one or more classes can implement.

Interface names are case-insensitive.

The optional interface-base-clause specifies the base interfaces from which the interface being defined is derived. In such a case, the derived interface inherits all the members from the base interfaces.

Examples

interface MyCollection
{
  const MAX_NUMBER_ITEMS = 1000;
  function put($item);
  function get();
}
class MyList implements MyCollection
{
  public function put($item)  { /* implement method */ }
  public function get()   { /* implement method */ }
  ...
}
class MyQueue implements MyCollection
{
  public function put($item)  { /* implement method */ }
  public function get()   { /* implement method */ }
  ...
}
function processCollection(MyCollection $p1)
{
  ... /* can process any object whose class implements MyCollection */
}
processCollection(new MyList(...));
processCollection(new MyQueue(...));

Interface Members

Syntax

interface-member-declarations:
   interface-member-declaration
   interface-member-declarations   interface-member-declaration

interface-member-declaration:
   class-const-declaration
   method-declaration

Semantics

The members of an interface are those specified by its interface-member-declaration, and the members inherited from its base interfaces.

An interface may contain the following members:

  • Constants – the constant values associated with the interface.
  • Methods – placeholders for the computations and actions that can be performed by implementers of the interface.

Constants

Constraints

All constants declared in an interface must be implicitly or explicitly public.

Semantics

An interface constant is just like a class constant, except that an interface constant cannot be overridden by a class that implements it nor by an interface that extends it.

Examples

interface MyCollection
{
  const MAX_NUMBER_ITEMS = 1000;
  function put($item);
  function get();
}

Methods

Constraints

All methods declared in an interface must be implicitly or explicitly public, and they must not be declared abstract.

Semantics

An interface method is just like an abstract method.

Examples

interface MyCollection
{
  const MAX_NUMBER_ITEMS = 1000;
  function put($item);
  function get();
}

Predefined Interfaces

Interface ArrayAccess

This interface allows an instance of an implementing class to be accessed using array-like notation. This interface is defined, as follows:

interface ArrayAccess
{
  function offsetExists($offset);
  function offsetGet($offset);
  function offsetSet($offset, $value);
  function offsetUnset($offset);
}

The interface members are defined below:

NamePurpose
offsetExistsThis instance method returns TRUE if the instance contains an element with key $offset, otherwise, FALSE.
offsetGetThis instance method gets the value having key $offset. It may return by value or byRef. (Ordinarily, this wouldn’t be allowed because a class implementing an interface needs to match the interface’s method signatures; however, the Engine gives special treatment to ArrayAccess and allows this). This method is called when an instance of a class that implements this interface is subscripted in a non-lvalue context.
offsetSetThis instance method sets the value having key $offset to $value. It returns no value. This method is called when an instance of a class that implements this interface is subscripted in a modifiable-lvalue context.
offsetUnsetThis instance method unsets the value having key $offset. It returns no value.

Interface Iterator

This interface allows instances of an implementing class to be treated as a collection. This interface is defined, as follows:

interface Iterator extends Traversable
{
  function current();
  function key();
  function next();
  function rewind();
  function valid();
}

The interface members are defined below:

NamePurpose
currentThis instance method returns the element at the current position.
keyThis instance method returns the key of the current element. On failure, it returns NULL; otherwise, it returns the scalar value of the key.
nextThis instance method moves the current position forward to the next element. It returns no value. From within a foreach statement, this method is called after each loop.
rewindThis instance method resets the current position to the first element. It returns no value. From within a foreach statement, this method is called once, at the beginning.
validThis instance method checks if the current position is valid. It takes no arguments. It returns a bool value of TRUE to indicate the current position is valid; FALSE, otherwise. This method is called after each call to Iterator::rewind() and Iterator::next().

Interface IteratorAggregate

This interface allows the creation of an external iterator. This interface is defined, as follows:

interface IteratorAggregate extends Traversable
{
  function getIterator();
}

The interface members are defined below:

NamePurpose
getIteratorThis instance method retrieves an iterator, which implements Iterator or Traversable. It throws an Exception on failure.

Interface Throwable

This type is the base interface for the type of any object that can be thrown via a throw statement. A user-written class cannot implement Throwable directly. Instead, it must extend Error or Exception.

This type is defined, as follows:

interface Throwable {
  function __toString(): string;
  function getCode(): int;
  function getFile(): string;
  function getLine(): int;
  function getMessage(): string;
  function getPrevious(): Throwable;
  function getTrace(): array;
  function getTraceAsString(): string;
}

The interface members are defined below:

NamePurpose
__toStringstring; retrieves a string representation of the exception in some unspecified format
getCodeint; retrieves the exception code
getFilestring; retrieves the name of the script where the exception was generated
getLineint; retrieves the source line number in the script where the exception was generated
getMessagestring; retrieves the exception message
getPreviousThrowable; retrieves the previous exception, if one exists; otherwise returns NULL
getTracearray; retrieves the function stack trace information as an array
getTraceAsStringstring; retrieves the function stack trace information formatted as a single string in some unspecified format

Interface Traversable

This interface is intended as the base interface for all traversable classes. This interface is defined, as follows:

interface Traversable
{
}

This interface has no members.

Interface Serializable

This interface provides support for custom serialization. It is defined, as follows:

interface Serializable
{
  function serialize();
  function unserialize ($serialized);

}

The interface members are defined below:

NamePurpose
serializeThis instance method returns a string representation of the current instance. On failure, it returns NULL.
unserializeThis instance method constructs an object from its string form designated by $serialized. It does not return a value.