{"id":13699931,"url":"https://github.com/distantmagic/resonance","last_synced_at":"2025-05-16T06:07:37.308Z","repository":{"id":203405958,"uuid":"701729734","full_name":"distantmagic/resonance","owner":"distantmagic","description":"PHP Framework designed to build IO-intensive web applications.","archived":false,"fork":false,"pushed_at":"2024-12-12T17:24:02.000Z","size":2985,"stargazers_count":220,"open_issues_count":0,"forks_count":13,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-05-14T16:48:44.858Z","etag":null,"topics":["ai","framework","llamacpp","llm","php","swoole"],"latest_commit_sha":null,"homepage":"http://resonance.distantmagic.com/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/distantmagic.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":"2023-10-07T11:53:23.000Z","updated_at":"2025-05-05T18:55:50.000Z","dependencies_parsed_at":"2024-05-01T03:23:16.662Z","dependency_job_id":"4b745e32-cad6-435d-9758-f23329ca9a51","html_url":"https://github.com/distantmagic/resonance","commit_stats":{"total_commits":568,"total_committers":4,"mean_commits":142.0,"dds":0.01936619718309862,"last_synced_commit":"1fac4c21be84a782a6d4d2e77c0e70f1c6116aa0"},"previous_names":["distantmagic/resonance"],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/distantmagic%2Fresonance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/distantmagic%2Fresonance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/distantmagic%2Fresonance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/distantmagic%2Fresonance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/distantmagic","download_url":"https://codeload.github.com/distantmagic/resonance/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254478193,"owners_count":22077676,"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":["ai","framework","llamacpp","llm","php","swoole"],"created_at":"2024-08-02T20:00:46.022Z","updated_at":"2025-05-16T06:07:32.280Z","avatar_url":"https://github.com/distantmagic.png","language":"PHP","funding_links":[],"categories":["Interop \u0026 Model Serving","Frameworks","LLM Frameworks"],"sub_categories":["Tokenizers \u0026 Prompt Utilities"],"readme":"# Resonance\n\n## About Resonance\n\nResonance is designed from the ground up to facilitate interoperability and messaging between services in your infrastructure and beyond. It provides AI capabilities, has a built in web server and integrates with [llama.cpp](https://github.com/ggerganov/llama.cpp).\n\nTakes full advantage of asynchronous PHP. Built on top of Swoole.\n\n## Why Resonance?\n\n### Predictable Performance\n\nResonance is designed with a few priorities: no memory leaks, blocking operations, and garbage collector surprises.\n\nMost of the internals are read-only and stateless. After the application startup, nothing disturbs JIT and opcode (Reflection is only used during the application startup), so there are no surprise slowdowns during runtime.\n\n### Opinionated\n\nAll the libraries under the hood have been thoroughly tested to ensure they work together correctly, complement each other, and work perfectly under async environments.\n\nFor example, Resonance implements custom \u003ca href=\"https://www.doctrine-project.org/\"\u003eDoctrine\u003c/a\u003e drivers, so it uses Swoole's connection pools.\n\n### Resolves Input/Output Issues\n\nResonance is designed to handle IO-intensive tasks, such as serving Machine Learning models, handling WebSocket connections, and processing long-running HTTP requests.\n\nIt views modern applications as a mix of services that communicate with each other asynchronously, including AI completions and ML inferences, so it provides a set of tools to make this communication as easy as possible.\n\n### Complete Package\n\nResonance includes everything you need to build a modern web application, from the HTTP server to the AI capabilities.\n\nIt provides security features, HTML templating, integration with open-source LLMs, and provides capability to serve ML models.\n\n## Documentation\n\nhttps://resonance.distantmagic.com/\n\n## Installation\n\nIt's best to install Resonance by using Composer's create-project command:\n\n```php\ncomposer create-project distantmagic/resonance-project my-project\n```\n\nResonance requires minimum 8.2 version of PHP, as well as Data Structures and Swoole extensions. Read more about required and recommended extensions, as well as other installation methods in our [installation guide](https://resonance.distantmagic.com/docs/getting-started/installation-and-requirements.html).\n\n### First-time use\n\nYou'll need to create a `config.ini` file after installing the project (`config.ini.example` is provided) and then use `bin/resonance.php` as an entry point.\n\n### Running the server\n\n`php bin/resonance.php` serve starts the built-in HTTP server. If you need to, you can generate the [SSL Certificate for Local Development](https://resonance.distantmagic.com/docs/extras/ssl-certificate-for-local-development/).\n\n## Features\n\n### Chat with Open-Source LLMs\n\nCreate prompt controllers to directly answer user's prompts.\n\nLLM takes care of determining user's intention, you can focus on taking an \nappropriate action.\n\n```php\n#[RespondsToPromptSubject(\n    action: 'adopt',\n    subject: 'cat',\n)]\n#[Singleton(collection: SingletonCollection::PromptSubjectResponder)]\nreadonly class CatAdopt implements PromptSubjectResponderInterface\n{\n    public function respondToPromptSubject(PromptSubjectRequest $request, PromptSubjectResponse $response): void\n    {\n        // Pipes message through WebSocket... \n\n        $response-\u003ewrite(\"Here you go:\\n\\n\");\n        $response-\u003ewrite(\"   |\\_._/|\\n\");\n        $response-\u003ewrite(\"   | o o |\\n\");\n        $response-\u003ewrite(\"   (  T  )\\n\");\n        $response-\u003ewrite(\"  .^`-^-`^.\\n\");\n        $response-\u003ewrite(\"  `.  ;  .`\\n\");\n        $response-\u003ewrite(\"  | | | | |\\n\");\n        $response-\u003ewrite(\" ((_((|))_))\\n\");\n        $response-\u003eend();\n    }\n}\n```\n\n### Asynchronous Where it Matters\n\nRespond asynchronously to incoming RPC or WebSocket\nmessages (or both combined) with little overhead.\n\nYou can set up all the asynchronous features using\nattributes. No elaborate configuration is needed.\n\n```php\n#[RespondsToWebSocketJsonRPC(JsonRPCMethod::Echo)]\n#[Singleton(collection: SingletonCollection::WebSocketJsonRPCResponder)]\nfinal readonly class EchoResponder extends WebSocketJsonJsonRPCResponder\n{\n    public function getConstraint(): Constraint\n    {\n        return new StringConstraint();\n    }\n\n    public function onRequest(\n        WebSocketAuthResolution $webSocketAuthResolution,\n        WebSocketConnection $webSocketConnection,\n        RPCRequest $rpcRequest,\n    ): void {\n        $webSocketConnection-\u003epush(new JsonRPCResponse(\n            $rpcRequest,\n            $rpcRequest-\u003epayload,\n        ));\n    }\n}\n```\n\n### Simple Things Remain Simple\n\nWriting HTTP controllers is similar to how it's done in \nthe synchronous code.\n\nControllers have new exciting features that take \nadvantage of the asynchronous environment.\n\n```php\n#[RespondsToHttp(\n    method: RequestMethod::GET,\n    pattern: '/',\n)]\nfunction Homepage(ServerRequestInterface $request, ResponseInterface $response): TwigTemplate\n{\n    return new TwigTemplate('website/homepage.twig');\n}\n```\n\n### Consistency is Key\n\nYou can keep the same approach to writing software \nno matter the size of your project.\n\nThere are no growing central configuration files \nor service dependencies registries. Every relation \nbetween code modules is local to those modules.\n\n```php\n#[ListensTo(HttpServerStarted::class)]\n#[Singleton(collection: SingletonCollection::EventListener)]\nfinal readonly class InitializeErrorReporting extends EventListener\n{\n    public function handle(object $event): void\n    {\n        // ...\n    }\n}\n```\n\n### Promises in PHP\n\nResonance provides a partial implementation of \nPromise/A+ spec to handle various asynchronous tasks.\n\n```php\n$future1 = new SwooleFuture(function (int $value) {\n    assert($value === 1);\n\n    return $value + 2;\n});\n\n$future2 = $future1-\u003ethen(new SwooleFuture(function (int $value) {\n    assert($value === 3);\n\n    return $value + 4;\n}));\n\nassert($future2-\u003eresolve(1)-\u003eresult === 7);\n```\n\n### GraphQL Out of the Box\n\nYou can build elaborate GraphQL schemas by using just \nthe PHP attributes.\n\nResonance takes care of reusing SQL queries and \noptimizing the resources' usage.\n\nAll fields can be resolved asynchronously.\n\n```php\n#[GraphQLRootField(\n    name: 'blogPosts',\n    type: GraphQLRootFieldType::Query,\n)]\n#[Singleton(collection: SingletonCollection::GraphQLRootField)]\nfinal readonly class Blog implements GraphQLFieldableInterface\n{\n    public function __construct(\n        private DatabaseConnectionPoolRepository $connectionPool,\n        private BlogPostType $blogPostType,\n    ) {}\n\n    public function resolve(): GraphQLReusableDatabaseQueryInterface\n    {\n        return new SelectBlogPosts($this-\u003econnectionPool);\n    }\n\n    public function toGraphQLField(): array\n    {\n        return [\n            'type' =\u003e new ListOfType($this-\u003eblogPostType),\n            'resolve' =\u003e $this-\u003eresolve(...),\n        ];\n    }\n}\n```\n\n## Tutorials\n\n* ['Hello, World' with Resonance](https://resonance.distantmagic.com/tutorials/hello-world/)\n* [Session-Based Authentication](https://resonance.distantmagic.com/tutorials/session-based-authentication/)\n* [Building a Basic GraphQL Schema](https://resonance.distantmagic.com/tutorials/basic-graphql-schema/)\n* [How to Serve LLM Completions (With llama.cpp)?](https://resonance.distantmagic.com/tutorials/how-to-serve-llm-completions/)\n* [How to Create LLM WebSocket Chat with llama.cpp?](https://resonance.distantmagic.com/tutorials/how-to-create-llm-websocket-chat-with-llama-cpp/)\n* [Semi-Scripted Conversational Applications](https://resonance.distantmagic.com/tutorials/semi-scripted-conversational-applications/)\n\n## Community\n\nFeel free to use [GitHub discussions](https://github.com/distantmagic/resonance/discussions) and other pages related to the repository.\n  \n## License\n\nThe Resonance framework is open-sourced software licensed under the \n[MIT license](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdistantmagic%2Fresonance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdistantmagic%2Fresonance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdistantmagic%2Fresonance/lists"}