diff --git a/DOCUMENTATION/DEVELOPERS/Plugins/README.md b/DOCUMENTATION/DEVELOPERS/Plugins/README.md
index 4e3b71fe23..78fe30f59a 100644
--- a/DOCUMENTATION/DEVELOPERS/Plugins/README.md
+++ b/DOCUMENTATION/DEVELOPERS/Plugins/README.md
@@ -1,8 +1,8 @@
Plugin Development
-=======================
+==================
SamplePlugin.php
------------------------
+----------------
Each plugin requires a main class to interact with the GNU social system.
@@ -15,7 +15,7 @@ have pre-defined arguments, based on which event they're handling. A typical
event handler:
```php
-function onSomeEvent($paramA, &$paramB)
+public function onSomeEvent($paramA, &$paramB): bool
{
if ($paramA == 'jed') {
throw new Exception(sprintf(_m("Invalid parameter %s"), $paramA));
@@ -26,7 +26,7 @@ function onSomeEvent($paramA, &$paramB)
```
Event Handlers
------------------------
+--------------
Event handlers must return a Boolean value.
@@ -41,50 +41,43 @@ If the handler throws an exception, processing will stop, and the exception's
error will be shown to the user.
Installation
-------------------
+------------
-To install a plugin (like this one), site admins add the following code to their
+To enable a plugin (like the SamplePlugin), site admins add the following code to their
config.php file:
```php
addPlugin('Sample');
```
-Plugins must be installed in one of the following directories:
-
-* local/plugins/{$pluginclass}.php
-* local/plugins/{$name}/{$pluginclass}.php
-* local/{$pluginclass}.php
-* local/{$name}/{$pluginclass}.php
-* plugins/{$pluginclass}.php
-* plugins/{$name}/{$pluginclass}.php
+Third Party Plugins must be installed in `local/plugins/{$name}/{$pluginclass}.php`
Here, `{$name}` is the name of the plugin, like 'Sample', and `{$pluginclass}`
is the name of the main class, like 'SamplePlugin'. Plugins that are part of
the main GNU social distribution go in 'plugins' and third-party or local ones
go in 'local'.
-Simple plugins can be implemented as a single module. Others are more complex
-and require additional modules; these should use their own directory, like
+Simple plugins can be implemented as a single plugin. Others are more complex
+and require additional plugins; these should use their own directory, like
'local/plugins/{$name}/'. All files related to the plugin, including images,
-JavaScript, CSS, external libraries or PHP modules should go in the plugin
+JavaScript, CSS, external libraries or PHP plugins should go in the plugin
directory.
Plugin Configuration
-------------------
+--------------------
Plugins are configured using public instance attributes. To set their values,
site administrators use this syntax:
```php
-addPlugin('Sample', ('attr1' => 'foo', 'attr2' => 'bar'));
+addPlugin('Sample', ['attr1' => 'foo', 'attr2' => 'bar']);
```
The same plugin class can be initialized multiple times with different arguments:
```php
-addPlugin('EmailNotify', array('sendTo' => 'evan@status.net'));
-addPlugin('EmailNotify', array('sendTo' => 'brionv@status.net'));
+addPlugin('EmailNotify', ['sendTo' => 'evan@status.net']);
+addPlugin('EmailNotify', ['sendTo' => 'brionv@status.net']);
```
```php
@@ -96,34 +89,34 @@ class SamplePlugin extends Plugin
```
Initialization
-------------------
+--------------
Plugins overload this method to do any initialization they need, like connecting
-to remote servers or creating paths or so on. @return boolean hook value; true
+to remote servers or creating paths or so on. @return bool hook value; true
means continue processing, false means stop.
```php
-function initialize()
+public function initialize(): bool
{
return true;
}
```
Clean Up
-------------------
+--------
Plugins overload this method to do any cleanup they need, like disconnecting from
remote servers or deleting temp files or so on.
```php
-function cleanup()
+public function cleanup(): bool
{
return true;
}
```
Database schema setup
-------------------
+---------------------
Plugins can add their own tables to the GNU social database. Plugins should use
GNU social's schema interface to add or delete tables. The ensureTable() method
@@ -135,25 +128,26 @@ the checkschema.php script is run, greatly improving performance. However, they
need to remember to run that script after installing or upgrading a plugin!
```php
-function onCheckSchema()
+public function onCheckSchema(): bool
{
$schema = Schema::get();
// '''For storing user-submitted flags on profiles'''
- $schema->ensureTable('user_greeting_count',
- array(new ColumnDef('user_id', 'integer', null,
- true, 'PRI'),
- new ColumnDef('greeting_count', 'integer')));
+ $schema->ensureTable('user_greeting_count',[
+ new ColumnDef('user_id', 'integer', null, true, 'PRI'),
+ new ColumnDef('greeting_count', 'integer')
+ ]
+ );
return true;
}
```
-Load related modules when needed
-------------------
+Load related plugins when needed
+--------------------------------
-Most non-trivial plugins will require extra modules to do their work. Typically
+Most non-trivial plugins will require extra plugins to do their work. Typically
these include data classes, action classes, widget classes, or external libraries.
This method receives a class name and loads the PHP file related to that class.
@@ -166,26 +160,26 @@ in this plugin! So, make sure to return true by default to let other plugins,
and the core code, get a chance.
```php
-function onAutoload($cls)
+public function onAutoload($cls): bool
{
- $dir = dirname(__FILE__);
+ $dir = __DIR__;
switch ($cls)
{
- case 'HelloAction':
- include_once $dir . '/' . strtolower(mb_substr($cls, 0, -6)) . '.php';
- return false;
- case 'User_greeting_count':
- include_once $dir . '/'.$cls.'.php';
- return false;
- default:
- return true;
+ case 'HelloAction':
+ include_once $dir . '/' . strtolower(mb_substr($cls, 0, -6)) . '.php';
+ return false;
+ case 'User_greeting_count':
+ include_once $dir . '/'.$cls.'.php';
+ return false;
+ default:
+ return true;
}
}
```
Map URLs to actions
-------------------
+-------------------
This event handler lets the plugin map URLs on the site to actions (and thus an
action handler class). Note that the action handler class for an action will be
@@ -193,28 +187,28 @@ named 'FoobarAction', where action = 'foobar'. The class must be loaded in the
onAutoload() method.
```php
-function onRouterInitialized($m)
+public function onRouterInitialized($m): bool
{
$m->connect('main/hello',
- array('action' => 'hello'));
+ ['action' => 'hello']);
return true;
}
```
Modify the default menu to link to our custom action
-------------------
+-----------------------------------------------------
Using event handlers, it's possible to modify the default UI for pages almost
without limit. In this method, we add a menu item to the default primary menu
for the interface to link to our action.
Action Class
-------------------
+------------
The Action class provides a rich set of events to hook, as well as output methods.
```php
-function onEndPrimaryNav($action)
+public function onEndPrimaryNav($action): bool
{
// '''common_local_url()''' gets the correct URL for the action name we provide
@@ -225,18 +219,20 @@ function onEndPrimaryNav($action)
public function onPluginVersion(&$versions): bool
{
- $versions[] = array('name' => 'Sample',
- 'version' => GNUSOCIAL_VERSION,
- 'author' => 'Brion Vibber, Evan Prodromou',
- 'homepage' => 'http://example.org/plugin',
- 'rawdescription' =>
- _m('A sample plugin to show basics of development for new hackers.'));
+ $versions[] = [
+ 'name' => 'Sample',
+ 'version' => GNUSOCIAL_VERSION,
+ 'author' => 'Brion Vibber, Evan Prodromou',
+ 'homepage' => 'http://example.org/plugin',
+ 'rawdescription' =>
+ _m('A sample plugin to show basics of development for new hackers.')
+ ];
return true;
}
```
hello.php
-------------------
+---------
This section is taken directly from the 'hello.php'. ( plugins/Sample/hello.php )
@@ -255,7 +251,7 @@ class HelloAction extends Action
```
Take arguments for running
-------------------
+--------------------------
This method is called first, and it lets the action class get all its arguments
and validate them. It's also the time to fetch any relevant data from the database.
@@ -263,8 +259,8 @@ and validate them. It's also the time to fetch any relevant data from the databa
Action classes should run parent::prepare(array $args = []) as the first line
of this method to make sure the default argument-processing happens.
-```php
-function prepare(array $args = [])
+```php
+public function prepare(array $args = []): bool
{
parent::prepare($args);
@@ -279,14 +275,14 @@ function prepare(array $args = [])
```
Handle request
-------------------
+--------------
This is the main method for handling a request. Note that most preparation
should be done in the prepare() method; by the time handle() is called the
action should be more or less ready to go.
```php
-function handle()
+public function handle(): void
{
parent::handle();
@@ -300,7 +296,7 @@ Title of this page
Override this method to show a custom title.
```php
-function title()
+public function title(): string
{
if (empty($this->user)) {
return _m('Hello');
@@ -311,7 +307,7 @@ function title()
```
Show content in the content area
-------------------
+--------------------------------
The default GNU social page has a lot of decorations: menus, logos, tabs, all
that jazz. This method is used to show content in the content area of the
@@ -319,15 +315,15 @@ page; it's the main thing you want to overload. This method also demonstrates
use of a plural localized string.
```php
-function showContent()
+public function showContent(): void
{
if (empty($this->user)) {
- $this->element('p', array('class' => 'greeting'),
+ $this->element('p', ['class' => 'greeting'],
_m('Hello, stranger!'));
} else {
- $this->element('p', array('class' => 'greeting'),
+ $this->element('p', ['class' => 'greeting'],
sprintf(_m('Hello, %s'), $this->user->nickname));
- $this->element('p', array('class' => 'greeting_count'),
+ $this->element('p', ['class' => 'greeting_count'],
sprintf(_m('I have greeted you %d time.',
'I have greeted you %d times.',
$this->gc->greeting_count),
@@ -337,7 +333,7 @@ function showContent()
```
Return true if read only.
-------------------
+-------------------------
Some actions only read from the database; others read and write. The simple
database load-balancer built into GNU social will direct read-only actions to
@@ -347,9 +343,8 @@ This defaults to false to avoid data integrity issues, but you should make sure
to overload it for performance gains.
```php
-function isReadOnly($args)
+public function isReadOnly($args): bool
{
return false;
}
```
-
diff --git a/plugins/Awesomeness/AwesomenessPlugin.php b/DOCUMENTATION/DEVELOPERS/Plugins/Sample Plugins/Awesomeness/includes/AwesomenessPlugin.php
similarity index 71%
rename from plugins/Awesomeness/AwesomenessPlugin.php
rename to DOCUMENTATION/DEVELOPERS/Plugins/Sample Plugins/Awesomeness/includes/AwesomenessPlugin.php
index 80c664d06b..14889baee9 100644
--- a/plugins/Awesomeness/AwesomenessPlugin.php
+++ b/DOCUMENTATION/DEVELOPERS/Plugins/Sample Plugins/Awesomeness/includes/AwesomenessPlugin.php
@@ -13,39 +13,13 @@
//
// You should have received a copy of the GNU Affero General Public License
// along with GNU social. If not, see .
-/**
- * StatusNet, the distributed open-source microblogging tool
- *
- * Module to add additional awesomenss to StatusNet
- *
- * PHP version 5
- *
- * LICENCE: This program is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Affero General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * 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 this program. If not, see .
- *
- * @category Module
- * @package StatusNet
- * @author Jeroen De Dauw
- * @license http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
- * @link http://status.net/
- */
defined('GNUSOCIAL') || die();
/**
* Fun sample plugin: tweaks input data and adds a 'Cornify' widget to sidebar.
*
- * @category Module
+ * @category Plugin
* @package GNUsocial
* @author Jeroen De Dauw
* @copyright 2019 Free Software Foundation, Inc http://www.fsf.org
@@ -63,7 +37,7 @@ class AwesomenessPlugin extends Plugin
'version' => self::PLUGIN_VERSION,
'author' => 'Jeroen De Dauw',
'homepage' => 'https://git.gnu.io/gnu/gnu-social/tree/master/plugins/Awesomeness',
- // TRANS: Module description for a sample plugin.
+ // TRANS: Plugin description for a sample plugin.
'rawdescription' => _m('The Awesomeness plugin adds additional awesomeness ' .
'to a GNU social installation.')
];
@@ -80,7 +54,7 @@ class AwesomenessPlugin extends Plugin
public function onEndShowSections(Action $action)
{
$action->elementStart('div', ['id' => 'cornify_section',
- 'class' => 'section']);
+ 'class' => 'section']);
$action->raw(
<<