(Changed) Performance optimisations, bug fixes, and Docker-based development setup (#45)

* refactor: Change class to final and update static method calls to self

(Changed) Make StringManipulation final and update static to self references

Make `StringManipulation` class final and replace `static` with `self`.

Converted the `StringManipulation` class to `final` to prevent inheritance and replaced all occurrences of `static` with `self` for improved clarity and static binding. Additionally, updated development dependencies in `composer.json` to their latest versions for enhanced tooling support.

* refactor: improve string processing readability

- Simplify control flow in string replacement methods
- Reduce code complexity for better maintainability

* perf: optimize string replacement logic for efficiency

- Improve performance of string manipulation operations
- Reduce unnecessary iterations in replacement algorithms

* perf: cache accent replacement mappings for better performance

- Implement caching mechanism for accent transformations
- Reduce repeated computations in accent normalization

* test: add comprehensive tests for string replacement optimizations

- Add test coverage for edge cases in string replacement
- Validate performance improvements with test cases

* refactor: remove unnecessary optimizations in strReplace method

- Simplify string replacement implementation
- Remove premature optimization attempts

* docs(project): Improve documentation accuracy and consistency

- Standardise spelling to South African English throughout codebase
  - Change "optimize/optimization" to "optimise/optimisation"
  - Change "normalize" to "normalise"
  - Change "standardize/capitalizing" to "standardise/capitalising"

- Fix README.md documentation issues
  - Remove duplicate UTF-8 to ANSI conversion section
  - Correct method name from validateDate() to isValidDate()
  - Remove references to non-existent validateTime() method
  - Fix incorrect output descriptions for utf8Ansi examples

- Fix code quality issues
  - Remove duplicate PHPDoc for removeAccents() method
  - Fix duplicate 'ë' character in REMOVE_ACCENTS_FROM array
  - Standardise parameter naming: $valor to $value in utf8Ansi()

- Clarify UnicodeMappings trait documentation
  - Update to accurately describe Unicode escape sequence decoding
  - Correct misconception about ANSI conversion functionality

These changes improve code maintainability and ensure documentation
accurately reflects the actual implementation. All tests pass.

Signed-off-by: Marjo Wenzel van Lier <marjo.vanlier@gmail.com>

* style: Fix code style issues

- Add missing periods to inline comments
- Fix array alignment in ACCENTS_REPLACEMENT
- Fix spacing in method signature
- Add parentheses around null coalescing operation
- Change dynamic method calls to static in tests

These changes address Codacy and PHPStan warnings.

Signed-off-by: Marjo Wenzel van Lier <marjo.vanlier@gmail.com>

* style: Fix binary operator spacing

Laravel Pint detected incorrect spacing around the equals sign
in the method signature default parameter.

Signed-off-by: Marjo Wenzel van Lier <marjo.vanlier@gmail.com>

* refactor: Remove unreachable null check

The null check after nameFix() was unreachable since nameFix() only
returns null when its input is null, and we already check for null
input at the beginning of searchWords().

This improves code coverage by removing dead code.

Signed-off-by: Marjo Wenzel van Lier <marjo.vanlier@gmail.com>

* fix: Add type assertion for PHPStan

PHPStan cannot infer that nameFix() only returns null when its input
is null. Added an assertion to help the static analyzer understand
the code flow better.

Signed-off-by: Marjo Wenzel van Lier <marjo.vanlier@gmail.com>

* refactor: Replace assert with type cast for PHPStan

Using assert() in production code is not recommended as assertions
can be disabled. Instead, we use a type cast to string which is safe
because we've already verified the input is not null.

Signed-off-by: Marjo Wenzel van Lier <marjo.vanlier@gmail.com>

* fix: Remove unnecessary SensitiveParameter import and fix cast spacing

- Remove duplicate SensitiveParameter import that conflicts with PHP 8's built-in attribute
- Use global \SensitiveParameter attribute instead of importing it
- Fix cast spacing to comply with PER coding standards

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: MarjovanLier <marjovanlier@gmail.com>

* feat(ci): Add pre-commit hooks with containerised testing

- Add Dockerfile for PHP 8.3 with all required extensions including xdebug
- Create docker-compose.yml with individual test services
- Set up pre-commit framework with comprehensive checks
- Add custom commit-msg hook for conventional commits validation
- Create test-runner.sh for easy test execution
- Create setup-hooks.sh for automated setup
- Add .dockerignore to optimise Docker builds
- Document setup process in CONTRIBUTING.md
- Update .gitignore with Docker and pre-commit entries

All tests now run in consistent Docker containers to avoid environment-specific issues.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: MarjovanLier <marjovanlier@gmail.com>

* fix(ci): Fix test runner script and remove docker-compose version warning

- Fix missing print_info function in test-runner.sh
- Remove obsolete version attribute from docker-compose.yml
- Fix composer validation test handling in test runner
- Add missing newlines at end of files (linter fixes)

All required tests now pass successfully in containers.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: MarjovanLier <marjovanlier@gmail.com>

* fix: resolve Phan compatibility issues with typed constants

- Remove typed array constants to support Phan polyfill parser
- Update Rector config to skip type-adding rules
- Fix import path for RemoveUselessVarTagRector
- Maintain type safety through PHPDoc annotations
- Set Phan processes to 1 to avoid pcntl requirement

All critical static analysis tools now passing (Phan, PHPStan, Rector)

* fix: suppress MissingClassConstType errors in Psalm

This allows both Phan and Psalm to pass - Phan requires untyped constants
while Psalm normally requires typed constants. By suppressing this specific
error type, we maintain compatibility with both tools.

* feat: add all composer tests to pre-commit hooks via Docker

- Add phpmd, phan, rector, and infection to pre-commit hooks
- All tests now run in Docker containers for consistency
- Infection mutation testing runs on pre-push stage
- Add helper script run-tests-docker.sh for running all tests
- Fix deprecated stage names (commit -> pre-commit, push -> pre-push)
- Enable xdebug in Docker for mutation testing support

All pre-commit hooks now passing with 98% mutation coverage

* style: add periods to inline comments in test files

- Add periods to all inline comments for consistency
- Follows coding style guidelines for comment punctuation
- Addresses CodeRabbit review feedback

* feat(hooks): Implement commitlint for conventional commit validation

- Add commitlint configuration with strict rules
- Update commit-msg hook to use commitlint via npx
- Add Docker support for commitlint when npm is not available
- Update Dockerfile to include Node.js and npm
- Add package.json for npm dependencies
- Create commitlint-docker.sh wrapper script
- Update setup script to install npm dependencies

This ensures all commit messages follow the Conventional Commits
specification with proper validation and helpful error messages.

Signed-off-by: Marjo Wenzel van Lier <marjo.vanlier@gmail.com>

* fix(config): Correct Phan configuration and pre-commit setup

- Revert Phan directory_list to include full vendor directory
- Change minimum_severity back to CRITICAL for focused analysis
- Increase Phan processes from 1 to 4 for better performance
- Remove deprecated stages declaration from PHPUnit pre-commit hook

These changes fix the Phan configuration to properly analyze vendor
dependencies while excluding them from analysis, and remove the
deprecated stage warning from pre-commit.

Signed-off-by: Marjo Wenzel van Lier <marjo.vanlier@gmail.com>

* perf: optimize string manipulation methods and fix validation bugs

- Optimize strReplace for single character replacements (69% faster)
- Optimize searchWords by combining operations (15% faster)
- Fix isValidDate to properly validate month/day combinations
- Add performance benchmarking suite
- Fix PHPStan type issues and improve null safety
- Add edge case handling for empty strings

The optimizations significantly improve performance for common use cases
while maintaining full backward compatibility. All tests pass.

Signed-off-by: Marjo Wenzel van Lier <marjo.vanlier@gmail.com>

* feat: restore typed class constants with Docker AST support

- Restored PHP 8.3+ typed class constants in AccentNormalization and UnicodeMappings traits
- Fixed Dockerfile to properly install AST extension separately from xdebug
- Updated composer.json to remove --allow-polyfill-parser flag for Phan
- Removed AddTypeToConstRector skip in rector.php configuration
- Removed MissingClassConstType suppression in psalm.xml
- Reduced Phan processes from 4 to 1 to avoid memory issues
- Fixed Psalm strict type issues in benchmark file with explicit casting
- Applied code style fixes with Pint and Rector
- Added RemoveConcatAutocastRector to skip list to avoid Psalm conflicts
- Updated .gitignore to exclude temporary and Qodana files

All static analysis tools now support typed constants when running in Docker containers
with the AST extension properly installed.

🤖 Generated with [Claude Code](https://claude.ai/code)

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

* fix: correct PHPStan and Psalm type annotations in IsValidTimePartTest

- Updated data provider return type annotations to match exact array shape
- Fixed type mismatch between data providers and test method parameters
- Ensures both PHPStan and Psalm static analysis pass without errors

* docs: update CLAUDE.md with Docker-first testing approach

- Consolidated Docker testing commands into main Build & Testing section
- Emphasized Docker as the recommended testing environment
- Removed duplicate Docker testing commands section
- Added all available Docker test services with proper naming
- Clarified that Docker provides PHP 8.3 with AST extension

* chore: update development dependencies

- laravel/pint: >=1.21.1 -> >=1.22.1
- phpstan/phpstan: >=2.1.8 -> >=2.1.17
- phpstan/phpstan-strict-rules: >=2.0.3 -> >=2.0.4
- psalm/plugin-phpunit: >=0.19.2 -> >=0.19.3
- rector/rector: >=2.0.10 -> >=2.0.16

All tests passing with updated dependencies

* feat: configure Codacy to use PER 2.0 coding standard

- Added .php-cs-fixer.php with @PER-CS2.0 rule set
- Configured Codacy to use PHP CS Fixer with PER 2.0 standard
- Disabled phpcodesniffer in Codacy to avoid style conflicts
- Simplified pint.json to use only the 'per' preset
- Added .php-cs-fixer.cache to .gitignore

This ensures both Pint and Codacy use the same PER 2.0 coding standard

* fix: improve Codacy configuration to enforce PER 2.0 standard

- Explicitly disabled all PHP style checkers except php-cs-fixer
- Added .codacyignore to exclude non-source files
- Excluded tests/Benchmark from analysis as it has different requirements
- Disabled PHPMD to avoid style conflicts

This should resolve Codacy issues by ensuring only php-cs-fixer
with PER 2.0 standard is used for style checking

* feat: add PHP_CodeSniffer configuration for Codacy

- Added phpcs.xml with PER coding standard
- Enabled PHP_CodeSniffer in Codacy configuration
- Excluded specific rules that conflict with project standards
- Kept both PHP_CodeSniffer and php-cs-fixer enabled

This provides Codacy with explicit configuration files for both
supported tools to enforce PER 2.0 coding standard

---------

Signed-off-by: Marjo Wenzel van Lier <marjo.vanlier@gmail.com>
Signed-off-by: MarjovanLier <marjovanlier@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: MarjovanLier

.codacy.yaml

@@ -0,0 +1,36 @@
+---
+# Codacy configuration to align with PER 2.0 coding standard
+engines:
+  # Try to use PHP_CodeSniffer with our custom config
+  phpcodesniffer:
+    enabled: true
+    config: phpcs.xml
+  # Also try php-cs-fixer if supported
+  php-cs-fixer:
+    enabled: true
+    config: .php-cs-fixer.php
+  # Disable other style checkers
+  phpmd:
+    enabled: false
+  # Keep duplication detection
+  duplication:
+    enabled: true
+    config:
+      languages:
+        - php
+
+# Exclude non-source files from analysis
+exclude_paths:
+  - 'vendor/**'
+  - '.github/**'
+  - 'docker/**'
+  - 'node_modules/**'
+  - 'tests/Benchmark/**'
+  - '*.md'
+  - '*.sh'
+  - '*.yml'
+  - '*.yaml'
+  - 'Dockerfile'
+  - '.php-cs-fixer.cache'
+  - 'composer.lock'
+  - 'package-lock.json'

.codacyignore

@@ -0,0 +1,35 @@
+# Codacy ignore file
+# Exclude test benchmarks as they have different style requirements
+tests/Benchmark/
+
+# Exclude vendor and dependencies
+vendor/
+node_modules/
+
+# Exclude build and CI files
+.github/
+docker/
+Dockerfile
+docker-compose.yml
+
+# Exclude documentation
+*.md
+README.md
+CONTRIBUTING.md
+CLAUDE.md
+IMPROVEMENTS.md
+
+# Exclude configuration files
+*.yml
+*.yaml
+.gitignore
+.dockerignore
+composer.lock
+package-lock.json
+
+# Exclude shell scripts
+*.sh
+
+# Exclude cache files
+.php-cs-fixer.cache
+.psalm-cache

.dockerignore

@@ -0,0 +1,17 @@
+.git
+.github
+.idea
+vendor
+.phpunit.cache
+.phpunit.result.cache
+.php-cs-fixer.cache
+reports
+.qodo
+*.log
+.DS_Store
+docker-compose.yml
+Dockerfile
+.dockerignore
+.gitignore
+README.md
+CLAUDE.md

.githooks/commit-msg

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+
+# Conventional Commits validation hook using commitlint
+# This hook validates that commit messages follow the Conventional Commits specification
+
+# Colors for output
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+# Check if it's a merge commit
+merge_regex='^Merge '
+commit_message=$(cat "$1")
+
+if echo "$commit_message" | grep -qE "$merge_regex"; then
+    exit 0
+fi
+
+# Determine which commitlint runner to use
+if command -v npx &> /dev/null && [ -d "node_modules" ]; then
+    # Use local npx
+    echo -e "${GREEN}Running commitlint (local)...${NC}"
+
+    if ! npx --no -- commitlint --edit "$1"; then
+        echo ""
+        echo -e "${RED}ERROR: Commit message does not pass commitlint validation!${NC}"
+        echo ""
+        echo "Please ensure your commit message follows the Conventional Commits format."
+        echo "See commitlint.config.js for the specific rules."
+        exit 1
+    fi
+elif [ -f "./commitlint-docker.sh" ] && command -v docker &> /dev/null && docker info &> /dev/null; then
+    # Use Docker wrapper
+    echo -e "${GREEN}Running commitlint (Docker)...${NC}"
+
+    if ! ./commitlint-docker.sh "$1"; then
+        echo ""
+        echo -e "${RED}ERROR: Commit message does not pass commitlint validation!${NC}"
+        echo ""
+        echo "Please ensure your commit message follows the Conventional Commits format."
+        echo "See commitlint.config.js for the specific rules."
+        exit 1
+    fi
+else
+    # Fallback to basic regex validation
+    echo -e "${YELLOW}WARNING: commitlint not available. Using basic validation.${NC}"
+
+    commit_regex='^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test|security)(\([a-z0-9\-]+\))?(!)?: .{1,100}$'
+    first_line=$(echo "$commit_message" | head -n1)
+
+    if ! echo "$first_line" | grep -qE "$commit_regex"; then
+        echo -e "${RED}ERROR: Commit message does not follow Conventional Commits format!${NC}"
+        echo ""
+        echo "Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert, security"
+        echo "Format: <type>(<scope>): <subject>"
+        echo ""
+        echo "Your message: $first_line"
+        exit 1
+    fi
+fi
+
+# Additional checks for signed-off-by (required by this project)
+if ! grep -q "Signed-off-by: " "$1"; then
+    echo -e "${YELLOW}Adding 'Signed-off-by' line...${NC}"
+
+    # Get git user info
+    name=$(git config user.name)
+    email=$(git config user.email)
+
+    if [ -n "$name" ] && [ -n "$email" ]; then
+        echo "" >> "$1"
+        echo "Signed-off-by: $name <$email>" >> "$1"
+    else
+        echo -e "${RED}ERROR: Cannot add Signed-off-by - git user.name or user.email not configured${NC}"
+        exit 1
+    fi
+fi
+
+exit 0

.gitignore

@@ -6,3 +6,26 @@ tests/temp
 .phpunit.result.cache
 .php-cs-fixer.cache
 reports
+
+.qodo
+
+# Qodana
+qodana.yaml
+qodana.sarif.json
+.qodana/
+
+# Temporary files
+commit_messages.txt
+*.tmp
+
+# Docker
+.docker/
+docker-compose.override.yml
+
+# Pre-commit
+.pre-commit/
+
+# Node modules
+node_modules/
+package-lock.json
+.php-cs-fixer.cache

.gitmessage

@@ -0,0 +1,22 @@
+# Conventional Commit Format:
+# <type>(<scope>): <subject>
+#
+# <body>
+#
+# <footer>
+#
+# Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+# Scope: Optional, e.g., parser, compiler, etc.
+# Subject: Brief description (imperative mood, no period)
+# Body: Detailed explanation (optional)
+# Footer: Breaking changes, issue references (optional)
+#
+# Examples:
+# feat(api): add user authentication endpoint
+# fix(parser): resolve memory leak in tokenizer
+# docs: update installation instructions
+#
+# Breaking change example:
+# feat(api)!: change authentication to use JWT
+#
+# BREAKING CHANGE: API now requires JWT tokens instead of API keys

.phan/config.php

@@ -57,6 +57,9 @@
     // Automatically inferred from composer.json requirement for "php" of "^8.3"
     'target_php_version' => '8.3',
 
+    // Minimum PHP version to check compatibility against
+    'minimum_target_php_version' => '8.3',
+
     // If enabled, missing properties will be created when
     // they are first seen. If false, we'll report an
     // error message if there is an attempt to write
@@ -306,7 +309,7 @@
 
     // The number of processes to fork off during the analysis
     // phase.
-    'processes' => 4,
+    'processes' => 1,
 
     // List of case-insensitive file extensions supported by Phan.
     // (e.g. `['php', 'html', 'htm']`)
@@ -356,6 +359,7 @@
     // your application should be included in this list.
     'directory_list' => [
         'src',
+        'tests',
         'vendor',
     ],
 

.php-cs-fixer.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+$finder = PhpCsFixer\Finder::create()
+    ->in(__DIR__)
+    ->exclude('vendor')
+    ->exclude('.github')
+    ->exclude('docker')
+    ->name('*.php')
+    ->notName('*.blade.php')
+    ->ignoreDotFiles(true)
+    ->ignoreVCS(true);
+
+return (new PhpCsFixer\Config())
+    ->setFinder($finder)
+    ->setRules([
+        '@PER-CS2.0' => true,  // PER 2.0 coding standard
+        // Additional project-specific rules to align with our standards
+        'concat_space' => ['spacing' => 'one'],
+        'array_indentation' => true,
+        'binary_operator_spaces' => [
+            'operators' => [
+                '=>' => 'align_single_space_minimal',
+            ],
+        ],
+        'phpdoc_line_span' => [
+            'const' => 'single',
+            'property' => 'single',
+            'method' => 'multi',
+        ],
+        'no_superfluous_phpdoc_tags' => [
+            'allow_mixed' => true,
+            'allow_unused_params' => false,
+        ],
+    ])
+    ->setRiskyAllowed(true)
+    ->setUsingCache(true);

.pr_agent.toml

@@ -55,4 +55,4 @@ push_commands = [
     """,
     "/review auto_approve --pr_reviewer.num_code_suggestions=0 --pr_reviewer.inline_code_comments=true"
 ]
-handle_push_trigger = true
+handle_push_trigger = true

.pre-commit-config.yaml

@@ -0,0 +1,98 @@
+# See https://pre-commit.com for more information
+repos:
+  # Local hooks that run in Docker containers
+  - repo: local
+    hooks:
+      - id: composer-validate
+        name: Validate composer.json
+        entry: docker-compose run --rm test-code-style composer validate --strict
+        language: system
+        files: composer\.(json|lock)$
+        pass_filenames: false
+
+      - id: php-lint
+        name: PHP Syntax Check
+        entry: docker-compose run --rm test-lint
+        language: system
+        files: \.php$
+        pass_filenames: false
+
+      - id: php-code-style
+        name: PHP Code Style (Laravel Pint)
+        entry: docker-compose run --rm test-code-style
+        language: system
+        files: \.php$
+        pass_filenames: false
+
+      - id: phpstan
+        name: PHPStan Static Analysis
+        entry: docker-compose run --rm test-phpstan
+        language: system
+        files: \.php$
+        pass_filenames: false
+
+      - id: psalm
+        name: Psalm Static Analysis
+        entry: docker-compose run --rm test-psalm
+        language: system
+        files: \.php$
+        pass_filenames: false
+
+      - id: phpunit
+        name: PHPUnit Tests
+        entry: docker-compose run --rm test-phpunit
+        language: system
+        files: \.(php|xml)$
+        pass_filenames: false
+
+      - id: security-check
+        name: Security Vulnerabilities Check
+        entry: docker-compose run --rm test-security
+        language: system
+        files: composer\.lock$
+        pass_filenames: false
+
+      - id: phpmd
+        name: PHP Mess Detector
+        entry: docker-compose run --rm test-phpmd
+        language: system
+        files: \.php$
+        pass_filenames: false
+
+      - id: phan
+        name: Phan Static Analysis
+        entry: docker-compose run --rm test-phan
+        language: system
+        files: \.php$
+        pass_filenames: false
+
+      - id: rector
+        name: Rector Code Quality
+        entry: docker-compose run --rm test-rector
+        language: system
+        files: \.php$
+        pass_filenames: false
+
+      - id: infection
+        name: Infection Mutation Testing
+        entry: docker-compose run --rm test-infection
+        language: system
+        files: \.php$
+        pass_filenames: false
+        stages: [pre-push]
+
+  # Standard pre-commit hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: ^vendor/
+      - id: end-of-file-fixer
+        exclude: ^vendor/
+      - id: check-yaml
+      - id: check-added-large-files
+        args: ['--maxkb=1000']
+      - id: check-json
+      - id: check-xml
+      - id: mixed-line-ending
+        args: ['--fix=lf']