henzeb / enumhancer

Your Swiss Army knife for PHP 8.1+ native enums

Enumhancer

This package is your framework-agnostic Swiss Army knife when it comes to PHP 8.1's native enums. In this package you will find a lot of tools for the most common use cases, and more will be added in the future.

If you have an idea, or you miss something that needs to be added, just let me know.

Enumhancer is case-agnostic, which means Enum equals ENUM equals enum. This is done with the idea that it is useless to have two different enums having the same name and different casing.

It is also type-agnostic. This way you can steer clear as much as possible from the extra work that comes with backed enums.

Note: While most functionality that also exists in Spatie's PHP Enum is made backwards compatible to allow for an easy migration to PHP native enums, currently this is not the case for their laravel package, PHPUnit assertions or Faker Provider.

Installation

You can install the package via composer:

composer require henzeb/enumhancer

Usage

You can simply add the Enhancers trait to your enum in order to use almost all functionality of this package. All features should work with basic enums as well as backed enums' unless stated otherwise.

use Henzeb\Enumhancer\Concerns\Enhancers;

enum YourEnum {
    use Enhancers;

    // ...
}

You can also just use one of the features by using the specific trait for that feature.

Note: all traits can be used next to each other, except for Mappers, which has implemented the methods of Getters, Extractor and Reporters.

Features

• Attributes
• Bitmasks
• Constructor
• Comparison
• Configure
• Defaults
• Dropdown
• Extractor
• From
• Getters
• Labels
• Macros
• Mappers
• Properties
• Reporters
• State
• Subset
• Value

Helper functions

• Backing
• Name
• Value

Development

• IDE-Helper
• PHPstan

Laravel specific Features

• Blade
• Casting
• FormRequest
• Implicit (basic) enum binding
• Validation

Laravel's auto-discovery

When you are installing this package into a laravel project, Enumhancer will automatically set macro's for the validation rules and sets the global Reporter for the getOrReport methods, so that it will use Laravel's Log facade.

If you don't want that to happen, you can tell Laravel not to discover the package.

"extra": {
        "laravel": {
            "dont-discover": [
                "henzeb/enumhancer"
            ]
        }
    }

Testing

composer test

PHPStan integration

If you are using PHPStan for static analysis, you can enable the extension.

Add the following to your projects phpstan.neon:

includes:
- vendor/henzeb/enumhancer/extension.neon

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Henze Berkheij

License

The GNU AGPLv. Please see License File for more information.

enumhancer's Issues

Deprecation warnings for php8.4

Hi,

I have a PR ready to submit to fix the php8.4 deprecation warnings, but Im unable to push a new branch to PR with.

Can you allow this?

Thanks
Lee

Cannot transition state on Backed Enum if value is non-lowercased

Given I have this enum

enum PostStatus: string
{
    use State;

    case DRAFT = 'DRAFT';
    case READY = 'READY';
    case PUBLISHED = 'PUBLISHED';
    case ARCHIVED = 'ARCHIVED';
}

Even the default allowedTransitions won't work, this is because when doint the comparison, specifically on

enumhancer/src/Helpers/EnumState.php

Lines 46 to 57 in cbf1230

	private static function getTransitions(UnitEnum $currentTransition): array
	{
	$transitions = array_change_key_case(
	EnumState::transitions($currentTransition::class, $currentTransition::class::transitions())
	);
	$transitions = $transitions[$currentTransition->name]
	?? $transitions[EnumValue::value($currentTransition)]
	?? [];
	return array_filter(is_array($transitions) ? $transitions : [$transitions]);
	}

the array_change_key_case make the key to be lowercased, meanwhile

the $transitions[EnumValue::value($currentTransition)] has

enumhancer/src/Helpers/EnumValue.php

Lines 13 to 20 in cbf1230

	public static function value(UnitEnum $enum, bool $keepCase = null): string|int
	{
	if (is_null($keepCase)) {
	$keepCase = self::isStrict($enum);
	}
	return $enum->value ?? ($keepCase ? $enum->name : strtolower($enum->name));
	}

in which if there are value it will use that, case is when the value is an uppercased letter, it will be compared to lowercased $transitions array from before

Our specific use case is because Laravel has Rule::enum for validation, already but in need to be backed, meanwhile, the transition is having this issue, for now my alternative is using Rule::isEnum this package provide,

Support integer backed enums in Comparison?

Right now, YourEnum::ENUM->equals() only supports strings. Are there plans to include some sort of support for integer matching as well?

Laravel casting for UnitEnum

Laravel supports casting for BackedEnum out of the box, but does not support UnitEnums.

idea is to add casting for UnitEnums by using CastsAttributes interface.

This is currently being blocked by laravel/framework#42648. Laravel just checks if the enum exists, not if it is a BackedEnum.

Request: functions to values or names from enum.

The following migration rule does not work because cases() returns an array of enum objects rather than an array of strings:

    $table->enum('status', TransactionStatus::cases());

names() and values() functions would be nice in this case, they would return an array with strings.

Example:

    public static function names(): array
    {
        return array_column(self::cases(), 'name');
    }

->equals regression in 1.7

Comparisons with strings seem to have broken in some way between 1.6 and 1.7.

$code = 'FR020100';
$is_false = TaxCode::SHIPPING->equals($code);
$is_true = TaxCode::SHIPPING->value === $code;

<?php

namespace Drupal\hc_commerce_avatax\Enum;

use Henzeb\Enumhancer\Concerns\Comparison;

/**
 * Provides enums that represent avatax tax codes.
 */
enum TaxCode: string {

  use Comparison;

  case DEFAULT = 'P0000000';

  case LUMBER = 'PA3000400';

  case SHIPPING = 'FR020100';

}