版本：5.1

步骤 1 基本模块

第一步的目标是让你有一个可用的站点模块，你可以在自己的 Joomla 实例中看到它。

在第一步中，模块将只输出 HTML

<h4>Hello</h4>

源代码也可以在 mod_hello step 1 中找到。

源代码

在这一步中，你需要在一个名为 mod_hello 的文件夹中创建 3 个文件，如以下图表所示

Module tutorial step 1 file structure

清单文件

mod_hello/mod_hello.xml
<?xml version="1.0" encoding="UTF-8"?>
<extension type="module" client="site" method="upgrade">
    <name>Joomla module tutorial</name>
    <version>1.0.1</version>
    <author>me</author>
    <creationDate>today</creationDate>
    <description>Code used in the Joomla module tutorial</description>
    <namespace path="src">My\Module\Hello</namespace>
    <files>
        <folder module="mod_hello">services</folder>
        <folder>src</folder>
    </files>
</extension>

此文件称为“清单”文件，它告诉 Joomla 安装程序有关你想要安装的扩展的关键信息

type="module" - 扩展类型为模块（而不是组件、插件等）
client="site" - 此模块用于“站点”，即 Joomla 前端。它不适用于管理员后端。
method="upgrade" - 这与下一个教程步骤更相关，意味着正在安装的版本可以安装在现有版本之上（即它提供升级）
<name>、<author>、<creationDate>、<description> 都是 Joomla 不验证的描述性元素。安装模块后，你可以通过转到“内容”/“站点模块”和“系统”/“管理”/“扩展”来查看它们。
<version> - 模块版本 - 你应该在后续版本中更新它。
<files> - 告诉安装程序哪些文件应被视为模块代码的一部分。module="mod_hello" 属性告诉 Joomla 在 /services 文件夹中查找服务提供程序文件，该文件是 mod_hello 的起点。如果你在目录中有未明确包含在 <files> 部分中的文件，那么 Joomla 安装程序将忽略它们。
<namespace> - 是我们模块 mod_hello 的命名空间前缀。它遵循 Joomla 建议，我们使用“My”作为我们的公司名称。

path="src" 属性意味着我们应该将我们的 PHP 类存储在 /src 子文件夹中，我们必须将它包含在 <files> 元素中，以便 Joomla 安装程序处理它。

然后命名空间前缀 \My\Module\Hello\Site 将指向此文件夹，我们应该根据 PSR-4 建议为其下面的类命名。

Joomla 中的命名空间在命名空间部分中描述。

清单文件在清单文件中描述。

服务提供程序文件

将以下代码放入 mod_hello/services/provider.php 中

mod_hello/services/provider.php
<?php

\defined('_JEXEC') or die;

use Joomla\CMS\Extension\Service\Provider\Module as ModuleServiceProvider;
use Joomla\CMS\Extension\Service\Provider\ModuleDispatcherFactory as ModuleDispatcherFactoryServiceProvider;
use Joomla\CMS\Extension\Service\Provider\HelperFactory as HelperFactoryServiceProvider;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;

return new class () implements ServiceProviderInterface {

    public function register(Container $container): void
    {
        $container->registerServiceProvider(new ModuleDispatcherFactoryServiceProvider('\\My\\Module\\Hello'));
        $container->registerServiceProvider(new HelperFactoryServiceProvider('\\My\\Module\\Hello\\Site\\Helper'));
        $container->registerServiceProvider(new ModuleServiceProvider());
    }
};

如果你不熟悉 Joomla 开发，那么这段代码可能看起来非常吓人。如果是这样，最好的办法就是现在接受它。这只是用于将 Joomla 核心代码与我们的 mod_hello 扩展链接的样板代码。我们将在本教程的后续步骤中解释它。

调度程序文件

当 Joomla 运行我们的 mod_hello 代码时，它首先会实例化我们的 Dispatcher 类并调用它的 dispatch() 函数。

mod_hello/src/Dispatcher/Dispatcher.php
<?php
namespace My\Module\Hello\Site\Dispatcher;

\defined('_JEXEC') or die;

use Joomla\CMS\Dispatcher\DispatcherInterface;

