Support for method parameter annotations

[sburba]

Is there interest in the library in supporting annotations tied to method parameters? I think there are several cases where annotating method parameters would be useful for library developers. Below is one example, providing luracast/restler-like functionality of annotating parameters to indicate where they come from in the HTTP request. In that example, the @From annotations would be returned in an API to fetch parameter annotations, which would include information about the parameter they are attached to.

This is a provisional syntax proposal, I'm not tied to a specific syntax

/**
 * @Path("GET", "/accounts/{id}/users")
 *
 * @param int $id The account id {@From("url")}
 * @param bool $include_inactive If true, response includes inactive users {@From("query")}
 */
function (int $id, bool $include_inactive) {
    //...
}

I would be interested in doing the work, but only if that's a direction the library is interested in supporting.

There are a few complications, we'd have to enhance the parser to keep track of a little more context so it could be aware of where it's finding the annotations. There's also the matter of deciding what locations for annotations count as attached to parameters and what ones don't. I would propose anything between a @param and an empty newline counts as attached to a parameter, but am open to suggestions.

The provisional syntax I've proposed above would already be compatible with existing IDE tooling, so at least there's little danger of breakage there.

[Ocramius]

I'd probably use a syntax like following, rather than coupling the existing docblock with the parameters (very error prone).

public function foo(/** @Inject */ Bar $bar)

On Sat, 17 Nov 2018, 14:48 Sam Burba <[email protected] wrote:

Is there interest in the library in supporting annotations tied to method parameters? I think there are several cases where annotating method parameters would be useful for library developers. Below is one example, providing luracast/restler-like functionality of annotating parameters to indicate where they come from in the HTTP request. In that example, the @From annotations would be returned in an API to fetch parameter annotations, which would include information about the parameter they are attached to.

This is a provisional syntax proposal, I'm not tied to a specific syntax

/** * @Path("GET", "/accounts/{id}/users") * * @param int $id The account id {@From("url")} * @param bool $include_inactive If true, response includes inactive users {@From("query")} */function (int $id, bool $include_inactive) { //...}

I would be interested in doing the work, but only if that's a direction the library is interested in supporting.

There are a few complications, we'd have to enhance the parser to keep track of a little more context so it could be aware of where it's finding the annotations. There's also the matter of deciding what locations for annotations count as attached to parameters and what ones don't. I would propose anything between a @param https://github.com/param and an empty newline counts as attached to a parameter, but am open to suggestions.

The provisional syntax I've proposed above would already be compatible with existing IDE tooling, so at least there's little danger of breakage there.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/doctrine/annotations/issues/227, or mute the thread https://github.com/notifications/unsubscribe-auth/AAJakCxLc-kFddDo_dAALzWtZLv-CFVZks5uwBO_gaJpZM4YndW0 .

[sburba]

Hmm, is there a reflection API that provides access to comments in that place? I can't find one myself. I suppose we could parse the entire file but that seems even more dangerous

[Ocramius]

None of that, sorry

On Sun, 25 Nov 2018, 19:58 Sam Burba <[email protected] wrote:

Hmm, is there a reflection API that provides access to comments in that place?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/doctrine/annotations/issues/227#issuecomment-441463518, or mute the thread https://github.com/notifications/unsubscribe-auth/AAJakLK4D5WnG629j9cjGPnC0ZitT-9Nks5uyug9gaJpZM4YndW0 .

[Majkl578]

I like the syntax proposal from @Ocramius:

public function foo(/** @Inject */ Bar $bar)

But as it's not reflectable, we can't support it out of box only by using reflection. We may support parsing of arbitrary annotations (given a docBlock string and context [i.e. use statements), you get a list of annotations) in 2.0, but this will be internal stuff. It's very unlikely it'd be exposed in public (or semi-public) API, unless we find some common denominator for Reflection-based and parser-based context.

[sburba]

So am I correct in interpreting this response as this project is not interested in PRs that would provide this functionality in any of the forms mentioned above?

Thanks for the heads up. I understand the reasoning.

[Majkl578]

There is one thing you can do: add support for doc comment reflection for function parameters directly in PHP's reflection. 👍

[Ocramius]

It can still be done by (very inefficiency) parsing the entire file. This is done by annotations already, in order to detect use and namespace statements, but the impact is massive.

[witchi]

I have add this functionality to https://github.com/witchi/annotations. You can use it like:

// you need a ReflectionMethod instance of the annotated method
$c = new ClassWithMethodParameterAnnotation();
$reflectionClass = \ReflectionClass($c);
$reflectionMethod = $reflectionClass->getMethod("testFunction");

// now you can parse the class file, which contains the method
// this will result in a list of the method parameters
// you can't use $reflectionMethod->getParameters(), because it won't return the DocComments
$p = new PhpParser();
$reflectionParameters = $p->getParameters($reflectionMethod);

// now you can use the ReflectionParameter instances within the AnnotationReader
$reader = new AnnotationReader();
foreach($reflectionParameters as $param) {
    error_log(print_r($reader->getParameterAnnotations($param), true));
}

There is a lot of space to optimize the code. So you could include the PhpParser call into the AnnotationReader and also you could change the parser a bit to return only the DocComment for a given parameter instead all parameters. Unfortunately I don't have PHP7.1 to test the code, but I have integrated it into the version 1.2.7 (for PHP5) and it seems to work (with gentle modifications). Hope it helps. I use the code to define in a Rest-Api, which method parameter will get which HTTP request value (@QueryParam for paging parameters, @CookieParam for assignments of Cookie values, @HeaderValue for HTTP header values and @PathParam for dynamic parts for the resource/route definition and so on)

[derrabus]

I think, this old feature request is obsolete now that PHP has native attributes that can be attached to method parameters.