[ForceGroup] Modernized plugin and improved documentation

plugins/ForceGroup/ForceGroupPlugin.php

@@ -1,40 +1,44 @@
 <?php
-/*
+// This file is part of GNU social - https://www.gnu.org/software/social
- * StatusNet - the distributed open-source microblogging tool
+//
- * Copyright (C) 2010, StatusNet, Inc.
+// GNU social is free software: you can redistribute it and/or modify
- *
+// it under the terms of the GNU Affero General Public License as published by
- * This program is free software: you can redistribute it and/or modify
+// the Free Software Foundation, either version 3 of the License, or
- * it under the terms of the GNU Affero General Public License as published by
+// (at your option) any later version.
- * the Free Software Foundation, either version 3 of the License, or
+//
- * (at your option) any later version.
+// GNU social is distributed in the hope that it will be useful,
- *
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
- * This program is distributed in the hope that it will be useful,
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
+// GNU Affero General Public License for more details.
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+//
- * GNU Affero General Public License for more details.
+// You should have received a copy of the GNU Affero General Public License
- *
+// along with GNU social.  If not, see <http://www.gnu.org/licenses/>.
- * You should have received a copy of the GNU Affero General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- */
 
 /**
+ * The ForceGroup plugin allows forced group memberships and allows forcing all notices
+ * to appear in some groups.
+ *
  * @package   ForceGroupPlugin
  * @maintainer Brion Vibber <brion@status.net>
+ * @copyright 2019 Free Software Foundation, Inc http://www.fsf.org
+ * @license   https://www.gnu.org/licenses/agpl.html GNU AGPL v3 or later
  */
 
-if (!defined('STATUSNET')) { exit(1); }
+defined('GNUSOCIAL') || die;
 
 class ForceGroupPlugin extends Plugin
 {
     const PLUGIN_VERSION = '2.0.0';
 
+    // settings which can be set in config.php with addModule('ForceGroup', ['param'=>'value', ...]);
+
     /**
      * Members of these groups will have all their posts mirrored into
      * the group even if they don't explicitly mention it.
      *
      * List by local nickname.
      */
-    public $post = array();
+    public $post = [];
 
     /**
      * New user registrations will automatically join these groups on
@@ -42,16 +46,17 @@ class ForceGroupPlugin extends Plugin
      *
      * List by local nickname.
      */
-    public $join = array();
+    public $join = [];
 
     /**
-     * If poster is in one of the forced groups, make sure their notice
+     * If poster is in one of the $post groups, make sure their notice
      * gets saved into that group even if not explicitly mentioned.
      *
      * @param Notice $notice
-     * @return boolean event hook return
+     * @return bool event hook return
+     * @throws ServerException
      */
-    function onStartNoticeDistribute($notice)
+    public function onStartNoticeDistribute($notice): bool
     {
         $profile = $notice->getProfile();
 
@@ -81,6 +86,13 @@ class ForceGroupPlugin extends Plugin
         return true;
     }
 
+    /**
+     * Make sure that this new user is added to all of the $join groups
+     *
+     * @param Profile $profile
+     * @return bool event hook return
+     * @throws ServerException
+     */
     public function onEndUserRegister(Profile $profile)
     {
         foreach ($this->join as $nickname) {
@@ -91,11 +103,15 @@ class ForceGroupPlugin extends Plugin
                 } catch (Exception $e) {
                     // TRANS: Server exception.
                     // TRANS: %1$s is a user nickname, %2$s is a group nickname.
-                    throw new ServerException(sprintf(_m('Could not join user %1$s to group %2$s.'),
+                    throw new ServerException(sprintf(
-                                               $profile->nickname, $group->nickname));
+                        _m('Could not join user %1$s to group %2$s.'),
+                        $profile->nickname,
+                        $group->nickname
+                    ));
                 }
             }
         }
+        return true;
     }
 
     /**
@@ -105,7 +121,8 @@ class ForceGroupPlugin extends Plugin
      *
      * @param array &$versions array of version data arrays; see EVENTS.txt
      *
-     * @return boolean hook value
+     * @return bool hook value
+     * @throws Exception
      */
     public function onPluginVersion(array &$versions): bool
     {
@@ -116,7 +133,7 @@ class ForceGroupPlugin extends Plugin
             'author' => 'Brion Vibber',
             'homepage' => $url,
             'rawdescription' =>
-            // TRANS: Plugin description.
+            // TRANS: Module description.
                 _m('Allows forced group memberships and forces all notices to appear in groups that users were forced in.'));
 
         return true;

plugins/ForceGroup/README

@@ -1,5 +1,5 @@
-The ForceGroup plugin allows forced group memberships and forces all notices
+The ForceGroup plugin allows forced group memberships and allows forcing all notices
-to appear in groups that users were forced in.
+to appear in some groups.
 
 Installation
 ============
@@ -8,9 +8,14 @@ to the bottom of your config.php
 
 Settings
 ========
-none
+post: Members of these groups will have all their posts mirrored into the group even if they don't explicitly mention it.
+join: New user registrations will automatically join these groups on registration. They're _not_ prevented from leaving, however.
 
 Example
 =======
 addPlugin('ForceGroup');
 
+Some Example Use Cases
+=======================
+(join) Forcing a group membership allows to have a group dedicated to your instance or some of your instance main topics.
+(join + post) Allows you to federate your instance timeline