### 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 Satis executable.

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

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

### Complete Satis Configuration Example

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

A comprehensive example of a Satis configuration file, demonstrating various settings such as repository definitions, package requirements, stability settings, and detailed configuration for Composer.

```json
{
    "name": "Private Composer Repository",
    "description": "Company-wide package repository",
    "homepage": "https://packages.company.com",
    "keywords": ["private", "packages"],
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/company/library-a.git"
        },
        {
            "type": "vcs",
            "url": "https://github.com/company/library-b.git"
        },
        {
            "type": "vcs",
            "url": "https://internal.company.com/git/legacy.git"
        }
    ],
    "repositories-dep": [
        {
            "type": "composer",
            "url": "https://repo.packagist.org"
        }
    ],
    "require-all": false,
    "require": {
        "company/library-a": ">=1.0",
        "company/library-b": "@dev"
    },
    "require-dependencies": true,
    "require-dev-dependencies": false,
    "minimum-stability": "stable",
    "minimum-stability-per-package": {
        "company/experimental": "dev"
    },
    "abandoned": {
        "company/old-lib": "company/library-a"
    },
    "blacklist": {
        "company/library": "<1.0"
    },
    "include-types": ["library", "symfony-bundle"],
    "exclude-types": ["metapackage"],
    "strip-hosts": [
        "internal.company.com",
        "192.168.0.0/16",
        "/private"
    ],
    "output-dir": "build",
    "output-html": true,
    "allow-seo-indexing": false,
    "notify-batch": "https://packages.company.com/downloads",
    "archive": {
        "directory": "downloads",
        "format": "zip",
        "prefix-url": "https://cdn.company.com/packages",
        "checksum": true,
        "skip-dev": false,
        "whitelist": ["company/*"],
        "rearchive": true
    },
    "config": {
        "process-timeout": 600,
        "preferred-install": "dist",
        "github-oauth": {
            "github.com": "ghp_xxx..."
        },
        "http-basic": {
            "internal.company.com": {
                "username": "satis",
                "password": "xxx"
            }
        }
    }
}
```

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

### Install Tooling and Dependencies

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

Installs tooling and dependencies for Satis development by iterating through directories in 'tools' and running composer install.

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

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

### Satis Configuration Example

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

A comprehensive example of a Satis configuration file. This JSON structure defines repository metadata, package requirements, and archive settings.

```json
{
  "name": "My Satis Repository",
  "description": "A descriptive line of text goes here.",
  "homepage": "http://packages.example.org",
  "repositories": [{
    "type": "composer",
    "url": "https://packagist.org"
  }],
  "repositories-dep": [],
  "require": {
    "company/package1": "1.2.0",
    "company/package2": "^1.5.2",
    "company/package3": "dev-master|dev-develop"
  },
  "archive": {
    "directory": "dist",
    "format": "tar",
    "skip-dev": true,
    "absolute-directory": "/path",
    "prefix-url": "https://amazing.cdn.example.org",
    "whitelist": [ "company/package1" ],
    "blacklist": [ "company/package2" ],
    "checksum": true,
    "ignore-filters": false,
    "override-dist-type": true,
    "rearchive": true
  },
  "abandoned": {
    "company/package": true,
    "company/package2": "company/newpackage"
  },
  "require-all": false,
  "require-dependencies": true,
  "require-dev-dependencies": true,
  "providers": false,
  "providers-history-size": 0,
  "output-dir": "output",
  "output-html": true,
  "twig-template": "views/index.html.twig",
  "config": {

  },
  "strip-hosts": [],
  "notify-batch": "https://example.com/endpoint"
}
```

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

### Install Satis from Source

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

Installs Satis using Composer. Ensure you are using a supported PHP version as specified in composer.json.

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

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

### Using Composer Satis Console Commands

Source: https://github.com/composer/satis/blob/main/_autodocs/04-console-commands.md

Once installed as a Composer dependency, Satis commands can be executed directly via the 'composer' executable. Examples include building the repository, initializing Satis, adding repositories, and purging old data.

```bash
composer satis:build satis.json ./build
```

```bash
composer satis:init
```

```bash
composer satis:add https://github.com/user/repo.git
```

```bash
composer satis:purge satis.json ./build
```

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

### Install Satis using Composer

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

Create a new Satis project using Composer and navigate into the project directory.

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

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

### Include Package Types Configuration

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

Example configuration showing how to specify package types to be included. Only packages with these types will be kept.

```json
"include-types": ["library", "symfony-bundle"]
```

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

### JSON Configuration Example

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

Demonstrates a simple JSON object used for configuration, presented in a language-tagged code block.

```json
// JSON configuration
{"key": "value"}
```

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

### Instantiate and Dump PackagesBuilder

Source: https://github.com/composer/satis/blob/main/_autodocs/02-builders-api.md

Example of how to instantiate the PackagesBuilder with necessary parameters and then use the dump method to generate repository metadata. Ensure the output directory and configuration are correctly set.