class Dispatcher implements DispatcherInterface
{
    public function dispatch()
    {
        echo '<h4>Hello</h4>';
    }

开头的 _JEXEC 检查是一项安全功能。如果有人输入直接指向此 PHP 源文件的 URL，那么 PHP 解释器将开始运行代码。为了避免黑客获取有关文件代码的信息，这行代码检查常量“_JEXEC”是否已定义，如果未定义，则退出。当 Joomla 正常运行时，它会定义此“_JEXEC”常量，因此当 Joomla 调用你的模块时，它将已经被定义。

（defined 函数前面的反斜杠只是为了表示我们想在全局命名空间中使用 PHP defined 函数，而不是此文件的命名空间。在这里，即使我们省略反斜杠也不会有什么问题，因为我们没有本地 defined 函数，如果在本地找不到该函数，PHP 会回退到全局函数。）

安装你的模块

接下来，将包含 3 个源文件的文件夹 mod_hello 打包成一个名为 mod_hello.zip 的文件。

在你的 Joomla 管理员后端，转到“系统”/“安装”/“扩展”，然后点击“上传包文件”选项卡

Installing an extension

点击“浏览文件”并选择你的 mod_hello.zip，让 Joomla 安装它。然后你应该看到一条确认消息

“模块安装成功。”

以及清单文件 <description> 元素中的文本。

Joomla 将你的代码存储在 /modules 文件夹中。如果你打开该文件夹，你应该看到你的 mod_hello 文件夹及其下面的文件结构。

使你的模块可见

要使你的模块可见，你需要做 3 件事

发布你的模块
为你的模块定义一个模板位置
定义哪些站点页面将显示你的模块

要执行这些操作，请在管理员后端中导航到“内容”/“站点模块”。你应该看到一个标题为“Joomla 模块教程”（或你在清单文件中输入的 <name>）的模块。你在“状态”列中会看到一个十字，表示此模块的状态为未发布。

点击模块标题（“Joomla 模块教程”）以编辑模块信息，然后点击“模块”选项卡。

Editing the module

在“位置”字段中选择“sidebar-right”作为你的模块位置。

在“状态”字段中选择“已发布”。

点击“菜单分配”选项卡，并在“模块分配”字段中选择“所有页面”。

“设置菜单分配”)

点击“保存并关闭”按钮。这将返回到站点模块列表。

现在，在此列表中，你的“Joomla 模块教程”模块应该在“状态”列中显示一个绿色的勾号，并在“位置”列中有一个“sidebar-right”条目。

如果你在你的网站上显示一个页面，你应该在右侧边栏中看到你的模块

Display Tutorial Module

故障排除

如果你收到“类未找到”异常，则意味着 Joomla 找不到你代码中指定的类。

仔细检查

清单文件中的 <namespace> 标签
PHP 文件中的 use 语句
PHP 类文件中的类名
PHP 类文件的文件名

Joomla 将使用这些详细信息来查找你的类源文件，如使用 PSR-4 查找类文件中所述。

另外，请确保 /src 文件夹下的子目录和 PHP 类文件的文件名大小写正确。如果你在 Windows 下开发，则操作系统会忽略文件名中大小写之间的区别。如果你随后将扩展安装在运行在 linux 上的实时站点上，你可能会遇到“类未找到”异常，因为 linux 对大小写不那么宽容。

查找模板位置

在上一节中，我建议你使用“sidebar-right”作为你的模块位置。但是，你会注意到有很多可供选择的位置。那么你如何知道该选择哪个呢？

如果你使用的是默认的 Joomla 站点模板 Cassiopeia，你可以查看模板位置此处。

另外，一个有用的技巧是转到管理员“系统”/“全局配置”，选择“模板”，并将“预览模块位置”选项设置为“启用”，然后保存你的更改。

然后转到你的站点，并在 URL 中添加 URL 查询参数 ?tp=1（例如，http://localhost/joomsite/index.php?tp=1）。然后会显示模板位置。

源代码​

清单文件​

服务提供程序文件​

调度程序文件​

安装你的模块​

使你的模块可见​

故障排除​

查找模板位置​

源代码