README

本项目提供Composer插件，用于将来自mautic/core项目的骨架文件（如index.php、update.php等）放置在网站根目录下所需的位置。此插件只能用单个文件进行骨架构建。

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

请注意，Mautic网站的依赖项只能通过在顶级composer.json文件中明确授予此权限来构建文件。有关更多信息，请参阅下文的允许的包。

使用方法

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

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

composer mautic:scaffold

允许的包

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

示例：允许从项目mautic/core进行骨架构建

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

允许包构建文件也允许它将构建权限委派给它所依赖的任何项目。这允许包根据自己的需求组织骨架资源。例如，项目mautic/core可以选择将其资源存储在子项目mautic/assets中。

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

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

顶级项目允许通过脚手架构建的项目将依次使用，allowed-packages 列表中声明较晚的项目将优先于之前命名的项目。顶级 composer.json 本身始终隐式允许构建文件，其构建文件具有最高优先级。

定义项目位置

顶级项目必须定义网站根目录的位置。它通过以下所示的 locations 映射来完成

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

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

如果没有显式定义网站根目录，则默认为 ./。

修改脚手架文件

有时，一个项目可能希望使用依赖项提供的脚手架文件，但以某种方式对其进行修改。支持两种修改形式：追加和修补。

以下示例显示了一个项目，它向 mautic/core 提供的 robots.txt 文件末尾追加额外的条目

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

也可以通过包含一个提供追加文件的相对路径的 "prepend" 条目来在追加之前或之后向脚手架文件中添加内容。

以下示例演示了使用 post-mautic-scaffold-cmd 插件来修补 .htaccess 文件

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

定义脚手架文件

脚手架资产的放置由提供它们的脚手架项目控制，但位置始终相对于根项目定义的某个目录 -- 通常为网站根目录。例如，以下代码段中，脚手架文件 robots.txt 从其源位置 assets/robots.txt 复制到网站根目录。

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

排除脚手架文件

有时，一个项目可能希望完全替换由依赖项提供的脚手架文件，并且不希望接收任何进一步的更新。这可以通过将脚手架文件的排除值设置为 false 来完成

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

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

覆盖

默认情况下，脚手架文件将覆盖目标位置上存在的任何内容。有时，项目可能希望为在后续更新中不会更改的文件提供初始内容。这可以通过将 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 来排除文件。

自动加载文件

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

规范

以下列出了 composer.json 文件 "extra" 部分 "mautic-scaffold" 部分的配置指令的参考部分。

allowed-packages

allowed-packages 配置设置包含一个有序列表的包名称，这些包名称将在脚手架阶段使用。

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

file-mapping

file-mapping 配置设置由将文件要构建的目标路径映射到一组控制如何构建文件属性的映射组成。

可用的属性如下

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 目录或支架文件。

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

默认情况下，如果需要，当写入支架文件时，.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": "3.x-dev",
    "service-provider/mautic-3x-scaffold-files": "^1"
  },
  "config": {
    "optimize-autoloader": true,
    "sort-packages": true
  },
  "extra": {
    "mautic-scaffold": {
      "allowed-packages": [
        "mautic/core"
      ],
      "locations": {
        "web-root": "./docroot"
      },
      "symlink": true,
      "overwrite": true,
      "file-mapping": {
        "[web-root]/.htaccess": false,
        "[web-root]/robots.txt": "assets/robots-default.txt"
      }
    }
  }
}

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

{
  "name": "mautic/core",
  "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"
]

nickveenhof / mautic-core-composer-scaffold

维护者

详细信息