[Summary view] [Print] [Text view]

   1  @title libphutil Libraries User Guide
   2  @group userguide
   3  
   4  Guide to creating and managing libphutil libraries.
   5  
   6  = Overview =
   7  
   8  libphutil includes a library system which organizes PHP classes and functions
   9  into modules. Some extensions and customizations of Arcanist and Phabricator
  10  require you to make code available to Phabricator by providing it in a libphutil
  11  library.
  12  
  13  For example, if you want to store files in some kind of custom storage engine,
  14  you need to write a class which can interact with that engine and then tell
  15  Phabricator to load it.
  16  
  17  In general, you perform these one-time setup steps:
  18  
  19    - Create a new directory.
  20    - Use ##arc liberate## to initialize and name the library.
  21    - Add a dependency on Phabricator if necessary.
  22    - Add the library to your Phabricator config or ##.arcconfig## so it will be
  23      loaded at runtime.
  24  
  25  Then, to add new code, you do this:
  26  
  27    - Write or update classes.
  28    - Update the library metadata by running ##arc liberate## again.
  29  
  30  = Creating a New Library =
  31  
  32  To **create a new libphutil library**:
  33  
  34    $ mkdir libcustom/
  35    $ cd libcustom/
  36    libcustom/ $ arc liberate src/
  37  
  38  Now you'll get a prompt like this:
  39  
  40    lang=txt
  41    No library currently exists at that path...
  42    The directory '/some/path/libcustom/src' does not exist.
  43  
  44      Do you want to create it? [y/N] y
  45    Creating new libphutil library in '/some/path/libcustom/src'.
  46    Choose a name for the new library.
  47  
  48      What do you want to name this library?
  49  
  50  Choose a library name (in this case, "libcustom" would be appropriate) and it
  51  you should get some details about the library initialization:
  52  
  53    lang=txt
  54    Writing '__phutil_library_init__.php' to
  55      '/some/path/libcustom/src/__phutil_library_init__.php'...
  56    Using library root at 'src'...
  57    Mapping library...
  58    Verifying library...
  59    Finalizing library map...
  60      OKAY   Library updated.
  61  
  62  This will write three files:
  63  
  64    - ##src/.phutil_module_cache## This is a cache which makes "arc liberate"
  65      faster when you run it to update the library. You can safely remove it at
  66      any time. If you check your library into version control, you can add this
  67      file to ignore rules (like .gitignore).
  68    - ##src/__phutil_library_init__.php## This records the name of the library and
  69      tells libphutil that a library exists here.
  70    - ##src/__phutil_library_map__.php## This is a map of all the symbols
  71      (functions and classes) in the library, which allows them to be autoloaded
  72      at runtime and dependencies to be statically managed by "arc liberate".
  73  
  74  = Linking with Phabricator =
  75  
  76  If you aren't using this library with Phabricator (e.g., you are only using it
  77  with Arcanist or are building something else on libphutil) you can skip this
  78  step.
  79  
  80  But, if you intend to use this library with Phabricator, you need to define its
  81  dependency on Phabricator by creating a ##.arcconfig## file which points at
  82  Phabricator. For example, you might write this file to
  83  `libcustom/.arcconfig`:
  84  
  85    {
  86      "project.name" : "libcustom",
  87      "load" : [
  88        "phabricator/src/"
  89      ]
  90    }
  91  
  92  For details on creating a ##.arcconfig##, see
  93  @{article:Arcanist User Guide: Configuring a New Project}. In general, this
  94  tells ##arc liberate## that it should look for symbols in Phabricator when
  95  performing static analysis.
  96  
  97  NOTE: If Phabricator isn't located next to your custom library, specify a
  98  path which actually points to the ##phabricator/## directory.
  99  
 100  You do not need to declare dependencies on ##arcanist## or ##libphutil##,
 101  since ##arc liberate## automatically loads them.
 102  
 103  Finally, edit your Phabricator config to tell it to load your library at
 104  runtime, by adding it to ##load-libraries##:
 105  
 106    ...
 107    'load-libraries' => array(
 108      'libcustom' => 'libcustom/src/',
 109    ),
 110    ...
 111  
 112  Now, Phabricator will be able to load classes from your custom library.
 113  
 114  = Writing Classes =
 115  
 116  To actually write classes, create a new module and put code in it:
 117  
 118    libcustom/ $ mkdir src/example/
 119    libcustom/ $ nano src/example/ExampleClass.php # Edit some code.
 120  
 121  Now, run ##arc liberate## to regenerate the static resource map:
 122  
 123    libcustom/ $ arc liberate src/
 124  
 125  This will automatically regenerate the static map of the library.
 126  
 127  = What You Can Extend And Invoke =
 128  
 129  libphutil, Arcanist and Phabricator are strict about extensibility of classes
 130  and visibility of methods and properties. Most classes are marked ##final##, and
 131  methods have the minimum required visibility (protected or private). The goal of
 132  this strictness is to make it clear what you can safely extend, access, and
 133  invoke, so your code will keep working as the upstream changes.
 134  
 135  When developing libraries to work with libphutil, Arcanist and Phabricator, you
 136  should respect method and property visibility and extend only classes marked
 137  `@stable`. They are rendered with a large callout in the documentation (for
 138  example: @{class@libphutil:AbstractDirectedGraph}). These classes are external
 139  interfaces intended for extension.
 140  
 141  If you want to extend a class but it is not marked ##@stable##, here are some
 142  approaches you can take:
 143  
 144    - Good: If possible, use composition rather than extension to build your
 145      feature.
 146    - Good: Check the documentation for a better way to accomplish what you're
 147      trying to do.
 148    - Good: Let us know what your use case is so we can make the class tree more
 149      flexible or configurable, or point you at the right way to do whatever
 150      you're trying to do, or explain why we don't let you do it.
 151    - Discouraged: Send us a patch removing "final" (or turning "protected" or
 152      "private" into "public"). We generally will not accept these patches, unless
 153      there's a good reason that the current behavior is wrong.
 154    - Discouraged: Create an ad-hoc local fork and remove "final" in your copy of
 155      the code. This will make it more difficult for you to upgrade in the future.
 156    - Discouraged: Use Reflection to violate visibility keywords.