Types: Introduction

In conjunction with the typechecker, the Hack language's typing capabilities is the cornerstone for every other Hack feature that is available. The primary motivation for the development of the Hack language was to be able to explicitly type various parts of your code, such that the code could be analyzed for type consistency and possible errors.

Take this pre-Hack example:

<?php

namespace Hack\UserDocumentation\Types\Intro\Examples\PreHack;

class Z {}
class A {
  public $a;
  public $b;

  public function __construct($a, $b) {
    $this->a = $a;
    $this->b = $b;
  }

  public function foo($x, $y) {
    return $x * $this->a + $y * $this->b;
  }
}

function bar(A $a, $x, $y) {
  return $a->foo($x, $y);
}

function baz() {
  $a = new A(2, 4);
  $z = new Z();
  var_dump(bar($a, 9, 4));
  // Did we really want to allow passing a stringy int?
  var_dump(bar($a, 8, "3"));
  // Did we really want to allow passing booleans?
  var_dump(bar($a, true, false));
  // This will throw a fatal at runtime
  var_dump(bar($z, 1, 1));
}

baz();
Output
int(34)
int(28)
int(2)

Catchable fatal error: Argument 1 passed to Hack\UserDocumentation\Types\Intro\Examples\PreHack\bar() must be an instance of Hack\UserDocumentation\Types\Intro\Examples\PreHack\A, Hack\UserDocumentation\Types\Intro\Examples\PreHack\Z given in /data/users/joelm/user-documentation/guides/hack/20-types/01-introduction-examples/pre-hack.php on line 22

The above example is a perfectly valid program that will run on HHVM (except a fatal that will occur in the last var_dump). However, it is unclear as to the intent of the programmer in many cases. For example, did the programmer really want to allow A::foo() to accept string-like ints. Of course, mitigation can occur through the use of checks like is_int() or exception throwing.

But look at this next example to see how much clearer the intent was.

<?hh

namespace Hack\UserDocumentation\Types\Intro\Examples\Hack;

class Z {}
class A {
  public int $a;
  public int $b;

  public function __construct(int $a, int $b) {
    $this->a = $a;
    $this->b = $b;
  }

  public function foo(int $x, int $y): int {
    return $x * $this->a + $y * $this->b;
  }
}

function bar(A $a, int $x, int $y): int {
  return $a->foo($x, $y);
}

function baz(): void {
  $a = new A(2, 4);
  $z = new Z();
  var_dump(bar($a, 9, 4));
  // Did we really want to allow passing a stringy int? NO!
  // The typechecker will actually error here before you even run the program,
  // so you can catch problems before runtime.
  var_dump(bar($a, 8, "3"));

  // Did we really want to allow passing booleans? NO!
  // The typechecker will error here too.
  var_dump(bar($a, true, false));

  // This will throw a fatal at runtime
  // The typechecker will error here as well
  var_dump(bar($z, 1, 1));
}

baz();

/****

Type checker errors:

hack.php:29:23,25: Invalid argument (Typing[4110])
  hack.php:20:28,30: This is an int
  hack.php:29:23,25: It is incompatible with a string
hack.php:31:20,23: Invalid argument (Typing[4110])
  hack.php:20:20,22: This is an int
  hack.php:31:20,23: It is incompatible with a bool
hack.php:31:26,30: Invalid argument (Typing[4110])
  hack.php:20:28,30: This is an int
  hack.php:31:26,30: It is incompatible with a bool
hack.php:33:16,17: Invalid argument (Typing[4110])
  hack.php:20:14,14: This is an object of type
                     Hack\UserDocumentation\Types\Intro\Examples\Hack\A
  hack.php:26:8,14: It is incompatible with an object of type
                    Hack\UserDocumentation\Types\Intro\Examples\Hack\Z
*****/
Output
int(34)

Catchable fatal error: Argument 3 passed to Hack\UserDocumentation\Types\Intro\Examples\Hack\bar() must be an instance of int, string given in /data/users/joelm/user-documentation/guides/hack/20-types/01-introduction-examples/hack.php.type-errors on line 22

Now we can see that the intent was to have only ints passed. And while the program will still run just like in the previous example, users of this API will now know what is expected. Combine adding these explicit types to methods and properties with the Hack typechecker, you have a real strong foundation for safe, dynamic programming.

To get a better feel for what types you can use in your code, and where and how to place your explicit type annotations, check out: