feat: add class SafeCast

[spawnia]

• Added automated tests
• Documented in README
• Updated the changelog (handled by semantic-release)

Changes

Adds a new SafeCast utility class that provides safe alternatives to PHP's native type casts.

PHP's native type casts like (int) and (float) can produce unexpected results, especially when casting from strings:

• (int)"hello" returns 0 (misleading, not an error)
• (int)"123abc" returns 123 (partial conversion, data loss)
• (float)"1.23.45" returns 1.23 (invalid format accepted)

The SafeCast class validates input before casting and throws exceptions for invalid inputs instead of silently producing incorrect values.

Each type has two variants:

• toX(): returns the cast value or throws \InvalidArgumentException
• tryX(): returns the cast value or null (like Enum::tryFrom())

Methods included:

• SafeCast::toInt() / SafeCast::tryInt() - Safely cast to integer
• SafeCast::toFloat() / SafeCast::tryFloat() - Safely cast to float
• SafeCast::toString() / SafeCast::tryString() - Safely cast to string
• SafeCast::toBool() / SafeCast::tryBool() - Safely cast to boolean

See README.md for usage examples and SafeCastTest.php for comprehensive test coverage.

Breaking changes

None - this is a new feature addition.

[Copilot]

Pull Request Overview

This PR introduces a new SafeCast utility class that provides safe type casting alternatives to PHP's native type casting operators. The utility validates input before casting and throws exceptions for invalid inputs instead of silently producing incorrect values.

• Adds SafeCast class with methods for safe casting to int, float, string, and bool types
• Includes comprehensive test coverage for all casting methods and edge cases
• Updates documentation with usage examples and explanations

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
src/SafeCast.php	Main implementation of the SafeCast utility class with validation logic
tests/SafeCastTest.php	Comprehensive test suite covering all methods and edge cases
README.md	Documentation update with usage examples for the new SafeCast utility
src/FluidXPlate/FluidXScanner.php	Minor refactoring to use in_array() for better readability

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[spawnia]

Thanks for the review! Addressing both comments:

Float formatting (comment 1): We've added a comment in the code explaining that we're using PHP's default float-to-string conversion for error messages. While sprintf('%.10g', $value) would provide more consistent formatting, the default conversion is sufficient for error reporting purposes and keeps the code simpler.

toBool documentation (comment 2): The toBool() method has been removed entirely from this PR. Boolean casting is too context-dependent and opinionated to include in a "safe" casting utility - different contexts use different conventions (HTML forms use 'on'/'off', APIs might use 'true'/'false', databases might use '1'/'0'). The final implementation only includes toInt(), toFloat(), and toString().

[spawnia]

Merge erst nach Vorstellung und generellem Approval im Fachvortrag. Ich implementiere es bis dahin noch in unseren Projekten um sicherzustellen dass das Design passt.