PHPackages                             sgkirby/commentions - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. sgkirby/commentions

AbandonedArchivedKirby-plugin[Utility & Helpers](/categories/utility)

sgkirby/commentions
===================

A versatile comment system and integrated Webmention endpoint for Kirby 3.

1.0.7(3y ago)581.2k7MITPHP

Since May 10Pushed 2y ago2 watchersCompare

[ Source](https://github.com/sebastiangreger/kirby3-commentions)[ Packagist](https://packagist.org/packages/sgkirby/commentions)[ RSS](/packages/sgkirby-commentions/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)Dependencies (3)Versions (21)Used By (0)

🛑 This project has been **archived and is no longer maintained** (for background, export, and alternatives: [see here](https://github.com/sebastiangreger/kirby3-commentions/issues/151)). The code is MIT-licensed: you are free to fork it or build something awesome from it. The archived version has not been tested beyond Kirby 3.7.x; it is not compatible with Kirby 4+.

Kirby 3 Commentions
===================

[](#kirby-3-commentions)

A versatile comment system and integrated Webmention endpoint for [Kirby CMS](https://getkirby.com), version 3.x.

- Comments can be submitted through a form on the page or as a [Webmention](https://indieweb.org/webmention)
- Incoming webmentions are stored in a queue and processed asynchronously
- Comments can be approved/deleted in the Panel
- A range of methods, API endpoints and hooks allow to build custom frontends, applications, and flows on top
- Supports multilingual sites and virtual pages

For more background and the philosophy behind this solution, see ["Designing a commenting system with data ethics in mind"](https://sebastiangreger.net/2020/06/commentions-comments-and-data-ethics).

> Versions 1.x (June 2020 and later) are **no longer compatible with the experimental 0.x versions**. After upgrading, you will have to follow the [version migration instructions](/.github/VERSIONMIGRATION.md); a migration tool assists in converting existing commention data to the new storage format.

*NB. The plugin only covers incoming webmentions, i.e. receiving notifications from other websites that link to a page. Sending outgoing webmentions to other websites requires a separate solution, such as [Kirby 3 Sendmentions](https://github.com/sebastiangreger/kirby3-sendmentions).*

Table of contents
-----------------

[](#table-of-contents)

- [Ethics and privacy](#ethics-and-privacy)
- [Installation](#installation)
- [Setup](#setup)
- [Frontend helper](#frontend-helper)
- [Panel sections](#panel-sections)
- [Page methods](#page-methods)
- [Pages methods](#pages-methods)
- [API endpoints](#api)
- [Hooks](#hooks)
- [Data structure and storage](#data-structure-and-storage)
- [Config options](#config-options)
- [Requirements, credits, license](#requirements)

Ethics and privacy
------------------

[](#ethics-and-privacy)

**Before implementing the functionalities enabled by this plugin, it is strongly advised to carry out an ethical and legal assessment.** By enabling users to post comments and/or by processing webmentions, a website deals with what is considered personal data in most jurisdictions. The processing of personal data is subject to often very strict privacy laws, coming with a potentially wide range of obligations. Legal aspects aside, dealing with other people's data always comes with ethical implications.

> Data ethics or "GDPR compliance" are never created by software, but by the way it is used. While this plugin aims to provide means for its responsible and legally compliant use, responsibility for ethical conduct and compliance with applicable laws ultimately rests with the operator of the website (aka. "the data controller"). If in doubt, always ask a qualified lawyer - and if this plugin does not meet your requirements, create a Github issue, don't use it, or adapt it to your needs.

Installation
------------

[](#installation)

While Kirby supports PHP 8 as of version 3.5, version 1.x of the Commentions plugin has not been thoroughly tested for compatibility with PHP 8. The [work-in-progress version 2.0 (still in beta)](https://github.com/sebastiangreger/kirby3-commentions/tree/develop) is compatible with PHP 8.0.

### Recommended: Composer

[](#recommended-composer)

```
composer require sgkirby/commentions
```

### Alternatives

[](#alternatives)

This plugin relies on two libraries not included in the repository due to potential licensing issues ([html-php5](http://masterminds.github.io/html5-php/) and [HTML Purifier](http://htmlpurifier.org/); used for filtering, analysing and formatting HTML input). The Composer method takes care of installing these dependencies. Alternatively, when installing as Git submodule or via download, the plugin [kirby-sanitizer](https://github.com/avoskitchen/kirby-sanitizer) should be installed as well, making the missing libraries available.

*NB. The Panel sections present an alert until all dependencies have been installed correctly, as their absence significantly limits the functionality of this plugin.*

#### Git submodule

[](#git-submodule)

```
git submodule add https://github.com/sebastiangreger/kirby3-commentions.git site/plugins/kirby3-commentions
```

#### Download

[](#download)

Download and copy this repository to `/site/plugins/kirby3-commentions`.

Setup
-----

[](#setup)

### Step 1: Template-based activation

[](#step-1-template-based-activation)

The plugin only accepts incoming comments and/or webmentions for page templates defined in setup. To activate the plugin for certain templates, add their names to either or both of the [template-specific configuration arrays](#activate-by-template) in the `site/config/config.php`:

```
'sgkirby.commentions.templatesWithComments' => ['note', 'article'],
'sgkirby.commentions.templatesWithWebmentions' => ['note'],
```

*NB. Not setting either of these leads to a "configuratin error" message in the panel. If not accepting any comments or webmentions is your intention, setting these as empty arrays removes the error message.*

### Step 2: Adding the Commentions UIs to the Panel blueprints

[](#step-2-adding-the-commentions-uis-to-the-panel-blueprints)

All comments are stored in small text files attached to each page in the Kirby CMS. In order to display and manage them, it is required to add [panel sections](#panel-sections) to your panel blueprints (general instructions about blueprints in the [Kirby guide](https://getkirby.com/docs/guide/blueprints/introduction)).

#### Page-specific list of comments

[](#page-specific-list-of-comments)

To display and manage the comments for each page, add the following to the according blueprint in `site/blueprints/pages` (i.e. to all page blueprints where you want to use comments):

```
# in the blueprint of a page with comments
sections:
  commentions:
    type: commentions
```

By default, newest comments are shown on top; this is to ensure you immediately notice new, unapproved comments. If you prefer sorting by ascending date, add the `flip` property as follows:

```
# in the blueprint of a page with comments
sections:
  commentions:
    type: commentions
    flip: true
```

#### Adding a "comments inbox" to a blueprint

[](#adding-a-comments-inbox-to-a-blueprint)

To approve/delete incoming comments, add the following to a suitable blueprint; e.g. to `site/blueprints/site.yml` if you want the Commentions inbox to be displayed in the main Panel view of your site:

```
# in a blueprint where the inbox should be shown
sections:
  commentions:
    type: commentions
    show: pending
```

Alternatively, `pending` can be replaced with `all`, in which case all comments (pending and approved) are displayed. This may be useful in setups where new comments are set to be approved automatically.

*NB. If you leave out the `show` attribute, the comments of the page itself are displayed instead (as described above). If you are embedding the inbox on a page that also receives comments/webmentions itself, you would have to set up two sections of `type: commentions`, one for the page comments and one for the inbox.*

### Step 3: Adding frontend UIs to your templates

[](#step-3-adding-frontend-uis-to-your-templates)

The plugin comes with a set of default snippets to display lists of approved comments and a comment form in the frontend. These are optimized for the Starterkit but might be of use in other themes as well; they can also serve as boilerplates for designing your own (general instructions in the Kirby guide: [templates](https://getkirby.com/docs/guide/templates/basics), [snippets](https://getkirby.com/docs/guide/templates/snippets))

To show comments on pages and display a form to leave new comments, there are three options:

#### Option A. Add everything at once

[](#option-a-add-everything-at-once)

In order to add everything at once, add helper [`commentions()`](#commentions) to the according templates in `site/templates` - a shorthand for the three helpers described in alternative B:

```

```

This is your one-stop-shop, and it should sit rather nicely at the bottom of your content (in the Starterkit theme, add it right after the `` tag in `site/templates/note.php` for best results).

If you would like to use basic CSS styles for these prefabricated HTML snippets (a minimalistic design suitable for the Kirby 3 Starterkit), add [`commentions('css')`](#commentionscss) to your HTML <head> area (e.g. in `snippets/header.php` in the Starterkit):

```