PHPackages blomstra/fathom-analytics - 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. blomstra/fathom-analytics ActiveFlarum-extension[Utility & Helpers](/categories/utility) blomstra/fathom-analytics ========================= Integrate Fathom Analytics into your Flarum forum. 1.0.0-beta.3(3y ago)032MIT-CMUTypeScript Since Oct 3Pushed 3y ago4 watchersCompare [ Source](https://github.com/blomstra/flarum-ext-fathom-analytics)[ Packagist](https://packagist.org/packages/blomstra/fathom-analytics)[ RSS](/packages/blomstra-fathom-analytics/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (3)Dependencies (1)Versions (4)Used By (0) Fathom Analytics ================ [](#fathom-analytics) [![License](https://camo.githubusercontent.com/f4c4b6b64203dc29b5afe57f7901364e42c8c7bcfdda358155da8d79593b6ec0/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d434d552d626c75652e737667)](https://camo.githubusercontent.com/f4c4b6b64203dc29b5afe57f7901364e42c8c7bcfdda358155da8d79593b6ec0/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d434d552d626c75652e737667) [![Latest Stable Version](https://camo.githubusercontent.com/4473dbb6292d2fae6e2c3527ede584f826dbc914ab239297993ea3e33f39cbe2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f626c6f6d737472612f666174686f6d2d616e616c79746963732e737667)](https://packagist.org/packages/blomstra/fathom-analytics) [![Total Downloads](https://camo.githubusercontent.com/8aa999972d01894354a182f1c94cad3fda438f51cf22d9063d825877d7fa89fc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f626c6f6d737472612f666174686f6d2d616e616c79746963732e737667)](https://packagist.org/packages/blomstra/fathom-analytics) A [Flarum](http://flarum.org) extension. Integrate Fathom Analytics into your Flarum forum. You can add custom events through your own extension! For more info, read the [extending](#extending) section Installation ------------ [](#installation) Install with composer: ``` composer require blomstra/fathom-analytics:"*" ``` Updating -------- [](#updating) ``` composer update blomstra/fathom-analytics:"*" php flarum migrate php flarum cache:clear ``` Links ----- [](#links) - [Packagist](https://packagist.org/packages/blomstra/fathom-analytics) - [GitHub](https://github.com/blomstra/fathom-analytics) - [Discuss](https://discuss.flarum.org/d/PUT_DISCUSS_SLUG_HERE) Extending --------- [](#extending) This extension is designed to be built upon by other Flarum extensions. We've tried to make this as simple as possible for you to do. ### Creating an event [](#creating-an-event) All custom events should be defined in your extension's `common` folder. Create a new folder inside `js/src/common` named `fathomEvents`. This is where all your custom events will be stored. Create a new Javascript/Typescript file in this folder with the following template: ``` import { extend } from "flarum/common/extend"; export default { name: "My event", description: "Triggered when someone does something", id: "extension_name.event_name", code(e) { // tracking code }, }; ``` Fill in the metadata accurately. **It's strongly recommended that your `id` is scoped to your extension to prevent conflicts.** You can import any Flarum code into this file, and run it inside the `code(e) { }` method. To track an event occurring, call `e.track()` and the extension will handle the rest. > ⚠️ Due to how the Fathom extension is designed, you will often need to import files from the `forum` namespace from Flarum or other extensions. This is ok, even though this file is in `common`, provided you only use these imports inside the `code(e)` method. For example, if you want to track when any button is clicked in Flarum, your event might look like this: ``` import { extend } from "flarum/common/extend"; import Button from "flarum/common/components/Button"; export default { name: "Button clicked", description: "Triggered when any button is clicked", id: "my_extension.any_button_clicked", code(e) { const track = () => e.track(); extend(Button.prototype, ["oncreate", "onupdate"], function () { this.$().on("click", track); }); extend(Button.prototype, "onremove", function () { this.$().off("click", track); }); }, }; ``` For more examples of events, check out the default events included with the extension: [`js/src/common/DefaultEvents`](js/src/common/DefaultEvents). ### Registering your events [](#registering-your-events) After you define your events, you need to register them with the extension. To do this, create a new file at `src/js/common/registerFathomEvents.js`. In this file, export a function which registers your events with `app.fathomEventsRepository`: ``` import app from "flarum/common/app"; import AnyButtonClicked from "./fathomEvents/AnyButtonClicked"; export function registerFathomEvents() { // Don't attempt to register events when the // Fathom Analytics extension is disabled if (!("blomstra-fathom-analytics" in flarum.extensions)) return; app.fathomEventsRepository.registerEvent(AnyButtonClicked); } ``` You should import and call this `registerFathomEvents()` function in your `src/admin/index.js` and `src/forum/index.js` files. > If you have multiple custom events, you can chain calls to `registerEvent()`: > > ``` > app.fathomEventsRepository > .registerEvent(MyEvent1) > .registerEvent(MyEvent2) > .registerEvent(MyEvent3); > ``` If you build your extension JS, you should see your custom event(s) inside the Fathom Analytics extension settings. Custom events are accompanied by a small plug-in icon to show that they are from another extension. [![](custom_events.png)](custom_events.png) ### Typescript support [](#typescript-support) For Typescript typings support, copy the code below into a new file at `js/src/@types/fathom.d.ts`. Typescript should automatically pick this up and remove those red squiggles under your code: ``` type FathomEventParams = Pick; interface FathomEventAttributeData { [key: string]: { eventId: string; enabled: boolean; }; } interface EventsRepository { // private events: Record = {}; getAllEvents(): FathomEvent[]; registerEvent(event: FathomEventParams): EventsRepository; getEnabledEvents(): FathomEvent[]; isEventEnabled(eventId: string): boolean; getServerEventData(): FathomEventAttributeData; propogateServerEventData(): void; saveServerEventData(eventData: FathomEventAttributeData): Promise; getEnabledEventIDs(): string[]; } declare module "flarum/common/Application" { export default interface Application { fathomEventsRepository: EventsRepository; } } export interface FathomEvent { /** * Unique ID to represent the event * * You should prefix this with your extension ID to avoid collisions */ id: string; /** * A code snippet to execute to set up the event. * * If your event needs to extend core or extension JS, you should call * `extend` or `override` within this snippet. * * This will only be executed if the event is enabled in the admin * dashboard. * * `this` will be assigned to the FathomEvent object. * * To log the event, call `e.track()`. * * **You can use `forum`-scoped imports within this block as the * code will never be executed on the admin dashboard.** */ code: (e: FathomEvent) => boolean | void; /** * An array of extension IDs exposed in `flarum.extensions` to check exist before enabling an event. * * This is useful if your event depends on an extension, for example. * * @example `['flarum-tags']` */ requiresExtensions?: string[]; /** * A name for the event to show in the admin dashboard */ name: string; /** * A description for the event to show in the admin dashboard */ description: string; /** * Fathom event ID for tracking purposes. */ fathomEventId: string; /** * Log the event to Fathom. */ track: () => void; } ``` ### Health Score 20 — LowBetter than 14% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity9 Limited adoption so far Community11 Small or concentrated contributor base Maturity35 Early-stage or recently created project Bus Factor1 Top contributor holds 60% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~5 days Total 3 Last Release 1311d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/504687?v=4)[Daniël Klabbers](/maintainers/Luceos)[@luceos](https://github.com/luceos) --- Top Contributors [![davwheat](https://avatars.githubusercontent.com/u/7406822?v=4)](https://github.com/davwheat "davwheat (12 commits)")[![flarum-bot](https://avatars.githubusercontent.com/u/39334649?v=4)](https://github.com/flarum-bot "flarum-bot (8 commits)") --- Tags flarum ### Embed Badge ![Health badge](/badges/blomstra-fathom-analytics/health.svg) ``` [![Health](https://phpackages.com/badges/blomstra-fathom-analytics/health.svg)](https://phpackages.com/packages/blomstra-fathom-analytics) ``` ### Alternatives [fof/byobu Well integrated, advanced private discussions. 61105.8k9](/packages/fof-byobu)[fof/user-bio Add a user bio to user profiles 2196.5k9](/packages/fof-user-bio)[fof/links Manage Flarum primary navbar menu links 39118.3k2](/packages/fof-links)[fof/drafts Allow users to create post and discussion drafts 1771.1k5](/packages/fof-drafts)[fof/nightmode Add a Night Mode option for your users to use on your Flarum forum 3774.5k2](/packages/fof-nightmode)[fof/best-answer Mark a post as the best answer in a discussion 26135.2k15](/packages/fof-best-answer) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)