Resolution of type-names in annotations such as @var and @property may be necessary.

Namespaces were a reasonably new thing when I wrote this library, and the PHP-DOC specification wasn't entirely clear on things like namespace-relative class-name references, e.g.:

namespace Foo;

use Wham\Baz;

class Bar 
{
    /**
     * @var Baz
     */
    public $baz;
}

Does this annotation refer to \Baz, \Foo\Baz or \Wham\Baz ? We know the latter is the answer, but it's dependent on namespace resolution rules, which, at the time, it wasn't clear if those applied to type-names in annotations. I used to write out annotations as @var Wham\Baz not knowing that namespace-resolution rules would apply to type-names in annotations like they do to source-code.

I think solving this is probably not "low-hanging fruit" - it would require some kind of extension to the API as such, to provide annotations with some means of resolving class-names found in various annotations. It would also require an extension to the AnnotationParser class, to parse the use clause.

We should ponder how the mechanics of this is going to work, but off the top of my head, I think we may need to expose the AnnotationParser instance during parsing, via IAnnotationParser::parseAnnotation(), e.g. by changing it's signature from parseAnnotation($value) to parseAnnotation($value, AnnotationParser $parser) - so that annotations can go back to a new method like AnnotationParser::resolveClassName($name) to resolve class-names to fully-qualified class-names, based on namespace and use clauses in the file.

When a PHPDoc has no type defined for a@Param entry it fails trying to get array index 1.

Ex:

/**
 * This function does something
 *
 * @param $value
 */
public static function myFunction($value)
{
}

Given a member or method included from a trait which has an annotation

<?php

trait TestTrait
{
    /**
     * @var SomeType
     */
    public $member;
}

class Test {
     use TestTrait;   
}

php-annotations will fail to detect the annotation on $member. This makes traits almost entirely useless if you need to annotate a trait member! [PHPUnit annotations handle this correctly, FWIW.]

I've included a failing test case for this in the first commit and a patch in the second. I realize the patch is unlikely to be accepted in its current form, since it introduces a dependency on the reflection API and AnnotationParser might be replaced entirely by #60? But food for thought!

