feat: Add support for separate cassettes per DataProvider cases

[cb-vova]

This PR introduces comprehensive support for creating separate VCR cassettes for each PHPUnit DataProvider case, providing better isolation and organization of HTTP recordings in data-driven tests.

🚀 New Features

Enhanced UseCassette Attribute

• separateCassettePerCase: When set to true, creates individual cassette files for each data provider case
• groupCaseFilesInDirectory: When set to true, organizes separate cassette files in subdirectories

Flexible Cassette Naming Strategies

• Numbered cases: cassette-0.yml, cassette-1.yml
• Named cases: cassette-example-com.yml, cassette-example-org.yml
• Directory organization: cassette/0.yml, cassette/example-com.yml
• Extension handling: Works with and without file extensions

Class and Method Level Support

• Works with UseCassette declared on test classes
• Works with UseCassette declared on individual test methods
• Maintains backward compatibility with existing usage

🔧 Implementation Details

Core Changes

• UseCassette.php: Enhanced with new optional parameters
• AttributeResolverTrait.php: Refactored to parse data provider information
• StartRecording.php: Added intelligent cassette naming logic
• New Value Objects: TestCaseParameters and TestMethodInfo for better data handling

Data Provider Name Normalization

• Converts special characters to hyphens
• Handles edge cases and invalid names
• Maintains consistency across different naming patterns

📚 Documentation

• Comprehensive README updates with multiple usage examples
• Examples for all supported configurations
• Clear migration path for existing users

🧪 Test Coverage

• New Test Classes:
  • AttributeDeclaredOnClassWithSeparateCassettesInSeparateFoldersTest
  • AttributeDeclaredOnClassWithSeparateCassettesInSingleFolderTest
  • WithoutVcrTest
• Enhanced Existing Tests: Updated AttributeDeclaredOnMethodsTest with new scenarios
• Complete Fixture Set: 20+ test fixtures demonstrating all naming patterns and organization strategies

🔄 Backward Compatibility

• All existing functionality remains unchanged
• New parameters are optional with sensible defaults
• No breaking changes to existing API

💡 Usage Examples

Basic Separate Cassettes

#[UseCassette(name: "api_test.yml", separateCassettePerCase: true)]
#[DataProvider("urls")]
public function testApiCalls(string $url): void
{
    // Creates: api_test-0.yml, api_test-1.yml
}

Organized in Directories

#[UseCassette(
    name: "api_test.yml", 
    separateCassettePerCase: true,
    groupCaseFilesInDirectory: true
)]
#[DataProvider("namedUrls")]
public function testApiCalls(string $url): void
{
    // Creates: api_test/example-com.yml, api_test/example-org.yml
}

This enhancement significantly improves the developer experience when working with data-driven tests that make HTTP requests, providing better isolation, easier debugging, and more organized test fixtures.

[angelov]

Thank you for the contribution @cb-vova!

It's a bit of a busy period for me, but I will try to review this as soon as possible. In meanwhile, can you maybe split this into a few smaller PRs so it'll be easier to review?

[cb-vova]

Thank you for the contribution @cb-vova!

It's a bit of a busy period for me, but I will try to review this as soon as possible. In meanwhile, can you maybe split this into a few smaller PRs so it'll be easier to review?

sure. the same thing..
I'll do my best to split, but other than splitting ci and code, I don't see many options to split. Only the 5 files are implemented, the others are tests 😃

[angelov]

Thank you again @cb-vova!

I left some minor comments, but in general it looks good.

[cb-vova]

Thank you, @angelov, for the review.
I've applied them, and I see the pipeline is green now. Could you please take another look at it?
(and I'm sorry for the many actions triggered, I've realised it too late 🤦‍♂️ )

[angelov]

Looks good! Thank you and sorry for the delay. 🍻