Add VUB parser and comprehensive README improvements

[tomaj]

Summary

• Add VubMailParser - Support for VUB bank emails (Slovakia)
• Comprehensive README improvements - Professional documentation with examples
• Proper project structure - VUB parser in correct src/Parsers/Vub/ directory

New VUB Parser Features

🏦 Bank Support

• VUB (Všeobecná úverová banka) - Major Slovak banking institution
• Handles plain text confirmation emails from nonstopbanking@vub.sk
• Extracts transaction details using regex pattern matching

📊 Extracted Data

• Transaction date - Parsed from "Dtum:" field
• Amount - From "Suma:" with comma decimal separator handling
• Source account - IBAN from "Z tu:" field
• Variable Symbol (VS) - From "VS:" field
• Constant Symbol (KS) - From "KS:" field
• Unicode handling - Proper support for non-breaking spaces

🧪 Testing

• Comprehensive test coverage with real email format examples
• Validates all extracted fields against expected values
• 40/40 tests passing including new VUB parser tests

Documentation Improvements

📚 Professional README Structure

• Bank support matrix with country flags and feature comparison
• Quick Start guide with immediate usage examples
• Email format examples showing actual bank email structures
• Complete MailContent API documentation with all getters
• Error handling guide with validation patterns and common scenarios

🛡️ Security & Best Practices

• PGP key management recommendations for encrypted emails
• Data validation examples for production environments
• Security considerations for handling sensitive banking data

🤝 Developer Experience

• Contributing guidelines with step-by-step bank parser creation
• Migration guides for all major version transitions
• PHP compatibility matrix showing supported versions
• Development setup instructions with required tools

Technical Implementation

🏗️ Architecture

namespace Tomaj\BankMailsParser\Parser\Vub;

class VubMailParser implements ParserInterface 
{
    public function parse(string $content): ?MailContent
}

📁 File Structure

src/Parsers/Vub/VubMailParser.php       # Main parser class
tests/Parsers/Vub/VubMailParserTest.php # Comprehensive tests

🔍 Code Quality

• PHPStan level 5 - No static analysis errors
• Strict typing - declare(strict_types=1) throughout
• PSR standards - Follows existing project coding conventions
• 100% backward compatibility - No breaking changes to existing APIs

Example Usage

use Tomaj\BankMailsParser\Parser\Vub\VubMailParser;

$parser = new VubMailParser();
$mailContent = $parser->parse($emailContent);

if ($mailContent) {
    echo "Amount: " . $mailContent->getAmount() . "\n";
    echo "VS: " . $mailContent->getVs() . "\n";  
    echo "Account: " . $mailContent->getAccountNumber() . "\n";
}

Testing Results

• ✅ 40/40 tests passing (338 assertions)
• ✅ PHPStan clean (0 errors at level 5)
• ✅ All existing parsers continue to work unchanged
• ✅ VUB parser handles real email format correctly

Impact

This PR expands the library's banking coverage to include VUB, one of Slovakia's largest banks, while significantly improving the developer experience through comprehensive documentation and examples.

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com