DOCSEARCHbyAlgolia
Submit Docs

Violinist Documentation

website·Indexed 33 days ago

https://docs.violinist.io

Documentation for Violinist, a tool for managing PHP package updates. Includes guides on repository access, PHP extensions, composer-patches integration, and detailed configuration options for controlling pull requests, automerging, security updates, and dependency constraints.

Tokens
11.4K
Snippets
57
Records
75
Agent score
55%

What's inside Violinist

  1. Understand data collection for self-hosted violinist update runners

    For on-prem / self-hosted violinist update check runners, no data is sent to violinist.io servers by default. Data collection is disabled unless explicitly enabled via an environment variable. To perform updates, the runner container requires full checkout access to the project's source code repository; this access is restricted to the container, is not shared externally, and the checked-out repository does not persist by default.

  2. Understand how violinist.io accesses source code

    To perform automated update checks on the hosted version of violinist.io, the service requires access to perform a full checkout of the project's source code. The source code is not stored or cached; the containers used for the checkout are destroyed immediately after the update jobs are run and are never reused.

  3. System requirements for self-hosting Violinist

    The only requirement to self-host Violinist is the ability to run a Docker container. This can be achieved via a local installation of Docker (from docker.com), a dedicated server, or as part of a CI/CD pipeline setup.

  4. Add private repositories to violinist.io

    Private repositories must be added by a user with administrative access to the repository. Because the logged-in user is recorded as the author of any resulting pull or merge requests, it is recommended to use a dedicated bot user to add repositories, especially for agencies or teams.

  5. Use config branches to decouple configuration from target branches

    Config branches allow you to specify which git branch Violinist should use to read the project configuration, overriding the default behavior where the config is read from the same branch that updates are targeting. This is available only on agency and enterprise plans.

    Common use cases include:

    • Managing multiple projects/customers within a single git repository using different branches (e.g., customer1 and customer2).
    • Implementing different update strategies for different branches (e.g., automatic security updates to main while using manual merge requests for all dependencies on develop).
    • Testing Violinist options or the tool itself without merging the configuration into the target branch.

  6. Share Violinist configurations using the extends option

    The extends option allows you to centralize shared settings in remote JSON documents or local files, preventing the need to duplicate the full configuration across every composer.json.

    Violinist processes the extends array in order: it fetches the configuration snippets, merges the keys, and finally applies local overrides defined in the extra.violinist block. Later entries in the array (and the local configuration itself) always override values defined in earlier entries.

    Supported source types for extends:

    1. Relative paths: A path to a JSON file inside the repository (e.g., .violinist/base.json).
    2. Composer packages: The name of a package that exposes a Violinist configuration in its own composer.json (e.g., acme/violinist-policies).
    {
  "name": "company/project",
  "extra": {
    "violinist": {
      "extends": [
        "vendor/shared-violinist-config",
        ".violinist/team-overrides.json"
      ]
    }
  }
}

  7. Define package-specific configuration rules

    The rules option is an array of rule objects used to apply different configuration settings to specific groups of packages. Rules are evaluated in order; when a package matches a rule, the rule's configuration is merged with the default configuration.

    Key Behaviors:

    • Grouping: When a rule matches multiple packages, they are collected into a single grouped pull request titled Update group <name>. This PR is created if any matched package has an update.
    • Merging: Configuration is merged per option. A value set in a rule replaces the root value entirely (it does not append).
    • Comparison to bundled_packages: Unlike bundled_packages, rules can trigger updates if any package in the group has an update (not just the parent), support flexible pattern matching (wildcards/negation), and allow for different configuration overrides per group.
    {
  "name": "company/project",
  "extra": {
    "violinist": {
      "rules": [
        {
          "name": "Human readable name",
          "slug": "machine-readable-slug",
          "matchRules": [
            {
              "type": "names",
              "values": ["vendor/*", "!vendor/excluded-package"]
            }
          ],
          "config": {
            "blocklist": [],
            "branch_prefix": "deps/",
            "security_updates_only": 1
          }
        }
      ]
    }
  }
}

  8. Identify available updates with Violinist

    By default, Violinist identifies available updates by running the Composer command composer outdated -D -m.

    • --direct (-D): Restricts the list to direct dependencies.
    • --minor-only (-m): Only shows packages with minor SemVer-compatible updates.

    This behavior can be modified via configuration:

    • Set check_only_direct_dependencies to 0 to remove the --direct flag.
    • Use the composer_outdated_flag option to control the update level (major, minor, or patch).
    composer outdated -D -m

  9. Ignore PHP platform requirements in Violinist

    The ignore_platform_requirements configuration option allows Violinist to ignore PHP platform requirements (such as PHP version or specific extensions) when resolving and updating dependencies. When enabled, Violinist sets the COMPOSER_IGNORE_PLATFORM_REQS environment variable for Composer.

    This is useful when the environment where Violinist runs differs from your production environment, preventing Composer from refusing to update packages due to missing extensions or version mismatches in the Violinist environment.

    Configuration Details:

    • Key: ignore_platform_requirements (located under extra.violinist in composer.json)
    • Type: Integer
    • Default: 0 (Disabled)
    • Enabled Value: 1

    Caveat: Your CI pipeline should still verify that updated dependencies are compatible with your actual production platform configuration.

    {
  "name": "company/project",
  "description": "My awesome project",
  "require": {
    "php": "^8.2",
    "ext-acme": "*",
    "vendor/package": "~1.0.0"
  },
  "extra": {
    "violinist": {
      "ignore_platform_requirements": 1
    }
  }
}

  10. Update packages using Violinist

    Violinist updates packages using the following default Composer command: composer update vendor/package --with-dependencies.

    To change this behavior:

    • Set the update_with_dependencies configuration option to 0 to prevent updating dependencies.
    • Use the bundled_packages option if you need to update a package that is bundled with another package.
    composer update vendor/package --with-dependencies

  11. Manage and update Violinist PR branches

    Violinist automatically keeps Pull Requests up to date by force-pushing the update branch whenever changes are pushed to the default branch. Because of this behavior, developers should avoid committing work directly to a Violinist-created branch to prevent data loss from force-pushes. To add custom changes to a Violinist PR, create a new separate branch based on the PR branch and perform work there.

  12. Contribute to Violinist documentation

    The Violinist documentation is open source. Users can contribute improvements, such as fixing typos or clarifying explanations, by submitting changes to the official GitHub repository.
    # Documentation source repository
https://github.com/violinist-dev/docs/