// Manual approach (breaks fluent chain)
$query = SM::make($userInput)
    ->trim()
    ->limit(100)
    ->getString();
$encoded = rawurlencode($query); // Can't chain! 
$url = 'https://api.example.com/search?q=' . $encoded;

// With encodeUrl() - fluent and clean
$url = 'https://api.example.com/search?q=' . 
    SM::make($userInput)
        ->trim()
        ->limit(100)
        ->encodeUrl();

// Search query with special characters
$searchTerm = 'Laravel & PHP:  Best practices';
$encoded = SM::encodeUrl($searchTerm);
// Output: 'Laravel%20%26%20PHP%3A%20Best%20practices'
$searchUrl = 'https://example.com/search?q=' .  $encoded;

// User profile URL with email
$email = '[email protected]';
$profileUrl = 'https://api.com/users/' . SM::encodeUrl($email);
// Output: 'https://api.com/users/user%40example.com'

// OAuth redirect with state parameter
$state = json_encode(['user_id' => 123, 'redirect' => '/dashboard']);
$oauthUrl = 'https://oauth.provider.com/auth?state=' . SM::encodeUrl($state);
// State safely encoded for URL transmission

// Download URL with filename
$filename = 'Relatório Técnico 2026.pdf';
$downloadUrl = '/downloads/' . SM::encodeUrl($filename);
// Output: '/downloads/Relat%C3%B3rio%20T%C3%A9cnico%202026.pdf'

// API endpoint with path segments
$category = 'Food & Beverage';
$product = 'Café Espresso (Premium)';
$apiUrl = '/api/categories/' . SM::encodeUrl($category) . 
          '/products/' . SM::encodeUrl($product);
// Both segments properly encoded

// Shareable link with metadata
$title = 'Top 10 PHP Tips & Tricks! ';
$shareUrl = 'https://share.com/post? title=' . 
            SM::encodeUrl($title) . '&utm_source=email';

use SSolWEB\StringMorpher\StringMorpher as SM;

// Encode search query
$encoded = SM::encodeUrl('Laravel & PHP');
echo $encoded; // 'Laravel%20%26%20PHP'

// Encode email for URL
$encoded = SM::encodeUrl('[email protected]');
echo $encoded; // 'user%40example.com'

// Encode special characters
$encoded = SM::encodeUrl('Hello World!  #test');
echo $encoded; // 'Hello%20World%21%20%23test'

// Encode international characters (UTF-8)
$encoded = SM::encodeUrl('Café Münster');
echo $encoded; // 'Caf%C3%A9%20M%C3%BCnster'

// Build complete URL
$query = 'best php frameworks 2026';
$url = 'https://search.com/q=' . SM::encodeUrl($query);
// https://search.com/q=best%20php%20frameworks%202026

use SSolWEB\StringMorpher\StringMorpher as SM;

// Chain with data cleaning for search URL
$searchUrl = 'https://api.com/search?q=' . 
    SM::make($_GET['search'])
        ->trim()
        ->limit(100)
        ->encodeUrl();
// Clean, limited, and URL-safe query parameter

// Build API endpoint with user input
$categorySlug = SM::make($userCategory)
    ->normalize()
    ->toLower()
    ->withoutSpaces()
    ->encodeUrl();
    
$apiEndpoint = "/api/categories/{$categorySlug}/products";

// OAuth state parameter with JSON
$stateData = ['user' => auth()->id(), 'return' => request()->path()];
$oauthState = SM::make(json_encode($stateData))
    ->encodeUrl()
    ->getString();
    
$authUrl = "https://oauth.com/auth?state={$oauthState}";

// Multi-step URL building for complex APIs
$endpoint = SM::make('/api')
    ->append('/v1/users/')
    ->append(SM::make($email)->encodeUrl())
    ->append('/posts/')
    ->append(SM::make($postSlug)->encodeUrl());
    
echo $endpoint; // '/api/v1/users/user%40example.com/posts/my-post-slug'

## Technical Considerations

The implementation should: 
- Use `rawurlencode()` (RFC 3986 compliant) instead of `urlencode()` (deprecated RFC 1738)
- Encode **all** characters except:  `A-Z a-z 0-9 - _ . ~` (unreserved characters)
- Handle UTF-8 multibyte characters properly
- Convert space to `%20` (not `+` like `urlencode()`)
- Work seamlessly with other String Morpher transformers
- Return URL-safe string ready for direct use in URLs

**Security Note:**
Proper URL encoding prevents **URL injection attacks** and ensures data integrity when transmitting user input through URLs.  Always encode user-generated content before including it in URLs to prevent malformed requests or security vulnerabilities.

## Checklist

- [x] I have read the [documentation](https://ssolweb.github.io/string-morpher)
- [x] I have read the existing [Methods](https://ssolweb.github.io/string-morpher/docs/methods/) documentation
- [x] I have searched for similar feature requests