```php
$builder = new PackagesBuilder($output, '/path/to/build', $config, false, true);
$builder->dump($selectedPackages);
// Creates /path/to/build/packages.json with metadata URLs
```

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

### ArchiveBuilderHelper Example Usage

Source: https://github.com/composer/satis/blob/main/_autodocs/02-builders-api.md

Demonstrates how to instantiate and use the ArchiveBuilderHelper to get the archive directory and check if packages should be archived.

```php
$helper = new ArchiveBuilderHelper($output, $config['archive']);
$archiveDir = $helper->getDirectory($outputDir);

foreach ($packages as $package) {
    if (!$helper->isSkippable($package)) {
        // Archive this package
    }
}
```

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

### Minimal Satis Configuration

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

This is a basic configuration file for Satis. It specifies the repository name, homepage, a VCS repository to mirror, and sets the output directory. Use this as a starting point for your Satis setup.

```json
{
    "name": "My Repository",
    "homepage": "https://example.com",
    "repositories": [{"type": "vcs", "url": "..."}],
    "require-all": true,
    "output-dir": "build"
}
```

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

### PHP Namespace Import Example

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

Demonstrates how to import a class using its full namespace in PHP.

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

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

### Enable Package Archives

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

Configure Satis to download and store packages locally for faster installations. This setup enables archiving with a specified directory, format, prefix URL, and checksum validation.

```json
{
    "name": "Private Packages",
    "homepage": "https://packages.company.com",
    "repositories": [...],
    "require-all": true,
    "archive": {
        "directory": "downloads",
        "format": "zip",
        "prefix-url": "https://cdn.company.com/packages",
        "checksum": true,
        "skip-dev": false
    },
    "output-dir": "build"
}
```

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

### Example Archive Whitelist/Blacklist Configuration

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

Configure archive directory, whitelist, and blacklist patterns. Supports wildcard matching for package names.

```json
{
    "archive": {
        "directory": "downloads",
        "whitelist": ["vendor/included-*", "other/*"],
        "blacklist": ["vendor/excluded-*"]
    }
}
```

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

### Basic Satis Configuration Structure

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

This is a minimal example of a Satis JSON configuration file, defining repository name, homepage, and a VCS repository.

```json
{
    "name": "Repository Name",
    "homepage": "https://packages.example.com",
    "repositories": [
        {"type": "vcs", "url": "https://github.com/user/repo.git"}
    ],
    "require-all": true,
    "output-dir": "build"
}
```

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

### Shell Command Example

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

Shows a typical command-line interface command for Satis, presented in a language-tagged code block.

```bash
# Shell commands
php bin/satis build
```

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

### ArchiveBuilder Example Usage

Source: https://github.com/composer/satis/blob/main/_autodocs/02-builders-api.md

Demonstrates how to instantiate and use the ArchiveBuilder to create package archives. This involves setting the Composer and input instances before calling the dump method.

```php
$archive = new ArchiveBuilder($output, '/path/to/build', $config, false);
$archive->setComposer($composer);
$archive->setInput($input);
$archive->dump($packages);
```

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

### Complete Satis Configuration Example

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

This JSON configuration defines a private repository with multiple VCS sources, package requirements, stability settings, and archive options. It includes authentication details for private repositories and output directory settings.

```json
{
    "name": "Company Private Repository",
    "description": "Production and staging packages",
    "homepage": "https://packages.company.com",
    "keywords": ["private", "packages", "company"],
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/company/lib-core.git",
            "name": "Core Library"
        },
        {
            "type": "vcs",
            "url": "https://github.com/company/lib-utils.git",
            "name": "Utilities"
        },
        {
            "type": "vcs",
            "url": "git@internal.company.com:repos/legacy.git",
            "name": "Legacy Code"
        }
    ],
    "require": {
        "company/lib-core": "^2.0",
        "company/lib-utils": "^1.0"
    },
    "require-dependencies": true,
    "minimum-stability": "stable",
    "minimum-stability-per-package": {
        "company/experimental": "beta"
    },
    "abandoned": {
        "company/old-lib": "company/lib-core"
    },
    "blacklist": {
        "company/lib-core": "<2.0"
    },
    "exclude-types": ["metapackage"],
    "strip-hosts": ["internal.company.com"],
    "output-dir": "build",
    "output-html": true,
    "allow-seo-indexing": false,
    "notify-batch": "https://packages.company.com/downloads",
    "archive": {
        "directory": "downloads",
        "format": "zip",
        "prefix-url": "https://cdn.company.com/packages",
        "checksum": true,
        "skip-dev": false,
        "whitelist": ["company/*"],
        "rearchive": true
    },
    "config": {
        "process-timeout": 600,
        "preferred-install": "dist",
        "http-basic": {
            "internal.company.com": {
                "username": "satis",
                "password": "xxx"
            }
        }
    }
}
```

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

### Example Repository File URLs

Source: https://github.com/composer/satis/blob/main/_autodocs/07-repository-output-format.md

