PHPackages                             hershel-theodore-layton/pragma - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. hershel-theodore-layton/pragma

ActiveLibrary

hershel-theodore-layton/pragma
==============================

A structured way of embedding source analyzer metadata in Hack

v0.4.0(7mo ago)012.8k↑50.9%4MITHackCI passing

Since Jan 14Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/hershel-theodore-layton/pragma)[ Packagist](https://packagist.org/packages/hershel-theodore-layton/pragma)[ RSS](/packages/hershel-theodore-layton-pragma/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (4)Dependencies (2)Versions (5)Used By (4)

Pragma
======

[](#pragma)

*A structured way of embedding source analyzer metadata in Hack.*

How to use
----------

[](#how-to-use)

```
// You must use use statements in exactly this form.
// `use namespace` or use statements with an `as` are not allowed.
use type HTL\Pragma\Pragmas;
use function HTL\Pragma\pragma;

// Apply an effect to an entire file.
>

// Apply an effect to a class.
>
final class Example implements Printable {
  public function print(): string {
    // Apply an effect to the next line.
    pragma('CodingStandards', 'refused_bequest=ignore');
    throw new Exception();
  }
}
```

For details on the strings passed to `pragma(...)` and `Pragmas(vec[...])`, read the documentation of the source analyzer.

For implementers
----------------

[](#for-implementers)

This package contains one class and one function:

- The `pragma` function, also known as the `pragma` directive.
- The `Pragmas` class, also known as the `Pragmas` attribute.

They are general replacements for structured comments.

```
// @lint-ignore[unused-pure-expression]
1 + 1;
```

`@lint-ignore` isn't a normal comment from the perspective of some tool. It suppresses a lint error from being raised for an unused pure expression.

I subscribe wholehartedly to the following quote from the [CppCoreGuidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines):

```
Compilers don’t read comments ... and neither do many programmers (consistently).

```

If over half of the comments in a project are to silence some tool, be it the Hack typechecker or a linter, programmers will be even more inclined to skip reading the comments. It will instill fear for removing useless comments, since some tool might rely on them.

The idea behind the `pragma(...)` directive is to eliminate these comments. The following code block expersses the same intent.

```
pragma('LinterFramework', 'ignore:unused-pure-expression');
1 + 1;
```

Q: Why would this string-based system be better than actual attributes?

- A: If your source code analyzer is a dev-dependency, you'd need to either:
    - Publish the attributes in a different package, to make production code typecheck without the source analyzer in the vendor/ directory.
    - Deploy the source analyzer code to production.
- The first user of this standard is [PhaLinters](https://github.com/hershel-theodore-layton/portable-hack-ast-linters)This is a dev-dependency with a single directive at the time of writing. The `pragma(...)` directive is preferred over the `Pragmas` annotation. By shipping `pragma` as standalone, PhaLinters can be a proper dev-dependency.

If you wish to accept `pragma(...)` directives and ``attributes in your own source analyzers, read [pragma.hack](./src/pragma.hack)for the details for this informal standard.

###  Health Score

39

—

LowBetter than 86% of packages

Maintenance75

Regular maintenance activity

Popularity25

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~211 days

Total

4

Last Release

220d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d16d159b7061287c506d4ab44d05ae042bc4ec697116d1bd132a007634d9ff21?d=identicon)[Hershel Theodore Layton](/maintainers/Hershel%20Theodore%20Layton)

---

Top Contributors

[![hershel-theodore-layton](https://avatars.githubusercontent.com/u/81193606?v=4)](https://github.com/hershel-theodore-layton "hershel-theodore-layton (23 commits)")

### Embed Badge

![Health badge](/badges/hershel-theodore-layton-pragma/health.svg)

```
[![Health](https://phpackages.com/badges/hershel-theodore-layton-pragma/health.svg)](https://phpackages.com/packages/hershel-theodore-layton-pragma)
```

###  Alternatives

[hhvm/hsl

The Hack Standard Library

1151.1M55](/packages/hhvm-hsl)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)