Satis

https://github.com/composer/satis
Admin
Satis is a static Composer repository generator that allows PHP developers to create private package...
Tokens:61,315
Snippets:436
Trust Score:9.2
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install and run Satis from source

Source: https://github.com/composer/satis/blob/main/docs/index.md

Clone the Satis repository, install dependencies with Composer, and run the bin/satis command.

```bash
git clone https://github.com/composer/satis
cd satis
composer install
bin/satis
```

--------------------------------

### Install Satis and build a repository from source

Source: https://github.com/composer/satis/blob/main/README.md

Installs Satis from the source and generates a static repository using the 'build' command. These commands appear in the "Run from source" section of the README.

```bash
composer create-project --keep-vcs --no-dev composer/satis:dev-main
```

```bash
php bin/satis build <configuration-file> <output-directory>
```

--------------------------------

### Satis configuration file (satis.json) example

Source: https://github.com/composer/satis/blob/main/_autodocs/configuration.md

Canonical example of a Satis configuration file. It shows the full set of keys used to control repository discovery, package selection, archiving, provider/includes generation, and web output. Use this as a reference when creating a satis.json for your own repository.

```json
{
    "name": "My Satis Repository",
    "homepage": "https://packages.example.org",
    "description": "A descriptive line of text goes here.",
    "repositories": [
        { "type": "vcs", "url": "https://github.com/mycompany/privaterepo" }
    ],
    "require": {
        "company/package1": "^1.5",
        "company/package2": "dev-master|dev-develop"
    },
    "require-dependencies": true,
    "require-dev-dependencies": false,
    "only-best-candidates": false,
    "minimum-stability": "dev",
    "abandoned": { "old/package": "company/newpackage" },
    "blacklist": { "broken/package": "*" },
    "archive": {
        "directory": "dist",
        "format": "tar",
        "skip-dev": true,
        "prefix-url": "https://cdn.example.org",
        "whitelist": ["company/*"],
        "checksum": true
    },
    "providers": false,
    "includes": true,
    "include-filename": "include/all$%hash%.json",
    "pretty-print": true,
    "notify-batch": "https://packages.example.org/downloads",
    "output-dir": "build-output",
    "output-html": true,
    "twig-template": "views/index.html.twig",
    "allow-seo-indexing": false,
    "strip-hosts": ["/local", "/private"],
    "config": { "process-timeout": 600 }
}
```

--------------------------------

### Basic usage of Application

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/application.md

Creates a new Application instance and runs it. The comment shows an example command: `php bin/satis build satis.json output`.

```php
use Composer\Satis\Console\Application;

$app = new Application();
$app->run();
// `php bin/satis build satis.json output`
```

--------------------------------

### Usage commands

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/plugin.md

Example commands to use the plugin after requiring composer/satis. These commands initialize, add, build, purge, and remove repositories.

```bash
composer satis:init
composer satis:add https://github.com/mycompany/private-repo
composer satis:build satis.json output
composer satis:purge satis.json output 1
composer satis:remove https://github.com/mycompany/private-repo
```

--------------------------------

### Install Satis using Composer

Source: https://github.com/composer/satis/blob/main/docs/index.md

Create a new Satis project with Composer, change into the directory, and run bin/satis.

```bash
composer create-project composer/satis satis dev-main
cd satis
bin/satis
```

--------------------------------

### Output layout example

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/packages-builder.md

Shows the default output directory structure generated by the builder when homepage is set to https://packages.example.org.

```text
build-output/
├── packages.json
├── include/
│   └── all<sha1>.json
└── p2/
    ├── vendor/package.json
    └── vendor/package~dev.json
```

--------------------------------

### Example archive configuration

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/archive-builder.md

Example JSON configuration for the archive feature, specifying directory 'dist', format 'zip', skip-dev true, whitelist 'company/*', checksum true, and prefix-url.

```json
{
    "archive": {
        "directory": "dist",
        "format": "zip",
        "skip-dev": true,
        "whitelist": ["company/*"],
        "checksum": true,
        "prefix-url": "https://cdn.example.org"
    }
}
```

--------------------------------

### Minified mode example

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/packages-builder.md

Shows how to enable minified mode by passing true as the last constructor argument, resulting in a 'minified' key in the output.

```php
$builder = new PackagesBuilder(new ConsoleOutput(), 'build-output', $config, false, true);
$builder->dump($packages);
// p2/vendor/package.json gets {"packages": [...], "minified": "composer/2.0"}
```

--------------------------------

### Satis configuration with require-all

Source: https://github.com/composer/satis/blob/main/docs/using.md

Example satis.json configuration that includes multiple VCS repositories and uses "require-all": true to select all versions of all packages.

```json
{
    "name": "My Repository",
    "homepage": "http://packages.example.org",
    "repositories": [
        { "type": "vcs", "url": "https://github.com/mycompany/privaterepo" },
        { "type": "vcs", "url": "http://svn.example.org/private/repo" },
        { "type": "vcs", "url": "https://github.com/mycompany/privaterepo2" }
    ],
    "require-all": true
}
```

--------------------------------

### Build command with --skip-errors and example output

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/archive-builder.md

Command to build with --skip-errors, which logs and skips failing archives instead of rethrowing. Example output shows a skipped exception for PEAR repository.

```bash
php bin/satis build --skip-errors satis.json output
# Skipping Exception 'The PEAR repository has been removed from Composer 2.0'.
```

--------------------------------

### BuilderInterface implementation example

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/builder.md

Example of implementing a custom builder using the BuilderInterface contract.

```APIDOC
## BuilderInterface implementation example

### Description
Shows how to implement a custom builder by implementing the BuilderInterface and using the same constructor pattern.

### Method
Implementation

### Signature
```php
class ChangelogBuilder implements BuilderInterface
{
    public function __construct(
        private \Symfony\Component\Console\Output\OutputInterface $output,
        private string $outputDir
    ) {}

    public function dump(array $packages): void
    {
        $lines = [];
        foreach ($packages as $package) {
            $lines[] = $package->getPrettyName() . ' ' . $package->getPrettyVersion();
        }
        file_put_contents($this->outputDir . '/CHANGELOG.txt', implode("\n", $lines));
        $this->output->writeln('<info>Writing CHANGELOG.txt</info>');
    }
}
```

### Parameters
- **$output** (OutputInterface) - Required - Console output instance.
- **$outputDir** (string) - Required - Directory where the output file will be written.

### Method: dump
- **$packages** (array) - Required - Array of package objects to process.
```

--------------------------------

### Satis configuration with require constraints

Source: https://github.com/composer/satis/blob/main/docs/using.md

Example satis.json configuration that cherry-picks packages using the classic composer require key with constraints like "*" and specific versions.

```json
{
    "repositories": [
        { "type": "vcs", "url": "https://github.com/mycompany/privaterepo" },
        { "type": "vcs", "url": "http://svn.example.org/private/repo" },
        { "type": "vcs", "url": "https://github.com/mycompany/privaterepo2" }
    ],
    "require": {
        "company/package": "*",
        "company/package2": "*",
        "company/package3": "2.0.0"
    }
}
```

--------------------------------

### Satis configuration with named repositories

Source: https://github.com/composer/satis/blob/main/docs/using.md

Example satis.json configuration that declares a name for each VCS repository to enable partial updates that scan only selected packages.

```json
{
    "repositories": [
        {
            "name": "company/privaterepo",
            "type": "vcs",
            "url": "https://github.com/mycompany/privaterepo"
        },
        {
            "name": "private/repo",
            "type": "vcs",
            "url": "http://svn.example.org/private/repo"
        },
        {
            "name": "mycompany/privaterepo2",
            "type": "vcs",
            "url": "https://github.com/mycompany/privaterepo2"
        }
    ]
}
```

--------------------------------

### Set up and run Satis development checks

Source: https://github.com/composer/satis/blob/main/README.md

Installs Satis development tooling and runs code checks (php-cs-fixer and phpstan). The final two commands show Composer shortcuts for the same tools.


```bash
# install tooling & dependencies
for d in tools/*; do composer --working-dir=$d install; done

# run php-cs-fixer
tools/php-cs-fixer/vendor/bin/php-cs-fixer fix

# run phpstan
tools/phpstan/vendor/bin/phpstan

# alternatively, use the shortcuts
composer phpstan
composer php-cs-fixer[-fix]
```

--------------------------------

### Custom builder implementing BuilderInterface

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/builder.md

Example of a custom builder that implements BuilderInterface. It writes a CHANGELOG.txt file with package names and versions, and outputs an info message. The constructor follows the same pattern as the built-in builders.

```php
use Composer\Satis\Builder\BuilderInterface;

class ChangelogBuilder implements BuilderInterface
{
    public function __construct(
        private \Symfony\Component\Console\Output\OutputInterface $output,
        private string $outputDir
    ) {}

    public function dump(array $packages): void
    {
        $lines = [];
        foreach ($packages as $package) {
            $lines[] = $package->getPrettyName() . ' ' . $package->getPrettyVersion();
        }
        file_put_contents($this->outputDir . '/CHANGELOG.txt', implode("\n", $lines));
        $this->output->writeln('<info>Writing CHANGELOG.txt</info>');
    }
}
```

--------------------------------

### init [file] [--name] [--homepage]

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/init-command.md

Initializes a Satis configuration file. Walks the user through name and homepage entry, then writes a fresh satis.json bootstrapped with "require-all": true.

```APIDOC
## [COMMAND] init

### Description
Initializes a Satis configuration file. Walks the user through name and homepage entry, then writes a fresh satis.json bootstrapped with "require-all": true.

### Command
init

### Usage
`init [file] [--name <name>] [--homepage <homepage>]`

### Arguments
#### Arguments
- **file** (string) - Optional - JSON file to use (the config file to create/overwrite). Default: './satis.json'

### Options
#### Options
- **--name** (string) - Required - Repository name
- **--homepage** (string) - Required - Home page (must be a valid http(s):// URL)

### Description
Interactive generator for Satis configuration files. Walks the user through name/homepage entry, then writes a fresh satis.json bootstrapped with "require-all": true.

### Command Name
init (also registered as satis:init when run through the Composer plugin)

### Source File
src/Console/Command/InitCommand.php

### Extends
Composer\Command\BaseCommand

### Namespace
Composer\Satis\Console\Command

```