Illustrates the URL structure for various files within a Composer Satis repository, including include files, providers, metadata, and archives.

```text
https://packages.example.com/include/all$hash.json
https://packages.example.com/p/vendor-package$hash.json
https://packages.example.com/p2/vendor/package.json
https://packages.example.com/downloads/vendor/package-1.0.0.zip
```

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

### PurgeCommand Usage Examples

Source: https://github.com/composer/satis/blob/main/_autodocs/04-console-commands.md

Demonstrates how to use the PurgeCommand to identify and delete unreferenced package archive files.

```bash
# See what would be deleted
php bin/satis purge satis.json ./build dry-run
```

```bash
# Actually delete unreferenced archives
php bin/satis purge satis.json ./build
```

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

### Get Satis Configuration and Composer Instance

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

Load the Satis configuration from a JSON file and obtain a Composer instance with the loaded configuration.

```php
$config = json_decode(file_get_contents('satis.json'), true);
$composer = $app->getComposerWithConfig($config);
```

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

### PHP Method Signature Example

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

Displays the syntax for a public method signature in PHP, including parameter types and return type.

```php
public function methodName(Type $param): ReturnType
```

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

### Satis Composer Plugin Implementation

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

Example of implementing the PluginInterface and Capable interface for a Satis Composer plugin. This defines the plugin's capabilities, such as providing commands.

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

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

### Non-interactive Satis Initialization with Options

Source: https://github.com/composer/satis/blob/main/_autodocs/04-console-commands.md

Initialize a satis.json file non-interactively by providing all required options as command-line arguments. This is useful for scripting or automated setups.

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

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

### Hash Computation for Cache Busting

Source: https://github.com/composer/satis/blob/main/_autodocs/07-repository-output-format.md

Example demonstrating how file content is hashed (SHA256 by default) and how this hash is incorporated into the file path for cache busting. This ensures clients automatically use updated content when package information changes.

```text
File content: {"packages":{"vendor/package":{"1.0.0":{...}}}}
SHA256 hash: abc123def456... (64 characters)
File path: include/all$abc123def456....json
```

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

### PHP Code Block Example

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

Illustrates a basic PHP class definition within a language-tagged code block.

```php
// PHP code
class Example {}
```

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

### Add Repository with Explicit Type and Name

Source: https://github.com/composer/satis/blob/main/_autodocs/04-console-commands.md

This example demonstrates adding a repository with an explicit VCS type (e.g., 'gitlab') and a custom name. This is useful for non-standard Git repositories or when you want to assign a specific name to the repository in your configuration.

```bash
php bin/satis add https://gitlab.example.com/group/repo.git satis.json \
    --type gitlab \
    --name "My Gitlab Repo"
```

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

### Enable Archive Downloads in Satis

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

Configure Satis to create local downloads for all package types, including Git, Mercurial, and Subversion. This speeds up installations by providing local copies.

```json
{
    "archive": {
        "directory": "dist",
        "format": "tar",
        "prefix-url": "https://amazing.cdn.example.org",
        "skip-dev": true
    }
}
```

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

### Initialize and Build Minimal Repository with Satis

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

Use these commands to initialize Satis, add a repository, and build the package index.

```bash
php bin/satis init
php bin/satis add https://github.com/user/repo.git
php bin/satis build satis.json ./build
```

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

### Initialize Satis Configuration

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

Use this command to create a new Satis configuration file. It will prompt for repository name and home page.

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

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

### Satis CLI: Initialize Command

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

Initializes a new Satis configuration file. Specify the output file and optionally a name for the repository.

```bash
# Initialize
php bin/satis init [file] [--name="..."] [--homepage="..."]
```

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

### Select All Packages in Satis Configuration

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

Use 'require-all': true to include all packages from the defined repositories. Specify 'output-dir' for the build output location.

```json
{
    "repositories": [{"type": "vcs", "url": "https://github.com/user/repo.git"}],
    "require-all": true,
    "output-dir": "build"
}
```

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

### Build Repository from Source

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

Builds a static Composer repository using the Satis CLI. Requires a configuration file and an output directory.

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

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

### Satis Build and Deploy Commands

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

These bash commands demonstrate how to build the Satis repository, deploy it to a web server using rsync, and clean up old archives.

```bash
# Full build with progress
php bin/satis build satis.json --stats
```

```bash
# Deploy to web server
rsync -av build/ user@packages.company.com:/var/www/packages/
```

```bash
# Clean up old archives
php bin/satis purge satis.json build
```

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

### ArchiveBuilderHelper Class Definition

Source: https://github.com/composer/satis/blob/main/_autodocs/02-builders-api.md

Defines the structure and methods of the ArchiveBuilderHelper class, including its constructor and methods for getting the archive directory and checking if a package is skippable.

```php
class ArchiveBuilderHelper
{
    public function __construct(OutputInterface $output, array $archiveConfig)
    
    public function getDirectory(string $outputDir): string
    
    public function isSkippable(PackageInterface $package): bool
}
```

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

### Basic Satis Configuration with Require-All

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

Define a Satis configuration file to list VCS repositories and use 'require-all' to include all versions of all packages from these repositories.

```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
}
```

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

### Interactive Initialization of Satis Configuration

Source: https://github.com/composer/satis/blob/main/_autodocs/04-console-commands.md

Use this command to interactively create a new satis.json configuration file. The command will prompt for necessary details like repository name and homepage.

```bash
php bin/satis init
# Prompts for name and homepage
```

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

### Build Repository Programmatically with Satis

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

Use the PackageSelection and PackagesBuilder classes to programmatically select packages and dump the repository index.

```php
$selection = new PackageSelection($output, $outputDir, $config, false);
$packages = $selection->select($composer, true);

$builder = new PackagesBuilder($output, $outputDir, $config, false);
$builder->dump($packages);
```

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

### BuildCommand Execution Flow

Source: https://github.com/composer/satis/blob/main/_autodocs/04-console-commands.md

Outlines the step-by-step process executed by the BuildCommand, from loading configuration to generating output.

```php
protected function execute(InputInterface $input, OutputInterface $output): int
```

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

### Use Available Package Patterns

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

Configure Satis to use patterns for available packages instead of listing all package names. This can improve performance for large repositories.

```json
{
    "available-package-patterns": [
        "company/*",
        "vendor/*",
        "special/*"
    ]
}
```

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

### Composer Configuration Options

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

Common Composer configuration options that can be set in the 'config' section. This includes process timeouts, preferred installation methods, and authentication details for GitHub and private repositories.

```json
{
    "config": {
        "process-timeout": 300,
        "preferred-install": "dist",
        "github-oauth": {
            "github.com": "your-token-here"
        },
        "http-basic": {
            "private.repo.com": {
                "username": "user",
                "password": "pass"
            }
        },
        "platform": {
            "php": "8.3"
        }
    }
}
```

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

### Select Specific Packages with Dependencies in Satis

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

Use the 'require' key to list specific packages and 'require-dependencies': true to include their dependencies. 'output-dir' specifies the build output.

```json
{
    "repositories": [{"type": "vcs", "url": "https://github.com/user/repo.git"}],
    "require": {
        "vendor/package1": "^1.0",
        "vendor/package2": "*"
    },
    "require-dependencies": true,
    "output-dir": "build"
}
```

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

### Override Docker Entrypoint

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

Overrides the default entrypoint for the Satis Docker container to run Satis interactively or with custom commands. Use this if you do not want to implicitly run Satis upon container start.

```sh
--entrypoint /bin/sh
```

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

### Build Satis Repository

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

Generate the static repository files using the 'build' command. This creates packages.json, index.html, and other necessary files.

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

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

### Build Repository with Archives and Purge Old Packages

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

After configuring archives in satis.json, build the repository and then purge old packages from the build directory.

```bash
# Edit satis.json to add archive configuration
php bin/satis build satis.json ./build --stats
php bin/satis purge satis.json ./build
```

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

### Initial Satis Configuration File

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

The default satis.json file created after initialization.

```json
{
    "name": "My Company Packages",
    "homepage": "https://packages.company.com",
    "repositories": [],
    "require-all": true
}
```

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

### Build with archives and display progress

Source: https://github.com/composer/satis/blob/main/_autodocs/04-console-commands.md

Command to build packages, including creating archives, and display a progress bar for download operations.

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

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

### Mirror Packages from Multiple Repositories in Satis

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

Define multiple repositories in the 'repositories' array and set 'require-all': true to mirror all packages from these sources. 'output-dir' is for the build output.

```json
{
    "repositories": [
        {"type": "vcs", "url": "https://github.com/user/repo1.git"},
        {"type": "vcs", "url": "https://github.com/user/repo2.git"}
    ],
    "require-all": true,
    "output-dir": "build"
}
```

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

### Build Repository using Satis CLI

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

The Satis CLI command for building a repository, specifying the configuration file, output directory, and optional packages or options.

```bash
php bin/satis build [file] [output-dir] [packages...] [options]
```

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

### Configure Satis with Filtering Options

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

This JSON configuration demonstrates how to set up Satis with package requirements, dependency handling, blacklisting, and type exclusion.

```json
{
    "require": {"vendor/pkg": "^1.0"},
    "require-dependencies": true,
    "blacklist": {"vendor/old": "<2.0"},
    "exclude-types": ["metapackage"]
}
```

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

### Satis CLI: Build Command

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

Builds the Satis repository metadata. Specify the configuration file, output directory, and optionally packages to include.

```bash
# Build
php bin/satis build [file] [output-dir] [packages...] [options]
```

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

### Configure Abandoned Packages in Satis

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

Specify packages that are abandoned or replaced by new ones. Use `true` for truly abandoned packages and a string for the replacement package name.

```json
{
    "abandoned": {
        "company/package": true,
        "company/package2": "company/newpackage"
    }
}
```

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

