README

Yii2 PHP框架的评论模块

Comus 是一个为 Yii 2.0 PHP 框架提供的完整的评论模块。

它允许经过身份验证的网站访问者发表评论。管理员和网站管理员可以在提交前后接受或拒绝评论。他们还可以更新或删除任何评论。评论者可以选择更新或删除自己的评论。

Comus 有三个小部件

评论显示一个评论块，其中包含在某个模型（主题）上发布的所有评论。打算在视图文件中使用。
评论计数 显示主题上发布的评论数量。可能在索引文件中使用。
用户评论 显示指向某个用户在多个主题上发表的所有评论的链接。

Comus 的演示在此处。

先决条件

Comus 依赖于基于角色的访问控制 (RBAC)。因此，必须配置 authManager 应用组件。 Comus 与 Yii 的 PhpManager 和 DbManager 都兼容。

Comus 假设网站使用 Bootstrap 4。我猜测它可以在 Bootstrap 3 下运行，但看起来不会那么令人满意。

Comus 还假设 Font Awesome 5.x 可用，无论是免费版还是专业版。如果您愿意冒险，您可能需要调整模块的 icons 选项以使 Comus 与另一个图标字体兼容。

强烈建议应用程序使用漂亮的URL。

安装

使用 Composer 以常规方式安装 yii2-comus。将以下内容添加到 composer.json 文件的 require 部分

"sjaakp/yii2-comus": "*"

或运行

composer require sjaakp/yii2-comus

您可以通过下载ZIP格式的源代码手动安装 yii2-comus。

模块

Comus 是 Yii2 框架中的一个模块。它必须在主配置文件中进行配置，通常称为 config 目录中的 web.php 或 main.php。将以下内容添加到配置数组中

<?php
// ...
'modules' => [
    'comment' => [
        'class' => 'sjaakp\comus\Module',
        // several options
    ],
],
// ...

该模块必须进行引导。通过将以下内容添加到应用程序配置数组中完成此操作

<php
// ...
'bootstrap' => [
    'comment',
]
// ...

配置文件中可能已经有一个 bootstrap 属性；只需将 'comment' 添加到其中即可。

重要：模块还必须在控制台配置（通常称为 console.php）中以相同的方式进行设置。

控制台命令

为了完成安装，需要运行两个控制台命令。第一个命令将为评论创建一个数据库表。

yii migrate

应用迁移的名称为sjaakp\comus\migrations\m000000_000000_init。

第二个控制台命令是

yii comus

这将设置RBAC系统中的一些角色和权限。

基本用法

假设我们有一个网站，展示书籍和电影的信息。我们定义了ActiveRecord模型Book和Movie。在Book模型的view文件中，我们可以像这样使用Comment小部件

   <?php
   // views/book/view.php
   use sjaakp\comus\Comment;
   
   /* @var app\models\Book $model */
   ?>
   
   <?= $model->title ?>
   <?= $model->author ?>
   // ... more information about $model ...
   
   <?= Comment::widget([
        'model' => $model
   ]) ?>

同样，在Movie模型的view文件中。

在index文件中，我们可能使用CommentCount小部件

   <?php
   // views/book/index.php
   use sjaakp\comus\CommentCount;
   use yii\grid\GridView;
   
   /* @var yii\db\ActiveDataProvider $dataProvider */
   ?>
   
   <?= GridView::widget([
        'dataProvider' => $dataProvider,
        'columns' => [
            'title:text',
            [
                'value' => function ($model, $key, $index, $widget) {
                    return CommentCount::widget([ 'model' => $model ]);
                },
                'format' => 'html'  // CommentCount displays a link
            ],
            // ... more columns ...
        ],
        // ... more options ...
   ]) ?>

网站还可以显示注册用户的信息。User模型的view文件可以使用UserComments小部件，可能看起来像这样

   <?php
   // views/user/view.php
   use sjaakp\comus\UserComments;
   
   /* @var app\models\User $user */
   ?>
   
   <?= $user->name ?>
   <?= $user->registeredSince ?>
   // ... more information about $user ...
   
   <?= UserComments::widget([
        'userId' => $user->id
   ]) ?>