--------------------------------

### Build with all options

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/build-command.md

Shows the build command with every available option: repository URL, strict mode, no HTML output, skip errors, stats, and minify.

```bash
php bin/satis build \
  --repository-url=https://github.com/mycompany/private-repo \
  --repository-strict \
  --no-html-output \
  --skip-errors \
  --stats \
  --minify \
  satis.json build-output vendor/package-a vendor/package-b
```

--------------------------------

### Standalone CLI entry point (bin/satis)

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/application.md

Instantiates the Satis console application and runs it. This is the entry point for the standalone `bin/satis` script.

```php
$application = new Composer\Satis\Console\Application();
$application->run();
```

--------------------------------

### Custom Twig environment with WebBuilder

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/web-builder.md

Sets a custom Twig environment on WebBuilder, e.g., to add your own extension. The example writes build-output/index.html.

```php
use Composer\Satis\Builder\WebBuilder;
use Twig\Environment;
use Twig\Loader\FilesystemLoader;

$twig = new Environment(new FilesystemLoader(['views'])));
$web = new WebBuilder($output, $outputDir, $config, false);
$web->setRootPackage($rootPackage);
$web->setTwigEnvironment($twig);
$web->dump($packages);
// writes build-output/index.html
```

--------------------------------

### Basic WebBuilder usage with BuildCommand

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/web-builder.md

Creates a WebBuilder instance and dumps packages to HTML. HTML is built unless --no-html-output or "output-html": false is set.

```php
$web = new WebBuilder($output, $outputDir, $config, $skipErrors);
$web->setRootPackage($composer->getPackage());
$web->dump($packages);
```

--------------------------------

### initialize method - prints welcome banner

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/init-command.md

Prints the welcome banner before any interaction. Runs before interact() and execute().

```php
protected function initialize(InputInterface $input, OutputInterface $output): void
{
    /** @var FormatterHelper $formatter */
    $formatter = $this->getHelper('formatter');

    $output->writeln([
        '',
        $formatter->formatBlock('Welcome to the Satis config generator', 'bg=blue;fg=white', true),
        '',
    ]);

    $output->writeln([
        '',
        'This command will guide you through creating your Satis config.',
        '',
    ]);
}
```

--------------------------------

### dump(array $packages): void

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/web-builder.md

Generates the web view and writes it to <outputDir>/index.html. Requires setRootPackage() to have been called. Prints hint lines if the root package name is '__root__' or if homepage is not set. The template context includes name, url, description, keywords, packages, dependencies, fieldsToToggle, and blockIndexing.

```php
public function dump(array $packages): void
{
    $mappedPackages = $this->getMappedPackageList($packages);

    $name = $this->rootPackage->getPrettyName();
    if ('__root__' === $name) {
        $name = 'A';
        $this->output->writeln('Define a "name" property in your json config to name the repository');
    }

    if (is_null($this->rootPackage->getHomepage())) {
        $this->output->writeln('Define a "homepage" property in your json config to configure the repository URL');
    }

    $this->setDependencies($packages);

    $this->output->writeln('<info>Writing web view</info>');

    $content = $this->getTwigEnvironment()->render($this->getTwigTemplate(), [
        'name' => $name,
        'url' => $this->rootPackage->getHomepage(),
        'description' => $this->rootPackage->getDescription(),
        'keywords' => $this->rootPackage->getKeywords(),
        'packages' => $mappedPackages,
        'dependencies' => $this->dependencies,
        'fieldsToToggle' => $this->fieldsToToggle,
        'blockIndexing' => !isset($this->config['allow-seo-indexing']) || true !== $this->config['allow-seo-indexing'],
    ]);

    file_put_contents($this->outputDir . '/index.html', $content);
}
```

--------------------------------

### Error handling in a script

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/add-command.md

Example of checking the exit code of the `add` command in a bash script, with exit code 3 indicating an invalid repository URL.

```bash
if ! php bin/satis add https://example.org/not-a-repo; then
  echo "exit code: $?"   # 3 — Invalid Repository URL
fi
```

--------------------------------

### InitCommand configure() definition

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/init-command.md

Defines the 'init' command with an optional 'file' argument (default './satis.json') and required '--name' and '--homepage' options. The homepage must be a valid http(s):// URL.

```php
$this->getName() ?? $this->setName('init');
$this
    ->setDescription('Initialize Satis configuration file')
    ->setDefinition([
        new InputArgument('file', InputArgument::OPTIONAL, 'JSON file to use', './satis.json'),
        new InputOption('name', null, InputOption::VALUE_REQUIRED, 'Repository name'),
        new InputOption('homepage', null, InputOption::VALUE_REQUIRED, 'Home page'),
    ])
    ->setHelp(<<<'EOT' ... EOT);
```

--------------------------------

### dump() method for archiving packages

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/archive-builder.md