### Initialize Satis Application

Source: https://github.com/composer/satis/blob/main/_autodocs/04-console-commands.md

Instantiates the Satis Application class. Used to manage Satis functionalities.

```php
class Application extends ComposerApplication
{
    public function __construct()
    
    public function getComposerWithConfig(mixed $config): ?Composer
}
```

```php
$app = new Application();
$config = json_decode(file_get_contents('satis.json'), true);
$composer = $app->getComposerWithConfig($config);
```

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

### Build Satis with Multiple Repositories

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

Use this command to build your Satis repository by including artifacts from multiple specified Git repositories.

```bash
php bin/satis build satis.json ./build \
    --repository-url https://github.com/company/main.git \
    --repository-url https://github.com/company/secondary.git
```

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

### Run Satis using Docker

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

Pull the Satis Docker image and run it, mounting a workspace for build artifacts.

```bash
docker pull composer/satis
docker run --rm -it -v <workspace>:/build composer/satis
```

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

### Mark Packages as Abandoned in Satis

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

Use the 'abandoned' key to mark packages. Set to 'true' to indicate abandonment or provide a string to suggest a replacement package. 'output-dir' specifies the build output.

```json
{
    "repositories": [...],
    "require-all": true,
    "abandoned": {
        "vendor/old-package": true,
        "vendor/replaced-package": "vendor/new-package"
    },
    "output-dir": "build"
}
```

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

### Verbose Build Output

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

Enable detailed information during the Satis build process, useful for debugging package selection issues.

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

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

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

### Satis Configuration with Added Repositories

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

The satis.json file after adding two Git repositories.

```json
{
    "name": "My Company Packages",
    "homepage": "https://packages.company.com",
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/company/lib-a.git"
        },
        {
            "type": "vcs",
            "url": "https://github.com/company/lib-b.git"
        }
    ],
    "require-all": true
}
```

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

### Add Repositories to Satis

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

Add your package repositories to the Satis configuration using the 'add' command.

```bash
php bin/satis add https://github.com/company/lib-a.git
php bin/satis add https://github.com/company/lib-b.git
```

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

### PackageSelection Constructor

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

Initializes a new instance of the PackageSelection class. Requires an output interface, output directory, configuration array, and a flag to skip errors.

```php
public function __construct(
    OutputInterface $output,
    string $outputDir,
    array $config,
    bool $skipErrors
)
```

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

### Build Satis with a Single Repository

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

Use this command to build your Satis repository using artifacts from only one specified Git repository.

```bash
php bin/satis build satis.json ./build \
    --repository-url https://github.com/company/main.git
```

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

### BuildCommand

Source: https://github.com/composer/satis/blob/main/_autodocs/04-console-commands.md

The BuildCommand is used to read Satis configuration, select packages, and generate repository output, including HTML pages.