评论级别

直接在主题上的评论被称为级别0。对这样的评论的评论被称为回复或级别1的评论。依此类推。评论的最大级别可以在模块配置中设置。默认值为0，表示只能直接评论。如果只允许直接评论，不要将最大级别设置得太高，因为每个级别都会有些缩进。

注意，如果版主删除了一个评论，它的所有回复也将被删除。

访客看到的评论块

版主的评论通过浅色背景色来区分。访客无法发表评论，她应该先登录。

认证用户看到的评论块

他的评论有浅青色背景色。将鼠标悬停在评论上会显示一个按钮，可以对其发表回复（如果maxLevel > 0）。

版主看到的评论块

被拒绝的评论内容可读。将鼠标悬停在评论上会显示几个管理按钮。

按钮

从左到右

接受/拒绝评论
上一条/下一条待处理评论
更新评论
删除评论
回复评论

鼠标悬停在评论上出现的按钮取决于用户的权限和评论的状态。

权限

Comus定义了一些权限。它们是

定义了一个角色：moderator。关联的权限是updateComment、deleteComment和manageComments。

如果网站有角色admin，则角色moderator包含在内。

只有版主可以查看评论概览，URL为

example.com/comment

从这里，他们可以轻松跳转到待处理的记录，等待被接受或拒绝。

注意在默认配置中，Comus允许所有认证用户创建评论，并且不需要显式授予他们权限。createComment权限用于需要限制发表评论的情况。

模块选项

Comus模块有一系列选项。它们在应用程序配置中设置，如下所示

 <?php
 // ...
 'modules' => [
     'comment' => [
         'class' => 'sjaakp\comus\Module',
         'maxLevel' => 2,
         // ...
         // ... more options ...
     ],
 ],
 // ...

选项（大多数是可选的）包括

loginUrl string|array 网站登录页面的URL，采用常规Yii格式。必填；必须设置。
profileUrl array|null|false 个人资料查看的URL。将被扩展为'id' => <user-id>。
- array 个人资料在网站的另一部分定义。例如：['/profile/view']。
- null（默认）使用Comus内置的轻量级个人资料。
- false 用户名永远不会作为链接呈现，而是作为纯文本。
maxLevel int 评论的最大深度。如果0（默认）评论只能直接在主题上发布，不能在另一个评论上发布
orderDescending bool 是否按降序显示评论。默认：true。
showPending bool 是否显示待审核评论。不影响具有 'manageComments' 权限的用户；她总是可以查看待审核评论。默认：true。
showRejected bool 是否显示被拒绝的评论。请注意，对于普通用户，会显示一条消息，而评论的实际内容会被隐藏。不影响具有 'manageComments' 权限的用户；她总是可以查看被拒绝的评论及其内容。默认：true。
showOwn bool 覆盖 showPending 和 showRejected 对于用户自己创建的评论。例如：如果您想隐藏被拒绝的评论，除了用户的自己的评论，设置 showRejected = false 和 showOwn = true。如果设置了 showPending = false，则强烈建议这样做；否则，用户将看不到她已发表的评论，可能会再次尝试。
datetimeFormat string 'standard' | 'relative' | 任何 yii\i18n\formatter::datetimeFormat 可以接受的值。默认是 'standard'，这会产生 'relative' 和 'short' 的组合。
viewPermission null | string。需要 RBAC 权限才能查看评论。如果 null（默认）：所有用户都可以查看评论，包括访客。
createPermission null | string。需要 RBAC 权限才能创建评论。如果 null（默认）：所有认证用户都可以创建评论。
usernameAttr string | callable。不是可选的；必须设置。默认：'name'。
- string：在 identity 类中用户名（昵称）的属性。
- callable：返回用户名的 function($identity)。
avatarAttr null | string | callable。默认：null。
- string：在 identity 类中头像图像的属性。
- callable：返回头像图像的 function($identity)。
- null：不显示头像。
maxLength int 评论的最大长度，以字符为单位。默认：400。
truncLength int 在 UserComments 小部件和评论管理员的评论概览中显示的评论片段的最大长度，以字符为单位。默认：80。
icons array Comus 使用的图标预设。默认：见源代码。

评论选项

Comment 小部件有三个选项

model ActiveRecord 与评论块相关的模型。
subject string 基本上，是 view 文件的相对 URL。必须设置 model 或 subject，最好设置 model。
options array 周围 div 的 HTML 选项。默认：[]。

评论计数选项

CommentCount 小部件有四个选项

model ActiveRecord 与评论计数相关的模型。
subject string 基本上，是 view 文件的相对 URL。必须设置 model 或 subject，最好设置 model。
showZero bool 如果没有与主题相关的评论，小部件是否应该显示。默认：false。
template string 输出的 HTML 模板。默认：见源代码。

UserComments 选项

UserComments 小部件有两个选项

userId int 发布评论的用户 ID。
datetimeFormat string 'standard' | 'relative' | 任何 yii\i18n\formatter::datetimeFormat 可以接受的值。如果没有设置，它将采用模块的设置。默认是 'short'。

用户评论 是从 Yii 的 GridView 衍生而来，因此它也具有该类所属的所有选项。

事件

Comus 没有定义它自己的事件。然而，评论只是一个普通的 ActiveRecord，你可以使用它的事件来拦截评论事件并注入自己的代码。有关可能的方法，请参考文件 'ComusEvents.php'。

国际化

Comus 的所有话语都是可翻译的。翻译位于 'sjaakp\comus\messages' 目录。

您可以通过设置主配置中的应用程序的消息源来覆盖 Comus 的翻译，如下所示

 <?php
 // ...
 'components' => [
     // ... other components ...     
     'i18n' => [
          'translations' => [
               // ... other translations ...
              'comus' => [    // override comus' standard messages
                  'class' => 'yii\i18n\PhpMessageSource',
                  'basePath' => '@app/messages',  // this is a default
                  'sourceLanguage' => 'en-US',    // this as well
              ],
          ],
     ],
     // ... still more components ...
 ]

翻译应在一个名为 'comus.php' 的文件中。

如果您想翻译单个或少数几个消息，并使用 Comus 的翻译作为主要内容，设置方法如下，并编写您的翻译文件类似如下

  <?php
  // app/messages/nl/comus.php
  
  $comusMessages = Yii::getAlias('@sjaakp/comus/messages/nl/comus.php');
  
  return array_merge (require($comusMessages), [
     'Empty' => 'Leeg',   // your preferred translation
  ]);

目前，唯一实现的语言是荷兰语。诚然，它是世界上第 52 种语言，但恰好是我的母语。请，欢迎翻译 Comus 为其他语言。我将非常乐意将它们包含在 Comus 的下一个版本中。

覆盖视图文件

Comus 的视图文件可以被覆盖。只需将模块的 views 设置为类似以下内容

 <?php
 // ...
 'modules' => [
     'comment' => [
         'class' => 'sjaakp\comus\Module',
         'views' => [
              'default' => [    // Comus controller id
                  'user' => <view file>    // action => view
              ]
         ],
         // ...
         // ... more options ...
     ],
 ],
 // ...

<view file> 可以是 yii\web\controller::render() 接受的任何形式。

模块 ID

默认情况下，模块 ID 是 'comment'。它在模块配置中设置。如果需要（例如，如果有与其他模块或应用程序组件冲突），您可以设置不同的模块 ID。 重要：在这种情况下，必须将 Comment 和 CommentCount 小部件的 moduleId 属性设置为这个新值。

Comus 是什么？

Comus 是古代的希腊酒神节和狂欢的之神。他是狄俄尼索斯的儿子，与无政府主义和混乱有关。此外，他的名字以 'com' 开头，在我看来，这使得 Comus 是一个很好的评论模块的名称。

sjaakp / yii2-comus

维护者

详细信息