I just gave a few tips I realized were probably not really written anywhere, so I'll put them here.
There are many places in an extension that use namespaced code, variables or structures. It might be a bit complicated to know which one must match each other. Looking at the source code of an existing extension might not help realize the following points, because the same name are usually reused.
Usually you try to use the same naming everywhere to reduce confusion, but as you will see below it's not required, and sometimes not possible to use the same naming.
So here are the main namespaced items:
Not specific to JS or PHP
The package name is the one you put in
composer.json and register on Packagist when you publish your extension.
By convention you should name your package
The extension name is the unique internal name of your extension inside Flarum. Its value is derived from the package name. It's the package name with
flarum-ext- removed and
/ replaced with
Example: the package
flarum/flarum-ext-tags on Packagist has the internal name
flarum-tags. The package
flagrow/linguist has the internal name
The package name should be used for translation keys and settings keys. For example the extension
flagrow-telegram will use the key
flagrow-telegram.admin.settings.title for a translation and
flagrow-telegram.botToken for a setting. This is not a strict requirement, for example most Flagrow extensions use
vendor.package.setting syntax for their settings.
The extension name is the one saved in the list of enabled extension that Flarum keeps in the database. It's also the name you have to use when registering a setting modal (
app.extensionSettings) or adding an initializer (
It's also a good idea to use the extension name to prefix the database tables and new models/serializers you create. For example Flagrow Linguist uses
flagrow-linguist-string as the serializer name for its "strings"
The PHP namespace is usually in the form
Vendor\Package. It does not have to match the package or extension name but it's a good idea to do so. It is registered in the
composer.json file and used as the namespace of every file and class that's in your extension.
For example the extension
flagrow-linguist uses the
Flagrow\Linguist namespace for PHP code.
forum (front-end) and
admin (admin panel). An additional
lib folder holds files common to both packages.
Each of these packages has a
Gulpfile.js that defines the namespace for all the code that is in them. The convention is to use the same namespace for both the
admin package, as both won't ever be loaded at the same time.
vendor/package. For example the
flagrow-linguist extension uses the JS namespace
The JS namespace is used everytime you
$app->addBootstrapper('flagrow/linguist/main'); will call the function from the file
main.js registered under the JS namespace
I've probably forgot stuff but here we go, I hope this is useful to new developers 😄