{"id":15018694,"url":"https://github.com/sof3/infoapi","last_synced_at":"2025-04-07T15:11:05.017Z","repository":{"id":42566069,"uuid":"184870267","full_name":"SOF3/InfoAPI","owner":"SOF3","description":"Placeholder registry and formatting API.","archived":false,"fork":false,"pushed_at":"2025-03-12T05:27:43.000Z","size":7655,"stargazers_count":33,"open_issues_count":3,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-31T11:05:28.171Z","etag":null,"topics":["php","pocketmine-plugin"],"latest_commit_sha":null,"homepage":"https://sof3.github.io/InfoAPI/defaults","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SOF3.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-04T08:29:43.000Z","updated_at":"2025-03-12T05:27:47.000Z","dependencies_parsed_at":"2023-12-01T05:41:45.039Z","dependency_job_id":null,"html_url":"https://github.com/SOF3/InfoAPI","commit_stats":{"total_commits":124,"total_committers":9,"mean_commits":"13.777777777777779","dds":0.2338709677419355,"last_synced_commit":"9998ad5d7a75d47ade93cac68c5278e888bc1edc"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SOF3%2FInfoAPI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SOF3%2FInfoAPI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SOF3%2FInfoAPI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SOF3%2FInfoAPI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SOF3","download_url":"https://codeload.github.com/SOF3/InfoAPI/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247675607,"owners_count":20977378,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["php","pocketmine-plugin"],"created_at":"2024-09-24T19:52:17.660Z","updated_at":"2025-04-07T15:11:04.993Z","avatar_url":"https://github.com/SOF3.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# InfoAPI\n\nExtensible templating for PocketMine plugins.\n\nIn a nutshell, InfoAPI provides a simple API to register placeholders between plugins.\nBut it is more powerful than just that:\n\n- Object-oriented placeholder expressions\n- Continuously update a template when variables change\n- Parametric infos \u0026mdash; mathematical operations on info expressions\n\n## Developer guide: Templating\n\nIf you let users customize messages in a config,\nyou can consider formatting the message with InfoAPI.\n\nPass the config message into InfoAPI:\n\n```php\nuse SOFe\\InfoAPI;\n\n// $this is the plugin main\n$player-\u003esendMessage(InfoAPI::render($this, $this-\u003egetConfig()-\u003eget(\"format\"), [\n    \"arg\" =\u003e $arg,\n], $player));\n```\n\n- \"message\" is the config key for the message template\n- The args array are the base variables for the template.\n  The types of the variables must be one of the default types\n  or provided by another plugin through `InfoAPI::addKind`.\n- `$player` is optional.\n  It tells InfoAPI how to localize the message better,\n  e.g. by formatting for the player's language.\n\n### Advanced: Continuous templating\n\nYou can create a template and watch for changes using the `renderContinuous` API:\n\n```php\nuse SOFe\\AwaitGenerator\\Await;\nuse SOFe\\InfoAPI;\n\nAwait::f2c(function() use($player) {\n    $traverser = InfoAPI::renderContinuous($this, $this-\u003egetConfig()-\u003eget(\"format\"), [\n        \"arg\" =\u003e $arg,\n    ], $player);\n\n    while(yield from $traverser-\u003enext($message)) {\n        $player-\u003esendPopup($message);\n    }\n});\n```\n\n## Developer guide: Register mapping\n\nA mapping converts one info to another,\ne.g. `money` converts a player to the amount of money in `{player money}`.\nYou can register your own mappings\nso that your plugin as well as other plugins using InfoAPI\ncan use this info in the template.\n\nFor example, to provide the money of an online player:\n\n```php\nInfoAPI::addMapping(\n    $this, \"myplugin.money\",\n    fn(Player $player) : ?int =\u003e $this-\u003egetMoney($player),\n);\n```\n\nThe source and return types must be a default or `InfoAPI::addKind` types.\n\n### Advanced: Register continuous mapping\n\nYou can additionally provide a `watchChanges` closure,\nwhich returns a [traverser](https://sof3.github.io/await-generator/master/async-iterators.html)\nthat yields a value when a change is detected.\nThe [pmevent](https://github.com/SOF3/pmevent) library may help\nwith building traversers from events:\n\n```php\nInfoAPI::addMapping(\n    $this, \"myplugin.money\",\n    fn(Player $player) : ?int =\u003e $this-\u003egetMoney($player),\n    watchChanges: fn(Player $player) =\u003e Events::watch(\n        $this, MoneyChangeEvent::class, $player-\u003egetName(),\n        fn(MoneyChangeEvent $event) =\u003e $event-\u003egetPlayer()-\u003egetName(),\n    )-\u003easGenerator(),\n);\n```\n\n## Developer guide: Install InfoAPI\n\n\u003e If you are not developing a plugin,\n\u003e you do **not** need to install InfoAPI yourself.\n\u003e Plugins should have included InfoAPI in their phar release.\n\nInfoAPI v2 is a virion library using virion 3.1.\nVirion 3.1 uses composer to install libraries:\n\n1. Include the InfoAPI virion by adding sof3/infoapi in your composer.json:\n\n```json\n{\n  \"require\": {\n    \"sof3/infoapi\": \"^2\"\n  }\n}\n```\n\n  You can place this file next to your plugin.yml.\n  Installing composer is recommended but not required.\n\n2. Build your plugin with the InfoAPI virion using [pharynx](https://github.com/SOF3/pharynx).\n  You can test it on a server using the custom start.cmd/start.sh provided by pharynx.\n\n3. Use the [pharynx GitHub action](https://github.com/SOf3/timer-pmmp/blob/master/.github/workflows/ci.yml)\n  to integrate with Poggit.\n  Remember to gitignore your vendor directory so that you don't push it to GitHub.\n\n## User guide: Writing a template\n\nInfoAPI replaces expressions inside `{}` with variables.\nFor example, if a chat plugin provides two variables:\n\n- `sender`: the player who sent chat (SOFe)\n- `message`: the chat message\nthe following will become something like `\u003cSOFe\u003e Hello world`\nif the plugin provides `sender` and `message` (\"Hello world\")for the template:\n\n```\n\u003c{sender}\u003e {message}\n```\n\nColor codes are default variables.\nInstead of writing \u0026sect;1 \u0026sect;b etc, you could also write:\n\n```\n{aqua}\u003c{sender}\u003e {white}{message}\n```\n\nYou can get more detailed info for a variable.\nFor example, to get the coordinates of a player `player`:\n\n```\n{player} is at ({player x}, {player y}, {player z}).\n```\n\nWriting `{` directly will cause error without a matching `}`.\nIf you want to write a `{`/`}` that is not part of an expression, write twice instead:\n\n```\nhello {{world}}.\n```\n\nThis will become\n\n```\nhello {world}.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsof3%2Finfoapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsof3%2Finfoapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsof3%2Finfoapi/lists"}