The GitHub Pages (http://pages.github.com/) is far more superior project website generation tool then the GitHub Wiki (https://github.com/gollum/gollum powered).

I recommend to use it.

The AnnotationManager::applyConstrains method designed to validate and filter given annotations list according to @usage annotation of annotations present in given annotations list (filter annotations based on annotation, tricky).

Problem No. 1 Line 340: https://github.com/php-annotations/php-annotations/blob/master/src/annotations/AnnotationManager.php#L340

if (!$usage->$member) {
    throw new AnnotationException("{$type} cannot be applied to a {$member}");
}

Looking at parent Annotation class we can see that there is __get method there, that will throw exception with ... is not a valid property name message when somebody will try accessing non-existing property of the UsageAnnotation. I bet this wasn't desired effect since in such case the nice exception message inside IF will never be thrown. Even if the __get method wasn't there check is still bad, since it doesn't validate if property with given name exists in that class. I recommend using !property_exists($member, $usage)` instead.

Problem No. 2 Line 344: https://github.com/php-annotations/php-annotations/blob/master/src/annotations/AnnotationManager.php#L352

if (!$usage->multiple) {
    foreach ($annotations as $inner => $other) {
        if ($inner >= $outer) {
            break;
        }

        if ($other instanceof $type) {
            if ($usage->inherited) {
                unset($annotations[$inner]);
            } else {
                throw new AnnotationException("only one annotation of type {$type} may be applied to the same {$member}");
            }
        }
    }
}

The $annotations variable contains annotations that are defined on this property/class/method along with annotations inherited from this property/class/method from the parent class. I understand that finding another annotation of same type on that property/class/method is an exception.

However, what I do not understand is what if ($usage->inherited) { and unsetting of inner annotations does. Maybe idea was to unset annotations that came from parent classes and only count ones, that are defined in inspected class. However the $usage->inherited doesn't really tell that inspected annotation came from parent class. It only tells that the annotation could came from parent class.

There is no test, that covers that unset, so I'm wondering what is the logic behind it.

The last line (of code below) introduces getShortName method (can decide better name of course), that would return annotation name, that was found in DocBlock (e.g. @var, @find-by, etc.).

Right now I already can filter annotations being returned by Annotations::ofProperty by specifying @var (and others) in $type parameter of that method.

// 1. create annotation (file1.php)
namespace RepkaQA\PageObject;

use Mindplay\Annotation\Annotation;

class FindByAnnotation extends Annotation { ... }

// 2. register annotation (file2.php)
Annotations::getManager()->registry['find-by'] = 'RepkaQA\PageObject\FindByAnnotation';

// 3. use annotation (file2.php)
$annotations = Annotations::ofProperty($property);

foreach ($annotations as $annotation) {
    $short_name = $annotation->getShortName(); // NEW
}

Hi,

This problem will prob. occur with every class that extends a PHP-Class which has no source.

class TestClass extends ArrayObject
{
}

$annotation_manager->getClassAnnotations('TestClass', 'some-annoation');

Will result in an exception trying to read the source file for ArrayObject.

AnnotationManager.php

$reflection = new ReflectionClass($class_name);
$file = $this->getAnnotationFile($reflection->getFileName());

getFileName() returns false which results later in using file_get_contents called with false which throws an exception.

as agreed... To prevent php from searching for the function in the current namespace. Logically, I only added slashes, so I did not ruin the PSR2 compliance.

Some annotation libraries for PHP supports nested annotations in form

@Block(@FindBy('xpath' => '//test'))

Will it work in this library? Any pros/cons on using nested annotations?

The presence of output parameters (ones that have "&" in them in method declaration) is bad practice.

I propose that we change the AnnotationManager::applyConstraints(array &$annotations, $member) method to return filtered annotation array instead of reducing one given in 1st parameter.

When I try to get annotations from an interface/trait then I'm getting exception from the getClassAnnotations method (see https://github.com/php-annotations/php-annotations/blob/master/src/annotations/AnnotationManager.php#L450-L452).

Even though a ReflectionClass instance is accepted the class_exists check follows which ends all the fun.

I think that we should allow interfaces/traits in as well.

Since PHP 8 introduces attributes, the future justification for this project is probably in question.

I've already voiced this thought to @aik099 who largely took over development after me, and he basically agreed.

I basically have one reservation about retiring this project.

There is one feature this project has that you don't get with PHP 8 attributes, and that's the doc-block syntax. Sometimes, you have doc-blocks that are there for two reasons: both for documentation, and for a piece of code to pick it up.

So if you still need doc-blocks for certain things, there's a chance you could end up having to duplicate certain information between a doc-block for documentation purposes, and an attribute for run-time purposes.

Probably the best example is things like @param, @type and @return annotations, but with the introduction of e.g. return-types and typed properties since the inception of this project, this may have limited usefulness as well.

So, is there still a reason for this project to exist?

If yes: likely this project needs to actually support PHP 8 attributes, so you would get both types of annotations from a single function-call. (Note that this is not what was recently introduced, which is just compatibility with PHP 8, which you can rely on while transitioning to attributes.)

If no: likely the project is ready to officially retire.

Note that I don't use annotations (or attributes) myself, so I have no interest in pursuing future development of this project either way. The project gets ~1500 installs/month, about half of which is from @aik099's QA-tools project, so I figured I'd ask the community to comment before officially retiring the project, since it doesn't sound like @aik099 intends to maintain it either.

If someone else is interested in taking over, I'd be happy to hand it off as well.

I experienced hard-to-reproduce errors in an app that uses php-annotations. Looks like the problem is that php-annotations cache cannot handle some concurrency scenarios.

Simplified caching workflow is: check if entity is in the cache (check if cached file exists) a. if file exists, a.1 include the file. a.2. end of workflow b. if file doesn't exist, b.1. create empty cache file b.2. lock the file b.3. write cache data b.4. end of workflow

Now consider that the cache is empty & we make two almost simultaneous requests that cause creation of the same cache entities.

Request I:

1. check if cached file exists (no)
2. create empty cache file
3. lock the file (the file is still empty) ...

Request II

1. check if cached file exists (yes)
2. include the file (but the file is still empty)

The solution can be to write to temp file, and then move it into the cache.

Due changes on HHVM/Travis CI the HHVM builds are failing with this message:

HHVM is no longer supported on Ubuntu Precise. Please consider using Trusty with `dist: trusty`.

See https://travis-ci.org/php-annotations/php-annotations/jobs/244611235

When class is created using eval(...) then $reflection->getFileName() (in \mindplay\annotations\AnnotationManager::getAnnotations method) would return something similar to: /path/to/file/with/eval_statement.php(16) : eval()'d code.

That in turn would result in following warning, when the \mindplay\annotations\AnnotationParser::parseFile method tried to get annotations from it:

file_get_contents(/path/to/file/with/eval_statement.php(16) : eval()'d code): failed to open stream: No such file or directory

Proposing to check for eval()'d code string in reflected class filename and if found consider it as internal class for which we can't get any annotations.

PSR4 AutoLoader and version of index.html that uses it rather than composer. standalone.php has the same wiki-doc.php profile as index.php. (Compare with index.html to see differences which would be difficult to make optional)

I've got an e-mail from ReadTheDocs today, that all readthedocs.org sub-domains now should be readthedocs.io sub-domain. They will redirect automatically, but we need to fix links by ourselves anyway.