thbighead/wordless

为厌倦WordPress的开发者设计的无头WordPress CMS

维护者

详细信息

github.com/thbighead/Wordless

源代码

问题

安装: 31

依赖: 0

建议者: 0

安全: 0

星级: 6

关注者: 3

分支: 0

开放问题: 0

语言:Dockerfile

类型:项目

v8.3.3 2024-09-17 14:48 UTC

Requires

Requires (Dev)

MIT b93423291f48ea3dd3db8510a26921d49fcc7394

  • Thales Nathan <thcmatias.woop@gmail.com>

This package is auto-updated.

Last update: 2024-09-17 14:49:18 UTC

README

为厌倦WordPress的开发者打造的无头WordPress项目

快速行动

新建项目

composer create-project thbighead/wordless example-app
cd example-app
cp .env.example .env
cp docker/nginx/sites/app.conf.example docker/nginx/sites/app.conf
  • 编辑.env的第3行，使用你的应用程序主机值。
  • 编辑docker/nginx/sites/app.conf的第11行，与.env中的APP_HOST值完全相同。
  • 将你的主机添加到本地hosts文件中（这取决于你的操作系统）。
docker compose up -d
docker compose exec --user=laradock workspace bash

现在在你的工作区容器内

composer install
php console wordless:install

初始化克隆的项目

cp .env.example .env
cp docker/nginx/sites/app.conf.example docker/nginx/sites/app.conf
  • 编辑.env的第3行，使用你的应用程序主机值。
  • 编辑docker/nginx/sites/app.conf的第11行，与.env中的APP_HOST值完全相同。
  • 将你的主机添加到本地hosts文件中（这取决于你的操作系统）。
docker compose up -d
docker compose exec --user=laradock workspace bash

现在在你的工作区容器内

composer install
php console wordless:install

下载Wordless

只需运行以下代码

composer create-project thbighead/wordless example-app
cd example-app

Wordless Docker

如你所见，我们基于Laradock项目构建了这些容器。

下载后，你应该启动Wordless提供的默认容器。要实现这一点，首先你应该创建一个新的docker/nginx/sites/app.conf，从docker/nginx/sites/app.conf.example复制，然后，只需编辑第11行，使用你想要的应用程序URL作为服务器名。这个值应该与你在稍后讨论的.env文件中设置的APP_HOST值相同。

接下来，只需运行docker compose up -d（我们推荐Docker Compose版本2）。

现在为了继续Wordless安装，我们建议使用内置的workspace容器，你可以通过以下命令访问

docker compose exec --user=laradock workspace bash

就是这样。在这个容器内，你可以使用wordless:install命令安装项目。

关于开发者和WordPress

如果你是WordPress爱好者，请确保你理解WordPress 不是 任何为开发者制作的工具。我们将在下面进一步讨论。

如果你是PHP开发者，请确保你理解WordPress 是 一个过时的项目，并且经常通过大规模更新来维持其生命力。你不应该害怕旧代码，你可以解决这个问题：你只需要时间。

WordPress是一个强大的CMS，经过多年的发展，现在可以为任何非IT人员提供一个完全创建和自定义类似博客网站的机会。但除了维护内容外，管理面板还让你能够改变整个页面的代码。这就是魔法的开始，也是问题的起源。

WordPress建立在插件和主题之上，它们不需要遵循任何项目结构。你所需要做的就是通过WordPress钩子进行冒险，有时也称为过滤器和/或动作，然后做你想要做的事情。尽管WordPress试图引入一些概念来组织和命名主题文件，如摘要、文章、页面、分类、分类法等，但每个主题都有一个完全不同的目录组织和项目结构。最后，当我们谈到插件时，项目组织变得更加复杂，我们意识到即使WordPress不断更新，其代码仍然缺乏一些重构。

那么，WordPress是不是很糟糕呢？不是。

最后，它就像魔法一样运作。但这并不是一个帮助开发者的工具！相反，WordPress是一个具有知名管理面板的可扩展CMS应用程序。我们这些IT人士必须理解的是，我们应该尊重它的本来面目。

对于开发者来说，整个问题在于WordPress中的行为变化可能发生在任何地方。真的。任何地方。所以当你让我们更改网站上某个元素的颜色时，它可能已经在CSS文件、PHP文件、通过管理面板管理的数据库中，或者CLI命令中完成。甚至一个JS文件也可能在更改它。没有规则，没有层次结构可以开始搜索，我们只是在谈论一个颜色更改。现在想象一下，如果用户以前从未以其他方式登录，那么通过他们的Facebook账户登录并填写表单的API消费。

