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 regenerate the static map of the library.

= What You Can Extend And Invoke =

libphutil, Arcanist and Phabricator are strict about extensibility of classes
and visibility of methods and properties. Most classes are marked ##final##, and
methods have the minimum required visibility (protected or private). The goal of
this strictness is to make it clear what you can safely extend, access, and
invoke, so your code will keep working as the upstream changes.

When developing libraries to work with libphutil, Arcanist and Phabricator, you
should respect method and property visibility and extend only classes marked
##@stable##. They are rendered with a large callout in the documentation (for
example: @{class@libphutil:AbstractDirectedGraph}). These classes are external
interfaces intended for extension.

If you want to extend a class but it is not marked ##@stable##, here are some
approaches you can take:

  - Good: If possible, use composition rather than extension to build your
    feature.
  - Good: Check the documentation for a better way to accomplish what you're
    trying to do.
  - Good: Let us know what your use case is so we can make the class tree more
    flexible or configurable, or point you at the right way to do whatever
    you're trying to do, or explain why we don't let you do it.
  - Discouraged: Send us a patch removing "final" (or turning "protected" or
    "private" into "public"). We generally will not accept these patches, unless
    there's a good reason that the current behavior is wrong.
  - Discouraged: Create an ad-hoc local fork and remove "final" in your copy of
    the code. This will make it more difficult for you to upgrade in the future.
  - Discouraged: Use Reflection to violate visibility keywords.