Packages — `hphp pkg`

HolyPHP ships with its own package manager. Packages are plain folders of .hphp files described by an hphp.json manifest, packed into a portable .hpx archive, and shared through a registry — which is itself a HolyPHP program (registry/server.hphp, ~250 lines).

Quick start

hphp pkg init                     # create hphp.json skeleton in this folder
hphp pkg check                    # typecheck the package's entry file
hphp pkg pack                     # build name-version.hpx into your pkg cache
hphp pkg publish                  # pack + upload to the configured registry
hphp pkg install mathx            # download + unpack into $HPHP_HOME/packages
hphp pkg remove mathx             # uninstall (alias: uninstall)
hphp pkg list                     # show installed packages
hphp pkg search clamp             # search the registry (falls back to local)
hphp pkg registry http://localhost:8930   # point the client at a registry
hphp pkg home                     # print the package home directory

The manifest: `hphp.json`

{
  "name": "mathx",
  "version": "1.0.0",
  "description": "tiny math helpers",
  "entry": "mathx.hphp",
  "author": "you"
}

entry is what hphp pkg check typechecks (defaults to <name>.hphp). Packing walks the whole package folder, so every file in it ships in the archive.

Using an installed package

hphp pkg install mathx unpacks into $HPHP_HOME/packages/mathx/. The compiler's import resolution then searches:

the importing file's directory (project-local files, e.g. lib/ui.hphp)
$HPHP_HOME/packages/<name>/ (installed packages)

// app.hphp — after: hphp pkg install mathx
import "mathx.hphp";

echo "clamped: " . clampi(42, 0, 10) . "\n";   // 10

Run your own registry

The registry is a normal HolyPHP program using the socket builtins (stream_socket_server, stream_ready, stream_recv, stream_send). It serves a browsable index, ?q= search, package downloads under /pkg/<name>, and accepts uploads via POST /publish.

cd registry
../hphp.exe run server.hphp          # listens on http://localhost:8930
HPHP_HOME=../store ../hphp.exe run server.hphp --store /var/hphp-packages

Packages live as <name>.hpx + <name>.json metadata in the store directory, so a registry can be backed up, synced, or moved to another machine by copying one folder. Point clients at it from any device:

hphp pkg registry http://your-server:8930

End-to-end walkthrough

# 1. author
mkdir mathx && cd mathx && hphp pkg init
#    ... edit mathx.hphp and hphp.json ...
hphp pkg check                        # types + borrows

# 2. share (machine A)
hphp pkg publish                      # -> uploaded to the registry

# 3. consume (machine B, same registry)
hphp pkg registry http://your-server:8930
hphp pkg install mathx
hphp run app.hphp                     # import "mathx.hphp" just works

How it works under the hood

.hpx format — a trivial tar-like container: repeated name size\n headers followed by raw payload, terminated by HPHX1. Human-readable, streamable, no dependencies.
Package home — HPHP_HOME (defaults to a per-user folder): cache/ for downloaded archives, packages/ for installed code, registry_url for the configured server.
Publish — the client packs, then POSTs the archive as application/octet-stream; the server validates the embedded manifest and stores it.
Install — the client downloads, unpacks to a temp dir, validates the manifest, then moves it into packages/<name>.

Packages — hphp pkg