说了这么多，一个更好地与WordPress协作的方法是定义这些层次结构，我们从将视图与业务代码分离开始。实现它的一个很好的方法是将其用作一个无头 CMS。

无头策略

我们这里的箴言是

让WordPress像应用一样工作，并在其他地方开发你的自定义功能。

为了实现它，我们将WordPress安装为无头CMS，这意味着它不再负责管理页面视图。相反，我们将使用WordPress REST API来作为前端项目的客户端。此外，为了准备整个WordPress项目，我们使用了由Composer、Symfony和WP-CLI构建的控制台安装程序。

无头引入了一个空白主题，它只是...嗯...什么也不做。但您甚至可以安装任何已知（或未知）的主题，并通过网络使用它来提供内容。

WordPressic主题

有时您可能希望使用Wordless作为后端构建项目，使用Wordless工具来提供页面，就像任何WordPress项目一样。为了实现这一点，我们还有一个扩展了空白主题的主题，称为SSR（就像最知名的前端框架中众所周知的“服务器端渲染”策略）。

目录和文件组织

| app (Composer initializes everything inside this directory)
| \
|  | Commands (Custom project commands to run through console)
|  | Controllers (Custom project Controllers to add routes to API)
|  | Hookers (WordPress action/filter done through an easy-to-use class)
|  | \
|  |  | Ajax (Wordless hookers for easy defining WordPress AJAX functions)
|  | Menus (WordPress menu registration classes)
|  | Scripts (WordPress front-end scripts registration classes)
|  | Styles (WordPress front-end styles registration classes)
| cache (Internal cache files)
| config (Published project configuration files)
| docker (Easy to use development environment containers based on Laradock)
| \
|  | adminer (Adminer container for database access through browser GUI)
|  | logs (Where all container log files shall be created)
|  | mariadb (MariaDB container as our default database)
|  | php-fpm (PHP container as our default programming language)
|  | workspace (Our developing container which we access to use Composer, NPM, etc.)
|  | nginx (MariaDB container as our default database)
|  | \
|  |  | sites (Where you should place your app config file for NGINX)
|  |  | \
|  |  |  | ssl (where your app cresencial for SSL access (HTTPS) shall be generated)
|  |  |  |>app.conf.example (a good start of NGINX config file for your app)
| migrations (Where we store our migration files)
| packages (Used by Wordless oficial package development)
| public (Websystem entrypoint where we place some symbolic links to WordPress folders)
| \
|  |>robots.txt (auto-generated after wordless:install)
| wp
| \
|  | wp-content
|  | \
|  |  | languages (Just like WordPress. Everything inside is ignored by Git)
|  |  | mu-plugins (Just like WordPress. Place any handmade or modified plugin here)
|  |  | plugins (Just like WordPress. Everything inside is ignored by Git. Installation controlled by Composer)
|  |  | themes (Just like WordPress. Ships with wordless theme)
|  |  | uploads (For built-in WordPress filesystem. Everything inside is ignored by Git)
|  |  |>debug.log (WordPress log file)
|  | wp-core (WordPress core files (anything but wp-content))
|  |>index.php (Just like WordPress)
|>.env.example (Used to create new .env files)
|>composer.json (Composer)
|>console (Wordless CLI file)
|>docker-compose.yml (Docker Compose file to up application containers)
|>wp-cli.yml (WP-CLI config file)

Wordless CLI

console有许多命令可以帮助您安装和保持项目运行。要检查可用的命令，只需运行php console list。要获取有关每个命令的更多信息，请运行php console {command:alias} --help。您可以在Commands目录中创建自己的命令，扩展\Wordless\Infrastructure\ConsoleCommand。

运行WP-CLI命令

通过运行php console wp:run "command with arguments and options here"，Wordless将执行任何WP-CLI命令。只需注意使用引号来包围命令，例如

php console wp:run "cache flush"

Wordless通过Composer保持WP-CLI，并将根据您的操作系统选择正确的脚本文件来执行。

安装Wordless

预配置文件

在运行任何命令之前，您应该检查以下预配置文件

.env

.env是一个文件，用于保存每个环境中可能不同的值（例如，如果您有一个产品，您还有本地和预发布环境）。因此，它永远不应该由GIT进行版本控制。您可以根据需要添加更多值，但请记住，已存在于.env.example中的值是Wordless的核心值。

