Differential D20980 Diff 49996 src/docs/article/overview.diviner

Changeset View

Standalone View

src/docs/article/overview.diviner

This file was added.

				@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. Most code in the library is
				general-purpose, and makes it easier to build applications in PHP.

				libphutil is principally the shared library for
				[[ http://www.phabricator.org \| Phabricator ]] and its CLI Arcanist, 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.

				libphutil is developed and maintained by
				[[ http://www.phacility.com/ \| Phacility ]]. Some of the code in this library
				was originally developed at Facebook, and parts of it appear in the core
				libraries for <http://www.facebook.com/>.

				= 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';

				This loads global functions and registers an autoload function with
				`spl_autoload_register()`, so you can also use classes.

				= Major Components =

				Some of the major components of libphutil are:

				- Core Utilities: 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
				- Library 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@phabcontrib:Contributor
				Introduction}.