```APIDOC
## BuildCommand

**Namespace**: `Composer\Satis\Console\Command`

Reads configuration, selects packages, and generates repository output.

```php
class BuildCommand extends BaseCommand
{
    protected function configure(): void
    protected function execute(InputInterface $input, OutputInterface $output): int
}
```

### Arguments

| Name | Required | Description |
|------|----------|-------------|
| file | No | JSON config file path (default: `./satis.json`). Can be HTTP(S) URL. |
| output-dir | No | Output directory for repository. Can be specified here or in config file. |
| packages | No | Specific package names to build (space-separated). If provided, only these packages are selected. |

### Options

| Option | Value | Description |
|--------|-------|-------------|
| --repository-url | Required, multiple | Only update repositories at given URL(s). Incompatible with `packages` argument. |
| --repository-strict | None | Apply repository filter when resolving dependencies |
| --no-html-output | None | Skip HTML page generation |
| --skip-errors | None | Continue on download or archive errors instead of failing |
| --stats | None | Display progress bar for archive downloads |
| --minify | None | Minify JSON output using `composer/2.0` algorithm |

### Configuration File Loading

The command loads configuration from:

1. HTTP(S) URL if file matches `{^https?://}i` pattern — fetched via RemoteFilesystem
2. Local file path — parsed as JSON

**Validation**: Configuration is validated against `res/satis-schema.json` schema using JsonSchema validator.

**Authentication**: Loads `auth.json` from `COMPOSER_HOME` for repository authentication.

**Environment Variables**:

- `SATIS_HOMEPAGE`: Overrides `homepage` in config
- `COMPOSER_HOME`: Composer configuration home directory

### Execution Flow

```php
protected function execute(InputInterface $input, OutputInterface $output): int
```

**Process**:

1. **Load config** from file (local or remote)
2. **Validate config** against JSON schema
3. **Check output directory** — must be specified in arguments or config
4. **Initialize Composer** with satis config merged into composer configuration
5. **Setup repositories** — add configured repositories to Composer's repository manager
6. **Create root package** — treat satis.json as a pseudo-package for dependency resolution
7. **Create PackageSelection** — with optional package/repository filters
8. **Select packages** via PackageSelection::select()
9. **Archive packages** (if archive.directory is configured)
10. **Clean packages** (apply strip-hosts filtering)
11. **Merge with existing packages** (if incremental build with filters)
12. **Dump packages** via PackagesBuilder
13. **Generate HTML** via WebBuilder (unless --no-html-output)

**Return Codes**:

- `0`: Success
- `1`: File not found or output directory not specified
- Other: Exception thrown (if not caught)

### Example Usage

**Build all packages from configured repositories**:

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

**Build specific packages**:

```bash
php bin/satis build satis.json ./build vendor/package1 vendor/package2
```

**Update single repository**:

```bash
php bin/satis build satis.json ./build --repository-url https://github.com/user/repo.git
```

**Build with archives and display progress**:

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

**Minify output for large repositories**:

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

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

### PackageSelection Class Overview

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

Provides an overview of the PackageSelection class methods and their signatures.

```php
class PackageSelection
{
    public function __construct(
        OutputInterface $output,
        string $outputDir,
        array $config,
        bool $skipErrors
    )
    
    public function select(PartialComposer $composer, bool $verbose): array
    
    public function clean(): array
    
    public function load(): array
    
    // Configuration
    public function setPackagesFilter(array $packagesFilter = []): void
    public function setRepositoriesFilter(?array $repositoriesFilter, bool $forDependencies = false): void
    
    // State checks
    public function hasFilterForPackages(): bool
    public function hasRepositoriesFilter(): bool
    public function hasBlacklist(): bool
    public function hasTypeFilter(): bool
}
```

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

### Build Satis Repository with Selective Inclusion

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

Build the repository using the configuration that specifies required packages. This ensures only the defined packages and their dependencies are included.

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

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

### load()

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

Loads existing packages from a previously built `packages.json` file, typically used for incremental builds.

```APIDOC
## load()

### Description
Loads existing packages from a previously built `packages.json` file, typically used for incremental builds.

### Method
`load(): array`

### Returns
- `array<string, PackageInterface>` — Packages from previously built packages.json

### Purpose
Loads existing packages for incremental builds. Used by `BuildCommand` when adding new packages to an existing repository.

### Process
1. Reads `packages.json` from outputDir
2. Processes both v1.0 includes and v2.0 providers
3. Returns all packages except those in `packagesFilter` (filtered packages are excluded)

### Example Usage
```php
// Incremental build: add new packages to existing repository
$packages = $packageSelection->select($composer, false);
if ($packageSelection->hasFilterForPackages()) {
    $oldPackages = $packageSelection->load();
    $packages += $oldPackages; // Merge new and old
    ksort($packages);
}
```
```

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

### Build specific packages

Source: https://github.com/composer/satis/blob/main/_autodocs/04-console-commands.md

Command to build only a specified list of packages from the configuration, useful for targeted updates.

```bash
php bin/satis build satis.json ./build vendor/package1 vendor/package2
```

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

### Satis Configuration with Specific Package Requirements

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

Configure Satis to include specific packages from defined repositories using the 'require' key. Use '*' to include all versions or specify exact 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"
    }
}
```

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

### Full Satis Configuration Structure

Source: https://github.com/composer/satis/blob/main/_autodocs/06-types.md

This defines the complete structure for the `satis.json` file, including all available options and their expected types. Use this as a reference for creating or validating your Satis configuration.

```php
array{
    'name': string,
    'homepage': string,
    'description'?: string,
    'keywords'?: array<string>,
    'repositories'?: array<array{
        'type': string,
        'url': string,
        'name'?: string
    }>,
    'repositories-dep'?: array,
    'require'?: array<string, string>,
    'require-all'?: bool,
    'require-dependencies'?: bool,
    'require-dev-dependencies'?: bool,
    'only-dependencies'?: bool,
    'only-best-candidates'?: bool,
    'require-dependency-filter'?: bool,
    'minimum-stability'?: string,
    'minimum-stability-per-package'?: array<string, string>,
    'abandoned'?: array<string, bool|string>,
    'blacklist'?: array<string, string>,
    'include-types'?: array<string>|null,
    'exclude-types'?: array<string>,
    'strip-hosts'?: array<string>|bool,
    'include-filename'?: string,
    'includes'?: bool,
    'available-package-patterns'?: array<string>,
    'output-dir'?: string,
    'output-html'?: bool,
    'providers'?: bool,
    'providers-history-size'?: int,
    'notify-batch'?: string,
    'twig-template'?: string,
    'allow-seo-indexing'?: bool,
    'pretty-print'?: bool,
    'archive'?: array{
        'directory': string,
        'absolute-directory'?: string,
        'prefix-url'?: string,
        'format'?: string,
        'checksum'?: bool,
        'skip-dev'?: bool,
        'whitelist'?: array<string>,
        'blacklist'?: array<string>,
        'ignore-filters'?: bool,
        'override-dist-type'?: bool,
        'rearchive'?: bool
    },
    'config'?: array<string, mixed>
}
```

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

### Select Packages

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

The `select` method is the core function for package selection. It filters repositories and packages, resolves dependencies, and applies various pruning rules. Use `verbose` for additional output during the process.

```php
public function select(PartialComposer $composer, bool $verbose): array
```

```php
$packageSelection = new PackageSelection($output, $outputDir, $config, false);
$packageSelection->setRepositoriesFilter(['https://github.com/user/repo.git']);
$packages = $packageSelection->select($composer, true);
```

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

### Build Satis with Progress Stats

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

Execute the Satis build command with the --stats flag to display progress and statistics during the build process. This is useful for monitoring the archiving of all packages.

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

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

### Build Custom Docker Image with GitHub Token

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

Create a custom Satis Docker image, injecting a GitHub token as a build argument for private repository access.

```bash
docker build -t my-satis \
  --build-arg GITHUB_TOKEN=ghp_xxx \
  .
