---
title: "Operations"
url: https://docs.zeroc.com/ice/3.8/slice/operations
language: php
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# Operations

Programming language: PHP. Other languages: [C++](https://docs.zeroc.com/ice/3.8/slice/operations/cpp.md), [C#](https://docs.zeroc.com/ice/3.8/slice/operations/csharp.md), [Java](https://docs.zeroc.com/ice/3.8/slice/operations/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/slice/operations/js.md), [MATLAB](https://docs.zeroc.com/ice/3.8/slice/operations/matlab.md), [Python](https://docs.zeroc.com/ice/3.8/slice/operations/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/slice/operations/ruby.md), [Swift](https://docs.zeroc.com/ice/3.8/slice/operations/swift.md).

## Operation Syntax

An operation definition has a name, a return type, and zero or more parameters.

For example:

```slice
module M
{
    struct TimeOfDay
    {
        short hour;         // 0 - 23
        short minute;       // 0 - 59
        short second;       // 0 - 59
    }

    interface Clock
    {
        TimeOfDay getTime();
        void setTime(TimeOfDay time);
    }
}
```

An operation that returns no value, such as `setTime`, declares `void` as its return type.

Parameters are input parameters by default: their values go from the client to the server. An output parameter, marked with the `out` keyword, carries a value from the server back to the client. An operation can have several input and output parameters, and its output parameters must follow its input parameters:

```slice
module M
{
    interface CircadianRhythm
    {
        void setSleepPeriod(TimeOfDay startTime, TimeOfDay stopTime);
        void getSleepPeriod(out TimeOfDay startTime, out TimeOfDay stopTime);
        void changeSleepPeriod(
            TimeOfDay startTime,
            TimeOfDay stopTime,
            out TimeOfDay prevStartTime,
            out TimeOfDay prevStopTime);
    }
}
```

Each parameter must have a name, and a parameter cannot be both an input and an output parameter.

## Optional Parameters and Return Values

An operation's return value and parameters may be declared as optional to indicate that a program can leave their values unset. Parameters not declared as optional are known as *required* parameters. In the discussion below, we use *parameter* to refer to input parameters, output parameters, and return values.

A unique, non-negative integer *tag* must be assigned to each optional parameter:

```slice
optional(3) bool example(optional(2) string name, out optional(1) int value);
```

The scope of a tag is limited to its operation and has no effect on other operations. You can assign tags in any order.

An optional parameter cannot have a class type, or a constructed type that holds a class type.

An operation's signature can include any combination of required and optional parameters, but output parameters still must follow input parameters:

```slice
bool example(
    string name,
    optional(3) string referrer,
    out optional(1) string promo,
    out int id);
```

Language mappings specify an API for passing optional parameters and testing whether a parameter is present.

## Exception Specifications

An operation lists the user exceptions it can throw in its [exception specification](https://docs.zeroc.com/ice/3.8/slice/exceptions/php.md#exception-specification-in-operations), a `throws` clause.

## Overloading Operations

Slice does not support overloading: operations in the same interface must have different names, regardless of the type and number of their parameters. A request identifies the operation it invokes by name only.

## Idempotent Operations

An operation is idempotent when calling it several times with the same arguments has the same effect as calling it once. Operations that do not modify the state of the object, such as `getTime` in the `Clock` interface, are idempotent; so is `setTime`, even though it modifies the state. You mark such operations with the `idempotent` keyword:

```slice
interface Clock
{
    idempotent TimeOfDay getTime();
    idempotent void setTime(TimeOfDay time);
}
```

The `idempotent` keyword makes this property part of the contract: the implementation must keep the operation idempotent, and callers can rely on it. Ice relies on it to retry invocations it would not retry otherwise; see [Automatic Retries](https://docs.zeroc.com/ice/3.8/runtime/invocation/automatic-retries/php.md).

## Client-Side Mapping for Operations

### Mapping for Operations

As we saw in the [Client-Side PHP Mapping for Interfaces](https://docs.zeroc.com/ice/3.8/slice/interfaces/php.md#client-side-mapping-for-interfaces), for each operation on an interface, a proxy for that interface supports a method with the same name. To invoke an operation, you call it via the proxy. For example, here is our definition from the [greeter example](https://docs.zeroc.com/ice/3.8/greeter-example/defining-the-greeter-interface-in-slice/php.md):

```slice
module VisitorCenter
{
    interface Greeter
    {
        string greet(string name);
    }
}
```

Given a proxy to an object of type `Greeter`, the client can invoke the `greet` operation as follows:

```php
$greeter = VisitorCenter\GreeterPrxHelper::createProxy(
    $communicator, 'greeter:tcp -h localhost -p 4061');

$greeting = $greeter->greet('Alice');  // Get name via RPC
```

### Exception Handling

Any operation invocation may throw a [runtime exception](https://docs.zeroc.com/ice/3.8/runtime/local-and-dispatch-exceptions/php.md) and, if the operation has an exception specification, may also throw [user exceptions](https://docs.zeroc.com/ice/3.8/runtime/local-and-dispatch-exceptions/php.md). Suppose we have the following simple interface:

```slice
exception Tantrum
{
    string reason;
}

interface Child
{
    void askToCleanUp() throws Tantrum;
}
```

Slice exceptions are thrown as PHP exceptions, so you can simply enclose one or more operation invocations in a `try-catch` block:

```php
$child = ...        // Get child proxy...

try {
    $child->askToCleanUp();
} catch(Tantrum $t) {
    echo "The child says: " . $t->reason . "\n";
}
```

## Mapping for Parameters and Return Values

### In Parameters

The PHP mapping for `in` parameters guarantees that the value of a parameter will not be changed by the invocation.

Here is an interface with operations that pass parameters of various types from client to server:

```slice
struct NumberAndString
{
    int x;
    string str;
}

sequence<string> StringSeq;

dictionary<long, StringSeq> StringTable;

interface ClientToServer
{
    void op1(int i, float f, bool b, string s);
    void op2(NumberAndString ns, StringSeq ss, StringTable st);
    void op3(ClientToServer* proxy);
}
```

The Ice extension gives a `ClientToServer` proxy the following methods:

```php
function op1($i, $f, $b, $s);
function op2($ns, $ss, $st);
function op3($proxy);
```

Each method also accepts an optional last argument: an associative array that holds the [request context](https://docs.zeroc.com/ice/3.8/runtime/invocation/request-contexts/explicit-request-contexts/php.md) of the invocation.

Given a proxy to a `ClientToServer` object, the client code can pass parameters as in the following example:

```php
$p = ...                                 // Get proxy...

$p->op1(42, 3.14, true, "Hello world!"); // Pass simple literals

$i = 42;
$f = 3.14;
$b = true;
$s = "Hello world!";
$p->op1($i, $f, $b, $s);                 // Pass simple variables

$ns = new NumberAndString;
$ns->x = 42;
$ns->str = "The Answer";
$ss = array("Hello world!");
$st = array();
$st[0] = $ss;
$p->op2($ns, $ss, $st);                  // Pass complex variables

$p->op3($p);                             // Pass proxy
```

### Out Parameters and Return Values

A method returns the operation's return value, and assigns each out parameter to the variable you pass by reference. Here again are the same Slice definitions we saw earlier, but this time with all parameters being passed in the `out` direction, and with `op1` returning a value:

```slice
struct NumberAndString
{
    int x;
    string str;
}

sequence<string> StringSeq;

dictionary<long, StringSeq> StringTable;

interface ServerToClient
{
    int op1(out float f, out bool b, out string s);
    void op2(out NumberAndString ns,
             out StringSeq ss,
             out StringTable st);
    void op3(out ServerToClient* proxy);
}
```

The Ice extension gives a `ServerToClient` proxy the following methods:

```php
function op1(&$f, &$b, &$s);
function op2(&$ns, &$ss, &$st);
function op3(&$proxy);
```

These methods also accept the optional request context argument after the out parameters.

Given a proxy to a `ServerToClient` object, the client code can receive the results as in the following example:

```php
$p = ...                 // Get proxy...
$i = $p->op1($f, $b, $s);
$p->op2($ns, $ss, $st);
$p->op3($stcp);
```

### Parameter Type Mismatches

Ice validates the arguments to a proxy invocation at runtime and reports any type mismatches as a `InvalidArgumentException` exception.

### Null Parameters

Slice strings, sequences, and dictionaries have no null value. When you pass `null` for one of these types, whether as a parameter, a field, or a sequence element, Ice sends an empty string, sequence, or dictionary.

### Optional Parameters

[Optional parameters](#optional-parameters-and-return-values) use the same mapping as required parameters. The only difference is that `Ice\None` can be passed as the value of an optional parameter or return value. Consider the following operation:

```slice
optional(1) int execute(optional(2) string params, out optional(3) float value);
```

A client can invoke this operation as shown below:

```php
$i = $proxy->execute("--file log.txt", $v);
$i = $proxy->execute(\Ice\None, $v);

if($v != \Ice\None)
{
    echo "value = " . $v . "\n";
}
```

A well-behaved program must always compare an optional parameter to `\Ice\None` prior to using its value. Keep in mind that the `\Ice\None` marker value has different semantics than `null`. Since `null` is a legal value for certain Slice types, the Ice runtime requires a separate marker value so that it can determine whether an optional parameter is set. An optional parameter set to `null` is considered to be set.
