Merge branch 'release/2.3.0'

Author: cerbero90

.github/workflows/build.yml

@@ -12,8 +12,8 @@ jobs:
             fail-fast: false
             matrix:
                 php: [8.1, 8.2, 8.3, 8.4]
-                dependency-version: [prefer-stable]
-                os: [ubuntu-latest]
+                dependency-version: [prefer-lowest, prefer-stable]
+                os: [ubuntu-latest, windows-latest, macos-latest]
 
         name: PHP ${{ matrix.php }} - ${{ matrix.dependency-version }} - ${{ matrix.os }}
 

CHANGELOG.md

@@ -26,6 +26,19 @@ Updates should follow the [Keep a CHANGELOG](https://keepachangelog.com/) princi
 - Nothing
 
 
+## 2.3.0 - 2024-12-22
+
+### Added
+- Enums discoverability
+- Console command to create an enum
+- Console command to annotate enums
+- Console command to turn PHP enums into TypeScript enums
+
+### Changed
+- Improved static analysis
+- CasesCollection::groupBy() does not wrap the result into a collection
+
+
 ## 2.2.1 - 2024-11-22
 
 ### Added

README.md

@@ -0,0 +1,27 @@
+#!/usr/bin/env php
+
+<?php
+
+use function Cerbero\Enum\fail;
+use function Cerbero\Enum\path;
+use function Cerbero\Enum\setPathsByOptions;
+use function Cerbero\Enum\splitArgv;
+
+is_file($autoload = dirname(__DIR__, 1) . '/vendor/autoload.php') && require $autoload;
+is_file($autoload = dirname(__DIR__, 4) . '/vendor/autoload.php') && require $autoload;
+is_file($autoload = dirname(__DIR__, 4) . '/enums.php') && require $autoload;
+
+if (is_file($command = path(__DIR__ . '/../cli/' . ($argv[1] ?? null) . '.php'))) {
+    try {
+        [$arguments, $options] = splitArgv($argv);
+        setPathsByOptions($options);
+
+        $outcome = require $command;
+    } catch (Throwable $e) {
+        $outcome = fail($e->getMessage());
+    }
+
+    exit($outcome ? 0 : 1);
+}
+
+require path(__DIR__ . '/../cli/help');

bin/enum

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+use Cerbero\Enum\Enums;
+use Cerbero\Enum\Services\Annotator;
+
+use function Cerbero\Enum\enumOutcome;
+use function Cerbero\Enum\normalizeEnums;
+use function Cerbero\Enum\succeed;
+
+$enums = array_intersect(['--all', '-a'], $options) ? [...Enums::namespaces()] : normalizeEnums($arguments);
+
+if (empty($enums)) {
+    return succeed('No enums to annotate.');
+}
+
+$succeeded = true;
+$force = !! array_intersect(['--force', '-f'], $options);
+
+foreach ($enums as $enum) {
+    $succeeded = enumOutcome($enum, fn() => (new Annotator($enum))->annotate($force)) && $succeeded;
+}
+
+return $succeeded;

cli/annotate.php

@@ -0,0 +1,57 @@
+Annotate enums to ease IDE autocompletion.
+
+Usage: enum annotate enum1 [enum2 ...]
+
+Available options:
+
+    -a, --all               Whether all enums should be annotated
+    -f, --force             Whether existing annotations should be overwritten
+
+Examples:
+    enum annotate App/Enums/MyEnum
+    enum annotate "App\Enums\MyEnum"
+    enum annotate App/Enums/MyEnum1 App/Enums/MyEnum2
+    enum annotate App/Enums/MyEnum --force
+    enum annotate --all
+    enum annotate --all --force
+
+――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
+
+Create a new enum.
+
+Usage: enum make enum case1 case2
+
+Available options:
+
+    --backed=VALUE          How cases should be backed. VALUE is either:
+                            snake|camel|kebab|upper|lower|int0|int1|bitwise
+    -f, --force             Whether the existing enum should be overwritten
+    -t, --typescript        Whether the enum should be synced in TypeScript
+
+Examples:
+    enum make App/Enums/MyEnum Case1 Case2
+    enum make "App\Enums\MyEnum" Case1 Case2
+    enum make App/Enums/MyEnum Case1=value1 Case2=value2
+    enum make App/Enums/MyEnum Case1 Case2 --backed=int1
+    enum make App/Enums/MyEnum Case1 Case2 --force
+    enum make App/Enums/MyEnum Case1 Case2 --backed=bitwise --force
+    enum make App/Enums/MyEnum Case1 Case2 --typescript
+
+――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
+
+Synchronize enums in TypeScript.
+
+Usage: enum ts enum1 [enum2 ...]
+
+Available options:
+
+    -a, --all               Whether all enums should be synchronized
+    -f, --force             Whether existing enums should be overwritten
+
+Examples:
+    enum ts App/Enums/MyEnum
+    enum ts "App\Enums\MyEnum"
+    enum ts App/Enums/MyEnum1 App/Enums/MyEnum2
+    enum ts App/Enums/MyEnum --force
+    enum ts --all
+    enum ts --all --force

cli/help

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+use Cerbero\Enum\Enums\Backed;
+use Cerbero\Enum\Services\Generator;
+
+use function Cerbero\Enum\enumOutcome;
+use function Cerbero\Enum\fail;
+use function Cerbero\Enum\option;
+use function Cerbero\Enum\runAnnotate;
+use function Cerbero\Enum\runTs;
+use function Cerbero\Enum\succeed;
+
+if (! $enum = strtr($arguments[0] ?? '', '/', '\\')) {
+    return fail('The name of the enum is missing.');
+}
+
+$force = !! array_intersect(['--force', '-f'], $options);
+
+if (enum_exists($enum) && ! $force) {
+    return succeed("The enum {$enum} already exists.");
+}
+
+if (! $cases = array_slice($arguments, 1)) {
+    return fail('The cases of the enum are missing.');
+}
+
+try {
+    $generator = new Generator($enum, $cases, option('backed', $options));
+} catch (ValueError) {
+    return fail('The option --backed supports only ' . implode(', ', Backed::names()));
+}
+
+$typeScript = !! array_intersect(['--typescript', '-t'], $options);
+
+return enumOutcome($enum, function () use ($generator, $enum, $force, $typeScript) {
+    return $generator->generate($force)
+        && runAnnotate($enum, $force)
+        && ($typeScript ? runTs($enum, $force) : true);
+});

cli/make.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+use Cerbero\Enum\Enums;
+use Cerbero\Enum\Services\TypeScript;
+
+use function Cerbero\Enum\enumOutcome;
+use function Cerbero\Enum\normalizeEnums;
+use function Cerbero\Enum\succeed;
+
+$enums = array_intersect(['--all', '-a'], $options) ? [...Enums::namespaces()] : normalizeEnums($arguments);
+
+if (empty($enums)) {
+    return succeed('No enums to synchronize.');
+}
+
+$succeeded = true;
+$force = !! array_intersect(['--force', '-f'], $options);
+
+foreach ($enums as $enum) {
+    $succeeded = enumOutcome($enum, fn() => (new TypeScript($enum))->sync($force)) && $succeeded;
+}
+
+return $succeeded;

cli/ts.php

@@ -27,13 +27,20 @@
     "autoload": {
         "psr-4": {
             "Cerbero\\Enum\\": "src"
-        }
+        },
+        "files": [
+            "helpers/core.php",
+            "helpers/cli.php"
+        ]
     },
     "autoload-dev": {
         "psr-4": {
-            "Cerbero\\Enum\\": "tests"
+            "Cerbero\\Enum\\": "tests",
+            "App\\": "tests/Skeleton/app",
+            "Domain\\": "tests/Skeleton/domain"
         }
     },
+    "bin": ["bin/enum"],
     "scripts": {
         "fix": "duster fix -u tlint,phpcodesniffer,pint",
         "lint": "duster lint -u tlint,phpcodesniffer,pint,phpstan",