From 04c50779468cb06c9c18135a571d73e1ec2072c7 Mon Sep 17 00:00:00 2001
From: techmahedy <mahedy150101@gmail.com>
Date: Fri, 30 Oct 2026 20:41:34 +0600
Subject: [PATCH 1/2] add string service contracts

---
 src/Phaseolies/Helpers/helpers.php            |   8 +-
 src/Phaseolies/Launchers/FacadeLauncher.php   |   7 +-
 .../Contracts/StringServiceInterface.php      | 298 ++++++++++++++++++
 src/Phaseolies/Support/Facades/Str.php        |   2 +-
 src/Phaseolies/Support/StringService.php      |   8 +-
 tests/StringServiceTest.php                   |  33 ++
 6 files changed, 346 insertions(+), 10 deletions(-)
 create mode 100644 src/Phaseolies/Support/Contracts/StringServiceInterface.php

diff --git a/src/Phaseolies/Helpers/helpers.php b/src/Phaseolies/Helpers/helpers.php
index 0617c08f..0014b577 100644
--- a/src/Phaseolies/Helpers/helpers.php
+++ b/src/Phaseolies/Helpers/helpers.php
@@ -3,7 +3,7 @@
 use Phaseolies\Utilities\Paginator;
 use Phaseolies\Translation\Translator;
 use Phaseolies\Support\Contracts\UrlGeneratorInterface;
-use Phaseolies\Support\StringService;
+use Phaseolies\Support\Contracts\StringServiceInterface;
 use Phaseolies\Support\Facades\Log;
 use Phaseolies\Support\Facades\Crypt;
 use Phaseolies\Support\CookieJar;
@@ -433,11 +433,11 @@ function is_auth(): bool
 
 if (!function_exists('str')) {
     /**
-     * Instance of the StringService class
+     * Instance of the string service
      *
-     * @return StringService
+     * @return StringServiceInterface
      */
-    function str(): StringService
+    function str(): StringServiceInterface
     {
         return app('str');
     }
diff --git a/src/Phaseolies/Launchers/FacadeLauncher.php b/src/Phaseolies/Launchers/FacadeLauncher.php
index 66394f60..4a562367 100644
--- a/src/Phaseolies/Launchers/FacadeLauncher.php
+++ b/src/Phaseolies/Launchers/FacadeLauncher.php
@@ -7,6 +7,7 @@
 use Phaseolies\Support\Contracts\UrlGeneratorInterface;
 use Phaseolies\Support\ViteManager;
 use Phaseolies\Support\StringService;
+use Phaseolies\Support\Contracts\StringServiceInterface;
 use Phaseolies\Support\Storage\StorageFileService;
 use Phaseolies\Support\Storage\Contracts\StorageInterface;
 use Phaseolies\Signals\SignalBus;
@@ -116,9 +117,11 @@ public function register()
             return new Sanitizer([], []);
         });
 
-        // Bind the 'str' service to a singleton instance of the StringService class.
+        // Bind the string service contract to a singleton implementation and
+        // retain the existing 'str' service name as an alias.
         // This handles string related helper jobs
-        $this->app->singleton('str', StringService::class);
+        $this->app->singleton(StringServiceInterface::class, StringService::class);
+        $this->app->alias(StringServiceInterface::class, 'str');
 
         // Bind the 'cookie' service to a singleton instance of the CookieJar class.
         // This handles cookie related jobs
diff --git a/src/Phaseolies/Support/Contracts/StringServiceInterface.php b/src/Phaseolies/Support/Contracts/StringServiceInterface.php
new file mode 100644
index 00000000..c7829a82
--- /dev/null
+++ b/src/Phaseolies/Support/Contracts/StringServiceInterface.php
@@ -0,0 +1,298 @@
+<?php
+
+namespace Phaseolies\Support\Contracts;
+
+interface StringServiceInterface
+{
+    /**
+     * Extract a substring from the given input string.
+     *
+     * @param string $input
+     * @param int $start
+     * @param int|null $length (Optional)
+     * @return string
+     */
+    public function substr(string $input, int $start, ?int $length = null): string;
+
+    /**
+     * Compute the length of the given string.
+     *
+     * @param string $input
+     * @return int
+     */
+    public function len(string $input): int;
+
+    /**
+     * Count the number of words in a string.
+     *
+     * @param string $string
+     * @return int
+     */
+    public function countWord(string $string): int;
+
+    /**
+     * Check if a given string is a palindrome.
+     *
+     * @param string $string
+     * @return bool
+     */
+    public function isPalindrome(string $string): bool;
+
+    /**
+     * Generate a random alphanumeric string of a given length.
+     *
+     * @param int $length
+     * @return string
+     */
+    public function random(int $length = 10): string;
+
+    /**
+     * Convert a snake_case or kebab-case string to camelCase
+     *
+     * @param string $input
+     * @return string
+     */
+    public function camel(string $input): string;
+
+    /**
+     * Mask a string with a specified number of visible characters at the start and end.
+     *
+     * @param string $string
+     * @param int $visibleFromStart
+     * @param int $visibleFromEnd
+     * @param string
+     */
+    public function mask(string $string, int $visibleFromStart = 1, int $visibleFromEnd = 1, string $maskCharacter = '*'): string;
+
+    /**
+     * Truncate a string to a specific length and append a suffix if truncated.
+     *
+     * @param string $string
+     * @param int $maxLength
+     * @param string $suffix
+     * @return string
+     */
+    public function truncate(string $string, int $maxLength, string $suffix = '...'): string;
+
+    /**
+     * Convert a camelCase string to snake_case.
+     *
+     * @param string $input
+     * @return string
+     */
+    public function snake(string $input): string;
+
+    /**
+     * Convert a string to title case (each word capitalized).
+     *
+     * @param string $input
+     * @return string
+     */
+    public function title(string $input): string;
+
+    /**
+     * Generate a URL-friendly slug from a string.
+     *
+     * @param string $input
+     * @param string $separator
+     * @return string
+     */
+    public function slug(string $input, string $separator = '-'): string;
+
+    /**
+     * Check if a string contains another string (case-insensitive or sensitive).
+     *
+     * @param string $haystack
+     * @param string|array $needles
+     * @param bool $ignoreCase
+     * @return bool
+     */
+    public function contains(string $haystack, string | array $needles, bool $ignoreCase = true): bool;
+
+    /**
+     * Limit the number of words in a string, handling Unicode and preserving
+     * natural word boundaries (splitting on whitespace).
+     *
+     * @param string $string
+     * @param int $words
+     * @param string $end
+     * @param string $encoding
+     * @return string
+     */
+    public function limitWords(string $string, int $words, string $end = '...', string $encoding = 'UTF-8'): string;
+
+    /**
+     * Determine if a string matches a given pattern.
+     *
+     * @param string $pattern
+     * @param string $value
+     * @return bool
+     */
+    public function is(string $pattern, string $value): bool;
+
+    /**
+     * Remove all whitespace from a string.
+     *
+     * @param string $input
+     * @return string
+     */
+    public function removeWhiteSpace(string $input): string;
+
+    /**
+     * Generate a UUID v4 string.
+     *
+     * @return string The generated UUID.
+     */
+    public function uuid(): string;
+
+    /**
+     * Check if a string starts with one or more given needles (case-sensitive).
+     *
+     * @param string $haystack
+     * @param string|array $needles
+     * @return bool
+     */
+    public function startsWith(string $haystack, string | array $needles): bool;
+
+    /**
+     * Check if a string ends with one or more given needles (case‐sensitive).
+     * This version is Unicode‐safe (works with any UTF‐8 text).
+     *
+     * @param string $haystack
+     * @param string|array $needles
+     * @param string $encoding
+     * @return bool
+     */
+    public function endsWith(string $haystack, string | array $needles, string $encoding = 'UTF-8'): bool;
+
+    /**
+     * Convert a string to StudlyCase (each “word” capitalized, no separators).
+     *
+     * @param string $input
+     * @param string $encoding
+     * @return string
+     */
+    public function studly(string $input, string $encoding = 'UTF-8'): string;
+
+    /**
+     * Reverse a UTF-8 string while preserving multi-byte characters.
+     *
+     * @param string $input
+     * @param string $encoding
+     * @return string
+     */
+    public function reverse(string $input, string $encoding = 'UTF-8'): string;
+
+    /**
+     * Extract all numeric digits from a string.
+     *
+     * @param string $input
+     * @return string
+     */
+    public function extractNumbers(string $input): string;
+
+    /**
+     * Find the longest common substring between two strings.
+     *
+     * @param string $str1
+     * @param string $str2
+     * @return string
+     */
+    public function longestCommonSubstring(string $str1, string $str2): string;
+
+    /**
+     * Convert a string to leetspeak (1337).
+     *
+     * @param string $input
+     * @return string
+     */
+    public function leetSpeak(string $input): string;
+
+    /**
+     * Extract all email addresses from a string.
+     *
+     * @param string $input
+     * @return array
+     */
+    public function extractEmails(string $input): array;
+
+    /**
+     * Highlight all occurrences of a keyword in a string using HTML tags.
+     *
+     * @param string $input
+     * @param string $keyword
+     * @param string $tag
+     * @return string
+     */
+    public function highlightKeyword(string $input, string $keyword, string $tag = 'strong'): string;
+
+    /**
+     * Convert string to uppercase
+     *
+     * @param string $input
+     * @return string
+     */
+    public function toUpper(string $input): string;
+
+    /**
+     * Append a suffix to a string if it doesn't already end with it.
+     *
+     * @param string $input
+     * @param string $suffix
+     * @return string
+     */
+    public function suffixAppend(string $input, string $suffix): string;
+
+    /**
+     * Remove a suffix from a string.
+     *
+     * @param string $input
+     * @param string $suffix
+     * @return string
+     */
+    public function removeSuffix(string $input, string $suffix): string;
+
+    /**
+     * Get the portion of $subject after the first occurrence of $search.
+     * 
+     * @param string $subject
+     * @param string $search
+     * @return string
+     */
+    public function after(string $subject, string $search): string;
+
+    /**
+     * Get the portion of $subject before the first occurrence of $search.
+     * 
+     * @param string $subject
+     * @param string $search
+     * @return string
+     */
+    public function before(string $subject, string $search): string;
+
+    /**
+     * Get the portion between two values.
+     * 
+     * @param string $subject
+     * @param string $from
+     * @param string $to
+     * @return string
+     */
+    public function between(string $subject, string $from, string $to): string;
+
+    /**
+     * Determine if a given string is valid JSON.
+     *
+     * @param string $value
+     * @return bool
+     */
+    public function isJson(string $value): bool;
+
+    /**
+     * Harmonize the given URL
+     *
+     * @param string $url
+     * @return string
+     */
+    public function urlHarmonize(string $url): string;
+}
diff --git a/src/Phaseolies/Support/Facades/Str.php b/src/Phaseolies/Support/Facades/Str.php
index b54f5f7d..b826b4ad 100644
--- a/src/Phaseolies/Support/Facades/Str.php
+++ b/src/Phaseolies/Support/Facades/Str.php
@@ -36,7 +36,7 @@
  * @method static string between(string $subject, string $from, string $to)
  * @method static bool isJson(string $value)
  * @method static string urlHarmonize(string $url)
