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 module which provides the scaffolding and
+ * functionality needed for Drupal to make changes to its own running code base.
+ *
+ * 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 lives
+ * in a separate location such as a temporary directory. Composer packages can
+ * be added to the staging area, and then the changes in the staging area can
+ * be copied into the live, running code base (which is referred to as the
+ * "active directory"). A strict limitation of Package Manager is that only one
+ * staging area can exist at any given time. Additionally, a staging area is
+ * "owned" by the user or session that originally created it, and can only be
+ * changed by that owner.
+ *
+ * In Package Manager's API, a stage is a class which controls the life cycle of
+ * a staging area, which consists of four distinct phases: create, require,
+ * apply, and destroy. Events are dispatched before and after each of these
+ * phases occurs. Event subscribers can analyze the current state of the staging
+ * area and flag errors if they detect problems. If errors are flagged, the
+ * staging area is prevented from continuing its life cycle until the errors are
+ * resolved.
+ *
+ * Package Manager implements a basic stage in \Drupal\package_manager\Stage.
+ * Modules which need to add additional special logic can extend this class, but
+ * generally, interaction with Package Manager should take place by implementing
+ * event subscribers.
+ *
+ * The events dispatched by a stage are, in order:
+ *
+ * - \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. This event is 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 has been copied into a separate, temporary
+ *   location. This event is only dispatched once during a stage's life cycle.
+ *
+ * - \Drupal\package_manager\Event\PreRequireEvent
+ *   Dispatched before one or more Composer packages are added to the staging
+ *   area. Because stages can exist indefinitely, this event might be fired
+ *   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. Because stages can exist indefinitely, this event might be
+ *   fired 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. It is possible for this event to
+ *   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. It is possible for this event to be dispatched multiple times
+ *   during a stage's life cycle.
+ *
+ * - \Drupal\package_manager\Event\PreDestroyEvent
+ *   Dispatched before the staging area is destroyed, meaning the temporary
+ *   directory will be completely deleted the stage will release its ownership.
+ *   This event is 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. This event is only dispatched once during a stage's life
+ *   cycle.
+ *
+ * All of Package Manager's event classes extend
+ * \Drupal\package_manager\Event\StageEvent, and carry a reference to the stage
+ * for subscribers to interact with.
+ *
+ * The public API of any stage consists of 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 owndership, and dispatches pre- and
+ *   post-destroy events.
+ */