imarc/opus

为composer提供的多框架资源和模块打包

维护者

详情

github.com/imarc/opus

源代码

问题

安装次数: 9,551

依赖者: 3

建议者: 0

安全: 0

星标: 11

关注者: 8

分支: 1

公开问题: 2

类型:composer-plugin

2.0-beta 2023-11-11 01:17 UTC

Requires

Requires (Dev)

MIT 886d54576f24c684a205f1610c29060baa6b0ce7

  • Matthew J. Sahagian <matt.woop@imarc.net>

package management

This package is auto-updated.

Last update: 2024-09-11 03:57:00 UTC

README

它做什么？

Opus将从composer包中复制文件和目录到您的项目文件夹中。这些文件可以是CSS/JS资源，甚至是启动插件代码。

它是如何工作的？

包提供了支持框架的安装映射，告诉Opus从源包中复制哪些文件或目录，并将它们复制到项目根目录的相对位置。

我为什么需要它？

Opus允许将框架模块或资源库打包在一起。例如，如果您有一个允许通过复制启动文件来安装插件的框架，这些文件可以自动复制给用户。

如果导入的文件可以自定义或修改，这尤其有用，因为Opus将确保您更改的完整性。但是，它也可以用于不经常更改的资产，如JS库或CSS，除非上游版本发生变化。

在项目的composer.json文件中启用Opus

注意：Opus将使用composer.json中的name属性来确定从支持包中使用的哪个安装映射。

要启用opus，您需要要求它，并将extra.opus.enabled参数设置为true

"require": {
	"imarc/opus": "*"
},
"extra": {
	"opus": {
		"enabled": true
	}
}

在包中指定安装映射

包可以通过创建一个以项目名称为键的安装映射来支持您的框架。如果您的项目基于或使用上游框架，但在composer.json中有一个不同的name属性，您可以如下指定框架

"extra": {
	"opus": {
		"options": {
			"framework": "<framework>"
		}
	}
}

注意：只有当项目composer.json中的name与支持框架不匹配时，才需要这样做。

Opus包

Opus包有两种类型

  1. 标准包
  2. 集成包

标准包

标准包是一个常规的composer包，已配置为通过提供以它们的名称为键的一个或多个安装映射来支持一个或多个项目或框架。

它向composer.json中添加以下信息

"type": "opus-package",
"extra": {
	"opus": {
		"<project / framework>": {
			"<source>": "<destination>",
			...
		},
		...
	}
}

在安装或升级时，Opus将查看项目的name或extra.opus.options.framework（如果包在extra.opus中具有匹配的安装映射，使用名称作为键）。如果找到匹配的键，Opus将遍历每个属性，使用<source>键来识别包中的文件或文件夹位置，并将其复制到支持项目中的<destination>值引用的路径。

单个包可以通过向extra.opus对象添加多个键对象来支持多个框架

"type": "opus-package",
"extra": {
	"opus": {
		"SomeVendor/CMS": {
			"js/jquery.listview.js": "public/assets/lib/",
			"css/listview.css": "public/assets/styles/views"
		},
		"Acme/Framework": {
			"js/jquery.listview.js": "docroot/js/",
			"css/listview.css": "docroot/css"
		}
	}
}

集成包

集成包在composer中类似于元包，尽管它们也可以提供一些文件。主要用途如下

  1. 当多个第三方包和/或包资产可以或应该组合在一起以提供单个可安装功能时。
  2. 当现有第三方包不支持Opus时。

简而言之，集成包允许您为那些在其自己的 composer.json 中没有提供安装映射或需要覆盖现有安装映射的一个或多个包提供安装映射。

集成包使用与标准包相同的格式，并额外包含一个按第三方包名称键入的嵌套对象。

"type": "opus-package",
"require": {
	"thirdparty/package": "~1.0"
},
"extra": {
	"opus": {
		"Acme/Framework": {
			"thirdparty/package": {
				"css/listview.css": "docroot/css"
			},
		}
	}
}

架构

框架/项目/根包

