README

This package adds a truth test helper for checking if class is an attribute.

Introduction

PHP Attributes were introduced in PHP 8.0. From the documentation, you can see that Attributes are defined similar to classes:

#[Attribute]
class SetUp
{
    //
}

However, if you're handed the name of a class, there's no good way to know if that class is a PHP Attribute or not. This is where the is_attribute() method, as defined by this package, comes in.

Installation

Install this package using Composer:

composer require reedware/is-attribute

Usage

function is_attribute(string|object|null $class, ?int $target = null, int $match = TARGET_MATCH_EQUALS): bool

Class Argument

Let's start with the basics. For more use-cases, you'll only need to pass one parameter to is_attribute(), being the class itself.

Here's an example of that:

echo is_attribute(SetUp::class); // true
echo is_attribute(CopyFile::class); // false

Target Argument

If you care what targets the attributes support, this is where an optional second parameter comes in.

For example, you can define an attribute like so:

#[Attribute(Attribute::TARGET_CLASS_CONSTANT|Attribute::TARGET_PROPERTY)]
class Serialize
{
    //
}

This defines a Serialize attribute that can applied to a class or property.

To check if an attribute can be applied to a class or property, you can pass in targets as the second parameter to is_attribute:

echo is_attribute(Serialize::class, Attribute::TARGET_CLASS_CONSTANT|Attribute::TARGET_PROPERTY); // true

Note that checking one or the other will return false:

echo is_attribute(Serialize::class, Attribute::TARGET_CLASS_CONSTANT); // false
echo is_attribute(Serialize::class, Attribute::TARGET_PROPERTY); // false

When the second argument is not specified (e.g. null), the specified class must simply be an Attribute, regardless of target. This is different from passing in Attribute::TARGET_ALL as the second argument, which will require the attribute to specify all targets (which is the default).

echo is_attribute(Serialize::class, Attribute::TARGET_ALL); // false

This is because the second parameter must be an exact match to the attribute.

Match Argument

If you don't want to do an exact match, you can use the optional third parameter.

TARGET_MATCH_EQUALS

This is the default value of the third argument, and exhibits the behavior already described above.

TARGET_MATCH_INCLUDES

This match setting requires ALL of the provided targets to be included (e.g. and/conjunction).

echo is_attribute(Serialize::class, Attribute::TARGET_CLASS_CONSTANT, TARGET_MATCH_INCLUDES); // true
echo is_attribute(Serialize::class, Attribute::TARGET_PROPERTY, TARGET_MATCH_INCLUDES); // true
echo is_attribute(Serialize::class, Attribute::TARGET_PROPERTY | Attribute::TARGET_PARAMETER, TARGET_MATCH_INCLUDES); // false

TARGET_MATCH_ANY

This match setting requires ANY of the provided targets to be included (e.g. or/disjunction).

echo is_attribute(Serialize::class, Attribute::TARGET_CLASS_CONSTANT, TARGET_MATCH_INCLUDES); // true
echo is_attribute(Serialize::class, Attribute::TARGET_PROPERTY, TARGET_MATCH_INCLUDES); // true
echo is_attribute(Serialize::class, Attribute::TARGET_PROPERTY | Attribute::TARGET_PARAMETER, TARGET_MATCH_INCLUDES); // true