README

本项目提供了一个Composer插件，可以将mautic/core-lib项目中的骨架文件（如index.php、update.php等）放置在Web根目录中所需的位置。只能使用此插件为单个文件创建骨架。

创建文件骨架的目的是允许Mautic站点完全由Composer管理，同时允许将单个资产文件放置在任意位置。这样做是为了使配置得当的composer模板能够生成与Mautic 3.x及更早版本tarball分发的文件布局完全匹配的文件布局。其他文件布局也将是可能的；例如，一个项目布局与当前的nickveenhof/mautic-project模板非常相似的项目布局也将被提供。当使用这些项目之一时，用户应能够在解压缩下载的存档后立即使用composer require和composer update在Mautic站点上。

请注意，Mautic站点的依赖关系只有在其顶级composer.json文件中明确授予该权限时才能创建骨架文件。请参阅下面的允许的包。

使用方法

Mautic Composer Scaffold通过在项目的composer.json文件的extra部分中提供配置设置，并使用mautic/core-composer-scaffold在项目中要求使用。也会参考项目依赖的composer.json文件中的额外配置来创建项目所需的文件。可以在骨架文件的开头或结尾添加额外信息，就像通常对.htaccess和robots.txt文件所做的那样。有关更多信息，请参阅修改骨架文件。

通常，骨架操作在需要时自动运行，例如在composer install之后，因此一旦在项目composer.json文件中设置好配置，通常不需要进行任何不同的操作来为项目创建骨架，如下所述。要直接创建骨架文件，请运行

composer mautic:scaffold

允许的包

骨架文件存储在主项目的composer.json文件中要求的项目内部。骨架操作在composer install之后发生，涉及将所需资产复制或符号链接到目标位置。为了防止任意依赖通过骨架机制复制文件，只有那些被顶级项目明确允许的项目才会用于创建骨架文件。

示例：允许从项目mautic/core-lib创建骨架

  "name": "my/project",
  ...
  "extra": {
    "mautic-scaffold": {
      "allowed-packages": [
        "mautic/core-lib"
      ],
      ...
    }
  }

允许一个包创建骨架文件也允许它将创建骨架的权限委托给它自己要求的任何项目。这允许一个包按照其认为合适的方式来组织其骨架资产。例如，项目mautic/core-lib可以选择将其资产存储在子项目mautic/assets中。

项目可以从多个项目获取骨架文件。例如，使用分发版并在特定的网络托管服务提供商上安装的Mautic项目可能从以下项目获取其骨架文件：

Mautic核心
其分发版
托管提供商提供的项目
项目本身

每个允许由顶级项目scaffold的项目将依次使用，allowed-packages列表中声明的项目晚于之前命名项目的项目优先级更高。顶级composer.json本身始终隐式允许scaffold文件，并且其scaffold文件具有最高优先级。

定义项目位置

顶级项目反过来必须定义Web根的位置。它通过下面的locations映射来实现

  "name": "my/project",
  ...
  "extra": {
    "mautic-scaffold": {
      "locations": {
        "web-root": "./docroot"
      },
      ...
    }
  }

这使得配置具有不同文件布局的项目成为可能；例如，可以使用mautic/mautic文件布局或nickveenhof/mautic-project文件布局来设置项目。

如果没有明确定义Web根，则默认为./。

修改scaffold文件

有时，项目可能希望使用依赖项提供的scaffold文件，但以某种方式修改它。支持两种修改形式：追加和修补。

下面的例子显示了一个项目，将额外的条目追加到mautic/core-lib提供的robots.txt文件末尾

  "name": "my/project",
  ...
  "extra": {
    "mautic-scaffold": {
      "file-mapping": {
        "[web-root]/robots.txt": {
          "append": "assets/my-robots-additions.txt",
        }
      }
    }
  }

也可以通过包括一个提供追加到scaffold文件的相对路径的"prepend"条目来在追加之前或之后预置到scaffold文件。

下面的例子演示了使用post-mautic-scaffold-cmd钩子通过修补来修改.htaccess文件。

  "name": "my/project",
  ...
  "scripts": {
    "post-mautic-scaffold-cmd": [
      "cd docroot && patch -p1 <../patches/htaccess-ssl.patch"
    ]
  }

定义scaffold文件

放置scaffold资产的位置由提供它们的该项目控制，但位置始终相对于根项目定义的某个目录——通常是Web根。例如，下面的代码段中将scaffold文件robots.txt从其源位置assets/robots.txt复制到Web根。

