Types: Type Refinement

A supertype has one or more subtypes, and while any operation permitted on a value of some supertype is also permitted on a value of any of its subtypes, the reverse is not true. For example, the type num is a supertype of int and float, and while addition and subtraction are well defined for all three types, bit shifting requires integer operands. As such, a num cannot be bit-shifted directly. (Similar situations occur with arraykey and its subtypes int and string, with nullable types and their subtypes, and with mixed and its subtypes.)

Certain program elements are capable of changing the type of an expression using what is called type refinement. Consider the following:

function f1(?int $p): void {
  //  $x = $p % 3;       // rejected; % not defined for ?int
  if ($p is int) { // type refinement occurs; $p has type int
    $x = $p % 3; // accepted; % defined for int
  }
}

When the function starts execution, $p contains null or some int. However, the type of the expression $p is not known to be int, so it is not safe to allow the % operator to be applied. When the test is int is applied to $p, a type refinement occurs in which the type of the expression $p is changed to int for the true path of the if statement only. As such, the % operator can be applied. However, once execution flows out of the if statement, the type of the expression $p is ?int.

Consider the following:

function f2(?int $p): void {
  if ($p is null) { // type refinement occurs; $p has type null
    //    $x = $p % 3;      // rejected; % not defined for null
  } else { // type refinement occurs; $p has type int
    $x = $p % 3; // accepted; % defined for int
  }
}

The first assignment is rejected, not because we don't know $p's type, but because we know its type is not int. See how an opposite type refinement occurs with the else. Similarly, we can write the following:

function f3(?int $p): void {
  if (!$p is null) { // type refinement occurs; $p has type int
    $x = $p % 3; // accepted; % defined for int
  }

  if ($p is nonnull) { // type refinement occurs; $p has type int
    $x = $p % 3; // accepted; % defined for int
  }
}

Consider the following example that contains multiple selection criteria:

function f4(?num $p): void {
  if (($p is int) || ($p is float)) {
    //    $x = $p**2;    // rejected
  }
}

An implementation is not required to produce the correct type refinement when using multiple criteria directly.

The following constructs involve type refinement:

• When used as the controlling expression in an if, while, or for statement, the operators ==, !=, ===, and !== when used with one operand of null, is, and simple assignment =. [Note that if $x is an expression of some nullable type, the logical test if ($x) is equivalent to if ($x is nonnull).]
• The operators &&, ||, and ?:.
• The intrinsic function invariant.
• Some built-in functions like Shapes::keyExists() and \HH\is_any_array() have special typechecking rules, but others, like is_string() and is_null() don't.

Thus far, all the examples use the value of an expression that designates a parameter (which is a local variable). Consider the following case, which involves a property:

class C {
  private ?int $p = 8; // holds an int, but type is ?int
  public function m(): void {
    if ($this->p is int) { // type refinement occurs; $this->p is int
      $x = $this->p << 2; // allowed; type is int
      $this->n(); // could involve a permanent type refinement on $p
      //      $x = $this->p << 2;   // disallowed; might no longer be int
    }
  }
  public function n(): void { /* ... */ }
}

Inside the true path of the if statement, even though we know that $this->p is an int to begin with, once any method in this class is called, the implementation must assume that method could have caused a type refinement on anything currently in scope. As a result, the second attempt to left shift is rejected.