README

Contao Composer 插件负责在 Composer 环境中正确安装 Contao 3 扩展。Composer 文件始终位于 vendor 文件夹中，但它们必须被复制/符号链接到 system/modules 以正确检测 Contao。

请注意，此插件对于 Contao 4 / Symfony 包不是必需的。如果您同时支持 Contao 3 和 Contao 4，请确保遵循 旧 方法，该方法在 Contao 4 中仍然完全受支持。不过，您显然无法使用新包的功能（如 DIC）。

composer.json

请参考 Composer 手册，了解您的库中基本的 composer.json 应该如何。

一些简单的规则可以使您的包与 Contao 3 兼容

1. 将您的包类型改为 contao-module
2. 添加对正确 Contao 版本的要求
3. 添加对 Contao Composer 插件的要求
4. 将源添加到 extras => contao 部分
5. 如果需要，指定您的单次运行文件

示例

{
    "name": "vendor/package-name", 
    "type": "contao-module",
    "license": "LGPL-3.0+",
    "require": {
        "contao/core-bundle": "4.*",
        "contao-community-alliance/composer-plugin": "3.*"
    },
    "extra": {
        "contao": {
            "sources": {
                "": "system/modules/extension-name"
            },
            "runonce": [
                "config/update.php"
            ]
        }
    },
    "replace": {
        "contao-legacy/extension-name": "self.version"
    }
}

需求 Contao

在 Contao 4 中，捆绑的模块被重新结构化，因此每个模块都是一个单独的 Symfony 包。这意味着用户可以选择不安装新闻或日历扩展，如果它们对他们的系统不是必需的。

您的扩展应始终在适当版本中 require contao/core-bundle（参见 关于语义版本化）。如果您的代码扩展了其他模块，如新闻或日历，请确保添加正确的要求，分别针对相应的 Symfony 包（例如 contao/news-bundle 或 contao/calendar-bundle）。

Contao 4 被设计成与 Contao 3 兼容。因此，拥有同时支持 Contao 3 和 Contao 4 的扩展是完全可能的。如果您的扩展与 Contao 3.5 和 Contao 4 一起工作，正确的要求可能如下所示

{
    "require": {
        "contao/core-bundle": "~3.5 || ~4.1"
    }
}

需求 Contao Composer 插件

目前有两个版本的插件正在积极支持。

• 插件版本 2 是为 Contao 3 制作的。它支持在 TL_ROOT/composer 中安装 Composer 包，而不是安装根目录。

• 插件版本 3 是为 Contao 4 制作的。在 Contao 4 中，vendor 文件夹位于您的安装根目录中，Contao 只是您的安装的另一个依赖项。

请确保要求正确的插件版本。如果您的模块同时支持 Contao 3 和 Contao 4，正确的需求声明如下所示

{
    "require": {
        "contao-community-alliance/composer-plugin": "~2.4 || ~3.0"
    }
}

版本低于 2.4 的版本将不支持 contao/core-bundle，因此请确保设置正确的依赖项。如果您只支持 Contao 4，所需版本可以是 3.*。但是，您可能应该创建一个 Symfony 包，而不是要求 Contao Composer 插件...

请注意，您的根项目（根文件夹中的 composer.json）应该是 项目 类型，否则插件将不会安装 Contao 源。

源

在源部分，您可以定义在安装时应该将哪些文件复制到何处。这对于 Contao 3 扩展安装到 system/modules 文件夹中是必要的。

如果你的GIT仓库仅包含应复制到 system/modules/extension-name 文件夹的文件，只需指定一个空的源文件夹和目标文件夹。

{
    "extra": {
        "contao": {
            "sources": {
                "": "system/modules/extension-name"
            }
        }
    }
}

然而，您也可以重新构建您的GIT，使Contao文件位于自己的文件夹中。在这种情况下，您可以使用Composer自动加载器并遵循PSR-0或PSR-4命名空间。然而，您的扩展与旧的扩展仓库不兼容。

您可以为要复制/符号链接到Contao安装的多个文件或文件夹进行定义。您的包甚至可以一次安装多个Contao扩展。

{
    "extra": {
        "contao": {
            "sources": {
                "config": "system/modules/extension-name/config",
                "dca": "system/modules/extension-name/dca",
                "templates": "system/modules/extension-name/templates"
            }
        }
    },
    "autoload": {
        "psr-4": {
            "VendorName\\ExtensionName\\": "src/"
        }
    }
}

用户文件

userfiles属性允许从Composer包中复制文件到Contao中的/files文件夹。由于此文件夹可以在Contao配置中重命名，安装程序将自动尝试找到正确的位置。

请注意，如果用户文件不存在，则只会复制一次，它们在更新时不会被覆盖。

{
	"extra": {
		"contao": {
			"userfiles": {
				"src/system/modules/my-module/files/images": "my-module/images"
			}
		}
	}
}

运行一次

将runonce.php文件放入您扩展的config目录是Composer的一个坏习惯。文件将在执行后被Contao删除，这意味着Composer将在下一次更新时抱怨文件已被修改。为了解决这个问题，您可以在composer.json中指定运行一次文件列表。它们将在每次安装或更新后执行，但不会被删除。也不需要将它们命名为runonce.php，您可以使用任何其他名称。

{
    "extra": {
        "contao": {
            "runonce": [
                "src/system/modules/extension-name/runonce/init_update.php",
                "src/system/modules/extension-name/runonce/do_db_update.php",
                "src/system/modules/extension-name/runonce/refresh_entities.php"
            ]
        }
    }
}

运行一次文件将按照您指定的顺序执行。

关于语义版本化

遵循语义版本化对于Composer安装的成功至关重要。如果您（开发者）不遵循语义版本化，其他人（包括依赖项管理器）很难安装您库的正确版本。

您还应熟悉Composer版本约束，以正确设置您的依赖项。不正确的依赖项会导致安装损坏，并且**总是**是开发者的责任！

服务器要求

Contao Composer插件需要最新的服务器配置。Contao 4不再支持所谓的“安全模式黑客”，并且插件现在需要符号链接支持。