Implement APIs

phprs use @annotation to define routes, bind parameters and manage dependencies.

• Class annotations
  • @path
• Method annotations
  • @route
  • @param
  • @return
  • @throws
  • @cache
• Property annotations
  • @property
  • @inject

Class annotations

@path

Required

Examples:

@path("/myapi")

Specify that all /myapi/* will route to this class. Matching is begin from root of the path by default, or set url_begin in conf.json

{
    "phprs\\Router": {
        "properties": {
            "url_begin":1 // if url is "/abc/123", then 1st path node "/abc/" will be ignored.
        } 
    }
}

Method annotations

@route

Define routes

If more than one route matching, only the precised route will be matched.

An method can contain more than one @route

Required

Examples:

@route({"GET", "func1"})

Match GET /myapi/func1 or GET /myapi/func1/xxxx

@route({"GET", "func1"， true})

Strict route, match GET /myapi/func1, not match /myapi/func1/xxxx

@route({"*", "func1"})

Match /myapi/func1 with all http methods

@route({"GET", "func1?param1=xxx&param2=123"})

Match GET /myapi/func1?param1=xxx&param2=123 or /myapi/func1?param2=123&param=xxx

@route({"GET", "patha/*"})

Match GET /myapi/patha/*， such as /myapi/patha/123, but not match /myapi/patha/

@route({"GET", "patha/*/pathb"})

Match GET /myapi/patha/*/pathb

@route({"GET", "resources/type1"}) @route({"GET", "resources/type2"}) @route({"GET", "resources/type3"})

Means any of those route can dispatch this function

@param

Two-way parameter binding with jsonpath, use $. to bind any variables of $GLOBALS

1. Bind parameters. If parameter not given and no default specified, BadRequest will be caused.

   /**
    * @route({"GET","/test"})
    * @param({"arg0","$._GET.arg0"})
    * @param({"arg1","$._GET.arg1"})
    */
   function public test($arg0, $arg1=null){
   }

   In this sample GET /test will cause BadRequest because "arg0" not given, and GET /test?arg0=1 will ok with default "arg1".

2. Output with reference param binding

   /**
    * @route({"GET","/test"})
    * @return({"cookie","token", "$token_val"})
    */
   function public test(&token_val){
       $token_val = 'xxxx';
   }

   in test()， assign $token_val will change "token" in cookies.

required(if method has params)

Examples:

@param({"arg0","$.path[1]"})

$.path is used for get path as array, for example, for path "/myapi/abc/123", arg0 is "abc"

@param({"arg1","123"})

specify $arg1 to const string "123"

@return

Bind return

If no @return, the return of function will bind to http body

By default array return will be json_encode to json string

Optional

Examples:

@return({"output_func", "$arg1","$arg2"...})

general form, output_func is the out put function(can be "body","res","status","header","cookie"), $arg1, $arg2 is the params of output_func, and must be reference or constant.

@return({"body"})

Output return of function as http body

@return({"body", "$arg0"})

Output value of $arg0 as http body

@return({"cookie", "$name", "$value", "$expire" })

Output cookie, as setcookie ( string $name [, string $value [, int $expire = 0 [, string $path [, string $domain [, bool $secure = false [, bool $httponly = false ]]]]]] )

@return({"header", "$name", "$value", "$expire" })

Output header, as void header ( string $string [, bool $replace = true [, int $http_response_code ]] )

@return({"status", "200 OK" })

Output http status code

@return({"res", "200 OK", {"res":"ok"} })

Output http status code + body

@throws

Bind throws

Optional

Examples:

@throws({"MyException","output_fun", "arg0", "arg1"})

Bind MyException or its subclass, the output_fun is same as @return, params can only be constant.

@throws({"NotFoundException", "res", "404 Not Found",{"msg":"something wrong"}})

If NotFoundException, then output "404 Not Found".

@cache

Enable cache for this method. If all params of the method are identical, the following calls will use cache.

Optional

Examples:

@cache({"ttl", 3600})

Use ttl

@cache({"check", "$check"})

Use dynamic strategy to check caches. $check is set in method, and will be invoked to check cache expired with $check($data, $create_time), for examples use $check = new FileExpiredChecker('file.tmp'); to make cache invalidated if file.tmp modified.

PHRRS use APC by default, to use other cache implement, see：

{
    ...

    "phprs\\Invoker": {
        "properties": {
        "cache":"@invokeCache"// 1.use the instance of invokeCache
        }
    },
     //2. define the instance 
    "invokeCache":{
        "class":"phprs\\util\\RedisCache",
        "singleton":true,
        "properties":{
            "serialize":true,
            "host":"127.0.0.1",
            "port":"6379"
        }
    },

    ...
}

Property annotations

@property

Set properties from config by IoCFactory.

**properties are set before ** __construct(), so can be accessed in __construct

Optional

Examples:

/** @property */
private $name;

$name is a required property.

/** @property */
private $name='value';

$name is a optional property with default value.

/** @property({"optional":true}) */
private $name;

$name is a optional property without default value.

@inject

Inject internal object of phprs.

Optional

Examples:

/** @inject("$.path[0]") */
private $app_name;

/** @inject("$.factory") inject the owner IoCFactory*/
private $factory;