- * @see \Phaseolies\Support\StringService
+ * @see \Phaseolies\Support\Contracts\StringServiceInterface
  */
 class Str extends BaseFacade
 {
diff --git a/src/Phaseolies/Support/StringService.php b/src/Phaseolies/Support/StringService.php
index 3becbd25..a1307eb7 100644
--- a/src/Phaseolies/Support/StringService.php
+++ b/src/Phaseolies/Support/StringService.php
@@ -2,7 +2,9 @@
 
 namespace Phaseolies\Support;
 
-class StringService
+use Phaseolies\Support\Contracts\StringServiceInterface;
+
+class StringService implements StringServiceInterface
 {
     /**
      * Extract a substring from the given input string.
@@ -71,7 +73,7 @@ public function random(int $length = 10): string
      * @param string $input
      * @return string
      */
-    function camel(string $input): string
+    public function camel(string $input): string
     {
         $input = str_replace(['-', '_'], ' ', $input);
         $input = mb_convert_case($input, MB_CASE_TITLE, 'UTF-8');
@@ -191,7 +193,7 @@ public function contains(string $haystack, string | array $needles, bool $ignore
      * @param string $encoding
      * @return string
      */
-    function limitWords(string $string, int $words, string $end = '...', string $encoding = 'UTF-8'): string
+    public function limitWords(string $string, int $words, string $end = '...', string $encoding = 'UTF-8'): string
     {
         $trimmed = trim($string);
 
diff --git a/tests/StringServiceTest.php b/tests/StringServiceTest.php
index bd94d1fb..f00130d7 100644
--- a/tests/StringServiceTest.php
+++ b/tests/StringServiceTest.php
@@ -2,8 +2,13 @@
 
 namespace Tests\Unit;
 
+use Phaseolies\Application;
+use Phaseolies\DI\Container;
+use Phaseolies\Launchers\FacadeLauncher;
+use Phaseolies\Support\Contracts\StringServiceInterface;
 use Phaseolies\Support\StringService;
 use PHPUnit\Framework\TestCase;
+use ReflectionClass;
 
 class StringServiceTest extends TestCase
 {
@@ -235,4 +240,32 @@ public function testReturnsFalseForInvalidJson()
         $this->assertFalse($this->stringService->isJson('Hello World'));
         $this->assertFalse($this->stringService->isJson(''));
     }
+
+    public function testStringServiceConformsToTheContract()
+    {
+        $this->assertInstanceOf(StringServiceInterface::class, $this->stringService);
+    }
+
+    public function testApplicationBindsTheStringContractAndLegacyServiceNameToTheSameSingleton()
+    {
+        $app = $this->getMockBuilder(Application::class)->disableOriginalConstructor()->onlyMethods([])->getMock();
+        (new ReflectionClass(Container::class))->getConstructor()->invoke($app);
+        $previous = Container::getInstance();
+        Container::setInstance($app);
+
+        try {
+            $originalAppUrl = getenv('APP_URL');
+            putenv('APP_URL=http://localhost');
+            (new FacadeLauncher($app))->register();
+
+            $contract = $app->get(StringServiceInterface::class);
+
+            $this->assertInstanceOf(StringService::class, $contract);
+            $this->assertSame($contract, $app->get('str'));
+            $this->assertSame($contract, str());
+        } finally {
+            Container::setInstance($previous);
+            $originalAppUrl === false ? putenv('APP_URL') : putenv("APP_URL={$originalAppUrl}");
+        }
+    }
 }

From 5beb0dd4f3e9fdcc1ac64eb487c416923fcdcd27 Mon Sep 17 00:00:00 2001
From: techmahedy <mahedy150101@gmail.com>
Date: Fri, 30 Oct 2026 20:46:17 +0600
Subject: [PATCH 2/2] fix doc comment

---
 .../Support/Contracts/StringServiceInterface.php         | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/src/Phaseolies/Support/Contracts/StringServiceInterface.php b/src/Phaseolies/Support/Contracts/StringServiceInterface.php
index c7829a82..cf4f4f33 100644
--- a/src/Phaseolies/Support/Contracts/StringServiceInterface.php
+++ b/src/Phaseolies/Support/Contracts/StringServiceInterface.php
@@ -60,7 +60,8 @@ public function camel(string $input): string;
      * @param string $string
      * @param int $visibleFromStart
      * @param int $visibleFromEnd
-     * @param string
+     * @param string $maskCharacter
+     * @return string
      */
     public function mask(string $string, int $visibleFromStart = 1, int $visibleFromEnd = 1, string $maskCharacter = '*'): string;
 
@@ -110,8 +111,7 @@ public function slug(string $input, string $separator = '-'): string;
     public function contains(string $haystack, string | array $needles, bool $ignoreCase = true): bool;
 
     /**
-     * Limit the number of words in a string, handling Unicode and preserving
-     * natural word boundaries (splitting on whitespace).
+     * Limit the number of words in a string, handling Unicode and preserving  natural word boundaries
      *
      * @param string $string
      * @param int $words
@@ -155,8 +155,7 @@ public function uuid(): string;
     public function startsWith(string $haystack, string | array $needles): bool;
 
     /**
-     * Check if a string ends with one or more given needles (case‐sensitive).
-     * This version is Unicode‐safe (works with any UTF‐8 text).
+     * Check if a string ends with one or more given needles (case-sensitive).
      *
      * @param string $haystack
      * @param string|array $needles