mattoid/flarum-ext-money-history

Allow users to track any changes made to their money

v1.1.3.2 2025-08-25 08:00 UTC

Requires

• antoinefr/flarum-ext-money: ^1.3
• flarum/core: ^1.2.0

Requires (Dev)

• flarum/testing: ^1.0.0

LPL-1.02

• mattoid

• flarum

README

A Flarum extension to record income and expenses of the users' money, allowing users to track any changes made to their money.

一个 Flarum 扩展， 用于记录用户的资金进出，以便于用户查看自己的资金流向信息。

Please note: This extension does not automatically record transactions. Other extensions need to actively notify this extension of transaction events to record them. Before other extensions are adapted to work with this extension, you can use Money History Auto extension for automatic recording.

注意：该插件不会自动记录，需要插件主动通知本插件的记录事件来完成消费。在其他插件为适配本插件之前，可以使用 Money History Auto 插件来实现自动记录功能。

Problem

This extension has been developed and tested only on Chinese forums and did not take into account that there will be multiple languages on the forums at the same time. Therefore, there may be problems when being used on multilingual forums. PRs are welcomed!😊

本插件仅在中文论坛上进行开发与测试，并未考虑到在论坛上同时存在多种语言的情况，因此在多语言论坛上可能存在问题。欢迎PR！😊

Screenshots

Installation

Install with composer:

composer require mattoid/flarum-ext-money-history:"*"

Updating

composer update mattoid/flarum-ext-money-history:"*"
php flarum migrate
php flarum cache:clear

How It Works

money-history is no longer meant to be the primary balance-changing entry point.

For new integrations:

1. Other extensions should call the services provided by antoinefr/flarum-ext-money.
2. money writes history through the BalanceHistoryRecorder contract when mattoid-money-history is enabled.
3. money-history provides the BalanceHistoryRecorder implementation and persists the history rows.

This keeps balance mutation and history recording aligned.

Recommended Integration For Other Extensions

If your extension needs to change user balance, inject:

use AntoineFr\Money\Service\BalanceManager;

Then use one of these methods:

• adjustBalance() for one user
• adjustBalances() for bulk updates
• transferBalance() for user-to-user transfers
• syncPersistedBalanceChange() only when your extension already changed and saved the balance itself inside its own transaction

Example:

$this->balances->adjustBalance(
    $user,
    -12.5,
    'MYEXTENSION',
    'vendor-my-extension.forum.history.purchase',
    [
        'itemTitle' => 'VIP Badge',
        'itemTypeKey' => 'vendor-my-extension.forum.item-type.badge',
    ],
    $actor
);

Important Notes For Integrators

• New integrations should not depend on money-history-auto.
• If you already persist balance manually in the same transaction as other domain writes, call syncPersistedBalanceChange() after the save, with balanceBefore and balanceAfter context handled by the money service call.
• Keep sourceParams flat. Do not store nested JSON objects.
• Use stable translation keys in source_key.
• Use source as a stable machine-readable source name, for example MONEYREWARDS or DECORATIONSTORE.

source_key And source_params

History reasons are rendered on the forum from:

• source_key
• source_params

The backend should store translation keys and raw parameters, not ready-to-display text.

Recommended conventions:

• plain values: postNumber, itemTitle, username, orderId
• translated values: keys ending with Key, for example purchaseTypeKey
• clickable links: keys ending with LinkHref, for example postLinkHref, userLinkHref

Example:

[
    'itemTitle' => 'VIP Badge',
    'purchaseTypeKey' => 'vendor-my-extension.forum.purchase-type.monthly',
    'postLinkHref' => '/d/12/34',
]

Then the frontend translation may use:

vendor-my-extension:
  forum:
    history:
      purchase: 'Purchased <postLink>{itemTitle}</postLink> ({purchaseType})'

Performance Notes

• money-history itself only writes history records when invoked by the money extension recorder integration.
• Avoid custom per-row history writes when a batch operation can use adjustBalances().
• Avoid fetching extra models just to render history reasons. Put the needed flat values in source_params.

Links

• Packagist
• GitHub
• Discuss