"name": "<framework>",                       // Used to identify package installation maps
"extra": {
	"opus": {
		"enabled": true|false,               // Enable/disable Opus altogether
		"options": {
			"framework": "<framework>",      // Override package name to specify a framework
			"external-mapping": true|false   // Enable/Disable external integration packages
			"integrity": "high|medium|low"   // Medium is default (see integrity section below)
		}
	}
}

内置 Opus 支持的包

"type": "opus-package",
"extra": {
	"opus": {
		"<framework>": {                     // Installation map keyed by the framework
			"<source>": "<destination>",     // Source / destination for this package
			...
		},
		...                                  // Additional supported frameworks and mappings
	}
}

集成包

"type": "opus-package",
"require": {
	"package": "version"                     // Third-party integrated package
},
"extra": {
	"opus": {
		"<framework>": {                     // Installation map keyed by the framework
			"<source>": "<destination>",     // Source / destination for this package
			"<package>": {                   // Installation map for third-party package
				"<source>": "<destination>", // Source / destination for third-party
				...
			},
			...
		},
		...                                  // Additional supported frameworks and mappings
	}
}

项目完整性

因为 Opus 会将文件从您的供应商目录复制到您的项目中，所以有一些检查和平衡措施，旨在确保您的代码的完整性。以下是一些基本内容的介绍。

安装完整性

在安装操作期间，如果 Opus 尝试复制的文件已经存在，则会引发冲突。用户可以直接响应此冲突，并提示是否应该覆盖文件或保留。此外，在做出决定之前，可以快速查看文件的差异。

更新完整性

安装完成后，Opus 将关于当前文件状态的元信息写入项目根目录中的 opus.map 文件。然后，该文件用于查询可能在未来更新中覆盖的任何文件的信息。

然而，与安装不同的是，由于预计文件将存在，并且因为不同的项目可能有不同的需求，因此完整性是可配置的。如上所述，您可以在项目 Opus 选项中指定一个 "integrity" 选项，其值为 high、medium 或 low。

"name": "<framework>",
"extra": {
	"opus": {
		"options": {
			"integrity": "medium"
		}
	}
}

中等完整性（默认）

中等项目完整性遵循一些基本规则

  • 如果没有现有文件，则复制新文件并将其校验和存储在映射中。
  • 如果现有文件与复制文件之间没有非空白差异，则复制新文件并将其校验和存储在映射中。
  • 如果存在差异，则将新文件的校验和与旧校验和比较，以确定它是否在包本身中已更改，如果没有，则不采取任何操作。
  • 如果已更改，则将映射中的校验和与当前文件的校验和比较，以确定它是否在磁盘上已更改，如果没有，则复制新文件并更新校验和。
  • 如果校验和不同（表示开发人员编辑了文件），则用户将获得冲突解决选项（覆盖、保留、差异）

中等完整性提供了一种简单的方法，其中从未被开发人员更改的复制文件会自动用包更新。但是，如果开发人员自定义了文件，则未来的更新不会简单地抹去他们的更改，而是提供选项以及查看差异的能力。

高完整性

高完整性是为那些不想在没有通知的情况下更新覆盖任何内容的偏执开发人员而设计的。因此，任何冲突都会显示给开发人员冲突解决选项。请注意，对于可能复制大量文件的包，这可能非常麻烦，并且通常只有在您非常关注上游包中做出的更改的有效性时才更可取。

低完整性

低完整性，类似于高完整性，做出简单的决定。任何冲突文件都将被更新版本覆盖。如果您只使用不需要任何自定义或更改复制文件的包，这可能是最有用的设置。但是，您应该意识到，有时包复制的非代码相关文件可能很重要。例如，如果包覆盖了一个配置文件，您需要以某种方式对其进行修改，则低设置意味着在未来更新时，您的配置文件将用默认值覆盖。

附录和支持框架

我们鼓励框架和库的开发者开始在他们的框架、Web应用、库或资产包中提供Opus支持。如果您是框架维护者并计划包含Opus，请在此项目上提交一个问题，我们将添加您的命名空间和链接到列表中。