Archives packages and rewrites dist metadata. Uses ArchiveBuilderHelper to get directory, computes endpoint from config, and mutates packages in place.

```php
/**
 * @param array<PackageInterface> $packages
 */
public function dump(array $packages): void
{
    $helper = new ArchiveBuilderHelper($this->output, $this->config['archive']);
    $basedir = $helper->getDirectory($this->outputDir);
    $this->output->writeln(sprintf("<info>Creating local downloads in '%s'</info>", $basedir));
    $endpoint = $this->config['archive']['prefix-url'] ?? $this->config['homepage'];
    $includeArchiveChecksum = (bool) ($this->config['archive']['checksum'] ?? true);
    // ...
}
```

--------------------------------

### new PackageSelection(OutputInterface $output, string $outputDir, array $config, bool $skipErrors)

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/package-selection.md

Creates a new PackageSelection instance. It initializes the output, output directory, repositories, and fetch options from the config array.

```APIDOC
## Constructor

### Description
Creates a new PackageSelection instance. It initializes the output, output directory, repositories, and fetch options from the config array.

### Method
Constructor

### Signature
`new PackageSelection(OutputInterface $output, string $outputDir, array $config, bool $skipErrors)`

### Parameters
- **$output** (OutputInterface) - Required - Console output used for progress/errors
- **$outputDir** (string) - Required - Output directory; used to compute the `packages.json` filename for `load()`
- **$config** (array<string, mixed>) - Required - The Satis config array (keys consumed: see Configuration)
- **$skipErrors** (bool) - Required - When `true`, repository/add errors are printed and skipped instead of rethrown

### Configuration Keys
- **repositories-dep** - Property: `$depRepositories` - Default: `[]`
- **require-all** - Property: `$requireAll` - Default: `false` (auto-enabled when neither `require-all` nor `require` is set — prints `'No explicit requires defined, enabling require-all'`)
- **require-dependencies** - Property: `$requireDependencies` - Default: `false`
- **require-dev-dependencies** - Property: `$requireDevDependencies` - Default: `false`
- **only-dependencies** - Property: `$onlyDependencies` - Default: `false`
- **only-best-candidates** - Property: `$onlyBestCandidates` - Default: `false`
- **require-dependency-filter** - Property: `$requireDependencyFilter` - Default: `true`
- **minimum-stability** - Property: `$minimumStability` - Default: `'dev'`
- **minimum-stability-per-package** - Property: `$minimumStabilityPerPackage` - Default: `[]`
- **abandoned** - Property: `$abandoned` - Default: `[]`
- **blacklist** - Property: `$blacklist` - Default: `[]`
- **include-types** - Property: `$includeTypes` - Default: `null`
- **exclude-types** - Property: `$excludeTypes` - Default: `[]`
- **strip-hosts** - Property: `$stripHosts` - Default: `false` (compiled via `createStripHostsPatterns()`)
- **archive.directory** + **archive.prefix-url**/`homepage` - Property: `$archiveEndpoint` - Default: `null`
- **homepage** - Property: `$homepage` - Default: `null`

### Source
`src/PackageSelection/PackageSelection.php:122`
```

--------------------------------

### Create PackageSelection instance

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/package-selection.md

Constructs a PackageSelection with a ConsoleOutput, build output directory, and configuration array. The configuration must include 'repositories' and 'require-all' keys as shown in the comment.

```php
use Composer\Satis\PackageSelection\PackageSelection;
use Symfony\Component\Console\Output\ConsoleOutput;

$selection = new PackageSelection(
    new ConsoleOutput(),
    'build-output',
    $config,       // ['repositories' => [...], 'require-all' => true, ...]
);
```

--------------------------------

### Basic build command

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/build-command.md

Runs a basic Satis build using a local configuration file and output directory.

```bash
php bin/satis build satis.json build-output
```

--------------------------------

### Direct usage of PackagesBuilder

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/packages-builder.md

Shows how to instantiate and use PackagesBuilder directly, typically done via the 'build' command. Includes configuration array and dump call.

```php
use Composer\Satis\Builder\PackagesBuilder;
use Symfony\Component\Console\Output\ConsoleOutput;

$config = [
    'name' => 'My Repo',
    'homepage' => 'https://packages.example.org',
    'includes' => true,
    'notify-batch' => 'https://packages.example.org/downloads',
];

$builder = new PackagesBuilder(new ConsoleOutput(), 'build-output', $config, false, false);
$builder->dump($packages); // $packages: PackageInterface[] from PackageSelection
```

--------------------------------

### Run init non-interactively with name and homepage

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/init-command.md

Non-interactive run that pre-fills the name and homepage options and writes to custom.json.

```bash
php bin/satis init --name="My Repo" --homepage="https://packages.example.org" custom.json
```

--------------------------------

### Run init interactively

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/init-command.md

Basic interactive run of the init command. Prompts for configuration values.

```bash
php bin/satis init
```

--------------------------------

### execute() method signature and partial implementation

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/build-command.md

Protected method that processes build command input. Reads options like 'verbose', 'repository-url', 'skip-errors', 'minify' and arguments 'file' and 'packages'. Returns 0 on success, 1 when the local config file does not exist. Validation errors are rethrown as exceptions unless --skip-errors is used.