您可以通过整个项目使用Environment::get()辅助函数来访问.env值。

use Wordless\Helpers\Environment;
// ...
$admin_mail = Environment::get('WP_ADMIN_EMAIL', 'A default value');

重要：如您所见，.env定义了SALT值。它们通过https://api.wordpress.org/secret-key/1.1/salt/自动生成。

docker/nginx/sites/app.conf

该文件应基于docker/nginx/sites/app.conf.example创建。请记住，在行11处，server_name应与您的.env APP_HOST变量具有相同的值。

.htaccess

由于我们使用NGINX而不是Apache，这些文件都被忽略。

运行console命令

新鲜启动后，在通过composer install命令安装所有Composer包之后，只需在项目根目录中运行php console wordless:install。

如果您想检查脚本运行时的过程，请使用-v标志：php console wordless:install -v。

此命令将按以下顺序解决以下内容

解决强制模式（-f）

此步骤负责在带有-f标志的安装命令运行时解决以下需求

  • 删除wp/wp-content/mu-plugins/wordless-plugin.php;
  • 删除wp/wp-core/wp-config.php;
  • 删除public/robots.txt。

如果这些文件中的任何一个不存在，我们将忽略它。如果我们无法删除文件，将引发FailedToDeletePath异常。

加载配置
将盐值填充到.env

WordPress盐值保存在.env变量中，并且如果它们尚未评估，此过程部分将评估它们。此外，在此步骤之后，过程已将所有环境变量加载到内存中。您可以在此处了解更多信息。

生成内部缓存

通过php console cache:create命令，所有配置的缓存都将创建在cache目录中。您可以在此处了解更多关于缓存的信息。

加载语言

Wordless将尝试通过,字符explode在config/wordpress.php中返回的languages键，并将它们安装到插件和核心中。

发布文件

发布步骤是将文件从存根复制到具有特定名称的特定位置。

发布wp-config.php

该过程调用php console publish:wp-config.php命令，在wp/wp-core处插入新的wp-config.php文件。如果该文件已存在，则此步骤将被跳过。

自定义wp-config.php

默认情况下，该文件应根据vendor/thbighead/wordless-framework/assets/stubs/wp-config.php创建。如果您想更改wp-config.php的行为，请在stubs/wp-config.php中创建自定义版本，该过程步骤将使用它。

发布robots.txt

将根据vendor/thbighead/wordless-framework/assets/stubs/robots_non_prod.txt创建基本的robots.txt，如果没有在public中创建，则根据vendor/thbighead/wordless-framework/assets/stubs/robots_prod.txt创建。您可以像修改自定义wp-config.php一样修改存根文件，并且甚至可以通过将它们用括号括起来来引用.env值（就像我们在其中对Sitemap值所做的）。为此，您只需创建一个与自定义wp-config.php相同的文件即可。

发布Wordless必须使用的插件文件

Wordless通过必须使用插件加载到WordPress环境中。应谨慎修改此存根文件。我们建议不要修改它，以便Wordless可以正常工作。

安装WordPress数据库

将数据库凭据填入.env后，Wordless能够检查您的服务器是否已安装必要的数据库以进行安装。如果数据库不存在，它将首先创建一个空的（目前没有表）数据库。

之后，Wordless将检查您的数据库并在必要时进行修复。

这里的一切都是由WP-CLI命令完成的，以下命令可能按以下顺序使用：

核心步骤

以下步骤是在维护模式下完成的。我们通过以下WP-CLI命令来控制它：

修复数据库URL

众所周知的选项siteurl和home将根据您的应用程序配置进行更新。

之后，通过WP-CLI执行数据库优化。

因此，以下WP-CLI命令将按以下顺序执行：

刷新重写规则

根据您的固定链接配置，WP-CLI通过以下命令从数据库中刷新旧规则：

激活主题和插件

激活来自config/wordpress.php中的theme键的主题。默认是我们的空白主题：wordless。

然后，激活所有插件。

同样，一切均通过以下顺序的WP-CLI命令进行控制：

安装WordPress语言

为插件安装所有语言，但WordPress核心只应安装第一个，所以请务必仔细选择要列出的语言**。如果languages配置键为空，则将跳过此过程。

同样，一切均通过以下顺序的WP-CLI命令进行控制：

使WordPress博客公开

