Issue #3248976: Add API documentation for Package Manager

package_manager/package_manager.api.php

@@ -7,27 +7,33 @@
 
 /**
  * Package Manager is an API-only module which provides the scaffolding and
- * functionality needed for Drupal to make changes to its own running code base.
- * It doesn't provide any user interface.
+ * functionality needed for Drupal to make changes to its own running code base
+ * via Composer. It doesn't provide any user interface.
  *
  * At the center of Package Manager is the concept of a staging area. A staging
- * area is a (nearly) complete copy of the active Drupal code base, which is
- * created in a separate location that isn't accessible over the web, such as a
- * temporary directory. Package Manager can run Composer commands in the staging
- * area to require or update packages in it, and then copy those changes back
- * into the live, running code base (which is referred to as the "active
- * directory"). When that's done, the staging area can be safely deleted. These
- * four distinct operations comprise the "stage life cycle".
- *
- * Only one staging area can exist at any given time, and it is "owned" by the
- * user or session that originally created it. Only the owner can perform
- * operations on the staging area.
+ * area is a complete copy of the active Drupal code base, which is created in a
+ * separate location that isn't accessible over the web, such as a temporary
+ * directory. The staging area doesn't include site-specific assets that aren't
+ * managed by Composer, such as settings.php, uploaded files, or SQLite
+ * databases.
+ *
+ * Package Manager can run Composer commands in the staging area to require or
+ * require or update packages in it, and then copy those changes back into the
+ * live, running code base (which is referred to as the "active directory").
+ * When that's done, the staging area can be safely deleted. These four distinct
+ * operations -- create, require, apply, and destroy -- comprise the "stage life
+ * cycle".
  *
  * Package Manager's PHP API is based on \Drupal\package_manager\Stage, which
  * controls the stage life cycle. This class may be extended to implement custom
  * behavior, but in most situations, custom code should use the event system
  * to interact with the stage.
  *
+ * Only one staging area can exist at any given time, and it is "owned" by the
+ * user or session that originally created it. Only the owner can perform
+ * operations on the staging area, and only using the same class (i.e.,
+ * \Drupal\package_manager\Stage or a subclass) they used to create it.
+ *
  * Events are dispatched before and after each operation in the stage life
  * cycle. There are two types of events: pre-operation and post-operation.
  * Pre-operation events can analyze the state of the staging area, or the system
@@ -35,7 +41,9 @@
  * flagged, the operation is prevented. Therefore, pre-operation events are
  * helpful to ensure that the staging area is in a valid state. Post-operation
  * events are simple triggers allowing custom code to react when an operation
- * is complete. They cannot flag errors.
+ * is complete. They cannot flag errors that block the stage life cycle from
+ * continuing, although they can use the core messenger and logging systems to
+ * log errors.
  *
  * All stage events extend \Drupal\package_manager\Event\StageEvent, and all
  * pre-operation events extend
@@ -54,11 +62,9 @@
  *   during a stage's life cycle.
  *
  * - \Drupal\package_manager\Event\PostCreateEvent
- *   Dispatched after the staging area is created, which means that nearly all
- *   of the running Drupal code base (normally excluding things like public and
- *   private files, SQLite databases, and other site-specific assets) has been
- *   copied into a separate, temporary location. Only dispatched once during a
- *   stage's life cycle.
+ *   Dispatched after the staging area is created, which means that all of the
+ *   running Drupal code base has been copied into a separate, temporary
+ *   location. Only dispatched once during a stage's life cycle.
  *
  * - \Drupal\package_manager\Event\PreRequireEvent
  *   Dispatched before one or more Composer packages are required into the
@@ -69,11 +75,12 @@
  *   staging area. May be dispatched multiple times during a stage's life cycle.
  *
  * - \Drupal\package_manager\Event\PreApplyEvent
- *   Dispatched before changes in the staging area (for example, new or updated
- *   packages) are copied to the active directory (i.e., the running Drupal code
+ *   Dispatched before changes in the staging area (i.e., new or updated
+ *   packages) are copied to the active directory (the running Drupal code
  *   base). This is the final opportunity for event subscribers to flag errors
- *   before the active directory is modified. May be dispatched multiple times
- *   during a stage's life cycle.
+ *   before the active directory is modified. Once the active directory has
+ *   been modified, the changes cannot be undone. May be dispatched multiple
+ *   times during a stage's life cycle.
  *
  * - \Drupal\package_manager\Event\PostApplyEvent
  *   Dispatched after changes in the staging area have been copied to the active
@@ -92,7 +99,11 @@
  *
  * - \Drupal\package_manager\Stage::create()
  *   Creates the staging area, records ownership, and dispatches pre- and
- *   post-create events.
+ *   post-create events. Returns a unique token which calling code must use to
+ *   verify stage ownership before performing operations on the staging area
+ *   in subsequent requests (when the staging area is created, its ownership
+ *   is automatically verified for the duration of the current request). See
+ *   \Drupal\package_manager\Stage::claim() for more information.
  *
  * - \Drupal\package_manager\Stage::require()
  *   Adds packages to the staging area and dispatches pre- and post-require
@@ -105,4 +116,36 @@
  * - \Drupal\package_manager\Stage::destroy()
  *   Destroys the staging area, releases ownership, and dispatches pre- and
  *   post-destroy events.
+ *
+ * - \Drupal\package_manager\Stage::getActiveComposer()
+ *   \Drupal\package_manager\Stage::getStageComposer()
+ *   These methods initialize an instance of Composer's API in the active
+ *   directory and staging area, respectively, and return an object which can
+ *   be used by event subscribers to inspect the directory and get relevant
+ *   information from Composer's API, such as what packages are installed and
+ *   where.
+ *
+ * Package Manager automatically enforces certain constraints at various points
+ * of the stage life cycle, to ensure that both the active directory and staging
+ * area are kept in a safe, consistent state:
+ *
+ * - No Composer operation which changes the lock file may be executed in the
+ *   active directory while a staging area exists, either via Package Manager's
+ *   API or externally.
+ * - Composer must use HTTPS to download packages and metadata (i.e., Composer's
+ *   secure-http configuration option must be enabled). This is the default
+ *   behavior.
+ * - The Drupal root, and vendor directory, must be writable.
+ * - A supported version of the Composer executable must be accessible by PHP.
+ *   Its path can be explicitly set in the package_manager.settings config, or
+ *   it will be auto-detected.
+ * - Certain files are never copied into the staging area because they are
+ *   irrelevant to Composer or Package Manager. Examples include settings.php
+ *   and related files, public and private files, SQLite databases, and git
+ *   repositories. Custom code can use
+ *   \Drupal\package_manager\Event\PreCreateEvent::excludePath() to exclude a
+ *   specific path from being copied from the active directory into the staging
+ *   area, or \Drupal\package_manager\Event\PreApplyEvent::excludePath() to
+ *   exclude a specific path from being copied from the staginga area back into
+ *   the active directory.
  */