```php
protected function execute(InputInterface $input, OutputInterface $output): int
{
    $verbose = $input->getOption('verbose');
    $configFile = $input->getArgument('file');
    $packagesFilter = $input->getArgument('packages');
    $repositoryUrl = $input->getOption('repository-url');
    $skipErrors = (bool) $input->getOption('skip-errors');
    $minify = (bool) $input->getOption('minify');
    // ...
}
```

--------------------------------

### getConfiguration method implementation

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/build-command.md

Creates a Composer Config, merges the home directory and global auth.json credentials, and sets an auth config source.

```php
private function getConfiguration(): Config
{
    $config = new Config();

    // add dir to the config
    $config->merge(['config' => ['home' => $this->getComposerHome()]]);

    // load global auth file
    $file = new JsonFile($config->get('home') . '/auth.json');
    if ($file->exists()) {
        $config->merge(['config' => $file->read()]);
    }
    $config->setAuthConfigSource(new JsonConfigSource($file, true));

    return $config;
}
```

--------------------------------

### new PackagesBuilder(OutputInterface $output, string $outputDir, array $config, bool $skipErrors, bool $minify = false)

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/packages-builder.md

Creates a new PackagesBuilder instance. It initializes the output filename, include file name, and minification settings based on the provided configuration.

```APIDOC
## Constructor

### Description
Creates a new PackagesBuilder instance. It sets the output filename to `<outputDir>/packages.json`, determines the include file name from the `include-filename` config option (defaulting to `'include/all$%hash%.json'`), and enables Composer v1 `includes` output unless explicitly disabled in the config.

### Method
Constructor

### Signature
`public function __construct(OutputInterface $output, string $outputDir, array $config, bool $skipErrors, bool $minify = false)`

### Parameters
- **$output** (OutputInterface) - Required - Console output (inherited)
- **$outputDir** (string) - Required - Output directory; `packages.json` is written there (inherited)
- **$config** (array<string,mixed>) - Required - Config; reads `include-filename`, `includes`, `providers`, `homepage`, `providers-history-size`, `pretty-print`, `notify-batch`, `available-package-patterns` (inherited)
- **$skipErrors** (bool) - Required - Skip-errors flag (inherited; not consulted by this builder — errors here are hard)
- **$minify** (bool) - Optional - Default: `false` - When `true`, package metadata is minified via `MetadataMinifier::minify()` and include files carry `"minified": "composer/2.0"`

### Derived State
- `$filename` = `"<outputDir>/packages.json"`
- `$includeFileName` = `config['include-filename']` or default `'include/all$%hash%.json'`
- `$config['includes']` defaults to `true` (Composer v1 `includes` output enabled unless explicitly `false`).

### Source
`src/Builder/PackagesBuilder.php:38`
```

--------------------------------

### execute() method implementation

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/add-command.md

Protected method that adds a repository to the configuration file. It validates the config file path, repository URL, and checks for duplicates. Returns exit codes: 0 success, 1 file missing, 2 remote file, 3 invalid repository URL, 4 duplicate URL, 5 duplicate name. Uses JsonFile to read and write the config.

```php
protected function execute(InputInterface $input, OutputInterface $output): int
{
    /** @var FormatterHelper $formatter */
    $formatter = $this->getHelper('formatter');

    $configFile = $input->getArgument('file');
    $repositoryUrl = $input->getArgument('url');
    $vcsDriver = $input->getOption('type');
    $repositoryName = $input->getOption('name');

    if (1 === preg_match('{^https?://}i', $configFile)) {
        $output->writeln('<error>Unable to write to remote file ' . $configFile . '</error>');

        return 2;
    }

    $file = new JsonFile($configFile);
    if (!$file->exists()) {
        $output->writeln('<error>File not found: ' . $configFile . '</error>');

        return 1;
    }

    if (!$this->isRepositoryValid($repositoryUrl, $vcsDriver)) {
        $output->writeln('<error>Invalid Repository URL: ' . $repositoryUrl . '</error>');

        return 3;
    }

    $config = $file->read();
    if (!isset($config['repositories']) || !is_array($config['repositories'])) {
        $config['repositories'] = [];
    }

    foreach ($config['repositories'] as $repository) {
        if (isset($repository['url']) && $repository['url'] === $repositoryUrl) {
            $output->writeln('<error>Repository url already added to the file</error>');

            return 4;
        }

        if (isset($repository['name']) && $repository['name'] === $repositoryName) {
            $output->writeln('<error>Repository name already added to the file</error>');

            return 5;
        }
    }

    $repositoryConfig = ['type' => $vcsDriver, 'url' => $repositoryUrl];

    if (is_string($repositoryName) && '' !== $repositoryName) {
        $repositoryConfig['name'] = $repositoryName;
    }

    $config['repositories'][] = $repositoryConfig;

    $file->write($config);

    $output->writeln([
        '',
        $formatter->formatBlock('Your configuration file successfully updated! It\'s time to rebuild your repository', 'bg=blue;fg=white', true),
        '',
    ]);

    return 0;
}
```

--------------------------------

### doRun() sets up styles, IO, and error handler

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/application.md

Runs before any command executes. Registers Composer's additional output styles, creates a ConsoleIO instance bound to the input/output and helper set, and registers Composer's ErrorHandler on that IO. Returns the exit code delegated from parent::doRun().

```php
public function doRun(InputInterface $input, OutputInterface $output): int
{
    $styles = Factory::createAdditionalStyles();
    foreach ($styles as $name => $style) {
        $output->getFormatter()->setStyle($name, $style);
    }

    $this->io = new ConsoleIO($input, $output, $this->getHelperSet());
    ErrorHandler::register($this->io);

    return parent::doRun($input, $output);
}
```

--------------------------------

### Add repository with default settings

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/add-command.md

Basic usage of the `add` command to append a repository URL to the default `satis.json` file.

```bash
php bin/satis add https://github.com/mycompany/private-repo
```

--------------------------------

### AddCommand configure() definition

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/add-command.md

Defines the 'add' command with required 'url' argument, optional 'file' argument defaulting to './satis.json', and options '--type' (default 'vcs') and '--name'. Sets help text.

```php
$this->getName() ?? $this->setName('add');
$this
    ->setDescription('Add repository URL to satis JSON file')
    ->setDefinition([
        new InputArgument('url', InputArgument::REQUIRED, 'VCS repository URL'),
        new InputArgument('file', InputArgument::OPTIONAL, 'JSON file to use', './satis.json'),
        new InputOption('type', null, InputOption::VALUE_OPTIONAL, 'VCS driver (see https://getcomposer.org/doc/05-repositories.md#git-alternatives)', 'vcs'),
        new InputOption('name', null, InputOption::VALUE_OPTIONAL, 'The name of the repository, will be added to satis.json', null),
    ])
    ->setHelp(<<<'EOT' ... EOT);
```

--------------------------------

### Application::run

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/application.md

Instantiates the Satis console application and runs it, processing the command-line arguments.

```APIDOC
## Application::run

### Description
Instantiates the Satis console application and runs it, processing the command-line arguments.

### Method
run()

### Usage
```php
use Composer\Satis\Console\Application;

$app = new Application();
$app->run();
// `php bin/satis build satis.json output`
```

```

--------------------------------

### execute() method implementation

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/remove-command.md

Implements the command logic: rejects remote config files (exit 2), checks file existence (exit 1), filters repositories to remove the matching URL, returns 4 if not found, otherwise writes the updated config and returns 0.

```php
protected function execute(InputInterface $input, OutputInterface $output): int
{
    /** @var FormatterHelper $formatter */
    $formatter = $this->getHelper('formatter');

    $configFile = $input->getArgument('file');
    $repositoryUrl = $input->getArgument('url');

    if (1 === preg_match('{^https?://}i', $configFile)) {
        $output->writeln('<error>Unable to write to remote file ' . $configFile . '</error>');

        return 2;
    }

    $file = new JsonFile($configFile);
    if (!$file->exists()) {
        $output->writeln('<error>File not found: ' . $configFile . '</error>');

        return 1;
    }

    $config = $file->read();
    $repositories = [];
    if (isset($config['repositories']) && is_array($config['repositories'])) {
        $repositories = $config['repositories'];
    }

    $remaining = array_values(array_filter(
        $repositories,
        static fn ($repository): bool => !isset($repository['url']) || $repository['url'] !== $repositoryUrl
    ));

    if (count($remaining) === count($repositories)) {
        $output->writeln('<error>Repository url not found in the file</error>');

        return 4;
    }

    $config['repositories'] = $remaining;

    $file->write($config);

    $output->writeln([
        '',
        $formatter->formatBlock('Your configuration file successfully updated! It\'s time to rebuild your repository', 'bg=blue;fg=white', true),
        '',
    ]);

    return 0;
}
```

--------------------------------

### getCommands() method

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/plugin.md

Returns an array of five command instances, each named with the 'satis:' prefix. The commands are constructed with a name argument, so the explicit constructor name wins over any name set in configure().

```php
public function getCommands()
{
    return [
        new AddCommand('satis:add'),
        new BuildCommand('satis:build'),
        new InitCommand('satis:init'),
        new PurgeCommand('satis:purge'),
        new RemoveCommand('satis:remove'),
    ];
}
```

--------------------------------

### PackagesBuilder constructor implementation

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/packages-builder.md

Initializes the builder with output, output directory, config, skip errors, and minify flag. Sets the filename to packages.json, include file name from config or default, and enables includes by default.

```php
/**
 * @param array<string, mixed> $config
 */
public function __construct(OutputInterface $output, string $outputDir, array $config, bool $skipErrors, bool $minify = false)
{
    parent::__construct($output, $outputDir, $config, $skipErrors);

    $this->filename = $this->outputDir . '/packages.json';
    $this->includeFileName = $config['include-filename'] ?? 'include/all$%hash%.json';
    $this->minify = $minify;
    $this->config['includes'] = $config['includes'] ?? true;
}
```

--------------------------------

