README

此 Composer 插件将使您的 Composer 项目使用 composer.yaml 作为其 Composer 配置，而不是 composer.json。它完全透明地执行，无需运行额外的命令。

composer.json 仍然需要，(例如，用于启动此插件)，但一旦检测到 composer.yaml 的更改，它就会自动生成。这类似于 composer.lock 的生成方式。

安装

composer require "empaphy/composer-yaml:^1.0"

用法

只需像往常一样使用 Composer！在安装此插件后第一次运行任何 Composer CLI 命令时，它将根据您现有的 composer.json 生成一个 composer.yaml。

请记住，从现在开始修改 composer.yaml，而不是修改 composer.json，因为对那个文件的任何更改都将被覆盖。

为什么是 YAML？JSON 有什么问题？

JSON 从未设计成可读格式。它的目的是让计算机相互交换信息。因此，它缺少了人类在处理文件时需要的一些基本功能，比如注释。

YAML 允许使用注释以及更多功能，使表达式的 Composer 配置成为可能。

• 注释 允许您澄清您的配置。
• 引号 是 不必要 的，这使得文件更容易阅读。
• 不需要尾随逗号，这减少了语法错误的风险。
• 支持 多行字符串，允许您将字符串拆分到多行。YAML 允许您折叠或保留多行字符串中的换行符。
• YAML 锚点 允许您引用并多次使用相同的数据。

YAML 与 JSON 的比较

例如，如果您有一个典型的 composer.json，如下所示

{
    "name":              "empaphy/foo",
    "description":       "Foo library for PHP",
    "license":           "MIT",
    "minimum-stability": "stable",
    "prefer-stable":     true,

    "require": {
        "php": ">=7.4",

        "symfony/config":         "~5.4.0",
        "symfony/console":        "~5.4.0",
        "symfony/filesystem":     "~5.4.0",
        "symfony/process":        "~5.4.0",
        "symfony/yaml":           "~5.4.0",

        "yogarine/composer-yaml": "~5.4.0"
    },

    "require-dev": {
        "phpunit/phpunit": "^9.0",
        "phploc/phploc":   "^7.0",
        "phpstan/phpstan": "^1.0"
    },

    "autoload": {
        "psr-4": { "Empaphy\\Foo\\": "src/" }
    },
    
    "config": {
        "platform": {
            "php": "8.0.20"
        }
    },

    "scripts": {
        "pre-install-cmd": [
            "if [ -d .git -o -f .git -a -d ../.git ]; then git submodule update; fi"
        ]
    }
}

您可以将它转换为如下所示的内容

##
# Example Composer configuration for the Foo package.
#
# Use composer to install dependencies for this package:
#
#     composer install --no-dev --optimize-autoloader
#

name:        empaphy/foo            # The name of the package.
description: Foo library for PHP    # A short description of the package.
license:     MIT                    # The license of the package.

# This defines the default behavior for filtering packages by stability.
minimum-stability: stable

# Prefer more stable packages over unstable ones when finding compatible stable
# packages is possible.
#
# If you require a dev version or only alphas are available for a package, those
# will still be selected granted that the minimum-stability allows for it.
prefer-stable: true

# Map of packages required by this package.
#
# The package will not be installed unless those requirements can be met.
require:
    php: '>=7.4'  # We depend on property types. 

    # Symfony dependencies:
    symfony/config:     &symfony-version '~5.4.0'
    symfony/console:    *symfony-version
    symfony/filesystem: *symfony-version
    symfony/process:    *symfony-version
    symfony/yaml:       *symfony-version

    yogarine/composer-yaml: 'dev-main'  # Adds support for this file. :-)

require-dev:
    phpunit/phpunit: '^9.0'
    phploc/phploc:   '^7.0'
    phpstan/phpstan: '^1.0'

autoload:
    psr-4: [ Empaphy\Foo: src/ ]
    
config:
    platform:
        php: '8.0.20'  # We currently run 8.0.20 on all our production servers,
                       # so ensure we're forward-compatible with PHP 8.
    allow-plugins:
        yogarine/composer-yaml: true  # Required to for composer.yaml support.

scripts:
    # Occurs before the `install` command is executed with a lock file present.
    pre-install-cmd:
      - |  # Ensure submodules are updated.
        if [ -d .git -o -f .git -a -d ../.git ]; then
          git submodule update
        fi

已知问题 / 路线图

• 使用会修改 composer.json 的 Composer CLI 命令仍然有效，并且可以正确修改 composer.yaml，但 它们 将删除您对 composer.yaml 文件所做的任何自定义格式更改和注释。

  我计划在未来的版本中修复这个问题，但这需要编写一个自定义的 YAML Manipulator，所以可能需要一些时间。目前，请避免使用 CLI 命令来修改 composer 配置。毕竟，您现在可以使用 YAML 标记来使您的 composer.yaml 更漂亮，对吧？;-)

• 正确处理 composer.yaml 项目的首次安装。

• 警告对 composer.json 所做的更改

• 添加配置选项以选择默认行为，例如用于覆盖现有的 YAML 文件。