attribute-collector

This project provides a composer package with collectors for collecting attributes located on classes, class constants, properties, methods, method parameters, functions, function parameters, and constants.

Installation

Run

composer require ergebnis/attribute-collector

Usage

Attributes

This package provides an Attribute that composes the location of an attribute and a concrete instance of the attribute collected at that location.

You can obtain an Attribute from an attribute collection by using a collector to collect attributes.

Attribute Collection

This package provides an AttributeCollection that composes a collection of attributes.

You can obtain an AttributeCollection by using a collector to collect attributes.

Filtering an attribute collection by attribute class name

You can filter an attribute collection by attribute class name:

<?php

declare(strict_types=1);

use Ergebnis\AttributeCollector;

$attributeClassName = AttributeCollector\Name\ClassName::fromString(\Deprecated::class);

/** @var AttributeCollector\AttributeCollection $attributeCollector */
$filteredAttributeCollection = $attributeCollector->whereAttributeClassNameEquals($attributeClassName);

You can filter an attribute collection by attribute location:

<?php

declare(strict_types=1);

use Ergebnis\AttributeCollector;

$attributeLocation = AttributeCollector\Location\ClassMethodLocation::create(
    AttributeCollector\Name\ClassName::fromString(Foo::class),
    AttributeCollector\Name\MethodName::fromString('bar')
);

/** @var AttributeCollector\AttributeCollection $attributeCollector */
$filteredAttributeCollection = $attributeCollector->whereAttributeLocationEquals($attributeLocation);

Locations

This package provides the following locations that describe where attributes could be or are located:

• Location\ClassLocation
• Location\ClassConstantLocation
• Location\ClassPropertyLocation
• Location\ClassMethodLocation
• Location\ClassMethodParameterLocation
• Location\ConstantLocation
• Location\FunctionLocation
• Location\FunctionParameterLocation

Collectors

This package provides the following collectors for collecting attributes:

• Ergebnis\AttributeCollector\Collector\TraversingAttributeFromClassNameCollector
• Ergebnis\AttributeCollector\Collector\TraversingAttributeFromFinderCollector
• Ergebnis\AttributeCollector\Collector\TraversingAttributeFromLocationCollector

Collector\TraversingAttributeFromClassNameCollector

Use Collector\TraversingAttributeFromClassNameCollector to collect attributes by iterating over and traversing into locations from class names.

Collecting attributes by finding class names

In most of the cases, you might want to collect attributes from classes in your project without having to specify these classes explicitly.

For example, you could use symfony/finder and ergebnis/classy to obtain a list of classy constructs names and then collect attributes from these locations:

<?php

declare(strict_types=1);

use Ergebnis\AttributeCollector;
use Ergebnis\Classy;
use Symfony\Component\Finder;

$finder = Finder\Finder::create()
  ->files()
  ->in(__DIR__ . '/src');

$classyConstructCollector = new Classy\Collector\DefaultConstructFromFinderCollector(new Classy\Collector\PhpTokenTokenizeConstructFromSourceCollector()));

$classyConstructs = $classyConstructCollector->collectFromFinder($finder);

$classNames = array_map(static function (Classy\Construct $construct): AttributeCollector\Name\ClassName {
    return AttributeCollector\Name\ClassName::fromString($construct->name()->toString());
}, $classyConstructs);

$attributeCollector = new AttributeCollector\Collector\TraversingAttributeFromClassNameCollector();

$attributeCollection = $attributeCollector->collectFromClassName(...$classNames);

foreach ($attributeCollection->toArray() as $attribute) {
    $instance = $attribute->instance();

    // inspect or process concrete attribute instance here
}

Collecting attributes by specifying class names

In other cases, you might want to collect attributes from specific class names that you already know.

<?php

declare(strict_types=1);

use Ergebnis\AttributeCollector;

$classNames = [
    AttributeCollector\Name\ClassName::fromString(Foo::class),
    AttributeCollector\Name\ClassName::fromString(Bar::class),
    AttributeCollector\Name\ClassName::fromString(Baz::class),
];

$attributeCollector = new AttributeCollector\Collector\TraversingAttributeFromClassNameCollector();

$attributeCollection = $attributeCollector->collectFromClassName(...$classNames);

foreach ($attributeCollection->toArray() as $attribute) {
    $instance = $attribute->instance();

    // inspect or process concrete attribute instance here
}

Collector\TraversingAttributeFromFinderCollector

Use Collector\TraversingAttributeFromFinderCollector to collect attributes by iterating over and traversing into locations found in classy constructs from an iterable of SplFileInfos:

<?php

declare(strict_types=1);

use Ergebnis\AttributeCollector;
use Symfony\Component\Finder;

$finder = Finder\Finder::create()
  ->files()
  ->in(__DIR__ . '/src');

$attributeCollector = new AttributeCollector\Collector\TraversingAttributeFromFinderCollector();

$attributeCollection = $attributeCollector->collectFromFinder($finder);

foreach ($attributeCollection->toArray() as $attribute) {
    $instance = $attribute->instance();

    // inspect or process concrete attribute instance here
}

Note

This collector is currently limited to collecting attributes by traversing into classy constructs found by ergebnis/classy, such as

• classes
• enums
• interfaces
• traits

Collector\TraversingAttributeFromLocationCollector

Use Collector\TraversingAttributeFromLocationCollector to collect attributes by iterating over and traversing into known locations.

<?php

declare(strict_types=1);

use Ergebnis\AttributeCollector;

$locations = [
    AttributeCollector\Location\ClassLocation::create(AttributeCollector\Name\ClassName::fromString(Foo::class)),
    AttributeCollector\Location\ClassPropertyLocation::create(
        AttributeCollector\Name\ClassName::fromString(Foo::class),
        AttributeCollector\Name\PropertyName::fromString('bar')
    ),
    AttributeCollector\Location\ClassMethodLocation::create(
        AttributeCollector\Name\ClassName::fromString(Foo::class),
        AttributeCollector\Name\MethodName::fromString('baz')
    ),
    AttributeCollector\Location\ClassMethodParameterLocation::create(
        AttributeCollector\Name\ClassName::fromString(Foo::class),
        AttributeCollector\Name\MethodName::fromString('baz'),
        AttributeCollector\Name\ParameterName::fromString('qux')
    ),
    AttributeCollector\Location\FunctionLocation::create(AttributeCollector\Name\FunctionName::fromString('baz')),
    AttributeCollector\Location\ConstantLocation::create(AttributeCollector\Name\ConstantName::fromString('BAZ')),
];

$attributeCollector = new AttributeCollector\Collector\TraversingAttributeFromLocationCollector();

$attributeCollection = $attributeCollector->collectFromLocation(...$locations);

foreach ($attributeCollection->toArray() as $attribute) {
    $instance = $attribute->instance();

    // inspect or process concrete attribute instance here
}

Changelog

The maintainers of this project record notable changes to this project in a changelog.

Contributing

The maintainers of this project suggest following the contribution guide.

Code of Conduct

The maintainers of this project ask contributors to follow the code of conduct.

General Support Policy

The maintainers of this project provide limited support.

PHP Version Support Policy

This project supports PHP versions with active and security support.

The maintainers of this project add support for a PHP version following its initial release and drop support for a PHP version when it has reached the end of security support.

Security Policy

This project has a security policy.

License

This project uses the MIT license.

Social

Follow @localheinz and @ergebnis on Twitter.