DocumentationhackLearnGetting StartedGetting Started

Getting Started

If you are new to Hack, this getting started guide should help you get familiar with the basics quickly; if you haven't yet please read our introduction to Hack's main features and afterwards you can dive deeper into topics of interest to gain more knowledge on what Hack has to offer.

Overview

The prerequisites you need to write and execute Hack code is pretty straightforward:

The HHVM runtime
The Hack typechecker (included as part of the build of the HHVM runtime)
Optionally, a Hack-aware editor. We recommend Nuclide, with its first-class support for Hack.

The HHVM runtime is required for both (1) executing Hack code (2) to run the Hack typechecker, which is the cornerstone benefit of using the Hack language -- to make sure your code is well written, safe and consistent.

Try our Interactive Hack Tutorial

You can actually start learning Hack without having to install any software. Just head over to the interactive Hack tutorial to learn step-by-step about some of the Hack features.

Your First Hack Program

Let's dive right in and create your first Hack program in five simple steps.

1. Install HHVM and the Typechecker

Check out the HHVM getting started guide on how to install HHVM.

After you install HHVM, the Hack typechecker will be available to you to statically check your code before you run it. It is not a compiler; but rather a super-fast code analyzer that tries to catch dynamic programming errors before code is run instead of during or after.

The typechecker is called hh_client and is available by default alongside HHVM in all official packages supported by the HHVM team. If you are using a community-contributed package, hh_client is very likely available there too, but you should check with your package maintainer.

2. Setup for the Typechecker

Choose a directory where you want to store your Hack code. In this directory, run touch .hhconfig. This creates an empty file that hh_client looks for as the root of your code to being typechecking. In order to properly analyze your code, the typechecker needs to do global analysis and be able to see all of your code. This means that it assumes a global autoloader for any code under this root, and checks all code recursively under this root together as one project.

3. Write your first Hack program

Using the editor of your choice (e.g., Nuclide, vim, Sublime Text), let's create a file called first.php with the following code:

<?hh

namespace Hack\UserDocumentation\Quickstart\Examples\First;

class Box<T> {
  public function __construct(private T $elem) {
  }

  public function get(): T {
    return $this->elem;
  }
}

function get_int(): int {
  return 42;
}

function use_box(): void {
  $box = new Box(get_int());
  $i = $box->get();
  var_dump($i);
}

use_box();

This getting started guide assumes some knowledge of programming (e.g., what a class is, what a function or method is, etc.). If you are familiar with PHP, Hack has a similar look and feel. If you are not familiar with PHP, then all of this is new, but hopefully the general constructs are familiar to you. The comments provide various details, but here are the key points:

This example creates a class called Box.
The Box class is generic.
Constructor parameter promotion was used on the class constructor.
Type annotations were used everywhere, for function parameters and return types.

4. Run the Typechecker

If you are using an editor like Nuclide, you will be seeing typechecking information as you write the program. If you run the typechecker from the command line, the command is just:

% hh_client

You should see:

No errors!

Now imagine if we changed the return type of get_int() to be a bool instead of an int. If you run the typechecker, you will see something like this:

first.php:15:10,11: Invalid return type (Typing[4110])
  first.php:14:21,24: This is a bool
  first.php:15:10,11: It is incompatible with an int

This demonstrates the power of the Hack type system and typechecker: it lets you know that you might not be returning what you think you are returning. The typechecker makes these checks all over your codebase, for all your code, without having to run it.

5. Run the code in HHVM

After you get your Hack program to typecheck clean with no errors, you can then run the program in HHVM.

% hhvm first.php

And here is the output:

int(42)

Learn More

Now that you have gotten your feet wet with a simple Hack program, the best resource for continuing to learn Hack is to keep reading our official Hack documentation. Here are the best places to start:

There is also an awesome book on HHVM and Hack, written by an engineer on the HHVM team. For PHP, PHP's documentation contains an introduction to PHP, and there are numerous tutorials online. Hack has an online interactive tutorial as well.

CollectionsOverview:

IntroductionTools: