Homec4science
Diffusion libphutil (production) Browse

libphutil/src/docs/overview.diviner
5c0cb28e6e45production

Last Change
Raw File

overview.diviner
View Options

@title libphutil Overview
@group overview
This document provides a high-level introduction to libphutil.
= Overview =
**libphutil** (pronounced as "lib-futile", like the English word //futile//) is
a collection of PHP utility classes and functions which provide powerful
extensions to the standard library.
This code was originally developed at Facebook and parts of it appear in the
core libraries for <http://www.facebook.com/>.
libphutil is principally the shared library for **Arcanist** and
**Phabricator** (see <http://www.phabricator.org/>), but is suitable for
inclusion in other projects. In particular, some of the classes provided in this
library vastly improve the state of common operations in PHP, like executing
system commands.
= Module System =
libphutil defines a vaguely Python-inspired module system, which divides code
into small directories of related functions and classes called "modules" which
declare their dependencies on other modules explicitly in ##__init__.php##
files. Dependencies are generated through static analysis.
Organizing code in this way has the principle advantage that it avoids creating
a big ball of dependencies, where the whole world must be loaded to do anything,
and some secondary benefits like making the layout of code easier to understand.
This system is based on the "flib" ("Facebook Library") system originally
developed by Mark Slee and others at Facebook.
= Loading libphutil =
To include libphutil in another project, include the
##src/__phutil_library_init__.php## file:
require_once 'path/to/libphutil/src/__phutil_library_init__.php';
Now you can load libphutil modules with ##phutil_require_module()##:
phutil_require_module('libphutil', 'future/exec');
This loads the ##future/exec## module, defined in ##libphutil/src/future/exec##.
Module names and paths on disk are always identical.
NOTE: libphutil registers an autoload function with ##spl_autoload_register()##,
so you can also just use classes directly after including libphutil.
= Major Components =
The major components of libphutil are:
- **Core Utilties**: a collection of useful functions like @{function:ipull}
which simplify common data manipulation;
- **Filesystem**: classes like @{class:Filesystem} which provide a strict API
for filesystem access and throw exceptions on failure, making it easier to
write robust code which interacts with files;
- **Command Execution**: libphutil provides a powerful system command
primitive in @{class:ExecFuture} which makes it far easier to write
command-line scripts which execute system commands
(see @{article:Command Execution});
- **@{function:xsprintf}**: allows you to define ##sprintf()##-style functions
which use custom conversions; and
- **Module System**: an introspectable, inventoried system for organizing PHP
code and managing dependencies, supported by static analysis.
= Extending and Contributing =
Information on extending and contributing to libphutil is available in the
Phabricator documentation:
- to get started as a contributor, see @{article@phabricator:Contributor
Introduction}.
c4science · Help