如果您的.env变量APP_ENV为production，我们将数据库值blog_public设置为true，否则将其设置为false。这是通过以下option update blog_public {如前所述} WP-CLI命令完成的。

更新WordPress数据库

通过WP-CLI core update-db命令执行。

生成符号链接

此步骤在public目录内生成符号链接，该目录由config/wordless.php中的public-symlinks键配置。您可以在此处了解更多信息。

应用WordPress管理配置

管理面板配置在此预先配置如下：

  • 使用php console options:date命令配置日期。
注册计划

使用 php console schedule:register 命令注册 WordPress CRON 调度。您可以在这里了解更多有关调度的信息。

运行迁移

使用 php console migrate 命令将缺失的迁移运行到您的 migrations 目录中。有关迁移的更多信息，请参阅这里。

同步用户角色

同步您的应用程序管理员用户角色，这些角色位于 config/wordpress.php 中的 permissions 配置键。有关用户角色同步的更多信息，请参阅这里。

WordPress 配置文件权限

为了避免在生产环境中（APP_ENV=production）出现任何问题，我们将 wp/wp-core/wp-config.php 文件的权限设置为 660。

WordPress插件

通过环境常量 DISALLOW_FILE_MODS 设置为 true 安装 Wordless blocks 插件。为了维护您的插件（以及主题），您应使用 Composer。您可以在https://wpackagist.org/ 查找可用的主题和插件。

WordPress 核心

要下载 WordPress 核心文件（从常规 WordPress 文件夹中的一切，除了 wp-content，我们已经在我们创建在 wp 内的文件夹中），我们同样使用 Composer。它们保存在 wp/wp-core 中。有关如何维护 WordPress 版本的更多信息，请参阅这里。

重要： 此过程不会完全安装 WordPress，只会下载其核心文件。

更改 WordPress 版本

要更改项目使用的 WordPress 版本，您必须更改项目 composer.json 文件中 roots/wordpress 包的版本约束，并运行以下命令

composer update roots/wordpress -W

Wordless 公共入口点和符号链接

WordPress 建议您的服务器使用其根目录作为入口点。在 NGINX 中，这意味着您的配置文件应该定义一个根，其绝对路径指向项目根目录。这里的主要问题是，当客户端通过互联网访问您的网站时，它可能会尝试访问项目中的任何目录/文件，这可能会成为严重的安全问题。为了避免这种情况，WordPress 会持续更新以正确阻止对敏感目录/文件的直接访问。然而，第三方插件目录/文件也必须持续更新以阻止这些问题。

正如我们所看到的，我们必须信任所有这些目录/文件都被正确地阻止了。此外，由于我们的代码将位于项目根目录中，我们也必须关注这个安全问题。为了帮助解决这个问题，Wordless 在其根目录中引入了一个 public 入口点目录。只有其中的目录/文件才能通过互联网直接由客户端访问。

要使必要的目录/文件对客户端可访问，您只需在 config/wordless.php 中配置 public-symlinks 键，它应该是一个数组，其键是客户端访问的 URI，其值是从 public 目录到相应可访问文件/目录的相对路径。

配置 public-symlinks

如前所述，要将符号链接包含在 public 目录中，您只需要将 public 内部的相对符号链接路径映射到给定的文件/目录相对路径，就像以下示例所示

use Wordless\Application\Commands\GeneratePublicWordpressSymbolicLinks;

return [
    // ...
    GeneratePublicWordpressSymbolicLinks::PUBLIC_SYMLINK_KEY => [
        // ...
        'index.php' => '../wp/index.php',
        // ...
    ],
    // ...
];

上面的代码将创建一个名为 index.php 的符号链接，链接到 public/../wp/index.php（意味着 wp/index.php）文件。请注意，由于我们已经将 public 目录作为 NGINX 服务器的入口点，index.php 成为了网站的合法 URI（https://example.test/ index.php）。

让我们看看另一个示例，这次使用目录作为符号链接的目标

use Wordless\Application\Commands\GeneratePublicWordpressSymbolicLinks;

return [
    // ...
    GeneratePublicWordpressSymbolicLinks::PUBLIC_SYMLINK_KEY => [
        // ...
        'wp-content/uploads' => '../wp/wp-content/uploads',
        // ...
    ],
    // ...
];

上面的代码将创建一个名为 uploads 的符号链接，链接到 public/../wp/wp-content/uploads（意味着 wp/index.php）文件。请注意，由于我们已经将 public 目录作为 NGINX 服务器的入口点，index.php 成为了网站的合法 URI（https://example.test/ index.php）。

