{"id":15144031,"url":"https://github.com/colinhdev/libasyncevent","last_synced_at":"2025-10-23T20:31:23.147Z","repository":{"id":62549443,"uuid":"458519104","full_name":"ColinHDev/libAsyncEvent","owner":"ColinHDev","description":"Simple implementation for creating asynchronous event execution for PocketMine-MP plugins.","archived":false,"fork":false,"pushed_at":"2024-08-23T01:30:22.000Z","size":55,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-30T21:01:37.342Z","etag":null,"topics":["async-event","event","php","pocketmine-plugins","poggit-virion","virion"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ColinHDev.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2022-02-12T12:44:15.000Z","updated_at":"2024-09-05T14:35:57.000Z","dependencies_parsed_at":"2024-08-23T02:48:39.589Z","dependency_job_id":null,"html_url":"https://github.com/ColinHDev/libAsyncEvent","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColinHDev%2FlibAsyncEvent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColinHDev%2FlibAsyncEvent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColinHDev%2FlibAsyncEvent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColinHDev%2FlibAsyncEvent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ColinHDev","download_url":"https://codeload.github.com/ColinHDev/libAsyncEvent/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237882172,"owners_count":19381176,"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":["async-event","event","php","pocketmine-plugins","poggit-virion","virion"],"created_at":"2024-09-26T10:21:12.516Z","updated_at":"2025-10-23T20:31:17.857Z","avatar_url":"https://github.com/ColinHDev.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# libAsyncEvent\n\nlibAsyncEvent provides you with multiple implementations for creating asynchronous event execution for PocketMine-MP \nplugins.\n\n## Why should I use this library?\nI came to the idea for this library while implementing [libasynql](https://github.com/poggit/libasynql) and \n[await-generator](https://github.com/SOF3/await-generator) to my plugin [CPlot](https://github.com/ColinHDev/CPlot). I \nthen realised how annoying it is, to deal with [PocketMine-MP's](https://github.com/pmmp/PocketMine-MP) events in this \ncase, since it is not possible e.g. to check if a player is allowed to build in a certain area with an asynchronous-run \nquery.\n\nSo when deciding to implement custom events into the plugin, I wanted to make it as developer-friendly as possible. So \nwhen someone decides to work with the events, they are not forced to directly decide, how to react (e.g. cancelling the \nevent) and be allowed e.g. to run asynchronous queries to validate their decision.\n\n## How to use this library in my plugin?\n### How should my event class look like?\nNormally your event class looks like this: It extends PocketMine-MP's `Event` class or one of its subclasses and maybe \nalso implements an interface like the `Cancellable` one.\n```php\nuse pocketmine\\event\\Event;\nuse pocketmine\\event\\Cancellable;\n\nclass MyEvent extends Event implements Cancellable {}\n```\nFirst, implement the `AsyncEvent` interface, which this library provides, to your event class.\nAnd second, use one of the `EventHandlerExecutionTrait`s in your event class:\n```php\nuse ColinHDev\\libAsyncEvent\\AsyncEvent;\nuse ColinHDev\\libAsyncEvent\\SomeEventHandlerExecutionTrait;\nuse pocketmine\\event\\Event;\nuse pocketmine\\event\\Cancellable;\n\nclass MyEvent extends Event implements AsyncEvent, Cancellable {\n    use SomeEventHandlerExecutionTrait;\n}\n```\nThere are multiple `EventHandlerExecutionTrait`s, which you can use and each of them has a different behaviour:\n- `ConsecutiveEventHandlerExecutionTrait`: This trait will execute all event listeners one after another. If one \n`block()`s the execution, the next listener will only be executed after the current one calls `release()`.\n- `PriorityEventHandlerExecutionTrait`: This trait will execute all event listeners of the same priority at the same \ntime. If one or more listeners `block()` the execution, the listeners of the higher priority will only be executed after\nall of the `block()`ing ones called `release()`.\n\n### How can I call my event?\nYou can simply call your event by creating a new event instance and using its `call()` method.\n```php\n$event = new MyEvent();\n$event-\u003ecall();\n```\nBut to get the result of the event, you need to provide a callback function which will be run when all listeners are finished.\n```php\n$event = new MyEvent();\n$event-\u003esetCallback(\n    function (MyEvent $event) : void {\n        if ($event-\u003eisCancelled()) {\n            // do something\n        } else {\n            // do something else\n        }\n    }\n);\n$event-\u003ecall();\n```\n\n### How to improve my event class?\nUnless both you and the person trying to register a listener for your async event use composer, they will not be able to\ncorrectly see libAsyncEvent's declared methods like `block()` or `release()` in their IDE.\n\nAlthough ideally composer should be used to develop plugins and to declare their dependencies, we can not force anyone \nto do so. So to make it easier for them, you can add following PHPDoc comments to your event class:\n```php\n/**\n * @link https://github.com/ColinHDev/libAsyncEvent/\n * @method void block()\n * @method void release()\n */\nclass MyEvent extends Event implements AsyncEvent, Cancellable {}\n```\nThis way, the IDE will know that these methods exist and will not show any errors.\n\n## How to handle an event made with this library?\nTo register an event listener for an async event, you can do it the same way, you would normally do it for every other event listener:\n```php\nServer::getInstance()-\u003egetPluginManager()-\u003eregisterEvents(new MyListener(), $this);\n```\nIn this class, you as well create a method which accepts the event, you want to listen to, as a parameter:\n```php\n    public function onMyEvent(MyEvent $event) : void {\n        // do something\n    }\n```\nSo basically there is no difference between a normal event listener and our async event listener.\nBut if you want to keep the event instance from continuing with its execution, you need to call the `block()` method.\nThis way the event won't finish its execution until you call the `release()` method.\n```php\n    public function onMyEvent(MyEvent $event) : void {\n        // some synchronous logic here\n        $event-\u003eblock();\n        // some asynchronous logic here\n        $event-\u003erelease();\n    }\n```\nIf you accidentally forget to call the `release()` method, an exception will be thrown once the event instance is \ndestroyed by the garbage collector.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolinhdev%2Flibasyncevent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcolinhdev%2Flibasyncevent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcolinhdev%2Flibasyncevent/lists"}