Knowledge base
Things that cost me a day, so they cost you none
Working notes from building Invision Community and Flarum applications. Mostly the failures that give no error at all — the ones where everything installs cleanly and quietly does the wrong thing.
92 articles
Invision Community 5
86 articlesExtensions and contracts
39What each extension point is for, what it must declare, and what happens when it is wrong — which is usually nothing visible.
- A content listener without $class takes down your whole community
- Content behaviours are TRAITS, so instanceof is always false
- Event listeners: all 58 hooks, and the argument-order trap
- Extension method signatures are fixed, and a mismatch is a fatal on installNew
- MemberFilter extensions are gated by a hardcoded area whitelist
- One content listener for every content type, including Pages databasesNew
- The core/AccountSettings extension in Invision Community 5
- The core/AchievementAction extension in Invision Community 5
- The core/AdminNotifications extension in Invision Community 5
- The core/Build extension in Invision Community 5
- The core/CommunityEnhancements extension in Invision Community 5
- The core/ContactUs extension in Invision Community 5
- The core/ContentRouter extension in Invision Community 5
- The core/Dashboard extension: ACP dashboard blocks in Invision Community 5
- The core/EditorMedia extension in Invision Community 5
- The core/FrontNavigation extension in Invision Community 5
- The core/GroupForm extension: adding fields to the member group form
- The core/GroupLimits extension: merging secondary group settings in Invision Community 5
- The core/IpAddresses extension in Invision Community 5
- The core/LiveSearch extension in Invision Community 5
- The core/MemberACPProfileBlocks extension in Invision Community 5
- The core/MemberACPProfileTabs extension: AdminCP member view tabs in Invision Community 5
- The core/MemberExportPersonalInformation extension in Invision Community 5
- The core/MemberHistory extension in Invision Community 5
- The core/MemberRestrictions extension in Invision Community 5
- The core/MetaData extension in Invision Community 5
- The core/MFAArea extension in Invision Community 5
- The core/ModCp extension in Invision Community 5
- The core/ModCpMemberManagement extension: adding tabs to the ModCP member management page in Invision Community 5
- The core/ModeratorPermissions extension in Invision Community 5
- The core/Notifications extension in Invision Community 5
- The core/OutputPlugins extension: how a {tag} in a template is resolved
- The core/OverviewStatistics extension in Invision Community 5
- The core/Permissions extension and node permission integration in Invision Community 5
- The core/ProfileSteps extension in Invision Community 5
- The core/Sitemap extension in Invision Community 5
- The core/Statistics extension in Invision Community 5
- The core/Uninstall extension in Invision Community 5
- Where OAuth account links live, and why you should not keep your own copyNew
Languages and text
5The string table, translation, and the places where text does not appear where you expected it to.
- A core/Notifications extension needs a language key named after the CLASS
- A module shows as module__myapp_thing on the administrator restrictions screen
- addToStack() often returns a placeholder, not translated text
- Creating a language in code: set_short() does not store the locale
- Why your app shows menutab__content or module__myapp_thing to customersNew
Theming, templates and forms
9Theme hooks, CSS that survives both colour schemes, and building forms that do not throw on render.
- "This theme may be out of date" usually means your form field, not the theme
- A container query cannot style its own container
- core/Loader js() and css() must return an array of arrays
- Custom CSS that works in both colour schemes, and the var() name trap
- Form\Editor needs an EditorLocations extension that actually exists
- Setting a theme custom_css and calling save() silently does nothing
- The Invision Community 4 CSS class that silently does nothing in 5New
- Theme hook types are an enum of four, there is no "replace", and how to change the page title anyway
- Widget conventions: two language keys, ipsWidget markup, and cached blanks
Background work and scheduled tasks
5The queue system, work that has to happen after the response, and jobs that finish without doing anything.
- A realtime gateway will let any member join any channel unless you sign the channel into the tokenNew
- Running code on every request, after the page has been sent
- The core/Queue extension in Invision Community 5
- The report that shows nothing: only_full_group_by, and why catching the exception is the real bug
- Your background task is running inside a visitor's page loadNew
Data, settings and storage
11The database layer, settings, tags, file storage, and backing up a live site.
- A Pages category created in code sends every article into a redirect loop
- Building a podcast feed Apple will acceptNew
- Creating a Pages database and categories in code
- Db::insert() third and fourth arguments do very different things
- Dumping an Invision Community database from PHP: ANSI_QUOTES, multi-member gzip, and the 0x trap
- Pages page content is not a template: why template syntax prints itself, and why removing an element does not stick
- S3 and R2 storage break in any CLI script without HTTPS=on
- Taggable::setTags() deletes every existing tag first
- The ?: fallback silently breaks any setting an admin can set to zero
- The core/FileStorage extension in Invision Community 5
- There is no event when a tag is created, and what that means for your app
AI features and expectations
5What these features do, what they cost, and what buyers reasonably but wrongly assume they do.
- A chat model in an embeddings field fails silently, and looks like a broken app
- Why a similarity threshold is never enough for automatic classification
- Why your AI assistant's links arrive as plain textNew
- Your AI assistant is only as good as what you gave it to read
- Your classifier does not learn, and everyone will assume it does
Application structure and releases
11The JSON files an application is made of, versioning and upgrade steps, and testing from the command line.
- "You do not have permission for that" on your own AdminCP screen: the $csrfProtected property
- A malformed manifest silently disables your whole application
- A shared image vanishes the moment one member changes their profile photoNew
- A stray "menutab_system" in your AdminCP: acpmenu.json tabs are not validated
- Application versions: why re-uploading the same version does nothing
- Invision Community already runs an OAuth 2.1 server — do not write another oneNew
- Raw language keys in the AdminCP menu: acpmenu.json must be an object
- Six ways an Invision Community 5 application fails silentlyNew
- What you can and cannot test from the command line
- Your editor toolbar button never appears, and nothing is loggedNew
- Your friendly URLs have the app name in them twiceNew
Realtime, chat and calls
1WebSocket gateways, relays and the server-side pieces live features depend on — where "it works when I test it" and "it works for your members" are different claims.
Flarum 2
6 articles- Flarum 2: AbstractModel mass assignment throws a 500
- Flarum 2: frontend model relations must use the hasOne/hasMany call pattern
- Flarum 2: json-api-server returns 403 for declared but unwritable fields
- Flarum 2: Laravel facades throw "facade root has not been set"
- Flarum 2: never redefine core CSS variables at :root
- Flarum 2: notification Blueprints need getFromUser()
Nothing matches that.
Data, settings and storage
The database layer, settings, tags, file storage, and backing up a live site.
11 Articles in this category
-
If you are adding podcast episodes to a community, the temptation is a Pages database with an audio upload field and a player on the template. That gets you a web page. It does not get you a podcast, because a podcast is the RSS feed, and directories are unforgiving about details that produce no error anywhere. These are the rules worth knowing before you write the feed, each one a documented rejection or a player misbehaving. The namespaces, spelled exactly <rss version="2.0" xmln
-
Create a Pages category from code, move some records into it, and every one of those records becomes unreachable. The browser reports too many redirects; the server is issuing a 301 to the same URL over and over. The category itself is fine — it lists correctly, the AdminCP shows nothing unusual, and the records are present and approved. The cause is one column that nothing asked you to fill in: category_full_path. Why it loops rather than 404s Pages builds a record's canonical URL from th
-
Two things about customising a Pages "html" page that each cost an hour, and both fail in a way that looks like something else. 1. page_content is not run through the template engine A theme's custom header is compiled — Theme::getHeaderAndFooter() calls Theme::compileTemplate(), so you can write {{if}}, {{foreach}} and {expression="..."} in it and they execute. A Pages page's page_content is not. Pages parses its own tags — {database="kb"}, {block="..."}, {media="..."} — and emits everythin
-
Writing a database dump in pure PHP is not hard. Writing one that actually restores is, because every way it fails is silent. These are the ones that cost real time on Invision Community specifically. Why pure PHP at all Invision Community's own Configuration Error notification lists exec, system, passthru, pcntl_exec, popen, proc_open and shell_exec as dangerous and tells administrators to disable them. Take that advice — as you should — and mysqldump becomes unreachable. Any backup approach
-
Invision Community 5 fires 58 event-listener hooks. None of them concern tags. Tags do not go through a model with a save() you can observe. They arrive through Content\Taggable::setTags(), which deletes the item's existing rows in core_tags and inserts the new ones directly. No event, no queue job, no notification. So there is no supported way to be told that a tag has come into existence. The trap this sets Any application whose state is derived from the tag list has to refresh that state
-
A core/FileStorage extension is how an application tells the suite that it owns a bucket of files. Each extension becomes one row on AdminCP → System → Files → Storage Settings, one entry in the upload_settings setting, and one unit of work for the MoveFiles background task. Core calls it in exactly four situations: when the admin repoints that bucket at a different storage configuration (count() then repeated move()), when the admin runs Find orphaned files (isValidFile() for every file in a co
-
Reading settings with ?: is idiomatic and, for anything numeric, wrong: $perPage = Settings::i()->myapp_per_page ?: 25; PHP treats 0, '0' and '' as falsy. If an administrator sets that field to 0 — a perfectly reasonable way to say "none" or "unlimited" — they get 25 instead. The setting appears to do nothing, and no amount of re-saving it helps. Where this actually bites Anything meaning "unlimited", where 0 is the natural way to express it. Anything meaning "off", where 0 disables a f
-
Two boolean flags in a row, easy to transpose, and they mean opposite things. Getting them the wrong way round produces data corruption rather than an error. The signature public function insert( string $table, Select|array $set, bool $odkUpdate = FALSE, // 3rd: ON DUPLICATE KEY UPDATE bool $ignoreErrors = FALSE // 4th: INSERT IGNORE ): int|string|mysqli_stmt What each does CallOn a duplicate key insert( $t, $v )Throws insert( $t, $v, TRUE )Overwrites the existing r
-
The supported entry point is Databases::createDatabase(), which builds the records table, the default title and content fields, and a default category. $db = new \IPS\cms\Databases; $db->key = 'kb'; $db->use_categories = 1; $db->save(); // createDatabase() READS these while building the fields, so write them first \IPS\Lang::saveCustom( 'cms', 'content_db_' . $db->id, 'Knowledge Base' ); \IPS\Lang::saveCustom( 'cms', 'content_db_lang_pu_' . $db->id, 'articles' ); \IP
-
Anything run from the command line that touches S3-compatible storage fails with BAD_XML. That includes cron tasks and any maintenance script. The symptom RuntimeException: BAD_XML #0 /system/File/Amazon.php(823): IPS\Http\Response->decodeXml() #1 /system/File/Amazon.php(349): IPS\File\Amazon::makeRequest(..., 'put', ...) In the AdminCP it often shows up first as a Locked Task warning for s3Delete, with a climbing lock count that never clears. The cause IPS\File\Amazon::buildBaseUrl() pic
-
There is no "add a tag" operation in Invision Community. Anything that tags content programmatically must pass the complete final set, or it silently destroys work someone did by hand. What setTags() actually does Db::i()->delete( 'core_tags', array( 'tag_aai_lookup=?', $aaiLookup ) ); foreach ( $set as $key => $tag ) { try { Tag::load( $tag, 'tag_text' ); // must already exist // ... insert } catch( \OutOfRangeException ) {} // unknown tags are dro
