Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -47,3 +47,68 @@ jobs:

- name: Unit tests
run: composer test

integration:
name: Integration, PHP ${{ matrix.php }}, ${{ matrix.db }} ${{ matrix.engine || 'default engine' }}
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
include:
# oldest supported server; InnoDB there has no FULLTEXT
- php: '8.2'
db: 'mysql:5.5'
engine: ''
# servers without InnoDB
- php: '8.4'
db: 'mysql:5.7'
engine: 'MyISAM'
- php: '8.5'
db: 'mariadb:10.11'
engine: ''
services:
db:
image: ${{ matrix.db }}
env:
MYSQL_ROOT_PASSWORD: root
MYSQL_DATABASE: icms_test
MYSQL_USER: icms
MYSQL_PASSWORD: icms
ports:
- 3306:3306
options: >-
--health-cmd="mysqladmin ping -h 127.0.0.1 -uroot -proot"
--health-interval=5s
--health-timeout=5s
--health-retries=20
env:
ICMS_CORE_PATH: ${{ github.workspace }}/core/htdocs
IMFORUM_TEST_DB_HOST: 127.0.0.1
IMFORUM_TEST_DB_NAME: icms_test
IMFORUM_TEST_DB_USER: icms
IMFORUM_TEST_DB_PASS: icms
IMFORUM_TEST_DB_ENGINE: ${{ matrix.engine }}
steps:
- name: Checkout module
uses: actions/checkout@v4

- name: Checkout ImpressCMS core
uses: actions/checkout@v4
with:
repository: fiammybe/impresscms
ref: main
path: core

- name: Set up PHP
uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php }}
extensions: pdo_mysql
coverage: none
tools: composer:v2

- name: Install dev dependencies
run: composer install --no-interaction --no-progress --prefer-dist

- name: Integration tests
run: composer test:integration
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,4 @@
## 1.0.0 Alpha (unreleased)

- Phase 0: module skeleton for ImpressCMS 2.0 in IPF mode, install and update routines, English and Dutch language files, CI on PHP 8.2 to 8.5.
- Phase 1: data model. 13 IPF objects with handlers (category, forum, moderator, topic, post, attachment, report, suspension, readmark, online, digest, archive, permtemplate), group permissions on categories and forums, counters and cascading deletes through handler events, indexes in `imforum_db_upgrade_1()`, labels in English and Dutch, integration tests against MySQL 5.5, MySQL 5.7 (MyISAM) and MariaDB 10.11.
7 changes: 6 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Community forum module for ImpressCMS 2.0, built on the ImpressCMS Persistable Framework (IPF). imforum is the successor of iForum: same features, new code, and an importer that takes over the data of a running iForum installation.

Status: phase 0 (foundation). The module installs and updates, but has no forum functions yet.
Status: phase 1 (data model). The module creates its tables and the data layer works, but there are no admin screens or forum pages yet.

## Requirements