### Resulting configuration file written by init

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/init-command.md

The JSON configuration that the init command writes when run with the given options.

```json
{
    "name": "My Repo",
    "homepage": "https://packages.example.org",
    "repositories": [],
    "require-all": true
}
```

--------------------------------

### ArchiveBuilderHelper constructor

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/archive-builder.md

Initializes the helper with the output interface and archive configuration. Sets default values for skip-dev, whitelist, and blacklist options.

```php
class ArchiveBuilderHelper
{
    /** @var OutputInterface The output Interface. */
    private $output;
    /** @var array<string, mixed> The 'archive' part of a configuration file. */
    private $archiveConfig;

    /**
     * @param array<string, mixed> $archiveConfig
     */
    public function __construct(OutputInterface $output,, array $archiveConfig)
    {
        $this->output = $output;
        $this->archiveConfig = $archiveConfig;
        $this->archiveConfig['skip-dev'] = (bool) ($archiveConfig['skip-dev'] ?? false);
        $this->archiveConfig['whitelist'] = (array) ($archiveConfig['whitelist'] ?? []);
        $this->archiveConfig['blacklist'] = (array) ($archiveConfig['blacklist'] ?? []);
    }
}
```

--------------------------------

### archive() method implementation (private)

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/archive-builder.md

Creates or reuses an archive based on configuration. Reads 'archive' config options: format, ignore-filters, override-dist-type, rearchive. Returns absolute path of the produced archive file.

```php
private function archive(DownloadManager $downloadManager, ArchiveManager $archiveManager, CompletePackageInterface $package, string $targetDir): string
{
    $format = (string) ($this->config['archive']['format'] ?? 'zip');
    $ignoreFilters = (bool) ($this->config['archive']['ignore-filters'] ?? false);
    $overrideDistType = (bool) ($this->config['archive']['override-dist-type'] ?? false);
    $rearchive = (bool) ($this->config['archive']['rearchive'] ?? true);
    // ... (see behavior)
}
```

--------------------------------

### PackageSelection::__construct

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/package-selection.md

Creates a new PackageSelection instance with the given output, build directory, configuration, and skipErrors flag.

```APIDOC
## PackageSelection::__construct

### Description
Creates a new PackageSelection instance.

### Method
Constructor

### Signature
```php
public function __construct(
    OutputInterface $output,
    string $buildDir,
    array $config,
    bool $skipErrors = false
)
```

### Parameters
- **$output** (OutputInterface) - Required - Output interface for writing messages.
- **$buildDir** (string) - Required - Directory where build output is stored.
- **$config** (array) - Required - Configuration array containing repositories, require-all, etc.
- **$skipErrors** (bool) - Optional - Whether to skip errors during selection.

### Example
```php
$selection = new PackageSelection(
    new ConsoleOutput(),
    'build-output',
    $config,
    false
);
```
```

--------------------------------

### PackageSelection constructor

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/package-selection.md

Constructor for PackageSelection. Initializes output, skipErrors, filename (outputDir/packages.json), repositories from config, and calls fetchOptions() to read config keys into state.

```php
/**
 * @param array<string, mixed> $config
 */
public function __construct(OutputInterface $output, string $outputDir, array $config, bool $skipErrors)
{
    $this->output = $output;
    $this->skipErrors = $skipErrors;
    $this->filename = $outputDir . '/packages.json';
    $this->repositories = $config['repositories'] ?? [];
    $this->fetchOptions($config);
}

```

--------------------------------

### activate method

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/plugin.md

Stores the Composer instance and IOInterface on the plugin object. Called once by Composer when interpreting the plugin.

```php
public function activate(Composer $composer,, IOInterface $io)
{
    $this->composer = $composer;
    $this->io = $io;
}
```

--------------------------------

### Constructor for Composer\Satis\Console\Application

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/application.md

Constructs the application, setting the name to 'Satis' and version to Satis::VERSION. Calls parent constructor without arguments.

```php
public function __construct()
{
    // Composer constructor does not allow passing
    parent::__construct();
    $this->setName('Satis');
    $this->setVersion(Satis::VERSION);
}
```

--------------------------------

### WebBuilder::__construct

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/web-builder.md

Creates a new WebBuilder instance with the given output, output directory, configuration, and error handling flag.

```APIDOC
## WebBuilder::__construct

### Description
Creates a new WebBuilder instance.

### Method
Constructor

### Parameters
- **$output** (mixed) - Required - Output stream or object.
- **$outputDir** (string) - Required - Directory where HTML output will be written.
- **$config** (array) - Required - Configuration array.
- **$skipErrors** (bool) - Required - Whether to skip errors.

### Example
```php
$web = new WebBuilder($output, $outputDir, $config, $skipErrors);
```
```

--------------------------------

### Usage with getComposerWithConfig

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/application.md

Creates an Application, then calls `getComposerWithConfig` with an initial config array. The returned Composer instance is shared; further calls can merge additional config into the same instance.

```php
use Composer\Satis\Console\Application;

$app = new Application();
$composer = $app->getComposerWithConfig([
    'name' => 'My Repo',
    'homepage' => 'https://packages.example.org',
]);
// $composer is a shared Composer instance; further callers may merge
// additional config into the same instance.
$app->getComposerWithConfig(['require-all' => true]);
```

