Issue #3248976: Add API documentation for Package Manager

package_manager/package_manager.api.php

+<?php
+
+/**
+ * @file
+ * Documentation related to Package Manager.
+ */
+
+/**
+ * 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.
+ *
+ * At the center of Package Manager is the concept of a staging area. A staging
+ * area is a (nearly) complete copy of the running Drupal code base, which is
+ * created in a separate location, like a temporary directory, which is not
+ * acessible over the web. Package Manager can run Composer commands in the
+ * staging area to require or update packages in it, and then the changes in the
+ * staging area can be copied back into the live, running code base (which is
+ * referred to as the "active directory"). When that's done, the staging area
+ * can be deleted. These four distinct phases are called the "stage life cycle".
+ *
+ * Only one staging area may exist at any given time, and this limitation is
+ * strictly enforced by Package Manager. Additionally, a staging area is "owned"
+ * by the user or session that originally created it, and can only be changed
+ * by that owner.
+ *
+ * Package Manager's PHP API revolves around \Drupal\package_manager\Stage,
+ * which is a class that controls the stage life cycle. This class may be
+ * extended to implement custom behavior during any phase of the stage life
+ * cycle. In most situations, though, custom code should use the event system
+ * to interact with the stage.
+ *
+ * Events are dispatched before and after each of the phases of the stage life
+ * cycle. There are two types of events: pre-operation and post-operation.
+ * Pre-operation events are dispatched before a given phase is run. They can
+ * analyze the state of the staging area, or the system at large, and flag
+ * errors if they detect any problems. If errors are flagged, the stage is
+ * prevented from continuing through its life cycle under the errors are
+ * resolved. Therefore, pre-operation events are useful to ensure that the
+ * staging area is in a valid state. Post-operation events are simple triggers
+ * to allow custom code to react when a stage life cycle phase is completed.
+ * They cannot flag errors.
+ *
+ * All stage life cycle events extend \Drupal\package_manager\Event\StageEvent,
+ * and all pre-operation events extend
+ * \Drupal\package_manager\Event\PreOperationStageEvent. All events have a
+ * getStage() method which allows access to the stage object itself.
+ *
+ * The stage dispatches the following events during its life cycle:
+ *
+ * - \Drupal\package_manager\Event\PreCreateEvent
+ *   Dispatched before the staging area is created. At this point, the stage
+ *   will have recorded which user or session owns it, so another staging area
+ *   cannot be created until the current one is destroyed. If subscribers flag
+ *   errors during this event, the stage will release its ownership. This is
+ *   the earliest possible time to detect problems that might prevent the
+ *   stage from completing its life cycle successfully. Only dispatched once
+ *   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.
+ *
+ * - \Drupal\package_manager\Event\PreRequireEvent
+ *   Dispatched before one or more Composer packages are required into the
+ *   staging area. May be dispatched multiple times during a stage's life cycle.
+ *
+ * - \Drupal\package_manager\Event\PostRequireEvent
+ *   Dispatched after one or more Composer packages have been added to the
+ *   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
+ *   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.
+ *
+ * - \Drupal\package_manager\Event\PostApplyEvent
+ *   Dispatched after changes in the staging area have been copied to the active
+ *   directory. May be dispatched multiple times during a stage's life cycle.
+ *
+ * - \Drupal\package_manager\Event\PreDestroyEvent
+ *   Dispatched before the staging area is destroyed, during which the temporary
+ *   directory will be completely deleted the stage will release its ownership.
+ *   Only dispatched once during a stage's life cycle.
+ *
+ * - \Drupal\package_manager\Event\PostDestroy
+ *   Dispatched after the staging area is destroyed and the stage has released
+ *   its ownership. Only dispatched once during a stage's life cycle.
+ *
+ * The public API of any stage consists of at least four methods:
+ *
+ * - \Drupal\package_manager\Stage::create()
+ *   Creates the staging area, records ownership, and dispatches pre- and
+ *   post-create events.
+ *
+ * - \Drupal\package_manager\Stage::require()
+ *   Adds packages to the staging area and dispatches pre- and post-require
+ *   events.
+ *
+ * - \Drupal\package_manager\Stage::apply()
+ *   Copies changes from the staging area into the active directory, and
+ *   dispatches pre- and post-apply events.
+ *
+ * - \Drupal\package_manager\Stage::destroy()
+ *   Destroys the staging area, releases ownership, and dispatches pre- and
+ *   post-destroy events.
+ */