README.md 3.11 KB
Newer Older
1 2
# HHI files for PHPUnit

3 4
[![build status][build-image]][build-link]

5 6 7 8 9 10 11 12 13 14 15
This package provides HHI files for the main [PHPUnit package][phpunit]. It does
not provide any runtime functionality.

HHI files are files which tell the Hack tools about non-Hack code, providing the
necessary names and types to allow Hack to make sure you're using the non-Hack
code correctly.

## Installation

The easiest way to install this package is with [Composer][composer].

Simon Welsh's avatar
Simon Welsh committed
16
To do so, add `"91carriage/phpunit-hhi": "~6.2.0"` to the `require-dev` section
17
of your `composer.json` or run
Simon Welsh's avatar
Simon Welsh committed
18
`composer require --dev '91carriage/phpunit-hhi:~6.2.0'`.
19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44

It is not recommended to install this as part of your `requires` section as it
should only be used during development.

Manual installation simply involves downloading the provided source code and
copying it into your repository.

## Issues

Issues can be submitted to the [issue tacker][issues].

If you are unable to create an issue through this, or think that it should not
be publicly disclosed, they can also be emailed directly to
[issues@91carriage.com][issue-email] or brought to my attention on IRC, where I
go by the handles `simon_w` and `simon_w|air` in the offical [#hhvm][hhvm-irc]
channel on FreeNode.

## Contributing

Contributions are very welcome. Please make sure that you run `hh_client` in the
source directory with `assume_php=false` in your `.hhconfig` and no errors are
reported.

### Code style

For Hack files, the coding style is enforced by the `hh_format` command, which
45 46
is included with the Hack tools alongside `hh_client`. As the HHI files are decl
files, you need to run `hh_format` with the `--yolo` option for these files.
47 48 49 50 51 52 53 54

For other files, the basic requirements are:
* Lines are no more than 80 characters wherever possible.
* Indentation is 2 spaces.
* Unix-style (`\n`) line endings.

### File types

55 56 57
* The HHI files should all be in [decl mode][decl-mode].
* The test files should extend `HHITest` and be in [strict mode][strict-mode].
* The HHIT files should be in [strict mode][strict-mode].
58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77

### Non-existent class types

If an object type is required and that object is in a different package or is
built into HHVM and doesn't yet have a HHI file, add the expected type as a
comment.

For example, if the function `foo` returns a `SplObject` and there's no inbuilt
HHI file for `SplObject`, the definition of `foo` would be:

```
function foo() /*: SplObject*/;
```

## License

This code is provided under the MIT (X11 variant) license. The full text of
which can be found in the [LICENSE.md](LICENSE.md) file.

<!-- Please keep these sorted alphabetically. -->
Simon Welsh's avatar
Simon Welsh committed
78 79
[build-image]: https://git.simon.geek.nz/91-carriage/phpunit-hhi/badges/phpunit-6.2/build.svg
[build-link]: https://git.simon.geek.nz/91-carriage/phpunit-hhi/commits/phpunit-6.2
80
[composer]: https://getcomposer.org/
Simon Welsh's avatar
Simon Welsh committed
81
[decl-mode]: http://docs.hhvm.com/hack/typechecker/modes#decl-mode
82
[strict-mode]: http://docs.hhvm.com/hack/typechecker/modes#strict-mode
83 84 85 86
[hhvm-irc]: http://webchat.freenode.net/?channels=hhvm
[issue-email]: mailto:issues@91carriage.com
[issues]: https://git.simon.geek.nz/91-carriage/phpunit-hhi/issues
[phpunit]: https://phpunit.de/