class InstalledPackagesList

final class InstalledPackagesList extends \ArrayObject {
    
    /**
     * {@inheritdoc}
     */
    public function append(mixed $value) : never {
        throw new \LogicException('Installed package lists cannot be modified.');
    }
    
    /**
     * {@inheritdoc}
     */
    public function offsetSet(mixed $key, mixed $value) : never {
        throw new \LogicException('Installed package lists cannot be modified.');
    }
    
    /**
     * {@inheritdoc}
     */
    public function offsetUnset(mixed $key) : never {
        throw new \LogicException('Installed package lists cannot be modified.');
    }
    
    /**
     * {@inheritdoc}
     */
    public function offsetGet(mixed $key) : ?InstalledPackage {
        // Overridden to provide a clearer return type hint and compatibility with
        // the null-safe operator.
        if ($this->offsetExists($key)) {
            return parent::offsetGet($key);
        }
        return NULL;
    }
    
    /**
     * {@inheritdoc}
     */
    public function exchangeArray(mixed $array) : never {
        throw new \LogicException('Installed package lists cannot be modified.');
    }
    
    /**
     * Returns the packages that are in this list, but not in another.
     *
     * @param self $other
     *   Another list of installed packages.
     *
     * @return static
     *   A list of packages which are in this list but not the other one, keyed by
     *   name.
     */
    public function getPackagesNotIn(self $other) : static {
        $packages = array_diff_key($this->getArrayCopy(), $other->getArrayCopy());
        return new static($packages);
    }
    
    /**
     * Returns the packages which have a different version in another list.
     *
     * This compares this list with another one, and returns a list of packages
     * which are present in both, but in different versions.
     *
     * @param self $other
     *   Another list of installed packages.
     *
     * @return static
     *   A list of packages which are present in both this list and the other one,
     *   but in different versions, keyed by name.
     */
    public function getPackagesWithDifferentVersionsIn(self $other) : static {
        // Only compare packages that are both here and there.
        $packages = array_intersect_key($this->getArrayCopy(), $other->getArrayCopy());
        $packages = array_filter($packages, fn(InstalledPackage $p) => Comparator::notEqualTo($p->version, $other[$p->name]->version));
        return new static($packages);
    }
    
    /**
     * Returns the package for a given Drupal project name, if it is installed.
     *
     * Although it is common for the package name to match the project name (for
     * example, a project name of `token` is likely part of the `drupal/token`
     * package), it's not guaranteed. Therefore, in order to avoid inadvertently
     * reading information about the wrong package, use this method to properly
     * determine which package installs a particular Drupal project.
     *
     * @param string $project_name
     *   The name of a Drupal project.
     *
     * @return \Drupal\package_manager\InstalledPackage|null
     *   The Composer package which installs the project, or NULL if it could not
     *   be determined.
     */
    public function getPackageByDrupalProjectName(string $project_name) : ?InstalledPackage {
        $matching_package = NULL;
        foreach ($this as $package) {
            if ($package->getProjectName() === $project_name) {
                if ($matching_package) {
                    throw new \UnexpectedValueException(sprintf("Project '%s' was found in packages '%s' and '%s'.", $project_name, $matching_package->name, $package->name));
                }
                $matching_package = $package;
            }
        }
        return $matching_package;
    }
    
    /**
     * Returns the canonical names of the supported core packages.
     *
     * @return string[]
     *   The canonical list of supported core package names.
     */
    private static function getCorePackageList() : array {
        // This method returns the installed packages that are considered part of
        // Drupal core. There's no way to tell by package type alone, since these
        // packages have varying types, but are all part of Drupal core's
        // repository.
        return [
            'drupal/core',
            'drupal/core-composer-scaffold',
            'drupal/core-dev',
            'drupal/core-dev-pinned',
            'drupal/core-project-message',
            'drupal/core-recommended',
            'drupal/core-vendor-hardening',
        ];
    }
    
    /**
     * Returns a list of installed core packages.
     *
     * Packages returned by ::getCorePackageList() are considered core packages.
     *
     * @param bool $include_dev
     *   (optional) Whether to include core packages intended for development.
     *   Defaults to TRUE.
     *
     * @return static
     *   A list of the installed core packages.
     */
    public function getCorePackages(bool $include_dev = TRUE) : static {
        $core_packages = array_intersect_key($this->getArrayCopy(), array_flip(static::getCorePackageList()));
        // If drupal/core-recommended is present, it supersedes drupal/core, since
        // drupal/core will always be one of its direct dependencies.
        if (array_key_exists('drupal/core-recommended', $core_packages)) {
            unset($core_packages['drupal/core']);
        }
        if (!$include_dev) {
            unset($core_packages['drupal/core-dev']);
            unset($core_packages['drupal/core-dev-pinned']);
        }
        return new static($core_packages);
    }

}