.wlsymlinks 文件

待定。

缓存

待定。

数据库迁移

待定。

WordPress 抽象

由于 WordPress 不是面向对象的，为了帮助开发者，我们引入了一些类来管理其抽象，如下所示。

自定义文章类型

待定。

定时任务

待定。

用户角色同步

待定。

WordPress 管理面板

诊断小部件

此面板可能会让通过信息如“自动更新已禁用”或“缺少默认主题”登录管理面板的用户感到烦恼。这些消息对那些没有开发者的用户管理自己的网站是有用的，但对于 Wordless 来说，这只是一个烦恼或者不重要的事情。因此，您可以通过在 config/wordpress.php 中管理可以查看此小部件的用户角色，来添加或删除 show_diagnostics_only_to 数组键中的用户角色别名。

常见问题

  • 在 Windows 中进入工作区容器时出现 Bash 错误：有时您的 Git for Windows 可能会绕过我们为 docker 目录配置的 .gitattributes，并以 CRLF 行结束符（Windows 风格）克隆其文件。如果您使用 \r\n 作为行结束符构建工作区容器，则会显示以下警告
    bash: $'\r': command not found
bash: $'\r': command not found
bash: /home/laradock/aliases.sh: line 118: syntax error near unexpected token `$'{\r''
'ash: /home/laradock/aliases.sh: line 118: `function mkd() {
    要解决这个问题，请将 docker 目录内所有文件的行结束符更改为 LF（Unix 风格），然后使用 docker compose build --no-cache 重新构建容器。
  • WSL 上的缓慢互联网连接（这也使得 Docker 容器也具有有限的互联网连接）：[https://townsyio.medium.com/wsl2-how-to-fix-download-speed-3edb0c348e29#2b4c](https://townsyio.medium.com/wsl2-how-to-fix-download-speed-3edb0c348e29#2b4c)。
  • WSL 上没有互联网连接（这也使得 Docker 容器也断开互联网连接）：[基于：https://askubuntu.com/a/1401317](https://askubuntu.com/a/1401317)。
    1. 打开 WSL2 终端；
    2. 在 /etc/wsl.conf 中创建或追加文件：sudo vim /etc/wsl.conf；
    3. 在其中写入以下行
      [network]
generateResolvConf = false
    4. 关闭 WSL2 终端并打开 PowerShell 终端；
    5. 运行 wsl --shutdown；
    6. 再次打开 WSL2 终端；
    7. 删除旧的 /etc/resolv.conf：sudo rm -rf /etc/resolv.conf；
    8. 创建一个新的 /etc/resolv.conf：sudo vim /etc/resolv.conf；
    9. 在其中写入以下行
      nameserver 8.8.8.8
nameserver 1.1.1.1
  • 创建 Docker 网络失败：如果在执行 docker compose up -d 或类似命令时遇到类似于“无法创建网络 your_network_name：从默认中找不到可用且不重叠的 IPv4 地址池以分配给网络”的错误，可能是 Docker 已经达到了可共存网络的最大数量。只需运行 docker network prune 并回答 y 即可。不要担心，当您将它们启动时，任何其他容器所需的网络都应该再次启动（如果它们没有，可能您的 Docker 容器配置只是乱糟糟的）。[基于：https://stackoverflow.com/questions/43720339/docker-error-could-not-find-an-available-non-overlapping-ipv4-address-pool-am#comment100438100_43720339](https://stackoverflow.com/questions/43720339/docker-error-could-not-find-an-available-non-overlapping-ipv4-address-pool-am#comment100438100_43720339)。
  • 守护进程无法找到网络：如果您使用 docker network prune 或类似命令修剪了网络，则需要重新挂载容器，为此，按顺序运行以下命令
    docker compose down
docker compose up -d
  • 启动容器时网络警告：只需忽略如下警告
    WARN[0000] a network with name wordless-frontend-network exists but was not created for project "your-project-name".
Set 'external: true' to use an existing network`
    Docker Compose 团队似乎不喜欢像我们一样在项目之间共享网络的想法，但这确实工作得很好。
  • 构建时敏感数据警告：在构建开发环境时，您可能可以忽略如下警告
    WARN: SecretsUsedInArgOrEnv: Do not use ARG or ENV instructions for sensitive data
    这是一个开发环境，如果您将其用于预发布/生产，请随意自定义以提高其安全性，但您将自行承担风险。