Add Importable interface to enable direct passing of importable objects

[Copilot]

This PR introduces an Importable interface that allows passing importable objects directly to methods like FullyQualified::maybeFromString() without explicit string casting.

Problem

Previously, when working with importable objects, you had to cast them to strings before passing them to methods:

$className = new ClassName('User');
$fqcn = FullyQualified::maybeFromString((string) $className); // Required casting

This was verbose and reduced type safety, especially when dealing with multiple importable types.

Solution

This PR adds an Importable interface that:

• Extends Stringable to maintain string conversion capability
• Defines common methods equals(object $other): bool and compare(object $other): int
• Is implemented by all importable classes: ClassName, FullyQualified, FunctionName, NamespaceName, and Alias

Changes

New Interface

• Importable - Common interface for all importable types

Updated Classes

All five importable classes now implement Importable:

• Added #[Override] attributes for interface method implementations
• Updated maybeFromString() methods to accept string|Importable instead of just string
• Maintained backward compatibility with existing string-based usage

Enhanced CodeGenerator

• Updated type hints to use Importable where appropriate:
  • import(Importable | string $fqcnOrEnum)
  • importByParent(Importable | string $name)
  • findAvailableAlias(Importable $type, ...)

Benefits

✅ Cleaner API: No more explicit string casting required
✅ Better type safety: Interface-based typing instead of union types
✅ Backward compatible: All existing code continues to work
✅ Consistent: All importable types follow the same pattern

Usage Example

// Before: Required explicit casting
$className = new ClassName('User');
$fqcn = FullyQualified::maybeFromString((string) $className);
$generator->import((string) $className);

// After: Direct object passing
$className = new ClassName('User');
$fqcn = FullyQualified::maybeFromString($className);
$generator->import($className);

Testing

Added comprehensive test suite (ImportableTest) with 8 test methods covering:

• Interface implementation verification
• Cross-type maybeFromString() usage
• CodeGenerator integration
• Alias creation with importable objects

All existing tests continue to pass, ensuring no regressions.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.