Download the PHP package huoxin/money-with-history without Composer

Money With History

A Flarum extension that adds a virtual currency system with full transaction history tracking.

As discussed here, this extension would be a merge of antoinefr/flarum-ext-money and mattoid/flarum-ext-money-history into a single, standalone package so no cross-extension dependency management is required. With this extension, I hope that we can eliminate the need of mattoid/flarum-ext-money-history-auto which relies on middleware to intercept API requests and record balance changes. However, achieving full compatibility will require support and integration from other extension developers.

Features

• Award money for posts, discussions, and likes
• Configurable auto-removal when content is hidden or deleted
• Cascade removal for posts when a discussion is deleted
• Minimum post length requirement
• Manual balance editing by moderators
• Full balance history
• Per-tag money disable permission

Installation

Updating

[!WARNING] Breaking Change for Developers & Integrators: In 1.2.0, all database setting keys and translation strings have been standardized to snake_case semantic formats (e.g., moneyname is now money_name). If your custom theme or third-party extension directly queries these keys from the Flarum settings repository, you must update your code to match the new snake_case format. Normal forum administrators are unaffected, as the php flarum migrate command seamlessly updates existing configurations.

Migrating From Legacy Extensions

Do note that some of the more complex ones are not covered, you will have to manually migrate it yourself if you want a 100% clean money history.

[!IMPORTANT] Enabling this extension for the first time will run migration tasks automatically. If you previously had a large money history database, the process may take some time to complete. It is recommended to enable the extension via CLI:

[!WARNING] Timezone DST Inaccuracy Fallback: If your Flarum database relies on SQLite, PostgreSQL, or a MySQL instance without global timezone tables loaded, the historical timezone migration will fall back to a PHP-computed offset. For timezones that observe Daylight Saving Time (e.g., America/New_York), records created during the opposite DST phase of when the migration is run will be shifted inaccurately by ±1 hour.

If you were previously using antoinefr/flarum-ext-money and/or mattoid/flarum-ext-money-history:

1. Backup your database.
2. Install this extension alongside the old ones.
3. Run php flarum migrate — idempotent migrations will:
   • Add the money column and user_money_history table if missing
   • Rename legacy columns (type → source, money → balance_delta, etc.)
   • Normalize source values (e.g. POSTWASPOSTED → POST_POSTED)
   • Migrate source_key translation prefixes to huoxin-money-with-history.forum.money-history.*
   • Copy settings keys from antoinefr-money.* and money-history.* to huoxin-money-with-history.*
4. Disable and uninstall the old extensions.

Legacy data from the deprecated mattoid-money-history-auto extension is also migrated.

For Other Extension Authors

This extension is the main balance-changing entry point. Other extensions should inject:

Available Methods

Method comparison

adjustBalance()

Single user balance change. Opens a transaction, locks the user row, updates the balance, writes history, and dispatches events — all self-contained.

Returns false if the user has insufficient balance (when preventOverdraft is enabled).

adjustBalances()

Batch update for multiple users in a single transaction. Preferred for system rewards and bulk grants.

Best Practice: If processing thousands of users simultaneously, chunk your input array (e.g., 500 users per call). This prevents PHP memory exhaustion and prevents MySQL lock exhaustion (since all rows are locked simultaneously during the transaction).

Returns the count of users actually updated. Silently skips users who can't afford the debit when preventOverdraft is enabled.

transferBalance()

Atomic user-to-user transfer. Always prevents overdraft on the sender side.

applyBalanceChange()

Use when your extension already manages its own database transaction and needs to persist the balance change alongside other domain fields atomically.

Unlike adjustBalance() which opens its own transaction and calls save() internally, applyBalanceChange() only mutates $user->money on the model object. History recording and event dispatching are deferred to an Eloquent afterSave callback — they only execute after your $user->save() succeeds. If the save fails or the transaction rolls back, no orphaned history row is written.

The caller is responsible for:

1. Opening a database transaction
2. Locking the user row (SELECT ... FOR UPDATE)
3. Calling $user->save() after this method

source, sourceKey, sourceParams

sourceParams conventions:

• Plain values: itemTitle, postNumber, username
• Translated values: keys ending with Key (e.g. purchaseTypeKey)
• Link values: keys ending with LinkHref (e.g. itemLinkHref)

Optional Integration (Soft Dependency)

If your extension wants to offer money features without requiring this extension:

Concurrency And Locking

BalanceManager locks affected user rows during write transactions to keep balance snapshots consistent.

• Prefer adjustBalances() and transferBalance() over hand-written loops
• Keep transaction work small and avoid slow side effects inside it

Screenshots

Credits

A special thanks to the original creators and contributors who made this project possible:

• AntoineFr for the flarum-ext-money extension.
• Mattoid for the flarum-ext-money-history and flarum-ext-money-history-auto extension.
• Ernest Defoe and the FriendsOfFlarum Team for the automated Flarum Community release workflow.

Links

• Packagist
• GitHub
• Discuss