```

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

### Application Class

Source: https://github.com/composer/satis/blob/main/_autodocs/04-console-commands.md

The main Satis application class, extending Composer's application, provides methods for initializing Composer with Satis configuration.

```APIDOC
## Application

**Namespace**: `Composer\Satis\Console`

```php
class Application extends ComposerApplication
{
    public function __construct()
    public function getComposerWithConfig(mixed $config): ?Composer
}
```

**Constructor**: No parameters. Sets application name to "Satis" and version from `Satis::VERSION`.

**Method**: `getComposerWithConfig()`

```php
public function getComposerWithConfig(mixed $config): ?Composer
```

**Parameter**: `mixed $config` — Configuration array (must be `array` if Composer instance already exists)

**Returns**: `?Composer` — Composer instance configured with satis configuration

**Process**:

1. Creates Composer instance from config using `Factory::create()`
2. Merges config with existing Composer config if instance already exists
3. Returns `null` if `InvalidArgumentException` occurs and exceptions are caught

**Example Usage**:

```php
$app = new Application();
$config = json_decode(file_get_contents('satis.json'), true);
$composer = $app->getComposerWithConfig($config);
```
```

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

### Satis Init Command

Source: https://github.com/composer/satis/blob/main/_autodocs/06-types.md

Represents the Init command for Composer Satis, extending the base command class.

```php
class InitCommand extends BaseCommand
```

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

### Configure HTTP Basic Auth for Private Repositories

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

Add credentials to `~/.composer/auth.json` for private repositories. This allows Composer to authenticate with private Git repositories using username and password.

```bash
# Create/edit ~/.composer/auth.json
{
    "http-basic": {
        "private.company.com": {
            "username": "satis-user",
            "password": "secure-password"
        }
    }
}
```

```json
{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://private.company.com/repos/lib-a.git"
        }
    ]
}
```

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

### BuildCommand Class Structure

Source: https://github.com/composer/satis/blob/main/_autodocs/04-console-commands.md

Defines the structure of the BuildCommand, responsible for reading configuration, selecting packages, and generating repository output.

```php
class BuildCommand extends BaseCommand
{
    protected function configure(): void
    protected function execute(InputInterface $input, OutputInterface $output): int
}
```

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

### Provide Platform Version in Composer Configuration

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

Mock PHP version or extensions within the Satis configuration. Useful when building on a different PHP version than the target environment.

```json
{
    "config": {
        "platform": {
            "php": "8.2",
            "ext-redis": "7.0"
        }
    }
}
```

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

### Include All Dependencies in Satis Config

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

Use this configuration to automatically resolve and include all regular and dev dependencies for a specified package.

```json
{
    "require": {
        "company/app": "@dev"
    },
    "require-dependencies": true,
    "require-dev-dependencies": true,
    "output-dir": "build"
}
```

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

### ArchiveBuilderHelper Constructor

Source: https://github.com/composer/satis/blob/main/_autodocs/02-builders-api.md

Initializes the ArchiveBuilderHelper with an output interface for logging and the archive configuration.

```APIDOC
## ArchiveBuilderHelper::__construct

### Description
Initializes the ArchiveBuilderHelper with an output interface for logging and the archive configuration.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **output** (`OutputInterface`) - Required - For logging skip reasons
- **archiveConfig** (`array`) - Required - The `config['archive']` section

### Request Example
```php
$helper = new ArchiveBuilderHelper($output, $config['archive']);
```

### Response
None
```

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

### Satis CLI: Add Repository Command

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

Adds a new repository to the Satis configuration. You can specify the repository URL, type, and name.

```bash
# Add repository
php bin/satis add <url> [file] [--type=vcs] [--name="..."]
```

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

### PackageSelection Constructor

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

Initializes a new instance of the PackageSelection class. It requires an output interface for progress messages, the output directory, configuration settings, and a flag to control error handling during package resolution.

```APIDOC
## Constructor PackageSelection