Expand All @@ -21,8 +21,11 @@ composer install
composer lint # php -l on every file
composer test # PHPUnit
ICMS_CORE_PATH=/path/to/impresscms/htdocs composer analyse # PHPStan, needs a core checkout
ICMS_CORE_PATH=/path/to/impresscms/htdocs composer test:integration # needs a database, see below
```

The integration tests install the module into an empty database with the core's own updater and then exercise the handlers. They need a core checkout and an empty MySQL or MariaDB database, set with `IMFORUM_TEST_DB_HOST`, `IMFORUM_TEST_DB_NAME`, `IMFORUM_TEST_DB_USER` and `IMFORUM_TEST_DB_PASS` (defaults: `127.0.0.1`, `icms_test`, `icms`, `icms`). Set `IMFORUM_TEST_DB_ENGINE=MyISAM` to test as on a server without InnoDB. Every run drops the tables with prefix `imft_` first, so never point it at a real site.

PHPStan reads the core classes from `ICMS_CORE_PATH`. Without that variable it stops with an error about a missing scan directory.

For a local test site, copy `src/` to `modules/imforum`. A symlink or Windows junction does not work: PHP resolves `__DIR__` to the real folder, and the module takes its name from that folder.
Expand All @@ -32,6 +35,8 @@ Conventions:
- Classes are named `mod_imforum_<Item>` and `mod_imforum_<Item>Handler` and live in `src/class/<Item>.php` and `src/class/<Item>Handler.php`; the core autoloads them once `object_items` is set.
- Form labels come from `_CO_IMFORUM_<ITEM>_<FIELD>` in `language/*/common.php`.
- English and Dutch ship with the module; other languages go through Crowdin.
- Object item names are single lower-case words that are not SQL reserved words: IPF uses them as table aliases (that is why read marks are called `readmark`).
- Counters such as `forum_posts` and `topic_replies` are recounted by `synchronise()` on the handlers after every change, never incremented by hand.
- Never rename or remove an object var in one release. The core drops columns that are no longer declared before the upgrade functions run, so add the new var and copy the data first, and remove the old var one release later.

## License
Expand Down
3 changes: 2 additions & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@
"scripts": {
"lint": "find src tests -name '*.php' -print0 | xargs -0 -n1 php -l",
"analyse": "phpstan analyse",
"test": "phpunit"
"test": "phpunit",
"test:integration": "phpunit -c phpunit.integration.xml.dist"
},
"config": {
"sort-packages": true
Expand Down
20 changes: 20 additions & 0 deletions phpstan.neon.dist
Original file line number Diff line number Diff line change
Expand Up @@ -14,3 +14,23 @@ parameters:
- %env.ICMS_CORE_PATH%/include/functions.php
- %env.ICMS_CORE_PATH%/include/cp_functions.php
- %env.ICMS_CORE_PATH%/libraries/icms.php
# Core docblocks that are narrower than the code they describe. The core
# itself passes these types everywhere; casting in the module would only
# hide that.
ignoreErrors:
-
# icms_db_criteria_Item::__construct() documents string, renders any scalar
message: '#^Parameter \#2 \$value of class icms_db_criteria_Item constructor expects string, int#'
identifier: argument.type
-
# icms_ipf_Object::initCommonVar() documents its parameters as "str"
message: '#^Parameter \#\d \$\w+ of method icms_ipf_Object::initCommonVar\(\) expects str, #'
identifier: argument.type
-
# icms_ipf_Tree::getFirstChild() documents string; the tree is keyed by integer ids
message: '#^Parameter \#1 \$key of method icms_ipf_Tree::getFirstChild\(\) expects string, int given\.$#'
identifier: argument.type
-
# icms_db_legacy_IDatabase::queryF() documents a resource, but returns false when the query fails
identifier: ternary.alwaysTrue
path: src/include/onupdate.php
17 changes: 17 additions & 0 deletions phpunit.integration.xml.dist
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Integration tests: the real ImpressCMS core against a real database.
See tests/integration-bootstrap.php for the environment variables.
-->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
bootstrap="tests/integration-bootstrap.php"
colors="true"
failOnWarning="true"
failOnNotice="true">
<testsuites>
<testsuite name="integration">
<directory>tests/Integration</directory>
</testsuite>
</testsuites>
</phpunit>
26 changes: 26 additions & 0 deletions src/class/Archive.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<?php
/**
* A copy of a post's text, kept when a topic is archived
*
* @copyright The iForum project
* @license MIT, see LICENSE
* @package imforum
* @since 1.0
*/

defined('ICMS_ROOT_PATH') || die('ImpressCMS root path not defined');

include_once dirname(__DIR__) . '/include/common.php';

