phorge-phorge/src/docs/userguide/libraries.diviner

@title libphutil Libraries User Guide
@group userguide

Guide to creating and managing libphutil libraries.

= Overview =

libphutil includes a library system which organizes PHP classes and functions
into modules. Some extensions and customizations of Arcanist and Phabricator
require you to make code available to Phabricator by providing it in a libphutil
library.

For example, if you want to store files in some kind of custom storage engine,
you need to write a class which can interact with that engine and then tell
Phabricator to load it.

In general, you perform these one-time setup steps:

  - Create a new directory.
  - Use ##arc liberate## to initialize and name the library.
  - Add a dependency on Phabricator if necessary.
  - Add the library to your Phabricator config or ##.arcconfig## so it will be
    loaded at runtime.

Then, to add new code, you do this:

  - Write or update classes.
  - Update the library metadata by running ##arc liberate## again.

= Creating a New Library =

To **create a new libphutil library**:

  $ mkdir libcustom/
  $ cd libcustom/
  libcustom/ $ arc liberate src/

Now you'll get a prompt like this:

  No library currently exists at that path...
  The directory '/some/path/libcustom/src' does not exist.

    Do you want to create it? [y/N] y
  Creating new libphutil library in '/some/path/libcustom/src'.
  Choose a name for the new library.

    What do you want to name this library?

Choose a library name (in this case, "libcustom" would be appropriate) and it
you should get some details about the library initialization:

  Writing '__phutil_library_init__.php' to
    '/some/path/libcustom/src/__phutil_library_init__.php'...
  Using library root at 'src'...
  Mapping library...
  Verifying library...
  Finalizing library map...
    OKAY   Library updated.

This will write three files:

  - ##src/.phutil_module_cache## This is a cache which makes "arc liberate"
    faster when you run it to update the library. You can safely remove it at
    any time. If you check your library into version control, you can add this
    file to ignore rules (like .gitignore).
  - ##src/__phutil_library_init__.php## This records the name of the library and
    tells libphutil that a library exists here.
  - ##src/__phutil_library_map__.php## This is a map of all the symbols
    (functions and classes) in the library, which allows them to be autoloaded
    at runtime and dependencies to be statically managed by "arc liberate".

= Linking with Phabricator =

If you aren't using this library with Phabricator (e.g., you are only using it
with Arcanist or are building something else on libphutil) you can skip this
step.

But, if you intend to use this library with Phabricator, you need to define its
dependency on Phabricator by creating a ##.arcconfig## file which points at
Phabricator. For example, you might write this file to
##libcustom/.arcconfig##:

  {
    "project_id" : "libcustom",
    "phutil_libraries" : {
      "phabricator" : "phabricator/src/"
    }
  }

For details on creating a ##.arcconfig##, see
@{article:Arcanist User Guide: Configuring a New Project}. In general, this
tells ##arc liberate## that it should look for symbols in Phabricator when
performing static analysis.

NOTE: If Phabricator isn't located next to your custom library, specify a
path which actually points to the ##phabricator/## directory.

You do not need to declare dependencies on ##arcanist## or ##libphutil##,
since ##arc liberate## automatically loads them.

Finally, edit your Phabricator config to tell it to load your library at
runtime, by adding it to ##load-libraries##:

  ...
  'load-libraries' => array(
    'libcustom' => 'libcustom/src/',
  ),
  ...

Now, Phabricator will be able to load classes from your custom library.

= Writing Classes =

To actually write classes, create a new module and put code in it:

  libcustom/ $ mkdir src/example/
  libcustom/ $ nano src/example/ExampleClass.php # Edit some code.

Now, run ##arc liberate## to regenerate the static resource map:

  libcustom/ $ arc liberate src/

This will automatically create and update ##__init__.php## files, and regenerate
the static map of the library.