### Description
Initializes a new instance of the PackageSelection class. It requires an output interface for progress messages, the output directory, configuration settings, and a flag to control error handling during package resolution.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **output** (`OutputInterface`) - Required - Symfony console output for progress messages
- **outputDir** (`string`) - Required - Path to built repository (needed to read packages.json if incremental build)
- **config** (`array<string, mixed>`) - Required - Configuration from satis.json
- **skipErrors** (`bool`) - Required - If true, exceptions in package resolution are logged; otherwise thrown

### Configuration Keys Processed
- **require** (`object`) - Optional - Package names and version constraints to explicitly require
- **require-all** (`bool`) - Optional - If true, all packages from repositories are included (default: `false`)
- **require-dependencies** (`bool`) - Optional - Include dependencies of required packages (default: `false`)
- **require-dev-dependencies** (`bool`) - Optional - Include dev-dependencies of required packages (default: `false`)
- **require-dependency-filter** (`bool`) - Optional - Apply repository filters when resolving dependencies (default: `true`)
- **only-dependencies** (`bool`) - Optional - Only include dependencies, not the explicitly required packages (default: `false`)
- **only-best-candidates** (`bool`) - Optional - Resolve only one or two versions per dependency (minimal set) (default: `false`)
- **minimum-stability** (`string`) - Optional - Global minimum stability: dev, alpha, beta, rc, stable (default: `dev`)
- **minimum-stability-per-package** (`object`) - Optional - Per-package stability overrides (default: `{}`)
- **abandoned** (`object`) - Optional - Mark packages as abandoned: `{"vendor/package": true}` or `{"vendor/package": "vendor/replacement"}` (default: `{}`)
- **blacklist** (`object`) - Optional - Version constraints to exclude: `{"vendor/package": ">=1.0,<2.0"}` (default: `{}`)
- **include-types** (`array` or `null`) - Optional - Only include packages with these types (default: `null`)
- **exclude-types** (`array`) - Optional - Exclude packages with these types (default: `[]`)
- **repositories** (`array`) - Optional - Repositories to select packages from (default: `[]`)
- **repositories-dep** (`array`) - Optional - Additional repositories for dependencies (default: `[]`)
- **strip-hosts** (`array` or `bool`) - Optional - Remove URLs from specified hosts, CIDR blocks, or local/private ranges (default: `false`)
- **archive** (`object`) - Optional - Archive configuration (for endpoint detection) (default: `{}`)
- **homepage** (`string`) - Optional - Repository homepage (used for URL normalization)
```

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

### Programmatically Build Packages

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

Use the PackagesBuilder to programmatically generate the package list. This is useful for custom build processes.

```php
$output = new ConsoleOutput();
$builder = new PackagesBuilder($output, $outputDir, $config, false);
$builder->dump($packages);
```

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

### Minimal Dependency Set Configuration for Satis

Source: https://github.com/composer/satis/blob/main/_autodocs/08-usage-examples.md

Configure Satis to include only the best-candidate versions, reducing metadata size while maintaining Composer functionality. This may limit version choices.

```json
{
    "require-all": true,
    "only-best-candidates": true,
    "output-dir": "build"
}
```

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

### select()

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

Selects packages based on configured filters and Composer instance. It resolves dependencies, applies abandoned marking, and prunes blacklisted or filtered packages.

```APIDOC
## select()

### Description
Selects packages based on configured filters and Composer instance. It resolves dependencies, applies abandoned marking, and prunes blacklisted or filtered packages.

### Method
`select(PartialComposer $composer, bool $verbose): array`

### Parameters
#### Path Parameters
- **composer** (PartialComposer) - Required - The Composer instance with configured repositories
- **verbose** (bool) - Required - If true, output additional messages for each operation

### Returns
- `array<string, PackageInterface>` — Selected packages indexed by unique name

### Process
1. Filter repositories based on `setRepositoriesFilter()` or use only repositories from config
2. Filter packages based on `setPackagesFilter()` if provided
3. Collect root links — all packages from repositories or explicit requires
4. Resolve packages from root links using Composer's resolver
5. Resolve dependencies if `require-dependencies` or `require-dev-dependencies` is true
6. Apply abandoned marking from config
7. Prune blacklisted packages based on version constraints
8. Prune by type based on include/exclude filters

### Exceptions
- `InvalidArgumentException`: If repository/package filters don't match any repositories (if `skipErrors` is false)
- `Exception`: Various Composer resolution errors (if `skipErrors` is false)

### Example Usage
```php
$packageSelection = new PackageSelection($output, $outputDir, $config, false);
$packageSelection->setRepositoriesFilter(['https://github.com/user/repo.git']);
$packages = $packageSelection->select($composer, true);
```
```

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

### v1.0 Provider File Format

Source: https://github.com/composer/satis/blob/main/_autodocs/07-repository-output-format.md

This JSON structure represents a per-package provider metadata file for v1.0 clients. It lists available package versions.

```json
{
    "packages": {
        "vendor/package": {
            "1.0.0": {...},
            "2.0.0": {...}
        }
    }
}
```