--------------------------------

### getCapabilities method

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/plugin.md

Maps the Composer command-provider capability to CommandProvider::class, causing Composer to register the satis commands (satis:add, satis:build, satis:init, satis:purge, satis:remove) on the CLI.

```php
public function getCapabilities()
{
    return [
        'Composer\Plugin\Capability\CommandProvider' => CommandProvider::class,
    ];
}
```

--------------------------------

### execute method - writes config file

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/init-command.md

Returns exit code 0 on success, 1 if file already exists, 2 for remote file. Rejects remote (http:// or https://) targets with exit code 2. Fails with 1 when the target file already exists - never overwrites. Writes skeleton config and prints success banner.

```php
protected function execute(InputInterface $input, OutputInterface $output): int
{
    /** @var FormatterHelper $formatter */
    $formatter = $this->getHelper('formatter');

    $configFile = $input->getArgument('file');

    if (1 === preg_match('{^https?://}i', $configFile)) {
        $output->writeln('<error>Unable to write to remote file ' . $configFile . '</error>');

        return 2;
    }

    $file = new JsonFile($configFile);
    if ($file->exists()) {
        $output->writeln('<error>Configuration file already exists</error>');

        return 1;
    }

    $config = [
        'name' => $input->getOption('name'),
        'homepage' => $input->getOption('homepage'),
        'repositories' => [],
        'require-all' => true,
    ];

    $file->write($config);

    $output->writeln([
        '',
        $formatter->formatBlock('Your configuration file successfully created!', 'bg=blue;fg=white', true),
        '',
    ]);

    $output->writeln([
        '',
        'You are ready to add your package repositories',
        'Use <comment>satis add repository-url</comment> to add them.',
        '',
    ]);

    return 0;
}
```

```json
{
    "name": "<name>",
    "homepage": "<homepage>",
    "repositories": [],
    "require-all": true
}
```

--------------------------------

### Run Satis Docker container to build repository

Source: https://github.com/composer/satis/blob/main/README.md

Runs the Satis Docker container with the build command, mounting the current directory and the Composer cache from the host.

```sh
docker run --rm --init -it \
  --user $(id -u):$(id -g) \
  --volume $(pwd):/build \
  --volume "${COMPOSER_HOME:-$HOME/.composer}:/composer" \
  composer/satis build <configuration-file> <output-directory>
```

--------------------------------

### dump() method signature and implementation

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/packages-builder.md

The dump() method accepts an array of packages, groups them by name and version, and uses ArrayDumper to dump each package. It then writes repository files according to configuration. The method returns void and may throw exceptions as documented.

```php
public function dump(array $packages): void
{
    $packagesByName = [];
    $dumper = new ArrayDumper();
    foreach ($packages as $package) {
        $packagesByName[$package->getName()][$package->getPrettyVersion()] = $dumper->dump($package);
    }
    // ... (see behavior below)
}
```

--------------------------------

### ArchiveBuilder usage via BuildCommand

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/archive-builder.md

Instantiate ArchiveBuilder with output, outputDir, config, and skipErrors, then set Composer and Input, and call dump with packages. Used when config['archive']['directory'] is present.

```php
$downloads = new ArchiveBuilder($output, $outputDir, $config, $skipErrors);
$downloads->setComposer($composer);
$downloads->setInput($input);
$downloads->dump($packages);
```

--------------------------------

### Error case when target file already exists

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/init-command.md

Running init when the target file already exists prints 'Configuration file already exists' and exits with code 1.

```bash
php bin/satis init
Configuration file already exists
echo $?
# 1
```

--------------------------------

### Add repository with explicit driver and name

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/add-command.md

Usage with `--type` and `--name` options to specify the repository type and a custom name.

```bash
php bin/satis add git@github.com:mycompany/private-repo.git \
  --type=git --name="mycompany source" my-satis.json
```

--------------------------------

### Incremental build with error handling

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/build-command.md

Runs the build with --skip-errors and checks the exit status to report success or hard failure.

```bash
if php bin/satis build --skip-errors satis.json build-output; then
  echo "build completed (errors skipped)"
else
  echo "hard failure: $?"
fi
```

--------------------------------

### Build with remote config

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/build-command.md

Builds using a configuration file fetched over HTTP.

```bash
php bin/satis build https://example.org/satis.json build-output
```

--------------------------------

### Error handling: URL not found

Source: https://github.com/composer/satis/blob/main/_autodocs/api-reference/remove-command.md

Shows the command output and exit code when the repository URL is not present in the config file.

```bash
php bin/satis remove https://example.org/never-added
# Repository url not found in the file
echo $?   # 4
```

--------------------------------

### Build command

Source: https://github.com/composer/satis/blob/main/docs/using.md

Command to build the Satis repository: php bin/satis build <configuration file> <build dir>. Add --no-interaction (or -n) for non-interactive use with SSH key authentication.

```bash
php bin/satis build <configuration file> <build dir>
```
Tokens:
Raw