class mod_imforum_Archive extends icms_ipf_Object {

public function __construct(mod_imforum_ArchiveHandler $handler) {
parent::__construct($handler);

$this->quickInitVar('archive_id', XOBJ_DTYPE_INT, true);
$this->quickInitVar('topic_id', XOBJ_DTYPE_INT, true);
$this->quickInitVar('post_id', XOBJ_DTYPE_INT, true);
$this->quickInitVar('post_text', XOBJ_DTYPE_TXTAREA);
$this->quickInitVar('archived_time', XOBJ_DTYPE_LTIME, false, '', '', 0);
}
}
27 changes: 27 additions & 0 deletions src/class/ArchiveHandler.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<?php
/**
* Handler for archived posts
*
* @copyright The iForum project
* @license MIT, see LICENSE
* @package imforum
* @since 1.0
*/

defined('ICMS_ROOT_PATH') || die('ImpressCMS root path not defined');

include_once dirname(__DIR__) . '/include/common.php';

class mod_imforum_ArchiveHandler extends icms_ipf_Handler {

public function __construct(icms_db_legacy_Database $db) {
parent::__construct($db, 'archive', 'archive_id', '', 'post_text', IMFORUM_DIRNAME);
}

protected function beforeInsert(mod_imforum_Archive $archive): bool {
if ((int) $archive->getVar('archived_time', 'e') === 0) {
$archive->setVar('archived_time', time());
}
return true;
}
}
43 changes: 43 additions & 0 deletions src/class/Attachment.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
<?php
/**
* A file attached to a post
*
* Replaces the base64-serialised list in bb_posts.attachment.
*
* @copyright The iForum project
* @license MIT, see LICENSE
* @package imforum
* @since 1.0
*/

defined('ICMS_ROOT_PATH') || die('ImpressCMS root path not defined');

include_once dirname(__DIR__) . '/include/common.php';

class mod_imforum_Attachment extends icms_ipf_Object {

public function __construct(mod_imforum_AttachmentHandler $handler) {
parent::__construct($handler);

$this->quickInitVar('attach_id', XOBJ_DTYPE_INT, true);
$this->quickInitVar('post_id', XOBJ_DTYPE_INT, true);
$this->quickInitVar('name_saved', XOBJ_DTYPE_TXTBOX, true);
$this->quickInitVar('name_display', XOBJ_DTYPE_TXTBOX, true);
$this->quickInitVar('mimetype', XOBJ_DTYPE_TXTBOX);
$this->quickInitVar('filesize', XOBJ_DTYPE_INT, false, '', '', 0);
$this->quickInitVar('downloads', XOBJ_DTYPE_INT, false, '', '', 0);
$this->quickInitVar('online', XOBJ_DTYPE_INT, false, '', '', 1);
$this->quickInitVar('attach_time', XOBJ_DTYPE_LTIME, false, '', '', 0);

$this->setControl('online', ['name' => 'yesno']);
}

/**
* Absolute path of the stored file
*
* basename() keeps a tampered name_saved inside the upload folder.
*/
public function getFilePath(): string {
return IMFORUM_UPLOAD_PATH . basename((string) $this->getVar('name_saved', 'e'));
}
}
37 changes: 37 additions & 0 deletions src/class/AttachmentHandler.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
<?php
/**
* Handler for attachments
*
* @copyright The iForum project
* @license MIT, see LICENSE
* @package imforum
* @since 1.0
*/

defined('ICMS_ROOT_PATH') || die('ImpressCMS root path not defined');

include_once dirname(__DIR__) . '/include/common.php';

class mod_imforum_AttachmentHandler extends icms_ipf_Handler {

public function __construct(icms_db_legacy_Database $db) {
parent::__construct($db, 'attachment', 'attach_id', 'name_display', '', IMFORUM_DIRNAME);
}

protected function beforeInsert(mod_imforum_Attachment $attachment): bool {
if ((int) $attachment->getVar('attach_time', 'e') === 0) {
$attachment->setVar('attach_time', time());
}
return true;
}

/**
* Remove the file together with its record
*
* A file that is already gone is not an error.
*/
protected function afterDelete(mod_imforum_Attachment $attachment): bool {
$path = $attachment->getFilePath();
return !is_file($path) || unlink($path);
}
}
31 changes: 31 additions & 0 deletions src/class/Category.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<?php
/**
* A category groups forums on the index page
*
* @copyright The iForum project
* @license MIT, see LICENSE
* @package imforum
* @since 1.0
*/

