{"id":13469808,"url":"https://github.com/laruence/yar","last_synced_at":"2025-05-14T11:10:33.639Z","repository":{"id":3607790,"uuid":"4672654","full_name":"laruence/yar","owner":"laruence","description":"Light, concurrent RPC framework for PHP \u0026 C","archived":false,"fork":false,"pushed_at":"2025-02-25T05:01:36.000Z","size":674,"stargazers_count":1436,"open_issues_count":38,"forks_count":318,"subscribers_count":140,"default_branch":"master","last_synced_at":"2025-04-11T04:55:27.747Z","etag":null,"topics":["c","concurrency","json","msgpack","php","rpc-framework","yar"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/laruence.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"laruence","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"custom":null}},"created_at":"2012-06-15T07:42:26.000Z","updated_at":"2025-04-10T10:52:43.000Z","dependencies_parsed_at":"2024-06-28T10:26:30.078Z","dependency_job_id":"cccc3607-5805-4efa-b58c-bec9bee9086d","html_url":"https://github.com/laruence/yar","commit_stats":{"total_commits":562,"total_committers":21,"mean_commits":"26.761904761904763","dds":0.08185053380782914,"last_synced_commit":"de347c86da5f6550b437672277f8ff852efbfaf7"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laruence%2Fyar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laruence%2Fyar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laruence%2Fyar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laruence%2Fyar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laruence","download_url":"https://codeload.github.com/laruence/yar/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254129490,"owners_count":22019628,"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":["c","concurrency","json","msgpack","php","rpc-framework","yar"],"created_at":"2024-07-31T16:00:16.803Z","updated_at":"2025-05-14T11:10:33.580Z","avatar_url":"https://github.com/laruence.png","language":"C","funding_links":["https://github.com/sponsors/laruence"],"categories":["C","网站框架","RPC框架"],"sub_categories":[],"readme":"# Yar - Yet Another RPC framework for PHP\n[![Build status](https://ci.appveyor.com/api/projects/status/syhw33wlt2nad64i/branch/master?svg=true)](https://ci.appveyor.com/project/laruence/yar/branch/master) [![Build Status](https://github.com/laruence/yar/workflows/integrate/badge.svg)](https://github.com/laruence/yar/actions?query=workflow%3Aintegrate)\n\nLight, concurrent RPC framework for PHP(see also: [Yar C framework](https://github.com/laruence/yar-c), [Yar Java framework](https://github.com/weibocom/yar-java))\n\n## Requirement\n- PHP 7.0+  (master branch))\n- PHP 5.2+  ([php5 branch](https://github.com/laruence/yar/tree/php5))\n- Curl\n- Json\n- Msgpack (Optional)\n\n## Introduction\n\nYar is a RPC framework which provides a simple and easy way to do communication between PHP applications, it also offers an ability of doing multiple calls to remote services concurrently.\n\n## Features\n- Fast, Easy, Simple\n- Concurrent RPC calls\n- Multiple data packager supported (php, json, msgpack built-in)\n- Multiple transfer protocols supported (http, https, TCP)\n- Detailed debug informations\n\n## Install\n\n### Install Yar \nYar is an PECL extension, could be installed simply by:\n```\npecl install yar\n```\n### Compile Yar in Linux\n```\n$/path/to/phpize\n$./configure --with-php-config=/path/to/php-config/\n$make \u0026\u0026 make install\n```\nAvailable instructions to configure are\n```\n--with-curl=DIR\n--enable(disable)-msgpack\n--enable(disable)-epoll (require Yar 2.1.2)\n```\n\n### Install Yar with msgpack \n\n1. Install msgpack for PHP extension:\n```\npecl install msgpack\n```\nor for ubuntu user\n```\napt-get install msgpack-php\n```\nor , you can get the github source here: https://github.com/msgpack/msgpack-php\n\n2. configuration:\n```\n$phpize\n$configure --with-php-config=/path/to/php-config/ --enable-msgpack\n$make \u0026\u0026 make install\n```\n\n## Runtime Configure\n- yar.timeout  //default 5000 (ms)\n- yar.connect_timeout  //default 1000 (ms)\n- yar.packager  //default \"php\", when built with --enable-msgpack then default \"msgpack\", it should be one of \"php\", \"json\", \"msgpack\"\n- yar.debug    //default Off\n- yar.expose_info // default On, whether output the API info for GET requests\n- yar.content_type // default \"application/octet-stream\"\n- yar.allow_persistent // default Off \n\n*NOTE* yar.connect_time is a value in milliseconds, which was measured in seconds before 1.2.1.\n\n## Constants\n- YAR_VERSION\n- YAR_OPT_PACKAGER\n- YAR_OPT_PERSISTENT\n- YAR_OPT_TIMEOUT\n- YAR_OPT_CONNECT_TIMEOUT\n- YAR_OPT_HEADER // Since 2.0.4\n- YAR_OPT_PROXY //Since 2.2.0\n- YAR_OPT_PROVIDER //Since 2.3.0\n- YAR_OPT_TOKEN //Since 2.3.0\n\n## Server\n\nIt's very easy to setup a Yar HTTP RPC Server\n```php\n\u003c?php\nclass API {\n    /**\n     * the doc info will be generated automatically into service info page.\n     * @params \n     * @return\n     */\n    public function some_method($parameter, $option = \"foo\") {\n    }\n\n    protected function client_can_not_see() {\n    }\n}\n\n$service = new Yar_Server(new API());\n$service-\u003ehandle();\n?\u003e\n```\nUsual RPC calls are issued as HTTP POST requests. \n\nIf a HTTP GET request is issued to the uri(access the api address directly via a browser), the service information (commented section above) will be returned, like:\n\n![yar service info page](https://github.com/laruence/laruence.github.com/raw/master/yar_server.png)\n\n\n### Custom server info\nSince 2.3.0, Yar allows you to custom the output in above example by defining \"__info\" magic method:\n```php\n\u003c?php\nclass API {\n    protected function __info($markup) {\n         return \"Hello world\";\n    }\n}\n```\nthen If a HTTP GET request is issued, \"hello world\" will be sent instead.\n\n### Authentication\nSince 2.3.0, Yar allows server to authentic client request by Provider/Token fileds in header, for achieve this, you should define a protected magic method named \"__auth\" in server side:\n```php\n\u003c?php\nclass API {\n     protected function __auth($provider, $token) {\n          return verify($provider, $token);\n     }\n\n```\n*NOTE* __auth method should always be defined as protected\n\nif a Yar server has __auth defined, then __auth will be called at the very first time for any request,\n\nif __auth method return true, the request will be processed further, otherwise the request will be terminated by an error of \"authentication failed\"\n\nin clent side, you can specific the provider/token by:\n```php\n\u003c?php\n    $client-\u003esetOpt(YAR_OPT_PROVIDER, \"provider\");\n    $client-\u003esetOpt(YAR_OPT_TOKEN, \"token\");\n    $client-\u003ecall();\n```\n\n## Client\nIt's very simple for a PHP client to call remote RPC:\n### Synchronous call\n```php\n\u003c?php\n$client = new Yar_Client(\"http://host/api/\");\n/* the following setopt is optinal */\n$client-\u003eSetOpt(YAR_OPT_CONNECT_TIMEOUT, 1000);\n\n$client-\u003eSetOpt(YAR_OPT_HEADER, array(\"hd1: val\", \"hd2: val\"));  //Custom headers, Since 2.0.4\n\n/* call remote service */\n$result = $client-\u003esome_method(\"parameter\");\n?\u003e\n```\n### Concurrent call\n```php\n\u003c?php\nfunction callback($retval, $callinfo) {\n     var_dump($retval);\n}\n\nfunction error_callback($type, $error, $callinfo) {\n    error_log($error);\n}\n\nYar_Concurrent_Client::call(\"http://host/api/\", \"some_method\", array(\"parameters\"), \"callback\");\nYar_Concurrent_Client::call(\"http://host/api/\", \"some_method\", array(\"parameters\"));   // if the callback is not specificed, \n                                                                               // callback in loop will be used\nYar_Concurrent_Client::call(\"http://host/api/\", \"some_method\", array(\"parameters\"), \"callback\", \"error_callback\", array(YAR_OPT_PACKAGER =\u003e \"json\"));\n                                                                               //this server accept json packager\nYar_Concurrent_Client::call(\"http://host/api/\", \"some_method\", array(\"parameters\"), \"callback\", \"error_callback\", array(YAR_OPT_TIMEOUT=\u003e1));\n                                                                               //custom timeout \n \nYar_Concurrent_Client::loop(\"callback\", \"error_callback\"); //send the requests, \n                                                           //the error_callback is optional\n?\u003e\n```\n### Persistent call\nAfter Yar 2.1.0, if YAR_OPT_PERSISTENT is set to true, then Yar is able to use HTTP keep-alive to speedup repeated calls to a same address, the link will be released at the end of the PHP request lifecycle.\n```php\n\u003c?php\n$client = new Yar_Client(\"http://host/api/\");\n$client-\u003eSetOpt(YAR_OPT_PERSISTENT, 1);\n\n$result = $client-\u003esome_method(\"parameter\");\n\n/* The following calls will speed up due to keep-alive */\n$result = $client-\u003esome_other_method1(\"parameter\");\n$result = $client-\u003esome_other_method2(\"parameter\");\n$result = $client-\u003esome_other_method3(\"parameter\");\n?\u003e\n```\n### Custom hostname resolving\nAfter Yar 2.1.0, if Yar runs on HTTP protocol, YAR_OPT_RESOLVE could be used to define custom hostname resolving.\n```php\n\u003c?php\n$client = new Yar_Client(\"http://host/api/\");\n\n$client-\u003eSetOpt(YAR_OPT_RESOLVE, array(\"host:80:127.0.0.1\"));\n\n/* call goes to 127.0.0.1 */\n$result = $client-\u003esome_method(\"parameter\");\n```\n\n### Use http proxy\nAfter Yar 2.2.1, if Yar runs on HTTP protocol, YAR_OPT_PROXY could be used to define http proxy , such as fidder or charles.\n\n```php\n\u003c?php\n$client = new Yar_Client(\"http://host/api/\");\n\n$client-\u003eSetOpt(YAR_OPT_PROXY,\"127.0.0.1:8888\"); //http proxy , Since 2.2.0\n\n/* call goes to 127.0.0.1 */\n$result = $client-\u003esome_method(\"parameter\"); \n```\n\n## Protocols\n### Yar Header\n\nYar is no only designed for PHP only, all RPC request and response are transferred by binary data stream.\n\nKey messages are exchanged by a struct called \"Yar Header\":\n```C\n#ifdef PHP_WIN32\n#pragma pack(push)\n#pragma pack(1)\n#endif\ntypedef struct _yar_header {\n    uint32_t       id;            // transaction id\n    uint16_t       version;       // protocol version\n    uint32_t       magic_num;     // default is: 0x80DFEC60\n    uint32_t       reserved;\n    unsigned char  provider[32];  // reqeust from who\n    unsigned char  token[32];     // request token, used for authentication\n    uint32_t       body_len;      // request body len\n}\n#ifndef PHP_WIN32\n__attribute__ ((packed))\n#endif\nyar_header_t;\n#ifdef PHP_WIN32\n#pragma pack(pop)\n#endif\n````\n### Packager Header\nYar also supports multi packager protocols,  which is a char[8] before the header struct, to identicate which packager the body is packaged by.\n\n### Request \nWhen a Client do an RPC request ,  the request is sent as an array(in PHP) like:\n```php\n\u003c?php\narray(\n   \"i\" =\u003e '', //transaction id\n   \"m\" =\u003e '', //the method which being called\n   \"p\" =\u003e array(), //parameters\n)\n```\n\n### Server\nWhen a server responses,  the response is sent also as an array (in PHP) like:\n```php\n\u003c?php\narray(\n   \"i\" =\u003e '',\n   \"s\" =\u003e '', //status\n   \"r\" =\u003e '', //return value \n   \"o\" =\u003e '', //output \n   \"e\" =\u003e '', //error or exception\n)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaruence%2Fyar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaruence%2Fyar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaruence%2Fyar/lists"}