{
  "name": "mautic/assets",
  ...
  "extra": {
    "mautic-scaffold": {
      "file-mapping": {
        "[web-root]/robots.txt": "assets/robots.txt",
        ...
      }
    }
  }
}

排除scaffold文件

有时，项目可能更喜欢完全替换由依赖项提供的scaffold文件，并且不再接收对它的任何更新。这可以通过将scaffold文件排除的值设置为false来完成

  "name": "my/project",
  ...
  "extra": {
    "mautic-scaffold": {
      "file-mapping": {
        "[web-root]/robots.txt": false
      }
    }
  }

尽可能使用上面在修改scaffold文件中解释的append和prepend指令。排除文件意味着您的项目将不会收到任何本地修改的文件（如错误修复或其他更新）。

覆盖

默认情况下，scaffold文件会覆盖目标位置上的任何内容。有时项目可能希望提供不会在后续更新中更改的文件的初始内容。这可以通过将overwrite标志设置为false来实现，如下面的示例所示

{
  "name": "service-provider/mautic-scaffold-files",
  "extra": {
    "mautic-scaffold": {
      "file-mapping": {
        "[web-root]/sites/default/settings.php": {
          "mode": "replace",
          "path": "assets/sites/default/settings.php",
          "overwrite": false
        }
      }
    }
  }
}

请注意，overwrite指令旨在由启动器、服务提供商等使用。单独的Mautic站点应通过将其值设置为false来排除文件。

自动加载文件

作为scaffold操作的一部分，scaffold工具自动在Mautic根目录创建所需的autoload.php文件。此文件不应以任何方式进行修改或自定义。如果将其提交到存储库，则scaffold工具将停止管理它。如果由于任何原因更改了vendor目录的位置，并且autoload.php文件已提交到存储库，则手动删除它，然后运行composer install以更新它。

规范

下面是composer.json文件“extra”部分的“mautic-scaffold”部分配置指令的参考部分。

allowed-packages

allowed-packages配置设置包含一个按顺序排列的包名称列表，将在scaffold阶段使用。

"allowed-packages": [
  "mautic/core-lib",
],

file-mapping

file-mapping配置设置由文件要scaffold的目标路径到控制如何scaffold文件的属性集映射。

可用的属性如下

mode: "replace"、"append"或"skip"之一。
路径：覆盖目标文件时要写入源文件的路径。
前置：要附加到目标文件的前面的源文件路径，这必须是其他项目提供的某些支架文件。
后置：类似于 prepend，但是是追加内容而不是前置。
覆盖：如果设置为 false，则在目标文件已存在时阻止发生 replace 操作。

模式可能可以从其他属性推断。如果没有指定模式，则将提供以下默认值

替换：如果存在 path 属性，或者条目的值是字符串而不是属性集，则选中。
追加：如果存在 prepend 或 append 属性，则选中。
跳过：如果条目的值是布尔值 false，则选中。

示例

"file-mapping": {
  "[web-root]/sites/default/default.settings.php": {
    "mode": "replace",
    "path": "assets/sites/default/default.settings.php",
    "overwrite": true
  },
  "[web-root]/sites/default/settings.php": {
    "mode": "replace",
    "path": "assets/sites/default/settings.php",
    "overwrite": false
  },
  "[web-root]/robots.txt": {
    "mode": "append",
    "prepend": "assets/robots-prequel.txt",
    "append": "assets/robots-append.txt"
  },
  "[web-root]/.htaccess": {
    "mode": "skip",
  }
}

上述示例的简短形式将是

"file-mapping": {
  "[web-root]/sites/default/default.settings.php": "assets/sites/default/default.settings.php",
  "[web-root]/sites/default/settings.php": {
    "path": "assets/sites/default/settings.php",
    "overwrite": false
  },
  "[web-root]/robots.txt": {
    "prepend": "assets/robots-prequel.txt",
    "append": "assets/robots-append.txt"
  },
  "[web-root]/.htaccess": false
}

请注意，没有明确的“前置”模式；“追加”模式用于同时对支架文件进行追加和前置。这样做的原因是支架文件条目在文件映射部分按其目标路径标识，并且不可能有多个条目具有相同的键。如果“前置”是一个单独的模式，那么就无法对同一文件同时进行前置和追加。

默认情况下，追加操作只能应用于由先前评估的项目构建的文件。但是，如果向 append 操作添加了 force-append 属性，则只有在追加文本尚未出现在文件中时，才会将追加应用到非支架文件。在使用此模式时，还可以提供默认内容，以便在目标文件完全缺失时使用。

以下示例演示了构建 settings-custom.php 文件，并将其包含在现有的 settings.php 文件中。