defined('ICMS_ROOT_PATH') || die('ImpressCMS root path not defined');

include_once dirname(__DIR__) . '/include/common.php';

class mod_imforum_Category extends icms_ipf_seo_Object {

public function __construct(mod_imforum_CategoryHandler $handler) {
parent::__construct($handler);

$this->quickInitVar('cat_id', XOBJ_DTYPE_INT, true);
$this->quickInitVar('cat_title', XOBJ_DTYPE_TXTBOX, true);
$this->quickInitVar('cat_description', XOBJ_DTYPE_TXTAREA);
$this->quickInitVar('cat_image', XOBJ_DTYPE_IMAGE);
$this->quickInitVar('cat_url', XOBJ_DTYPE_TXTBOX);
$this->initCommonVar('weight');
$this->initiateSEO();

$this->setControl('cat_description', ['name' => 'textarea', 'form_editor' => 'default']);
$this->setControl('cat_image', ['name' => 'image']);
}
}
49 changes: 49 additions & 0 deletions src/class/CategoryHandler.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
<?php
/**
* Handler for categories
*
* @copyright The iForum project
* @license MIT, see LICENSE
* @package imforum
* @since 1.0
*/

defined('ICMS_ROOT_PATH') || die('ImpressCMS root path not defined');

include_once dirname(__DIR__) . '/include/common.php';

class mod_imforum_CategoryHandler extends icms_ipf_Handler {

public function __construct(icms_db_legacy_Database $db) {
parent::__construct($db, 'category', 'cat_id', 'cat_title', 'cat_description', IMFORUM_DIRNAME);
$this->addPermission('category_access', _CO_IMFORUM_PERM_CATEGORY_ACCESS, _CO_IMFORUM_PERM_CATEGORY_ACCESS_DSC);
}

/**
* Options for a category select box, ordered as on the index page
*
* @return array<int, string>
*/
public function getCategorySelectList(): array {
$criteria = new icms_db_criteria_Compo();
$criteria->setSort('weight');
$criteria->setOrder('ASC');
return $this->getList($criteria);
}

/**
* Refuse to delete a category that still holds forums
*
* Deleting forums takes their topics and posts with them, so that must be
* an explicit choice per forum rather than a side effect.
*/
protected function beforeDelete(mod_imforum_Category $category): bool {
$forums = icms_getModuleHandler('forum', IMFORUM_DIRNAME)
->getCount(new icms_db_criteria_Item('cat_id', $category->id()));
if ($forums > 0) {
$category->setErrors(_CO_IMFORUM_CATEGORY_NOT_EMPTY);
return false;
}
return true;
}
}
24 changes: 24 additions & 0 deletions src/class/Digest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<?php
/**
* A digest: the list of featured topics sent by mail
*
* @copyright The iForum project
* @license MIT, see LICENSE
* @package imforum
* @since 1.0
*/

defined('ICMS_ROOT_PATH') || die('ImpressCMS root path not defined');

include_once dirname(__DIR__) . '/include/common.php';

class mod_imforum_Digest extends icms_ipf_Object {

public function __construct(mod_imforum_DigestHandler $handler) {
parent::__construct($handler);

$this->quickInitVar('digest_id', XOBJ_DTYPE_INT, true);
$this->quickInitVar('digest_time', XOBJ_DTYPE_LTIME, false, '', '', 0);
$this->quickInitVar('digest_content', XOBJ_DTYPE_TXTAREA);
}
}
Loading
Loading