Facebook’s h2tp Experimental Tool Helps Enable PHP Releases from Hack Projects

Facebook announced the experimental release of a new tool that enables projects that have converted from PHP to Hack to still offer releases that target the PHP language: h2tp, or the Hack Transpiler.

HHVMHackLogos650Facebook announced the experimental release of a new tool that enables projects that have converted from PHP to Hack to still offer releases that target the PHP language: h2tp, or the Hack Transpiler.

Software developers Vishnu Iyengar and Joshua Van Dyke Watzman announced the release of h2tp in a post on the Facebook engineering blog:

Since the launch of Hack, many community members have asked us how to manage forward compatibility. Hack is backwards-compatible with PHP — if you’re running PHP on HHVM, Hack code will seamlessly integrate with it. But the inverse is not true. Once a project has converted to Hack, there is no way to run that Hack code with the PHP5 engine. Anyone who wants to use that project needs to be able to run HHVM to run the Hack code — and leave in the dust any existing users who aren’t able to make the leap for whatever reason. This is not something most established projects are willing to do for all but the most major of major releases, and for good reason.

Because the Hack language is so close to PHP, it’s reasonable to ask if you can just mechanically convert from Hack back into PHP. Erasing type annotations is easy, but Hack is much more than just its type system. It contains many features such as collections and short lambda expressions that cannot simply be erased in order to get back valid PHP. Furthermore, any such tool would be an inferior experience to using Hack directly on HHVM, and the team didn’t want converted code to be the canonical way Hack was used. We hoped that we would be able to find some better solution to the problem — one that would not run into the aforementioned issues.

So we’ve spent the last couple of months building h2tp. It is a combination of a command line tool that transpiles your entire Hack project into PHP, and an additional library of PHP functions and classes meant to be used alongside the transpiled output.

The documentation provided with this tool highlights what we support and what we don’t. You will notice that the list of things we do not support is very small, and in the long run we do hope to support all these constructs.

Finally, we want to emphasize that while h2tp is a great way to maintain compatibility with existing installed users when doing releases, it’s not the best way to work with Hack on a daily basis. Its output is machine-generated; while it’s close enough to the original source that investigating bug reports filed by people using it won’t be a problem, it’s also not something intended to be manually edited, or for edits to be preserved in any way.

The use case that h2tp excels at is as a final build step for a project to make a backwards-compatible release. The ideal is for a project to convert to Hack, have its source of truth be in Hack, have its contributors work in Hack day-to-day, etc., and then only run h2tp as a final build step to create an alternate version of a release. When using h2tp like this, an existing project can get all the benefits of converting to Hack with none of the drawbacks of leaving existing users behind. Right now, h2tp is still experimental — try it out and give us feedback!