"file-mapping": {
  "[web-root]/sites/default/settings-custom.php": "assets/settings-custom.php",
  "[web-root]/sites/default/settings.php": {
    "append": "assets/include-settings-custom.txt",
    "force-append": true,
    "default": "assets/initial-default-settings.txt"
  }
}

请注意，上述示例在使用构建 settings.php 文件的项目中仍然有效。

gitignore

gitignore 配置设置控制此插件是否管理支架操作期间写入的 .gitignore 文件。

true：.gitignore 文件将在写入支架文件时更新。
false：.gitignore 文件永远不会被修改。
未设置：.gitignore 文件将在目标目录是 Git 仓库的本地工作副本，并且该仓库中忽略了 vendor 目录时更新。

位置

locations 配置设置包含一个命名位置列表，这些位置可用于放置支架文件。唯一必需的位置是 web-root。如果需要，也可以定义其他位置。

"locations": {
  "web-root": "./docroot"
},

符号链接

symlink 属性会导致 replace 操作为源文件创建符号链接而不是复制它。这对于进行核心开发很有用，因为符号链接文件本身不应被编辑。请注意，append 操作会覆盖 symlink 选项，以防止更改原始支架资产。

"symlink": true,

管理支架文件

支架文件应与处理 vendor 目录的方式相同。如果您需要提交 vendor（例如，为了部署您的网站），则还应提交您的支架文件。除非有必要，否则您不应提交 vendor 目录或支架文件。

如果依赖项提供的支架文件将 overwrite 设置为 false，则应将该文件提交到您的仓库。

默认情况下，如果需要，当写入支架文件时，将自动更新 .gitignore 文件。请参阅上面规格部分中的 gitignore 设置。

示例

以下是一些完整的示例。

依赖 composer-scaffold 包的项目 composer.json 示例

{
  "name": "my/project",
  "require": {
    "nickveenhof/mautic-core-composer-scaffold": "*",
    "composer/installers": "^1.2",
    "cweagans/composer-patches": "^1.6.5",
    "mautic/core-lib": "3.x-dev",
    "service-provider/mautic-3x-scaffold-files": "^1"
  },
  "config": {
    "optimize-autoloader": true,
    "sort-packages": true
  },
  "extra": {
    "mautic-scaffold": {
      "allowed-packages": [
        "mautic/core-lib"
      ],
      "locations": {
        "web-root": "./docroot"
      },
      "symlink": true,
      "overwrite": true,
      "file-mapping": {
        "[web-root]/.htaccess": false,
        "[web-root]/robots.txt": "assets/robots-default.txt"
      }
    }
  }
}

放置在另一个项目的 mautic/core-lib 中的资产 composer.json 示例

{
  "name": "mautic/core-lib",
  "extra": {
    "mautic-scaffold": {
      "allowed-packages": [
        "mautic/assets",
      ]
    }
  }
}

放置在 mautic/assets 中的 composer-scaffold 文件 composer.json 示例

{
  "name": "mautic/assets",
  "extra": {
    "mautic-scaffold": {
      "file-mapping": {
        "[web-root]/.csslintrc": "assets/.csslintrc",
        "[web-root]/.editorconfig": "assets/.editorconfig",
        "[web-root]/.eslintignore": "assets/.eslintignore",
        "[web-root]/.eslintrc.json": "assets/.eslintrc.json",
        "[web-root]/.gitattributes": "assets/.gitattributes",
        "[web-root]/.ht.router.php": "assets/.ht.router.php",
        "[web-root]/.htaccess": "assets/.htaccess",
        "[web-root]/index.php": "assets/index.php",
        "[web-root]/index.php": "assets/index_dev.php",
        "[web-root]/robots.txt": "assets/robots.txt",
      }
    }
  }
}

实现 composer-scaffold 的库 composer.json 示例

{
  "name": "service-provider/mautic-3x-scaffold-files",
  "extra": {
    "mautic-scaffold": {
      "file-mapping": {
        "[web-root]/app/config/config_prod.php": "assets/app/config/config_prod.php"
      }
    }
  }
}

追加到 robots.txt

{
  "name": "service-provider/mautic-3x-scaffold-files",
  "extra": {
    "mautic-scaffold": {
      "file-mapping": {
        "[web-root]/robots.txt": {
          "append": "assets/my-robots-additions.txt",
        }
      }
    }
  }
}

复制文件后修复文件

"post-mautic-scaffold-cmd": [
  "cd docroot && patch -p1 <../patches/htaccess-ssl.patch"
]

mautic / core-composer-scaffold

维护者

详细信息