Light, concurrent RPC framework for PHP & C
C PHP M4 Other
Latest commit 0ff9df3 Jul 2, 2016 @laruence back to dev
Permalink
Failed to load latest commit information.
packagers php7 support Feb 12, 2015
tests Add tests for comments May 5, 2016
tools Ass shebang Jun 12, 2015
transports Fixed printing Aug 27, 2015
travis Add Travis Aug 26, 2012
.gitignore Initial commit Jun 15, 2012
.travis.yml update travis Oct 27, 2015
CREDITS Fixed windows build Jun 24, 2015
EXPERIMENTAL change name to Yar , and merge some new changes Jun 19, 2012
LICENSE Fixed ISSUE #6 Add License file Jul 21, 2013
README.md Update README.md Oct 29, 2015
config.m4 Add build dir Sep 8, 2015
config.w32 Fix config.* Jan 2, 2014
package2.xml preparing for 2.0.1 Jul 2, 2016
php_yar.h back to dev Jul 2, 2016
yar.c fix mem leaks of module transport Sep 14, 2015
yar.php change name to Yar , and merge some new changes Jun 19, 2012
yar_client.c Fixed printing Aug 27, 2015
yar_client.h Merge branch 'php7' of https://github.com/zxcvdavid/yar into php7 Feb 13, 2015
yar_exception.c Merge branch 'master' into php7 May 2, 2016
yar_exception.h Cleanup Feb 26, 2015
yar_packager.c Fixing things Feb 26, 2015
yar_packager.h Fixing things Feb 26, 2015
yar_protocol.c php7 support Feb 12, 2015
yar_protocol.h php7 support Feb 12, 2015
yar_request.c Fixing things Feb 26, 2015
yar_request.h Fixed issue #56 (Failed test with PHP 7.0.0beta2 / 32bits) Jul 24, 2015
yar_response.c Fixed memleaks Feb 26, 2015
yar_response.h Cleanup Feb 26, 2015
yar_server.c fix for PHP 7.1 Jun 11, 2016
yar_server.h Refactor Yar, make the arch more clear for the persistent link Jan 8, 2013
yar_transport.c restore le_plink Feb 26, 2015
yar_transport.h Cleanup Feb 26, 2015
yar_transports.h php7 support Feb 12, 2015

README.md

Yar - Yet Another RPC framework for PHP

Build Status

Light, concurrent RPC framework for PHP(c, java etc will be supported soon)

Requirement

  • PHP 5.2+
  • Curl
  • Json
  • Msgpack (Optional)

Introduction

Yar is a RPC framework which aims to provide a simple and easy way to do communication between PHP applications

It has the ability to concurrently call multiple remote services.

Features

  • Fast, Easy, Simple
  • Concurrent RPC calls
  • Multiple data packager supported (php, json, msgpack built-in)
  • Multiple transfer protocols supported (http implemented, tcp/unix will be supported later)
  • Detailed debug informations

Install

Install Yar

Yar is an PECL extension, thus you can simply install it by:

pecl install yar

Compile Yar in Linux

$/path/to/phpize
$./configure --with-php-config=/path/to/php-config/
$make && make install

Install Yar with msgpack

first you should install msgpack-ext

pecl install msgpack

or , you can get the github source here: https://github.com/msgpack/msgpack-php

then:

$phpize
$configure --with-php-config=/path/to/php-config/ --enable-msgpack
$make && make install

Runtime Configure

  • yar.timeout //default 5000 (ms)
  • yar.connect_timeout //default 1000 (ms)
  • yar.packager //default "php", when built with --enable-msgpack then default "msgpack", it should be one of "php", "json", "msgpack"
  • yar.debug //default Off
  • yar.expose_info // default On, whether output the API info for GET requests
  • yar.content_type // default "application/octet-stream"
  • yar.allow_persistent // default Off

NOTE yar.connect_time is a value in milliseconds, and was measured in seconds in 1.2.1 and before.

Constants

  • YAR_VERSION
  • YAR_OPT_PACKAGER
  • YAR_OPT_PERSISTENT
  • YAR_OPT_TIMEOUT
  • YAR_OPT_CONNECT_TIMEOUT

Server

It's very easy to setup a Yar HTTP RPC Server

<?php
class API {
    /**
     * the doc info will be generated automatically into service info page.
     * @params 
     * @return
     */
    public function some_method($parameter, $option = "foo") {
    }

    protected function client_can_not_see() {
    }
}

$service = new Yar_Server(new API());
$service->handle();
?>

Usual RPC calls will be issued as HTTP POST requests. If a HTTP GET request is issued to the uri, the service information (commented section above) will be printed on the page:

yar service info page

Client

It's very easy for a PHP client to call remote RPC:

Synchronous call

<?php
$client = new Yar_Client("http://host/api/");
/* the following setopt is optinal */
$client->SetOpt(YAR_OPT_CONNECT_TIMEOUT, 1000);

/* call remote service */
$result = $client->some_method("parameter");
?>

Concurrent call

<?php
function callback($retval, $callinfo) {
     var_dump($retval);
}

function error_callback($type, $error, $callinfo) {
    error_log($error);
}

Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback");
Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"));   // if the callback is not specificed, 
                                                                               // callback in loop will be used
Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", "error_callback", array(YAR_OPT_PACKAGER => "json"));
                                                                               //this server accept json packager
Yar_Concurrent_Client::call("http://host/api/", "some_method", array("parameters"), "callback", "error_callback", array(YAR_OPT_TIMEOUT=>1));
                                                                               //custom timeout 

Yar_Concurrent_Client::loop("callback", "error_callback"); //send the requests, 
                                                           //the error_callback is optional
?>

Protocols

Yar Header

Since Yar will support multi transfer protocols, so there is a Header struct, I call it Yar Header

#ifdef PHP_WIN32
#pragma pack(push)
#pragma pack(1)
#endif
typedef struct _yar_header {
    unsigned int   id;            // transaction id
    unsigned short version;       // protocl version
    unsigned int   magic_num;     // default is: 0x80DFEC60
    unsigned int   reserved;
    unsigned char  provider[32];  // reqeust from who
    unsigned char  token[32];     // request token, used for authentication
    unsigned int   body_len;      // request body len
}
#ifndef PHP_WIN32
__attribute__ ((packed))
#endif
yar_header_t;
#ifdef PHP_WIN32
#pragma pack(pop)
#endif

Packager Header

Since Yar also supports multi packager protocl, so there is a char[8] at the begining of body, to identicate which packager the body is packaged by.

Request

When a Client request a remote server, it will send a struct (in PHP):

<?php
array(
   "i" => '', //transaction id
   "m" => '', //the method which being called
   "p" => array(), //parameters
)

Server

When a server response a result, it will send a struct (in PHP):

<?php
array(
   "i" => '',
   "s" => '', //status
   "r" => '', //return value 
   "o" => '', //output 
   "e" => '', //error or exception
)