I think you are right. To add a new token, the current workaround involves a local commit in your local Phorge :)

If you are proficient with git, I think that is a reasonable solution. That is one of the nice features of Phorge/Phabricator: you can quickly hack your local installation and maintain your patches across any git update, since you update the app just using git pull basically.

Example downstream change:

https://phabricator.wikimedia.org/T364239

https://gitlab.wikimedia.org/repos/phabricator/phabricator/-/merge_requests/40/diffs?commit_id=95abe8502f8199010047c8313b6e44428df48608

So, as you can see, at the moment people just hack their local Phorge. So if you don't have enough time to contribute in Phorge itself I can just say: do this to fix your problem :)

Talking about contributing upstream in Phorge.

In general Phorge/Phabricator is usually extended by just adding classes (for example from an extension) (https://we.phorge.it/book/contrib/article/adding_new_classes/ ). At startup, Phorge knows all your classes, and can query them, and use them. That's the way you usually add Phorge features.

This is an (untested) example line that may be integrated in upstream Phorge to make Tokens generally defined also from you local installation:

$extraTokens = return id(new PhutilClassMapQuery())
  ->setAncestorClass(PhabricatorToken::class)
  ->execute();

The semantic of this snippet is "give me all the well-known extensions of PhabricatorToken". So you can easily define local classes (again, for example from an extension) to declare custom tokens, and see them without touching the Phorge codebase anymore.

So this snippet could be somehow integrated to also allow to define more local PhabricatorToken classes. Maybe adding that here somewhere:

https://we.phorge.it/source/phorge/browse/master/src/applications/tokens/query/PhabricatorTokenQuery.php;9cd62bdcc4326a35f9e5dd159a202968ba033dea

Task welcome, I think :) and also patch welcome.

Very well answered @valerio.bozzolan I think you've covered this really well. I'd be willing to help out with making this into a general solution so that it's easy to add more tokens via an extension. We might need to think through the implications of what happens if a token gets removed and also the layout issues, etc. But it is a fairly common request, people often want to customize the list of tokens. Seems worthwhile to make it properly extensible like the other well-utilized and universally appreciated extensible apis. Can anyone think of potential issues that we should consider? Are there other potential foot-guns besides what happens when one is removed or replaced? Should we make them permanent once added? Not actually sure if that's possible, at least it seems impractical to actually enforce.